Skip to main content
Go to homepage
Tips & tricks

Developing with the Contensis Image API

Jon MaskreyUX engineer
1 min read04 July 2019

The 11.3 release has been largely based around improving the experience of using images in Contensis. Content authors can now easily upload, crop, and publish images. Admins can restrict the size and orientation these are delivered at. But what about developers?

Introducing the new Image API

Our new Image API gives developers more control over how images are rendered to the front-end, no matter the device. This API improves massively over the previous cached image handler, and can deliver images a fraction of their original size but without a significant loss of quality.

The Image API applies transformations in real time and caches the results for fast delivery.

It allows you to:

  • Resize and crop
  • Rotate and flip
  • Apply grayscale and blur effects
  • Change the format of the image
  • Set the level of compression

These are applied by adding a query string to the URI of the image. For example:

Combining the Image API with the new features of the image editor in Contensis gives you much more control over how images are displayed. You can make full use of the srcset attribute to deliver the appropriate size and resolution image to any device. Authors can select different creative crops of the same image to be displayed on desktop and mobile.


You resize an image by appending the width or height (or both) parameter to the image query string. This allows an author to upload a large high-resolution image while giving the developer an easy way to serve it at an appropriate size for the device or situation in which it's displayed.

See the Pen Image API - resize by Zengenti (@zengenti) on CodePen.


The crop parameter controls how the image is cropped, scaled, and aligned. Crops can be from top, right, bottom, centre or set manually with specific coordinates. More details can be found in the Image API crop documentation.

See the Pen Image API - crop by Zengenti (@zengenti) on CodePen.

Rotate and flip

You can rotate images by using the rotate parameter with the value set to an integer between 0 and 359. You can also flip an image by using the flip parameter with a value of horizontal, vertical, or both. Perfect for reversing an image to make it better fit a layout.

See the Pen Image API - rotate and flip by Zengenti (@zengenti) on CodePen.

Grayscale and blur

Images can be made grayscale by using the effect parameter with a value of grayscale. Blur can be applied by setting the blur parameter to a value between 1-100.

See the Pen Image API - grayscale and blur by Zengenti (@zengenti) on CodePen.


The format parameter allows the conversion of one image format to another. Allowed values are jpgpng, and webp.

See the Pen Image API - format by Zengenti (@zengenti) on CodePen.


Image quality is controlled by the quality parameter. A value between 0 and 100 sets the compression level.

See the Pen


Images served with the image API are set to be cached for a year, meaning they don’t have to be re-downloaded every time the user visits the site. Contensis adds a unique hash to the file name so if the image changes the browser will not serve the old one. Read more about Image API caching.

Advanced examples of using the Image API

We designed the Image API to support a number of modern development techniques.

Automatically setting an image to resize using srcset

Even if an image has been saved in Contensis at full size, it can be processed and delivered to the browser at the optimum size for the device or connection speed.

Using the srcset attribute, an image can be displayed at different sizes depending on the device size and resolution.

See the Pen

Creating an image component and using the picture element

Using a simple component in Contensis, you can allow an editor to create 3 different crops of the same image and use the picture element to display them. This is especially powerful as it allows an editor to artistically crop an image to best fit the device or aspect ratio it’s displayed in.

In your code, you can then use the picture element to display a different image depending on the available space. Here’s an example:

See the Pen Responsive Images - Art Direction by Zengenti (@zengenti) on CodePen.

Using a modern web format

WebP is a modern image format developed by Google. WebP images are generally around 25-34% smaller than a comparable JPEG image. This means they load quicker and use less data than older formats.

WebP is a relatively new format and isn’t supported by all browsers (WebP compatibility chart). The Image API detects if the browser is compatible and will serve a standard JPEG if it isn’t.

See the Pen Image API - webP by Zengenti (@zengenti) on CodePen.

Try it now!

The Image API is available in Contensis 11.3 and higher and can be easily applied to any image served by Contensis. Just add the query string to any image in your templates, Razor views, or React apps to serve higher quality, better optimised images in a modern format.

Check out the full Image API documentation.

Jon MaskreyUX engineer

As a UX designer and front-end developer, Jon works with the Contensis product team to build a great user experience that is accessible, easy to use and fast. He has extensive experience in front-end development and Contensis integration.

Ready to get started?

Contensis supports modern development practices. And it works with your preferred tools – from VS Code to Git. Browse the documentation to get started.

Request a demo