Image Delivery API

Introduction

Contentstack is a headless, API-first content management system (CMS) that provides everything you need to power your web or mobile properties. To learn more about Contentstack, visit our website or refer to our documentation site to understand what we do.

This document is a detailed reference to Contentstack’s Image Delivery API and covers the parameters that you can add to the URL to retrieve images. The Image Delivery API is used to retrieve, manipulate and/or convert image files of your Contentstack account and deliver it to your web or mobile properties.

Supported input formats

  • JPEG
  • PNG
  • WEBP
  • GIF

Supported output formats

  • JPEG (baseline & progressive)
  • PNG
  • WEBP (lossy & lossless)
  • GIF

If you are looking for APIs to deliver content to your web or mobile properties, use our Content Delivery API, and to manage content, you should use the Content Management API.

Reference

Automate Optimization

Auto

The auto parameter lets you enable the functionality that automates certain image optimization features. As of now, there is only one possible value for this field, i.e., webp. When the auto parameter is set to webp, it enables WebP image support. WebP images have higher compression rate with minimum loss of quality.

Enable auto optimization

Try

WebP images are not supported by all browsers. If the auto parameter is used along with the format parameter, the former overrides the latter in browsers that support WebP format. In browsers that do not support WebP format, the format parameter will be applied.

Enable auto optimization and encode to progressive JPEG

Try

Additional Notes
  1. WEBP format is not supported by all browsers.
  2. If the format parameter is used with this parameter, the format parameter will be ignored in browsers that support WEBP format.

Control Quality

Quality

The quality parameter lets you control the compression level of images that have Lossy file format. The value for this parameters can be entered in any whole number (taken as a percentage) between 1 and 100. The lower the number, the smaller will be file size and lower quality, and vice versa. If the source image file is not of Lossy file format, this parameter will be ignored.

Change Quality.png

Quality

Try

Additional Notes
  1. Lower the value, lower will be the quality of the output image, and vice versa.
  2. The quality parameter is not applicable for the image types (GIF and PNG) that are not lossy.
  3. When only the quality parameter is specified, and if the output image is larger than the actual image, the original image will be returned.

Convert Formats

Format

The format parameter lets you converts a given image from one format to another. The formats that the source image can be converted to are gif, png, jpg (for JPEG), pjpg (for Progressive JPEG), webp, webpll (Loseless), and webply (Lossy).

Of the formats mentioned above, JPEG, Progressive JPEG, and WEBP (Lossy) support the quality parameter.

Let’s try converting an image to GIF format.

Convert to GIF

Try

Images can also be easily converted to PNG format.

Convert to PNG

Try

JPEG is one of most common image formats. To convert an image file to JPEG, use the API request given below.

Convert to JPEG

Try

A Progressive JPEG is an image file created using a compression method that displays higher detail in progression. When a Progressive JPEG image is loaded, it first loads a lower-quality pixelated version, and then gradually increases in quality and detail. Due to this, Progressive JPEG files (or its lower-quality version) loads faster than the baseline JPEG files.

Convert to Progressive JPEG

Try

WEBP images are usually lower in size and have good quality. The WEBP images files are currently supported only in Google Chrome, Opera, and Android browsers.

Convert to WEBP

Try

WEBP images are of two types: Lossy and Lossless. In the former, the data lost while compression cannot be reversed, hence the quality can be lower. While with the later format, no data is lost while compression and quality remains the same even after compression. 

Let’s try converting to WEBP Lossy first.

Convert to WEBP Lossy

Try

Now let’s convert an image to WEBP Lossless format.

Convert to WEBP Lossless

Try

Additional Notes
  1. The quality parameter can used only with JPEG, Progressive JPEG, or WEBP (Lossy) image types.
  2. The WEBP image type is supported only by Google Chrome, Opera, and Android browsers.
  3. GIF transcoding is not supported as of now.
  4. If 'auto=webp' is used with the format parameter, the browsers that support the WEBP format will ignore the format parameter.

Resize Images

Width

The width parameter lets you dynamically resize the width of the output image by specifying pixels or percentage values. To specify pixel width, use any positive integer between 1 and 8192. For percentage width, use any value between 0.0 and 0.99. To get image width of more than 99 percent, use a value above 99 and append a p parameter to the value. For example, for image width of 300 percent, use width=300p.

The width parameter will automatically adjust the height of the image using the aspect ratio of the image. If the height parameter is specified, the given value will be used. And if both the height and the width parameters are not specified, the dimensions of the input image will be used.

In case the dimensions specified for the output image is greater than the dimensions of the input image, the image will be upscaled. You can disable upscaling of the image by using the disable=upscale parameter. 

Resize image width.png

Resize image width

Try

Additional Notes
  1. In case the dimensions specified for the output image is greater than the dimensions of the input image, the image will be upscaled.
  2. To disable upscaling, use the disable=upscale parameter.
  3. To specify a width more than 100% of the original image, use the p parameter. For example, to get a width of 250%, use width=250p.

Height

The height parameter lets you dynamically resize the height of the output image by specifying pixels or percentage values. To specify pixel height, use any positive integer between 1 and 8192. For percentage height, use any value between 0.0 and 0.99. To get image height of more than 99 percent, use a value above 99 and append a p parameter to the value. For example, for image height of 300 percent, use height=300p.

The height parameter will automatically adjust the width of the image using the aspect ratio of the image. If the width parameter is specified, the given value will be used. And if both the height and the width parameters are not specified, the dimensions of the input image will be used.

In case the dimensions specified for the output image is greater than the dimensions of the input image, the image will be upscaled. You can disable upscaling of the image by using the disable=upscale parameter.

Resize image height

Try

Additional Notes
  1. In case the dimensions specified for the output image is greater than the dimensions of the input image, the image will be upscaled.
  2. To disable upscaling, use the disable=upscale parameter.
  3. To specify a height of more than 100% of the original image, use the p parameter. For example, to get a height of 250%, use height=250p.

Disable

The disable parameter disables the functionality that is enabled by default. For instance, upscale is always enabled, in which the image is upscaled if the output image (by specifying the width or height) is bigger than the source image. To disable this feature, you can use the query ?disable=upscale. This ensures that even if the specified height or width is much bigger than the actual image, it will not be rendered disproportionately. 

As of now, there is only one value, i.e., upscale, that you can use with the disable parameter.

Disable upscaling of image

Try

To see this parameter in action, the height or width (or both) parameter should be used with it.

The fit parameter enables you to fit the given image properly within the specified height and width. You need to provide values for the height, width and fit parameters. The two available values for the fit parameter are bounds and crop.

Fit to bounds

If fit is set to bounds, it will constrain the given image into the specified height and width.

Fit to bounds

Try

Fit by cropping

If fit is set to crop, it will crop the given image to the defined height and width.

Fit by cropping

Try

Additional Notes
  1. The fit parameter requires both the height and the width parameters.

Crop Images

Crop

The crop parameter allows you to remove pixels from an image. You can crop an image by specifying the height and width in pixels or percentage value, or defining height and width in aspect ratio. You can also define a sub region (i.e., define the starting point for crop) before cropping the image, or you can offset the image on its X and Y axis (i.e., define the centre point of the crop) before cropping the image.

When simply cropping an image, use the query ?crop={width_value},{height_value} to crop the image from the center. The value can be in pixels (for example, ?crop=300,400) or in percentage (for example, ?crop=0.50,0.60). The width and height can also be specified in aspect ratio (for example, ?crop=1:2).

Crop by width and height.png

Crop by width and height

Try

You can set the X-axis and Y-axis position of the top left corner of the crop by using the query ?crop={width_value},{height_value},x{value},y{value}. This lets you define the starting point of the crop region. The x-axis value and y-axis value can be defined in pixels or percentage. An example of this would be ?crop=300,400,x150,y75 or ?crop=300,400,x0.50,y0.60.

Crop sub region.png

Crop sub region

Try

You can also set the horizontal and vertical offset of the crop region by using the query ?crop={width_value},{height_value},offset-x{value},offset-y{value}. This lets you define the centre point of the crop area. The x-axis offset value and y-axis offset value can be defined only in percentage. An example of this would be ?crop=300,400,offset-x0.45,offset-y0.75.

Crop and offset

Try

Additional Notes
  1. The x and y, or offset-x and offset-y parameters are not mandatory.
  2. The x and y, or offset-x and offset-y parameters can be used in any order. The only rule is that these parameters should come after the width parameter in the API request.
  3. If the x and y, or offset-x and offset-y parameters are not specified, the image will be cropped from the center.
  4. The x parameter can be used without y (and vice versa), and the offset-x parameter can be used without offset-y (and vice versa).

Fit Mode

This parameter enables you to fit the given image properly within the specified height and width. You need to provide values for the height, width and fit parameters. The two available values for the fit parameter are bounds and crop.

Fit to bounds

If fit is set to bounds, it will constrain the given image into the specified height and width.

Fit to bounds

Try

Fit by cropping

If fit is set to crop, it will crop the given image to the defined height and width.

Fit by cropping

Try

Additional Notes
  1. The fit parameter requires both the height and the width parameters.

Trim Images

Trim

The trim parameter lets you trim an image from the edges. This is especially useful for removing border or white spaces that the downloaded images usually come with. The value for this parameter can be given in pixels or percentage. 

You can specify values for top, right, bottom, and left edges of an image. For example, to trim the top edge by 25px, right edge by 50px, bottom edge by 75px and left edge by 100, using the query ?trim=25,50,75,100.

You can also combine two or more values. For example, to trim the top edge by 25px, right edge by 50px, bottom edge by 75px and left edge by 50px, use the query ?trim=25,50,75. Similarly, to trim the top and bottom edge by 50px, and right and left by 100, use ?trim=50,100. To trim all edges by 50px, use ?trim=50.

Trim Small.png

Trim image

Try

Additional Notes
  1. CSS style shorthand values are also acceptable.

Reorient Images

Orientation

The orient parameter lets you control the cardinal orientation of the given image. Using this parameter, you can orient the image right or left, flip horizontally or vertically or both, and do a lot more. It can automatically correct the orientation of the image if the source image contains orientation details within its EXIF data (Exchangeable Image File Format).

You can use any of the following values for the orient parameter: 

  • 1 - Set image to default
  • 2 - Flip image horizontally
  • 3 - Flip image horizontally and vertically 
  • 4 - Flip image vertically
  • 5 - Flip image horizontally and then rotate 90 degrees towards left
  • 6 - Rotate image 90 degrees towards right
  • 7 - Flip image horizontally and then rotate 90 degrees towards right
  • 8 - Rotate image 90 degrees towards left

Let’s try to change the orientation of the image. Use the request given below to orient the image right.

Orient the image right

Try

Now let’s flip the image horizontally.

Flip.png

Flip the image horizontally

Try

You can also use a combination of the two example given above. So, in the following API request, the image will be flipped horizontally, and then orient it right.

Flip horizontally and orient right.png

Flip horizontally and orient right

Try

Additional Notes
  1. This parameter can automatically correct the orientation of the image if the source image contains orientation details within its EXIF data (Exchangeable Image File Format).

Overlay Settings

Overlay

The overlay parameter allows you to put one image on top of another. You need to specify the relative URL of the image as value for this parameter.

Overlay small.jpg

Overlay image

Try

Additional Notes
  1. By default, the cropping alignment will be middle, center. See overlay-align for more details.

Overlay Align

The overlay-align parameter lets you define the position of the overlay image. The acceptable values for this parameter are given below:

  • top: Align the overlay image to the top of the actual image 
  • bottom: Align the overlay image to the bottom of the actual image  
  • left: Align the overlay image to the left of the actual image 
  • right: Align the overlay image to the right of the actual image 
  • middle: Align the overlay image to the middle (vertically) of the actual image  
  • center: Align the overlay image to the center (horizontally) of the actual image 

You can also specify two values for this parameter, for example ?overlay-align=left,bottom. By default, the overlay alignment is set to middle,center.

Align overlay.png

Align overlay

Try

Overlay Repeat

The overlay-repeat parameter lets you define how the overlay image will be repeated on the given image. The three acceptable values for this parameter are given below:

  • x: Horizontal repetition
  • y: Vertical repetition
  • both: Horizontal and vertical repetition

Let’s use these different parameters to understand how they work. First, try the horizontal repetition of overlay image.

Overlay Repeat horizontally.png

Repeat overlay horizontally

Try

Let us now try how the vertical repetition of overlay image works.

Repeat overlay vertically.png

Repeat overlay vertically

Try

Now, let’s see what happens to an image when the vertical as well as horizontal repetition is enabled for the overlay image.

Repeat overlay vertically and horizontally.png

Repeat overlay vertically and horizontally

Try

Overlay Width

The overlay-width parameter lets you define the width of the overlay image. The value for this parameter can be set in pixels or percentage. For pixel value, use any whole number between 1 and 8192. For percentage value, use any decimal number between 0.0 and 0.99. When height is defined in percentage, it relative to the output image.

In order to set the overlay image width to more than 99%, use the p parameter along with the value, for example, ?overlay-width=300p. If the overlay image width exceeds the width of the image, the overlay image will be cropped.

Set overlay width

Try

Additional Notes
  1. When width is specified in percentage, the width is relative to the output image.
  2. To specify a width more than 100% of the original image, use the p parameter. For example, to get a width of 250%, use overlay-width=250p.
  3. If the overlay image used is larger than the actual image, the overlay image will be cropped to fit the actual image.

Overlay Height

The overlay-height parameter lets you define the height of the overlay image. The value for this parameter can be set in pixels or percentage. For pixel value, use any whole number between 1 and 8192. For percentage value, use any decimal number between 0.0 and 0.99. When height is defined in percentage, it relative to the output image.

In order to set the overlay image height to more than 99%, use the p parameter along with the value, for example, ?overlay-height=300p. If the overlay image height exceeds the height of the image, the overlay image will be cropped.

Set overlay height

Try

Additional Notes
  1. When height is specified in percentage, the height is relative to the output image.
  2. To specify a height more than 100% of the original image, use the p parameter. For example, to get a height of 250%, use overlay-height=250p.
  3. If the overlay image used is larger than the actual image, the overlay image will be cropped to fit the actual image.

Pad

This parameter lets you add extra pixels to the edges of an image. This is useful if you want to add whitespace or border to an image. The value for this parameter can be given in pixels or percentage. 

You can specify values for top, right, bottom, and left padding for an image. For example, to add padding to the top edge by 25px, right edge by 50px, bottom edge by 75px and left edge by 100, use the query ?pad=25,50,75,100.

You can also combine two or more values. For example, to add padding to the top edge by 25px, right edge by 50px, bottom edge by 75px and left edge by 50px, use the query ?pad=25,50,75. Similarly, to give padding to the top and bottom edge by 50px, and right and left by 100, use ?pad=50,100. To provide padding on all edges, use ?pad=50.

It is important to note that by default the pad parameter applies white background. If the given image contains transparent background, and the output image also has transparency, then transparent padding will be applied. 

Add padding

Try

To add a colored border, you need to use the bg-color parameter along with pad. For example, to add a red border, use the query ?pad=10&bg-color=FF0000. Also, note that if the canvas and pad parameters are used together, the pad parameter will be ignored.

Padding with BG.png

Add padding and background color

Try

Additional Notes
  1. By default, this parameter applies padding in white color.
  2. If the given image contains transparent background and the output image also has transparency, then transparent padding will be applied.
  3. CSS style shorthand values are also acceptable.
  4. If the pad and the canvas parameters are used together in the same request, the pad parameter will be ignored.

Background Color

The bg-color parameter lets you set a backgroud color for the given image. This is useful when applying padding or for replacing the transparent pixels of an image. There are three possible types of values for this parameter. 

The first type is the 3- or 6-digit hexadecimal value, for example ?bg-color=cccccc.

Change BG Color.png

Change background color using hexadecimal value

Try

The second type is the Red, Blue, Green value which defines the intensity of the corresponding color, with the value ranging anywhere between 0 and 255 for each. An example of this is ?bg-color=140,220,123. 

Change background color by Red, Blue, Green value

Try

And the last type is the Red, Blue, Green, Alpha value, which is an extension of the second type with an addition of the alpha element. The alpha value defines the transparency, with 0.0 being fully transparent and 1.0 being completely opaque. An example of this is ?bg-color=140,220,123,0.5.

Change background color by Red, Blue, Green, Alpha value

Try

Device Pixel Ratio

The dpr parameter lets you deliver images with appropriate size to devices that come with a defined device pixel ratio. The device pixel ratio of any device determines the screen resolution that its CSS would interpret. This ratio is the ratio between the physical pixels of the image and its logical pixels. 

For example, if the iPhone 6s has a device pixel ratio of 2, it means that the actual resolution is double the logical resolution. Different devices have different pixel ratios. This parameter, therefore, lets you render appropriately sized images to different devices. 

The value for this parameter could be a whole number (between 1 and 10000) or any decimal number (between 0.0 and 9999.9999...).

Device Pixel Ratio(2).png

Set device pixel ratio

Try

top-arrow