Images API
Introduction
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": "//images.contentful.com/yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc060607df0f3baef/quwowooybuqbl6ntboz3.jpg"
}
}
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
https://images.contentful.comReference
Retrieval
Image
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
Resizing & cropping
Specify width & height
Choose a custom width and height for the image.
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 thefparameter 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.A combination of the above like
bottom_right.faceorfacesto 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
rdefining 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.