Do this with AI
Install the cms-assets skill from Contentstack agent skills and connect the Asset Librarian profile in MCP Profile Hub. Then ask your agent:
Find image assets in my stack that are larger than 12,000 pixels on either side or heavier than 50 MB, list them with their folder and the entries that reference them, and do not change anything.
New to this? Set up your AI workbench first.
Image transforms that surprise you
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=1600For screenshots, logos and diagrams, ask for lossless WebP instead:
.../diagram.png?environment=production&format=webpllauto 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=1600Two 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=1200dpr 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=2That 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=1200This 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=2Crop 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=boundsbounds 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=upscaleYou 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.pngEntries 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.outFor 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.