Roll out a video transformation

Once you've designed and validated a video transformation that you want to use across many videos, 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 video 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 videos 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_demo, 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 visually in Video Canvas (Beta), a node-based editor where you connect blocks to form a transformation pipeline. Saving the flow creates an applet, which is backed by a named transformation, so you can use it in delivery URLs and SDK calls just like any other.

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 logo-overlay, which adds a brightened, partially transparent logo to the top-right corner, 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 videos.

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 videos 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 videos 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 videos that need it, so the derived video 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 video your delivery URL asks for. Any difference, including the order of the parameters, results in a separate derived video 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 video, eagerly generate each format and codec combination you deliver, since the format alone doesn't determine the codec:

• f_webm with vc_vp9 (VP9 codec in WebM format)
• f_mp4 with vc_h264 (H.264/AVC codec in MP4 format), the widest-compatibility fallback
• f_mp4 with vc_h265 (H.265/HEVC codec in MP4 format)
• f_mp4 with vc_av1 (AV1 codec in MP4 format)

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 videos 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 videos 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 videos you've already uploaded

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

Run this over the relevant videos, 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, and eagerly generates each format and codec combination you deliver.
• Long transformations run asynchronously, with a notification URL to tell you when they're ready.
• You've run explicit over your existing videos, so their derived versions already exist.
• If you changed an existing named transformation, you've invalidated and regenerated the affected derived videos.