Image transformation

Overview

By adding parameters to your image URL, 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.

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.

JSON
"image": {
  "type": "asset",
  "name": "Image",
  "value": [
    {
      "name": "how-to-insert-images.jpg",
      "description": "Person sitting on a wooden pier",
      "type": "image/jpeg",
      "size": 1680096,
      # Absolute image URL
      "url": "https://assets-us-01.kc-usercontent.com:443/8d20758c-d74c-4f59-ae04-ee928c0816b7/6e38c039-ad00-47f3-a584-26252827655a/daylight.jpg",
      "width": 4000,
      "height": 2525,
    }
  ]
}
"image": {
  "type": "asset",
  "name": "Image",
  "value": [
    {
      "name": "how-to-insert-images.jpg",
      "description": "Person sitting on a wooden pier",
      "type": "image/jpeg",
      "size": 1680096,
      # Absolute image URL
      "url": "https://assets-us-01.kc-usercontent.com:443/8d20758c-d74c-4f59-ae04-ee928c0816b7/6e38c039-ad00-47f3-a584-26252827655a/daylight.jpg",
      "width": 4000,
      "height": 2525,
    }
  ]
}

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.

JSON
"body": {
  "type": "rich_text",
  "name": "Body",
  "images": {
    "04e4957f-08ed-4329-9c7a-0d7b7c6f3590": {
      "image_id": "04e4957f-08ed-4329-9c7a-0d7b7c6f3590",
      "description": "Person sitting on a wooden pier",
      "url": "https://assets-us-01.kc-usercontent.com:443/8d20758c-d74c-4f59-ae04-ee928c0816b7/6e38c039-ad00-47f3-a584-26252827655a/daylight.jpg",
      "width": 4000,
      "height": 2525
    }
  },
  "links": {},
  "modular_content": [],
  "value": "<figure data-asset-id=\"04e4957f-08ed-4329-9c7a-0d7b7c6f3590\" data-image-id=\"04e4957f-08ed-4329-9c7a-0d7b7c6f3590\"><img src=\"https://assets-us-01.kc-usercontent.com:443/8d20758c-d74c-4f59-ae04-ee928c0816b7/6e38c039-ad00-47f3-a584-26252827655a/daylight.jpg\" data-asset-id=\"04e4957f-08ed-4329-9c7a-0d7b7c6f3590\" data-image-id=\"04e4957f-08ed-4329-9c7a-0d7b7c6f3590\" alt=\"Person sitting on a wooden pier\"></figure>\n"
}
"body": {
  "type": "rich_text",
  "name": "Body",
  "images": {
    "04e4957f-08ed-4329-9c7a-0d7b7c6f3590": {
      "image_id": "04e4957f-08ed-4329-9c7a-0d7b7c6f3590",
      "description": "Person sitting on a wooden pier",
      "url": "https://assets-us-01.kc-usercontent.com:443/8d20758c-d74c-4f59-ae04-ee928c0816b7/6e38c039-ad00-47f3-a584-26252827655a/daylight.jpg",
      "width": 4000,
      "height": 2525
    }
  },
  "links": {},
  "modular_content": [],
  "value": "<figure data-asset-id=\"04e4957f-08ed-4329-9c7a-0d7b7c6f3590\" data-image-id=\"04e4957f-08ed-4329-9c7a-0d7b7c6f3590\"><img src=\"https://assets-us-01.kc-usercontent.com:443/8d20758c-d74c-4f59-ae04-ee928c0816b7/6e38c039-ad00-47f3-a584-26252827655a/daylight.jpg\" data-asset-id=\"04e4957f-08ed-4329-9c7a-0d7b7c6f3590\" data-image-id=\"04e4957f-08ed-4329-9c7a-0d7b7c6f3590\" alt=\"Person sitting on a wooden pier\"></figure>\n"
}

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.

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.

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.

Dependencies: You must specify width, height, or both for this parameter to work.

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

The fit parameter controls how the output image is constrained within the provided size values after resizing. Valid values are clip, scale, and crop. The default value is clip.

Dependencies: You must specify width (w), height (h), or both for this parameter to work. The resize fit mode set to crop (fit=crop) is incompatible with the source rectangle region (rect) method.

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.

When using the default clip 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 be 100 × 100 will result in an image that is 100 × 67 because the aspect ratio of the original image is maintained.

When using the scale fit mode, the image is scaled and distorted to fit dimensions. When resizing the image to wider than the original, the image is scaled horizontally to fit dimensions. Similarly, when resizing the image to taller than the original, the image is scaled vertically to fit dimensions.

The crop fit mode crops the excess image data while keeping the image centered. This means that the center of the output image corresponds with the center of the input image.

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.

Dependencies: The rect parameter is incompatible with the focal point crop (crop=focalpoint) method and resize fit mode set to crop (fit=crop).

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 then resized and cropped, the focal point determines which areas are centered and within bounds of the image, and what gets cropped out.

Dependencies: The focal point crop parameter must always be used with the fit=crop and crop=focalpoint parameters. Focal point crop is incompatible with the source rectangle region (rect) method.

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

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 Delivery API uses the default value of 0.5 that represents the center of the image. 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/ad858591-7c5b-00e9-52c1-796f3aebc535/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. A lower number represents a lower-quality output image with 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.

If no quality parameter is present, the output image will be returned with a default value of 85.

Dependencies: Quality parameter only works with the JPG, PJPG, and WebP input image formats.

Lossless parameter

The lossless parameter enables delivery of lossless images in the WebP format. Valid values are 1 and 0 or true and false. The default value is false, meaning a lossy compression. For example, /on-roasts-1080px.jpg?fm=webp&lossless=1 converts the JPEG image to the WebP format using lossless compression.

When unset or set to an invalid value, lossless defaults to false.

When the lossless parameter is set to true or 1, the quality parameter (q) is ignored.

Dependencies: Lossless parameter needs to be used with the fm parameter set to the WebP format.

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 fails as well, the image stays in its original format which is jpg.