Image transformation API is a real-time image manipulation and optimization feature of the Delivery API that speeds up image delivery. Because the Delivery API caches the results of image transformations, you can retrieve the transformed images even faster the next time you need them.
By adding parameters to your image URLs, you can enhance, resize, and crop images, compress them, or change their format for better performance. These operations can be applied programmatically in real-time without the need to batch process or maintain multiple copies of an image to match device breakpoints.
Image transformation API requires the source images to be in one of the following formats:
JPEG
PNG
GIF
WebP
The format of the source image files must be reflected in their file extensions and MIME types. For example, an image in the JPEG format needs the .jpg or .jpeg file extension and the image/jpeg MIME type.
The optimized output image can be any of the following image formats:
JPEG
PJPG
PNG
PNG8
GIF
WebP
You can convert the output image to these formats using the format parameter.
For an image to be customizable, it must meet the following criteria:
The source image resolution must be 12,000 × 12,000 px or less.
File size must be less than 50Â MB.
Image transformation works by applying the query parameters of the transformation methods to the absolute URLs of images. You can get the image URL directly from the asset details in the UI.Â
Once the image is added to a content item, the image URL can also be retrieved via the Delivery API. You can get the image URLs by either listing the items or retrieving a single content item containing the images.
Adjustable images can be used in the Asset elements and in the Rich text elements of the content items.
In Asset elements, the absolute URL for the image can be found in the url property of the asset object returned in the JSON response.
In Rich Text elements, the absolute URL for the image can be found in the url property of the images object and in the formatted text of the value property.
You can use the size parameters to resize, crop, and change the aspect ratio of your images. In general, when using an invalid combination of parameters for the image, the Delivery API returns the original image without applying any changes. The maximum output dimensions are 8192 × 8192 pixels. All output images will be sized down to accommodate this limit.
Image width represents the width of the output image. You can use the w parameter to dynamically resize the image based on pixels and percent values. If the width is represented by an integer greater than or equal to 1, the value is interpreted as a pixel width. If the width is a float greater than 0 but less than 1, it's interpreted as a percentage width. The maximum output width can be 8192 px. If both width and height parameters are omitted, the input image dimensions are used.
Value
Units
Description
Example
Integer
Pixels
A whole number between 1 and 8192.
/on-roasts-1080px.jpg?w=300 changes image width to 300Â px.
Float
Percentage
A floating-point number greater than 0 but less than 1.
/on-roasts-1080px.jpg?w=0.1 changes the width to 10 % of the input image.
When using the width parameter with a value greater than the input image width, the Delivery API returns the original image without any changes to its width.
Image height represents the height of the output image. You can use the h parameter to dynamically resize the image based on pixels and percent values. If the height is represented by an integer greater than or equal to 1, the value is interpreted as a pixel height. If the height is a float greater than 0 but less than 1, it's interpreted as a percentage height. The maximum output height can be 8192 px. If both width and height are omitted, the input image dimensions are used.
Value
Units
Description
Example
Integer
Pixels
A whole number between 1 and 8192.
/on-roasts-1080px.jpg?h=300 changes image height to 300 px.
Float
Percentage
A floating-point number greater than 0 but less than 1.
/on-roasts-1080px.jpg?h=0.1 changes image height to 10 % of the input image.
When using a height parameter greater than the input image height, the Delivery API returns the image with its original height value.
Device pixel ratio is used to serve correctly sized images on different devices. The dpr parameter value represents the ratio between physical and logical pixels. For example, when a mobile device has a device pixel ratio of 2, there are twice as many physical pixels on the screen.
The maximum supported device pixel ratio value is 5. When the value is higher than 5, the device pixel ratio is calculated as if the value was equal to 5.
Value
Units
Description
Example
Float
DPR
A floating-point number greater than 0 but less than 5.
/on-roasts-1080px.jpg?w=300&dpr=2 changes the width to 300 px for screens with a device pixel ratio of 2.
After resizing, the fit parameter controls how the output image is constrained within the provided size values. Valid values are clip, scale, and crop. The default value is clip.Â
There are differences in how the resize fit modes change the aspect ratio. The aspect ratio of an image describes the proportional relationship between its width and its height.
With the default clip fit mode, the image is resized to match one of the constraining dimensions. For example, attempting to resize the image of 300 × 200 (aspect ratio of 3:2) to 100 × 100 will result in an image that is 100 × 67 because the original image’s aspect ratio is maintained.
When using the scale fit mode, the image is scaled and distorted to fit the specified dimensions. When resizing the image to be wider than the original, the image is scaled horizontally to fit the dimensions. Similarly, when resizing the image to be taller than the original, the image is scaled vertically to fit the dimensions.
The crop fit mode crops the excess image data while keeping the image centered. This means that the output image’s center corresponds with the input image’s center. You can control what gets centered using focal point crop or smart crop. With the resize fit mode set to crop (fit=crop), you can only specify the width (w) and height (h) parameters in pixels, not percentages.
Fit mode
Description
Aspect ratio
Example
clip
Default mode. Resizes the image to fit within the width and height boundaries without cropping or distorting the image.
The resulting image will match one of the constraining dimensions, while the other dimension is altered to maintain the same aspect ratio as the input image.
/on-roasts-1080px.jpg?w=600&h=500&fit=clip tries to resize the image to 600 × 500 px with a fit mode of clip.
scale
Scales the image to fit the constraining dimensions exactly.
The resulting image will fill the dimensions and will not maintain the aspect ratio of the input image.
Example: Resizing the original image coffe-cup.jpg to 300 × 100 using different resize fit modes.
By default, the entire image is used as the area for processing. The rect parameter selects a sub-region of the source image to use for processing.
The value for rect is four relative values representing the starting coordinates of x and y and the width (w) and height (h), all separated by commas. All the values must be greater than or equal to 0.
If any of the values are represented by an integer greater than or equal to 1, they are interpreted in pixels. If the value is a float greater than 0 but less than 1, it's interpreted in percentages.
Value
Units
Description
Example
Integer
Pixels
A whole number between 0 and 8192.
/on-roasts-1080px.jpg?rect=0,0,700,466 selects a top-left region of the image for processing.
Float
Percentage
A floating-point number greater than 0 but less than 1.
/on-roasts-1080px.jpg?rect=1,1,0.7,0.7 selects a top-left region of the image for processing.
Example: Choosing a sub-region of the source image (604 × 403). Only the rectangle region of the image shown on the right will be used for processing.
By default, using fit=crop alone centers the crop on the image. You can further control the area to focus on with focal point crop and smart crop. Focal point crop allows you to manually specify crop coordinates (fp-x, fp-y) and zoom level (fp-z) for precise control, while smart crop uses AI to automatically detect the most relevant subject.
Smart crop works best when:
You're processing many images and need automation.
The main subject is visually prominent.
You can accept some variation in results.
Focal point crop is more suitable when:
You need guaranteed control over what stays in frame.
The important content isn't the most visually dominant element.
Precision matters more than automation speed.
You cannot combine focal point crop and smart crop in a single request.
You can use the focal point crop parameter to intentionally art-direct a point of interest when cropping an image. As the image is resized and cropped, the focal point determines which areas are centered and within the image's bounds and what gets cropped out.
The focal point crop consists of the horizontal (fp-x), vertical (fp-y), and zoom (fp-z) parameters.
To zoom in on an image, the fp-z value needs to be greater than 1, with fp-z=1 representing the original size of the image. Every full step is then the equivalent of a 100% zoom, e.g., fp-z=2 is the same as viewing the image at 200%.
The focal point crop consists of the following parameters:
fp-x – The horizontal value of the focal point of an image. Must be a float between 0.0 and 1.0, inclusive. The default value is 0.5 – the center of the image.
fp-y – The vertical value of the focal point of an image. Must be a float between 0.0 and 1.0, inclusive. The default value is 0.5 – the center of the image.
fp-z – The zoom value of a focal point of an image. The default value is 1. The maximum value depends on the quality of the image, but we recommend using a float value between 1 and 100.
The top-left corner of an image is represented by fp-x=0.0 and fp-y=0.0. When the fp-x and fp-y values are not set, the API uses the default value of 0.5, representing the image's center. For example, /on-roasts-1080px.jpg?fit=crop&crop=focalpoint&fp-z=3 zooms in on the center of the image by 300%.
Example: Choosing a focal point with the fp-x and fp-y values and then using a 200% zoom with the fp-z=2 results in the image on the right.
You can use the smart crop parameter to automatically detect the most prominent subject or area of interest in an image when cropping, including faces. The smart crop uses AI to detect the focal point, eliminating the need to manually specify coordinates.
The smart crop consists of the following required parameters:
w – The target width of the cropped image in pixels. Must be a positive integer value.
h – The target height of the cropped image in pixels. Must be a positive integer value.
fit=crop – Specifies the crop fit mode.
crop=smart – Activates the AI-powered smart crop functionality.
Example: /office.jpg?w=200&h=400&fit=crop&crop=smart automatically detects the most relevant subject in the image and crops it to 200 x 400 pixels.
You can use the background color (bg) parameter to fill in any transparent areas in your image with a color of your choice.
The bg parameter supports these color value formats:
a 3-digit hexadecimal value (RGB)
a 4-digit hexadecimal value (ARGB)
a 6-digit hexadecimal value (RRGGBB)
an 8-digit hexadecimal value (AARRGGBB)
"R", "G", and "B" represent red, green, and blue color values. The "A" in the 4- or 8-digit hex values represents the color's alpha transparency.
The 3- and 4-digit formats are shortened versions of the 6- and 8-digit formats. You can use them when the first and second (third and fourth, etc.) characters of the code are the same: CC00DD can be shortened to C0D while CC01DD cannot.
For example, here's Mozilla Firefox logo with a programmatically added semi-transparent bright-green background: https://assets-us-01.kc-usercontent.com/40886722-9bde-00cb-08d7-36b32d4a6d7b/407af963-ca0e-45b4-8273-5723415f153f/firefox_logo.png?bg=6600ff00.
Convert an image to a specific format and set the output quality by choosing the compression strength.
You can use the format (fm) parameter to convert the source image from one format to another. Valid values for the fm parameter are gif, png, png8, jpg, pjpg, and webp. For example, when converting a jpg image to a png format, the request would look like this: /on-roasts-1080px.jpg?fm=png.
The source image can be any of the following image formats: gif, png, jpeg, and webp.
Value
Description
Quality parameter (q)
gif
Graphics Interchange Format
No
png
Portable Network Graphics
No
png8
Portable Network Graphics palette variant with 8-bit transparency and 256 colors
No
The quality (q) parameter enables control over the compression level for lossy file-formatted images (jpg, pjpg, webp). The value is an integer between 0 and 100. If not set, quality defaults to 85.
A lower number represents a lower-quality output image with a smaller file size and vice-versa. For example, /on-roasts-1080px.jpg?q=20 will lower the quality of the output image as well as its file size.
The quality parameter (q) is ignored for all formats that are not lossy because lossless formats always retain the original image quality. Similarly, the quality parameter is ignored for WebP output when the lossless parameter is set to true or 1.
The lossless parameter enables the delivery of lossless images in the WebP format. Valid values are 1 and 0 or true and false. The default value is unset, meaning neither true nor false.
If you don’t specify the lossless parameter explicitly, the image transformation API automatically sets lossless to true or false based on the input file format. By default, the API uses lossy compression for lossy file formats like JPG and lossless compression for formats like PNG.
For example, using /on-roasts-1080px.jpg?fm=webp&lossless=1 converts the JPEG image to the WebP format using lossless compression.
When the lossless parameter is set to true or 1, the quality parameter (q) is ignored.
Automatic delivery of WebP format images can be enabled by using the auto=format parameter. This overrides the format parameter in browsers that support WebP.
If auto=format is set and the browser does not support the WebP format, the Delivery API falls back to any format specified by the fm parameter and finally the source image type. For example, the /on-roasts-1080px.jpg?fm=png&auto=format request is evaluated as follows: If the web browser supports the WebP format, the image is converted to webp. If the WebP format is not supported, the Delivery API tries to convert the image to png format. If this also fails, the image stays in its original format, jpg.
/on-roasts-1080px.jpg?w=1200&h=150&fit=scale scales the image to 1200 × 150 px, wider than the original.
crop
Resizes the image to fill the width and height dimensions and crops any excess image data.
The resulting image will match the width and height constraints without distorting the image.
/on-roasts-1080px.jpg?w=300&h=150&fit=crop crops the image to 300 px in width and 150 px in height.
Transform images outside content itemsThe image doesn't need to be added to a content item to be used for transformation.
DependenciesFor the device pixel ratio parameter to work, you need to specify the width (w), height (h), or both.
DependenciesFor the fit parameter to work, you need to specify the width (w), height (h), or both. The resize fit mode set to crop (fit=crop) is incompatible with the source rectangle region (rect) method.
DependenciesThe focal point crop parameter must always be used with the fit=crop and crop=focalpoint parameters. The focal point crop is incompatible with the source rectangle region (rect) method.
DependenciesThe smart crop parameter must always be used with the fit=crop parameter and both the width (w) and height (h) parameters. Smart crop is incompatible with the source rectangle region (rect) method and cannot be combined with focal point crop parameters (fp-x, fp-y, fp-z).
GIF images aren't converted to WebP even when requested. When you use fm=webp on a GIF image, you'll get the original GIF image.Converting GIF to other formats works but if your GIF is animated, you'll lose the animation.
DependenciesThe quality parameter only works with the JPG, PJPG, and WebP input image formats.
DependenciesThe lossless parameter needs to be used with the format set to WebP (fm=webp).
Martina Farkasova, Jan Cerman
21 minutes
Image transformation (API)
. All rights reserved.