Skip to main content
Contentstack MCP profile hub is in general availability!

Image transforms that surprise you

•
8 min read

The Image Delivery API turns one uploaded image into every size and format your site needs, with query parameters on the asset URL. Most parameters do exactly what their name says. A handful do something slightly different, and those are the ones that end up as "the hero image looks blurry on Safari" in your bug tracker.

This guide collects the transforms that surprise developers, explains why they behave the way they do, and gives a URL that works for each. Every parameter here comes from the Image Delivery API reference.

What you'll learn

  • How auto, format and quality interact

  • Why dpr, crop and fit need a width or height

  • What happens to SVGs, GIFs and very large images

  • Why a replaced image keeps showing the old file

  • How to serve images from your own domain

Symptoms

What you see

Where to look

Images look soft or blocky after adding auto=webp

Quality is not set

format=avif or auto=avif returns JPEG or PNG

AVIF fallback and size limit

Adding quality alone does not shrink the file

Quality on its own

dpr=2 does nothing

dpr needs a dimension

A crop looks stretched, or the request errors

Crop needs a dimension

A small image gets blurry when you set a large width

Upscaling is on by default

Transform parameters are ignored on an SVG or a GIF

SVG and GIF

The old image still shows after you replaced the file

Replaced assets

422 or an error instead of an image

Environment and publishing

Why it happens

Contentstack concept: An asset URL points at one stored file. Query parameters describe a transformation that the Image Delivery API runs on that file and caches at the CDN. The source file never changes.

The URL looks like this:

https://images.contentstack.io/v3/assets/{stack_api_key}/{asset_uid}/{file_uid}/{filename}

Each region has its own image host, such as eu-images.contentstack.com for AWS Europe. Always build transforms from the url field the API returns, so the host and path are correct for your stack.

The surprises come from three places: parameters that depend on another parameter, formats with their own rules, and the file_uid segment that changes when someone replaces the file.

Fix it

auto=webp looks soft

auto=webp serves WebP to browsers that support it. WebP output is lossy by default, so a photo that looked fine as a high-quality JPEG can come back noticeably softer, and text or line art in an image can show artifacts.

Set quality explicitly. It takes a whole number from 1 to 100 and applies to the lossy formats: JPEG, progressive JPEG, lossy WebP and AVIF.

https://images.contentstack.io/v3/assets/blt95131ce7919c7429/blt293c6dd97376af9f/60b258bg299917402992601b/hero.jpg?environment=production&auto=webp&quality=85&width=1600

For screenshots, logos and diagrams, ask for lossless WebP instead:

.../diagram.png?environment=production&format=webpll

auto does not work for GIF files. An animated GIF stays a GIF.

AVIF falls back

auto=avif serves AVIF only to browsers that support it. Every other browser gets the image in the format the format parameter asks for, or in a standard format like JPEG or PNG if you did not set one. So a request that "returns JPEG" in one browser can be working as designed.

Make the fallback explicit so you know what older browsers get:

.../hero.jpg?environment=production&auto=avif&format=pjpg&quality=80&width=1600

Two more rules apply:

  • AVIF output is limited to 4,096 x 4,096 pixels. Resize large images with width or height before you ask for AVIF.

  • HEIC sources need an explicit format, because browsers barely support HEIC.

If you put your own CDN or image proxy in front of the Image Delivery API, make sure it does not cache the AVIF response from one browser and serve it to a browser that cannot decode it.

Quality on its own

If you set only quality and the result would be larger than the original, the API returns the original file. That happens with images that were already compressed hard before upload. quality also does nothing for PNG and GIF, because those formats are not lossy.

To actually shrink a PNG photo, change the format and resize it:

.../photo.png?environment=production&format=jpg&quality=80&width=1200

dpr needs a width or height

dpr multiplies the output size for high-density screens. It needs width or height to multiply. On its own it has nothing to scale.

.../avatar.jpg?environment=production&width=200&dpr=2

That returns a 400 pixel wide image, which you display at 200 CSS pixels. In a srcset, generate one URL per density:

<img
  src="https://images.contentstack.io/v3/assets/.../avatar.jpg?environment=production&width=200"
  srcset="https://images.contentstack.io/v3/assets/.../avatar.jpg?environment=production&width=200&dpr=2 2x"
  width="200" height="200" alt="Author avatar">

The output is capped at 8,192 x 8,192 pixels. A large width multiplied by a large dpr hits that ceiling.

Crop and fit need dimensions

crop cuts a region out of the image. It also needs width, height or both. Without them, the image can come out stretched out of proportion.

Crop to an aspect ratio and then size the result:

.../hero.jpg?environment=production&crop=16:9&width=1200

This is also the combination that works with dpr. The aspect ratio stays the same and dpr scales the final width:

.../hero.jpg?environment=production&crop=16:9&width=600&dpr=2

Crop values can be pixels or percentages. To start the crop at a point, add x and y after the width and height, like crop=300,400,x150,y75. A crop that reaches outside the source image fails. Append safe to get the intersection of the image and the crop area instead, which can be smaller than what you asked for. Use smart for content-aware cropping that keeps faces and other important parts in frame.

fit takes bounds, cover or crop, and it needs both width and height:

.../product.jpg?environment=production&width=400&height=400&fit=bounds

bounds keeps the whole image inside the box. cover fills the box and crops from the center. If you only pass width, fit has nothing to fit against.

Upscaling is on by default

If you ask for a width larger than the source image, the API scales it up. That fills the layout but looks blurry. Turn it off with disable=upscale, together with width or height:

.../logo.png?environment=production&width=2000&disable=upscale

You get the source size instead of a stretched version, and your CSS decides how it fills the space.

SVG and GIF are different

The Image Delivery API accepts JPEG, PNG, WebP, GIF and AVIF as input. SVG is not in that list, so resize and format parameters do not apply to it. Size SVGs with width and height attributes or CSS.

GIFs have their own rules. width, height and auto do not work for GIF files. The frame parameter returns only the first frame of an animated GIF, which is the closest you get to a poster image. If you need a resized still, export one and upload it as its own asset.

Replaced assets keep their old URL

When an editor replaces the file of an asset, the asset_uid stays the same but the file_uid in the URL changes. The new URL looks like this:

before: .../blt293c6dd97376af9f/60b258bg299917402992601b/sample_logo.png
after:  .../blt293c6dd97376af9f/60b158bf299917401442602e/new_sample_logo.png

Entries that reference the asset through a File field or the JSON RTE pick up the new URL once the asset is published. Anything that stored or cached the old URL does not:

  • Pages your site rendered and cached before the replace

  • URLs pasted into text fields, other systems or emails

  • Your own data cache of the entry

Republish or revalidate the pages that use the asset. For URLs that live outside the CMS, generate a permanent asset URL. It uses a slug you choose and stays the same when the file is replaced:

https://images.contentstack.io/v3/assets/{stack_api_key}/{asset_uid}/{slug}

You can generate a permanent URL only once per asset, and you cannot change it afterwards, so pick the slug with care.

The image must be published

Requests with the environment parameter go through the CDN and get higher rate limits. The image has to be published to that environment. An unpublished image returns an error, even though it shows up fine in the entry editor. On a branch other than main, add branch={branch_uid} as well.

Serving images from your own domain

Asset URLs contain contentstack.io or contentstack.com. To serve them from a domain you own, put a CDN in front of the image and asset hosts and rewrite the URLs in your app. Contentstack documents a Fastly setup for masking asset domains: one origin for images.contentstack.io, one for assets.contentstack.io, each with an override host. Forward the full query string, or every transform parameter is lost on the way.

If you use next/image, let the Image Delivery API do the work instead of resizing a second time on your server. A custom loader maps the next/image props to query parameters:

// lib/contentstack-image-loader.ts
export default function contentstackLoader({
  src,
  width,
  quality,
}: {
  src: string;
  width: number;
  quality?: number;
}) {
  const url = new URL(src);
  url.searchParams.set('width', String(width));
  url.searchParams.set('quality', String(quality ?? 80));
  url.searchParams.set('auto', 'webp');
  return url.toString();
}
// next.config.js
module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './lib/contentstack-image-loader.ts',
  },
};

Check that it worked

Request the transformed URL with curl and read the headers and the output size:

curl -sI "https://images.contentstack.io/v3/assets/.../hero.jpg?environment=production&auto=avif&format=pjpg&width=1600" \
  -H "Accept: image/avif,image/webp,*/*" | grep -i "content-type\|content-length"

Run it again without image/avif in the Accept header. The first request should return image/avif, the second image/jpeg. To check dimensions, download the file and inspect it:

curl -s -o hero.out "https://images.contentstack.io/v3/assets/.../hero.jpg?environment=production&crop=16:9&width=600&dpr=2"
file hero.out

For a crop at width=600&dpr=2, you should see a width of 1200 pixels and a 16:9 ratio.

Prevent it

  • Build image URLs in one helper that always sets environment, quality and a width, so no component ships a bare auto=webp.

  • Pair every dpr, crop and fit with the dimensions it needs.

  • Add disable=upscale to logos and small source images.

  • Use permanent asset URLs for anything that leaves the CMS.

  • Keep source images under the input limits: 50 MB and 12,000 x 12,000 pixels.

Key takeaways

  • auto=webp and auto=avif depend on the browser. Set quality and a fallback format explicitly.

  • quality alone can return the original file, and it does nothing for PNG or GIF.

  • dpr, crop and fit need width, height or both.

  • SVG is not transformed. GIFs ignore width, height and auto.

  • Replacing a file changes its URL. Permanent asset URLs survive a replace.

Frequently asked questions

  • Why does auto=webp make my images look worse?

    WebP output is lossy unless you ask for lossless. Set quality explicitly, or use format=webpll for graphics with sharp edges and flat colors.

  • Why do I get JPEG when I asked for AVIF?

    auto=avif only serves AVIF to browsers that support it and falls back to the format parameter for the rest. AVIF output is also limited to 4,096 x 4,096 pixels.

  • Can I resize an SVG with the Image Delivery API?

    No. SVG is not a supported input format, so size SVGs in your markup or CSS instead.

  • Why does my page still show the old image after I replaced the file?

    Replacing a file changes the file UID in the asset URL. Pages that copied or cached the old URL keep pointing at the old file. Use a permanent asset URL for links that must survive a replace.

  • Can I serve Contentstack images from my own domain?

    Yes, by putting your own CDN in front of the image and asset hosts. Contentstack documents a Fastly setup for masking asset domains.