Image transformation API

Overview

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.

Input and output formats

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. You can set up your content types to only accept adjustable image formats, ensuring content creators use only the supported image files. 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.

Working with the image URLs

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.

Size

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

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. 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

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. 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

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.

Resize fit mode

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. 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.

Example: Resizing the original image coffe-cup.jpg to 300 × 100 using different resize fit modes.

Source rectangle region

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. 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.

Focal point crop

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.

Background color

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.

Format

Convert an image to a specific format and set the output quality by choosing the compression strength.

Format parameter

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.

Quality parameter

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.

Lossless parameter

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 format selection

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.