Images API
Introduction
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": "//images.ctfassets.net/yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc060607df0f3baef/quwowooybuqbl6ntboz3.jpg"
}
}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.
Basic API information
https://images.ctfassets.netReference
Retrieval
Image
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:
jpgpngwebpgifavif
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
AVIF
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.facefor the largest face detected.facesfor 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.
maxkeyword 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
Quality
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.