Roll out an image transformation

Once you've designed and validated an image transformation that you want to use across many images, there's a bit more to do before it's ready for production. The goal is to have a single definition of that transformation that your whole app references, so that every image using it is delivered in its optimized form and already generated by the time your users request it.

Following the procedure on this page gives you three things:

• One place to change the transformation. A named transformation replaces a long list of parameters with a short alias, so when the design changes you update one definition instead of hunting through your codebase.
• Optimized delivery. Keeping f_auto and q_auto out of the named transformation and chaining them in the delivery URL lets the CDN pick the best format and quality per request.
• A warm cache. Eager transformations generate the derived images up front, so your first visitor doesn't wait for them to be created on the fly.

Step 1: Create a named transformation

Start by saving your transformation under a name, leaving out the f_auto and q_auto optimization parameters. You'll add those back in the delivery URL in step 2.

Why leave the optimization out? f_auto isn't applied at all when it's buried inside a named transformation: the CDN chooses the format per request based on the requesting browser, and it can't see parameters hidden behind the alias. q_auto does work inside a named transformation, but it loses the ability to downgrade to q_auto:eco when a browser asks for reduced data. Keeping both out of the named transformation also makes the optimization visible to anyone reading the URL. For more details, see Limitations of named transformations.

So if the transformation you validated was:

the named transformation, here called product_card, should contain only:

There are three ways to create it, and for most people one of the first two is the easiest.

Create a named transformation with an AI agent

The Environment Config MCP server manages product environment entities including named transformations and upload presets, so an AI agent connected to it can create the transformation for you, for example:

For installation instructions, see MCP servers.

Create a named transformation in the Console

Build the transformation step-by-step in Studio and save it with your chosen name. You can also start from an existing example in the Playground, click Use it, refine it, and save.

Your saved named transformations are listed in the Console under Image > Templates > Named Transformations, for both image and video named transformations.

For more details, see Creating named transformations.

Create a named transformation with the Admin API

Call the create a named transformation method of the Admin API:

Step 2: Deliver the named transformation with optimization

With the named transformation saved, deliver it by chaining the optimization parameters after it:

Here's that pattern working on a real asset. The demo product environment has a named transformation called fill_square_400, defined as ar_1:1,c_fill,g_auto,w_400, delivered here with the optimization chained after it. Switch between the tabs to see the delivery URL and the equivalent SDK code:

The t_ prefix applies the named transformation, and the f_auto and q_auto components that follow stay visible to the CDN so it can pick the best format and quality for each request. For more on what these two parameters do, see Optimize images.

Note that the delivery URL above has no file extension. The extension counts as part of the transformation, so leaving it off means f_auto alone determines the delivered format, and you only need one eager transformation per format in step 3 rather than one per format and extension combination.

If you already have images in production that use the same transformation as directly defined parameters, in delivery URLs or in SDK calls, replace those with the named transformation now. A global find and replace across your codebase is usually enough. From then on, changing how the transformation looks means updating the named transformation's definition in one place, with no code change or deployment. Bear in mind that images already derived with the old definition aren't regenerated automatically, so you also need to invalidate and regenerate them.

Step 3: Warm the cache with eager transformations

At this point the transformation is generated the first time someone requests it. To have it ready in advance, add an eager transformation to the upload presets used by the images that need it, so the derived image is generated at upload time rather than on first view.

Match the delivery URL exactly

An eager transformation only warms the cache if it produces the same derived image your delivery URL asks for. Any difference, including the order of the parameters, results in a separate derived image and a cold cache for the URL you're actually serving. For example, if you eagerly generate c_fill,h_400,w_600, your delivery URL has to use that same order, not c_fill,w_600,h_400. See Test before production.

q_auto goes in the eager transformation as its own component, exactly as it appears in your delivery URL, and so does any quality applied by default. The one thing that can't match is f_auto. Because there's no requesting browser at upload time, f_auto has no effect in an eager transformation, so instead you eagerly generate the specific formats that f_auto will later serve. See Using automatic format in eager transformations, and Don't use f_auto, use specific formats instead for the upload preset specifics.

When you set an explicit format in an SDK or API call, also set the format parameter to an empty string. Otherwise the generated URL picks up a file extension as well as the f parameter, and no single f_auto delivery URL can match every eagerly generated variant.

For images, eagerly generate the formats f_auto actually delivers to your audience:

• f_webp (WebP), selected for the vast majority of modern browsers
• f_jpg (JPEG), or f_png for images that need transparency, as the fallback
• f_avif (AVIF), which gives the best compression for the browsers that support it

There's no point eagerly generating a format f_auto won't serve, so only include AVIF if it's available on your plan. Each extra format is another derived image per asset.

The examples below generate the first two, which covers most delivery scenarios.

Add the eager transformation to your upload presets

Update the upload presets used by the images that need this transformation, so that each new upload eagerly generates it. The eager value references the named transformation, so you still only maintain the transformation itself in one place.

If you're setting the eager transformation in the Console under Settings > Upload > Upload presets, the field takes URL syntax rather than SDK parameters, and you add each transformation separately using the + button. Chain the components within one transformation with a slash (/), so the first two are entered as:

If your transformations take a while to generate, turn on the Apply eager transformations asynchronously toggle below the transformation fields, so uploads aren't held up while the derived images are created.

Using the Admin API or an SDK instead:

You can also ask an agent connected to the Environment Config MCP server to update all the relevant presets for you, which saves writing a loop when you have many of them.

For the full set of options, see Create an upload preset and Update an upload preset in the Admin API Reference, and Managing upload presets, including the best practices for upload presets.

Warm the cache for images you've already uploaded

Upload presets only affect new uploads. To generate the same derived images for images already in your product environment, use the explicit method:

Run this over the relevant images, for example by listing them with the Admin API or by searching for the tag or folder that identifies them.

Checklist

Before you consider the rollout done, confirm that:

• The named transformation contains the full transformation, without f_auto or q_auto.
• Every delivery URL and SDK call in your app references the named transformation, chained with f_auto/q_auto.
• The eager transformation in your upload presets matches the delivery transformation exactly, including parameter order, with explicit formats in place of f_auto.
• You've run explicit over your existing images, so their derived versions already exist.
• If you changed an existing named transformation, you've invalidated and regenerated the affected derived images.