Images API


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

The JSON for an asset on 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 add to the URL specified in the file.url field to manipulate and convert images.

Basic API information

This is a read-only API




Retrieves an unmodified image. This is the same URL from an asset's file.url field, containing the token ids and image name required.

Retrieve an image

Changing formats

Image format

You can convert images to a different format, jpg, png or webp are supported. If no parameter is specified, you will receive your image in its original format.

Retrieve an image

JPEG quality

You can define the quality of JPEG images retrieved.

Retrieve an image

Progressive JPEGs

You can request JPEG images as progressive JPEGs.

The progressive JPEG format stores multiple passes of an image in progressively higher detail. When a progressive image is loading, the viewer will first see a lower quality pixelated version which will gradually improve in detail, until the image is fully downloaded. This is to display an image as early as possible to make the layout look as designed.

Retrieve an image

8-bit PNGs

You can request PNG images as 8-bit PNGs.

8-bit PNG images support up to 256 colors and weigh 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

Resizing & cropping

Specify width & height

Choose a custom width and height for the image.
The maximum allowed size is 4000px.

Retrieve an image

Change the resizing behavior

By default, images are resized to fit inside the bounding box given by w and h while retaining their aspect ratio. Using the fit parameter, you can change this behavior.

The possible values are:

  • pad: Same as the default resizing, but adds padding so that the generated image has the specified dimensions.

  • crop: Crop a part of the original image to match the specified size.

  • fill: Crop the image to the specified dimensions, if the original image is smaller than these dimensions, then the image will be upscaled.

  • thumb: When used in association with the f parameter below, creates a thumbnail from the image based on a focus area.

  • scale: Scale the image regardless of the original aspect ratio.

Retrieve an image

Specify focus area for resizing

Changes the focus area when using the fit type of thumb as outlined above.

Possible value:

  • top, right, left, bottom, center.

  • A combination of the above like bottom_right.

  • face or faces to focus the resizing via face detection.

Retrieve an image

Crop rounded corners & circle/elipsis

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

Possible values:

  • A float value r defining the corner radius.

Retrieve an image

Image manipulation

Background color

The background color when used with the pad fit type. It accepts RGB values such as rgb:9090ff and the default color is transparent.

Retrieve an image