Skip navigation

Image transformation

Image transformation is a real-time image manipulation and optimization feature of the Delivery API that speeds up image delivery. As Kentico Kontent caches the results of image transformation, you can retrieve the adjusted images even faster the next time you need them.

Table of contents

    Overview

    Input and output formats

    In order to transform images stored in Kentico Kontent, the source images need to be in any of the following image formats:

    • jpeg, png, gif, and webp

    You can also set the limitations in content types to only accept these adjustable image formats.

    The optimized output image can be any of the following image formats:

    • jpg, pjpg, png, png8, gif, and webp

    The format parameter allows you to convert the image by choosing the output format.

    By adding parameters to your image URL, you can enhance, resize and crop images, compress them, or change the format for better performance. These operations can be applied programmatically in real time, removing the need to batch process or maintain multiple copies of an image to match device breakpoints.

    NameParameterNotes
    Size

        WidthwResize the width of the image.
        HeighthResize the height of the image.
        Device pixel ratiodprServe correctly sized images for devices that expose a device pixel ratio.
        Resize fit modefitSet how the image will fit within the size bounds provided.
        Source rectangle regionrectSelect a sub-region of the source image to use for processing.
    Focal point crop

        Focal point cropfp-x, fp-y, fp-zChoose the point of interest of your image when cropping the image.
    Background color

        Background colorbgFill in transparent areas of the image with the specified color.
    Format

        Output formatfmSpecify the output format to convert the image to.
        QualityqOptimize the image to the given compression level for lossy file formatted images.
        LosslesslosslessEnable delivery of lossless images in formats that support lossless compression.
        Automatic format selectionautoAutomatic delivery of WebP format images.

    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. Note that the image doesn't need to be added to a content item to be used for transformation.

    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
    "teaser_image": { "type": "asset", "name": "Teaser image", "value": [ { "name": "coffee-beverages-explained-1080px.jpg", "type": "image/jpeg", "size": "90895", "description": null, # Absolute image URL "url": "https://assets-us-01.kc-usercontent.com/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/e700596b-03b0-4cee-ac5c-9212762c027a/coffee-beverages-explained-1080px.jpg" } ] }
    "teaser_image": { "type": "asset", "name": "Teaser image", "value": [ { "name": "coffee-beverages-explained-1080px.jpg", "type": "image/jpeg", "size": "90895", "description": null, # Absolute image URL "url": "https://assets-us-01.kc-usercontent.com/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/e700596b-03b0-4cee-ac5c-9212762c027a/coffee-beverages-explained-1080px.jpg" } ] }

    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
    "description": { "type": "rich_text", "name": "Description", "images": { "14mio": { "image_id": "14mio", "description": "Roasting coffee beans", # Absolute image URL "url": "https://assets-us-01.kc-usercontent.com/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/237362b4-5f2b-480e-a1d3-0ad5a6d5f8bd/roaster.jpg" } }, "links": { "f4b3fc05-e988-4dae-9ac1-a94aba566474": { "type": "article", "codename": "on_roasts", "url_slug": "" } }, "modular_content": [ "coffee_processing_techniques" ], # Absolute image URL in the <img> tag "value": "<p>We operate our own roasteries, one on every continent we cover, from where we distribute right to the shops. This allows you to experience every cup as if you were right at the very farm it originated from. To achieve this, we use a refurbished 1920s Probat coffee roasters.</p>\n<figure data-image-id=\"14mio\"><img src=\"https://assets-us-01.kc-usercontent.com/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/237362b4-5f2b-480e-a1d3-0ad5a6d5f8bd/roaster.jpg\" alt=\"Roasting coffee beans\" data-image-id=\"14mio\"></figure><p>We know that roasting is something you must keep on constantly perfecting. Each coffee requires a different roast to get the aroma and taste just right. That’s why our experts fine tune the way we <a data-item-id=\"f4b3fc05-e988-4dae-9ac1-a94aba566474\" href=\"\">roast coffees</a> every day. It’s a constant struggle.</p><object type=\"application/kenticocloud\" data-type=\"item\" data-codename=\"coffee_processing_techniques\"></object>" }
    "description": { "type": "rich_text", "name": "Description", "images": { "14mio": { "image_id": "14mio", "description": "Roasting coffee beans", # Absolute image URL "url": "https://assets-us-01.kc-usercontent.com/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/237362b4-5f2b-480e-a1d3-0ad5a6d5f8bd/roaster.jpg" } }, "links": { "f4b3fc05-e988-4dae-9ac1-a94aba566474": { "type": "article", "codename": "on_roasts", "url_slug": "" } }, "modular_content": [ "coffee_processing_techniques" ], # Absolute image URL in the <img> tag "value": "<p>We operate our own roasteries, one on every continent we cover, from where we distribute right to the shops. This allows you to experience every cup as if you were right at the very farm it originated from. To achieve this, we use a refurbished 1920s Probat coffee roasters.</p>\n<figure data-image-id=\"14mio\"><img src=\"https://assets-us-01.kc-usercontent.com/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/237362b4-5f2b-480e-a1d3-0ad5a6d5f8bd/roaster.jpg\" alt=\"Roasting coffee beans\" data-image-id=\"14mio\"></figure><p>We know that roasting is something you must keep on constantly perfecting. Each coffee requires a different roast to get the aroma and taste just right. That’s why our experts fine tune the way we <a data-item-id=\"f4b3fc05-e988-4dae-9ac1-a94aba566474\" href=\"\">roast coffees</a> every day. It’s a constant struggle.</p><object type=\"application/kenticocloud\" data-type=\"item\" data-codename=\"coffee_processing_techniques\"></object>" }

    Size

    Size parameters allow you 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.

    See also the tutorial on Optimizing images for web where the size parameters are used in a real-world scenario.

    Image width

    Image width represents the width of the output image. The w parameter allows you 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.

    ValueUnitsDescriptionExample
    IntegerPixelsA whole number between 1 and 8192./on-roasts-1080px.jpg?w=300 changes image width to 300 px.
    FloatPercentageA 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.

    Note: It is not possible to upscale an image. When using a width parameter 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. The h parameter allows you 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.

    ValueUnitsDescriptionExample
    IntegerPixelsA whole number between 1 and 8192./on-roasts-1080px.jpg?h=300 changes image height to 300 px.
    FloatPercentageA 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.

    Note: It is not possible to do an upscale of an 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

    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.

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

    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.

    Note: 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 modeDescriptionAspect ratioExample
    clipDefault 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.
    scaleScales 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./on-roasts-1080px.jpg?w=1200&h=150&fit=scale scales the image to 1200 × 150 px, wider than the original.
    cropResizes 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.

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

    Different fit modes used to resize the image to 300x100.

    Resize fit modes used to resize the image to 300x100.

    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.

    ValueUnitsDescriptionExample
    IntegerPixelsA whole number between 1 and 8192./on-roasts-1080px.jpg?rect=1,1,700,466 selects a top-left region of the image for processing.
    FloatPercentageA 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.

    Choosing a rectangle sub-region of the source image for processing.

    Source rectangle region: /coffee-cup.jpg?rect=115,230,0.4,0.4

    Focal point crop

    Focal point crop allows you 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.
    • 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.
    • 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.

    When the fp-x and fp-y values are not set, the Delivery API uses the default value of 0.5, which 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.

    Example of how focal point determines which areas of the image are centered and within bounds of the image, and what gets cropped out.

    Focal point crop: /coffee-cup.jpg?fit=crop&crop=focalpoint&fp-x=0.4&fp-y=0.8&fp-z=2

    Background color

    The background color (bg) parameter allows you 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 is an image with programmatically added light-blue semi-transparent background: https://assets-us-01.kc-usercontent.com/14372844-0a5d-434a-8423-605b8a631623/d3160fb7-d01f-423e-b07b-eb250f2c534b/kentico.png?bg=7A0099EE

    Format

    Convert the image by choosing the output format and the quality of the compression.

    Format parameter

    The format (fm) parameter enables the source image to be converted from one encoded 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.

    ValueDescriptionQuality parameter (q)
    gifGraphics Interchange FormatNo
    pngPortable Network GraphicsNo
    png8Portable Network Graphics palette variant with 8-bit transparency and 256 colorsNo
    jpgJPEGYes
    pjpgProgressive JPEGYes
    webpWebPYes

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

    If no quality parameter is present, the output image will be returned with a default value of 85. Note that the quality parameter will be ignored by all output formats that are not lossy.

    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 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 WebP format via lossless compression.

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

    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 will override 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 will fall 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 will be evaluated as follows: If the web browser supports the WebP format, the image will be converted to webp. If the WebP format is not supported, the Delivery API will try to convert the image to png format. If this fails as well, the image will stay in its original format which is jpg.