Named transformations

A named transformation is a pre-defined set of transformation parameters that has been given a custom name for easy reference. Instead of applying each of the required transformations separately to an asset, you can apply a single named transformation to apply all the transformations defined for it. This makes it easy to:

• Reuse transformations on multiple assets
• Shorten complex transformation URLs
• Hide the details of a transformation in your delivery URL.
• Simplify the enabling/disabling of transformations in Strict Transformations mode.

Named transformations can include other named transformations, which allows you to define a chain of transformations to run on multiple assets more easily.

They're required for baseline transformations, which save processing time and cost by avoiding regeneration of shared transformation steps.

You can create and manage named transformations via the API or in the console UI using the Transformation Builder.

Once defined, you can apply a named transformation by setting the transformation parameter (or t in a URL) to the transformation's name. For example t_instagram-auto-crop.

You can include user-defined variables in your named transformations, and then pass the value for the user-defined variable into the transformation from an external source. This enables creating a named transformation 'template' with a lot of flexibility.

For example, you could define a complex named transformation that includes a text overlay as a named transformation, using a user-defined variable for the text string value.

Cloudinary automatically tracks which named transformations were used to generate each derived asset. You can view this information in the Derived Assets tab of the Manage page. For more information, see Derived Assets in the Media Library for developers guide.

You can also set named transformations as transformation templates, which you can apply as templates in the Media Library so that you can preview how assets will look with different named transformations applied.

For more details, see user-defined variables. For a use-case example demonstrating named transformations with user-defined variables, see Named transformation with a user-defined variable.

Creating named transformations

You can create a named transformation programmatically or using the Transformations UI in your Cloudinary console.

To create a named transformation programmatically:

Use the Transformations Admin API method.

For example, the following defines a named transformation called small_profile_thumbnail that uses automatic cropping to resize assets to the required size for a particular application's thumbnail display:

For more details and examples, see the Create Transformation method in the Admin API Reference.

To create a named transformation using the UI:

1. Expand the Transform and Customize section, accessible from the Console Product Navigation menu.
2. Choose one of the following options to create your named transformation:
   • Start with a pre-defined transformation: Select a transformation from the Image Home examples as a template and experiment with it in the UI. Click Use it to open the Transformation Builder and refine the transformation to your needs, and save it with your chosen name.
     
   • Save a delivered dynamic transformation: View all your delivered dynamic transformations (those that were generated and delivered on the fly) in the Log tab of the Manage Transformations page and save one of those with your chosen name.
   • Create from scratch: Create a new transformation from scratch using the Transformation Builder (Beta) and save with your chosen name. Open the builder by clicking New Transformation from either of the Transform and Customize pages.

Once you've saved your named transformations, you can view a list of them in the Console in the Image > Manage Transformations > Named Transformations tab. From here, you can edit, copy, or enable/disable Strict Transformations.

You can also select to include a transformation as a preset so that users can apply it to assets using the Download Options tab of the asset management drill-down page (available for Assets Enterprise plans).

Transformation Builder

The Cloudinary Transformation Builder is the UI for creating and saving your transformations in a simple and easy to use way. The Transformation Builder has two modes of operation:

• Construct: Build transformations manually by selecting and configuring transformation actions.
• Converse: Build transformations using AI chat by describing the transformation with natural language.

Transformation Builder video tutorial

Watch this video for a quick introduction to the Transformation Builder:

Tutorial contents

Create a transformation using the Builder

To create a new transformation:

1. Open the Builder.
2. Select the mode to use.

Construct mode

The Transformation Builder in construct mode provides:

• A simple and intuitive UI for selecting and configuring transformation actions - easily discover actions and parameters as you build.
• Transformations built as a series of self-contained actions so you can see the results of each one as you apply it.
• URL and SDK code ready to copy and paste directly to your code.
• The ability to update the default preview image to something from your own product environment.
• Quick edit functionality, to easily add transformations using URL syntax.

The builder supports most common transformation actions. If the transformation action you are trying to apply is not listed, you can add an Additional Transformation action and use transformation URL syntax to specify your transformation. Alternatively, you can switch to the legacy editor to create your transformation.

Converse mode

The Transformation Builder in converse mode provides:

• An AI-powered conversational interface to describe the transformation you want to create with natural language.
• Iterative prompts to continue the conversation and perfect the transformation.
• URL and SDK code ready to copy and paste directly to your code.
• The ability to update the default preview image to something from your own product environment.

Named transformation examples

Below are two quite different named transformations applied to the same lighthouse_reflection image:

• fill_square_400 is defined as ar_1:1,c_fill,g_auto,w_400, which fills (scales and crops) the image into a 400*400 square, automatically focussing on the most interesting area of the image:
  

   

• rounded_cartoonified_frame is defined as e_cartoonify/r_max/co_rgb:add8e6,e_outline:30/b_rgb:add8e6, which applies a cartoonify effect, rounds it to a circle or oval shape, adds a light blue outline around the oval so that the image won't be touching the edges of the frame, and then fills the transparent background with the same color as the outline:
  

Chaining named transformations

You can chain named transformations before or after other transformations. For example, here the oval_cartoonified_frame named transformation is applied after a grayscale effect:

You can also chain multiple named transformations. For example, to chain the named transformations defined in the previous section:

Chaining transformations can create long URLs, so instead you could define a named transformation that includes a chain of other transformations, including other named transformations. For example, we can create a named transformation that is a composite of the named transformations from the section above.

It is now simple to specify a single named transformation and apply it to any asset:

Where the fill_circle_cartoon named transformation is defined as: t_fill_square_400/t_rounded_cartoonified_frame.

Limitations of named transformations

Automatic format

The automatic format transformation parameter (f_auto) is not effective if used in named transformations.

When f_auto is used in a delivery URL, the CDN layer determines the best format to deliver. If this parameter is hidden in a named transformation then it is not visible to the CDN.

You can use f_auto together with a named transformation by chaining the components, for example, t_square/f_auto.

Automatic quality

The automatic quality transformation parameter (q_auto) is effective in named transformations, except in one situation.

When q_auto is used in a delivery URL and the browser sets the Save-Data HTTP header to on in the request, q_auto is translated to q_auto:eco at the CDN level. If this parameter is hidden in a named transformation then it is not visible to the CDN, so the default level is applied, q_auto:good.

To accommodate this situation, you may prefer to use q_auto together with a named transformation by chaining the components, for example, t_square/q_auto.

Learn more: Save-Data support

Default image placeholder caching

When a requested asset doesn't exist and a default image is delivered, Cloudinary sets stricter cache headers than for regular non-default images:

• Default image: private, with a short max-age (five minutes)
• Non-default image: public, with a max-age of 30 days for a res.cloudinary.com hostname or one year for a custom hostname.

The shorter max-age causes browsers to check back sooner for the real asset.

If you include the default image parameter (d_) inside a named transformation, the stricter cache settings don't apply. To ensure short caching for placeholders, use d_ directly in the delivery URL, not within a named transformation.

Automatic width

The automatic width transformation parameter (w_auto) is not effective if used in named transformations.

For responsive image solutions, w_auto must appear directly in the delivery URL. If it's hidden within a named transformation, it won't be visible to the client or CDN (depending on the solution) and therefore won't take effect.

See Responsive images using the cloudinary-core JS library and Responsive images using client hints.

Automatic device pixel ratio

The automatic device pixel ratio transformation parameter (dpr_auto) is not effective if used in named transformations.

For responsive image solutions, dpr_auto must appear directly in the delivery URL. If it's hidden within a named transformation, it won't be visible to the client or CDN (depending on the solution) and therefore won't take effect.

See Responsive images using the cloudinary-core JS library and Responsive images using client hints.

Named transformation video tutorial

Watch this video tutorial to learn how to create re-usable named transformations with the Cloudinary Transformation Builder UI.

Tutorial contents

Copying named transformations between product environments

You can copy named transformations from one product environment to another using the Admin API.

1. In the source product environment, list named transformations using Get transformations with named=true.
2. If the response includes next_cursor, continue requesting additional pages until all named transformations are returned.
3. In the destination product environment, recreate each named transformation using Create a named transformation.

Java example

For Java SDK implementations, this workflow is typically handled by:

• calling api.transformations(...) on the source product environment
• iterating through the returned named transformations
• calling api.createTransformation(...) on the destination product environment for each transformation you want to copy

If your source response includes a next_cursor value, continue requesting additional pages until all named transformations have been processed.