Images API


The Contentful Images API allows the retrieval and manipulation of image files referenced from assets.

The JSON representation of an asset in Contentful looks like this:

"fields": {
    "title": "Playsam Streamliner",
    "file": {
      "fileName": "quwowooybuqbl6ntboz3.jpg",
      "contentType": "image/jpg",
      "details": {
        "image": {
          "width": 600,
          "height": 446
        "size": 27187
      "url": "//"

This reference covers the parameters you can append to the URL specified in the file.url field to manipulate and convert images.

To upload images to Contentful, refer here.

Note: As per the Technical Limits specifications, size of an image uploaded must not exceed 20MB. Images exceeding the size limit are treated as assets and the transformation features offered by the API are not applicable.

Note: For EU data residency customers, the Base URL is

Basic API information

This is a read-only API




You can retrieve the original image. The URL is the same as in the asset's file.url field.

Retrieve an image

Changing formats

Image format

You can convert the image to a different format.

Possible values:

  • jpg

  • png

  • webp

  • gif

  • avif

The default is the original image format.

Retrieve an image

Progressive JPEGs

You can request a JPEG image as a progressive JPEG.

The progressive JPEG format stores multiple passes of an image in progressively higher detail. While a progressive image is loading, the viewer first sees a lower quality pixelated version, which gradually improves in detail, until the image is fully downloaded. This displays the image as early as possible in order to maintain the layout as designed.

Retrieve an image

8-bit PNGs

You can request a PNG image as a 8-bit PNG.

8-bit PNG images support up to 256 colors and weight less than the standard 24-bit PNG equivalent. The 8-bit PNG format is mostly used for simple images, such as icons or logos.

Retrieve an image


For images transformed into AVIF format, the image size limits as defined in Technical Limits apply. Additionally, there is a 9 Megapixel limit on the size of the source image. The limit applies to all service tiers (see Technical Limits).

Resizing & cropping

Specify width & height

You can resize the image to the desired width and height. The maximum allowed value is 4000 pixels. The default is the original image width and height.

Retrieve an image

Change the resizing behavior

By default, images are resized to fit into the specified dimensions. You can request a different behavior using the fit parameter.

Possible values:

  • pad: Resize the image to the specified dimensions, padding the image if needed.

  • fill: Resize the image to the specified dimensions, cropping the image if needed.

  • scale: Resize the image to the specified dimensions, changing the original aspect ratio if needed.

  • crop: Crop a part of the original image to fit into the specified dimensions.

  • thumb: Create a thumbnail from the image.

pad behavior uses background color as padding color.

Retrieve an image

Specify focus area

You can choose the focus area for resizing when using fit type pad, fill, crop or thumb. Focus area has no effect on the default or scale fit type.

Possible values:

  • center, top, right, left, bottom.

  • top_right, top_left, bottom_right, bottom_left.

  • face for the largest face detected.

  • faces for all the faces detected.

The default is center.

Retrieve an image

Crop rounded corners & circle/elipsis

You can add rounded corners to your image or crop to a circle/ellipse.

Possible values:

  • The size of the corner radius in pixels.

  • max keyword for a full circle/ellipse.

The default is 0.

Rounded corners use background color as padding color, unless the format is jpg and resizing behavior is pad, then default to white.

Retrieve an image

Image manipulation


You can alter the quality of the image, expressed as a percentage value between 1 and 100. Quality value is only ignored for 8-bit PNGs.

Retrieve an image

Background color

You can choose the background color when using corner radius or the pad fit type. It accepts RGB values such as rgb:9090ff. The default is white for JEPGs and transparent for PNGs and WEBPs.

Retrieve an image


To delete an image, please refer to the CMA documentation on assets.