Image Delivery API

Images that are managed in the Uniform Asset Library are cached, optimized, and delivered via a CDN using the Uniform Image Delivery API.

The Image Delivery API provides a public URL for the image you can use in your application. By default, the CDN delivers the image in the original dimensions and the image format supported by the browser (AVIF, WebP, or the source format).

Base URL#

Image assets are delivered from the following base URL:

https://img.uniform.global

Each image in the Uniform Asset Library has a unique path that typically includes the original filename. The easiest way to get the complete image URL is to use the Copy URL button in the detail view of any image in the asset library.

To apply transformations to images, you can append transformation parameters to the URL as query parameters. This allows you to dynamically resize, crop, and optimize images for different devices and use cases without modifying the original asset.

Output formats#

When you use the Image Delivery API, it automatically picks the best image format based on what the visitor's browser can display. This helps make sure everyone sees high-quality images that load quickly, no matter what device or browser they're using.

Following logic is applied:

If the browser supports AVIF, the image is delivered in AVIF format.
If the browser supports WebP, the image is delivered in WebP format.
Otherwise, the image is delivered in the original format.

SVG images are always delivered in SVG format and are not transformed.

Image transformation#

To transform and optimize images for different use cases, the Image Delivery API exposes several query parameters:

Parameter	Description	Allowed values	Default value
width	Maximum width of the image in pixels	1 < n < 4096	/
height	Maximum height of the image in pixels	1 < n < 4096	/
fit	How to resize the image	`scale-down` - resize the image to fit within the given dimensions, but never larger than the original size, while maintaining the aspect ratio `contain` - resize the image to fit within the given dimensions, including possibly enlarging the image, while maintaining the aspect ratio `cover` - resize the image to fully cover the given dimensions, cropping as needed	`scale-down`
focal	A focal point of the image around which the image will be cropped. It only takes effect when `fit` is set to `cover`	`auto` - uses the maximum symmetric surround algorithm `center` - uses the center of the image `NxM` - N and M are numbers between 0.0 and 1.0, N representing the x-axis and M representing the y-axis	`center`

Limitations and fair use policy#

The Image Delivery API only supports images that are hosted by Uniform.
.avif images can not be transformed by the Image Delivery API.
The Image Delivery API is subject to Uniform's fair use policy.

Cropping an image with a focal point#

The focal point that is set on an image asset only defines the coordinates of the subject of the image in the properties of the asset.

To take effect, the image must be resized using the fit=cover parameter and passing the focal point value to the focal parameter of the Image Delivery API.

Example usage of an image query string that would serve a 400 by 800 image with a focal point at around 20% from the top left corner:

https://img.uniform.global/<path-to-asset>?width=400&height=800&fit=cover&focal=0.2x0.2

Focal points on external images#

When connecting to an image from an external source (through a custom URL or an integration) in an asset parameter, the focal point can be specified but it is not used for the image cropping as only images hosted by Uniform can be transformed.

If the external source system (e.g. a DAM) supports focal points for image transformations, you can pass the value of the focal property to the the external source URL.