Programmable Media

Named transformations (video tutorial)

Last updated: May-08-2024


Named transformations are one of the most useful aspects of Cloudinary's service, allowing you to take one or more transformations you have created for your images and/or videos and develop a codename for them.

In this tutorial, you'll gain an overview of what transformations and named transformations are used for in Cloudinary's APIs and Programmable Media products. Then you'll learn how to programmatically create and apply Cloudinary's named transformations to assets. Finally, you'll go a step further, optimizing your assets by utilizing Cloudinary's automatic format (f_auto) and quality (q_auto) features.

Video tutorial

This video is brought to you by Cloudinary's video player - embed your own!

Tutorial contents

This tutorial presents the following topics. Click a timestamp to jump to that part of the video.

What is a transformation?

Jump to this spot in the video  0:06 A transformation is essentially one or more instructions that tell Cloudinary how to change the properties of a media asset. Cloudinary transformations are displayed as abbreviated parameters directly in the URL that accesses the media.

What is a named transformation?

Jump to this spot in the video  0:31 Named transformations allow you to take one or more transformations, and group them under a unique custom name. Learn more in the named transformation documentation for images or video.

Example of a named transformation in the wild

Jump to this spot in the video  0:38 The first example exposes all of the parameters within the URL. The second example keeps your set of transformations concealed within a single named transformation.

Use cases for named transformations

Jump to this spot in the video  0:51 Named transformations help with security, reusability, and reducing human error. When we add many transformations, the URL can get quite lengthy, and all transformations applied are visible in the URL structure. Creating a named transformation will conveniently condense all the transformation parameters into one item in the URL structure, hiding your transformation parameters.

Clone this repository to follow along

Jump to this spot in the video  1:02 It may be helpful to clone the repository we've created and will be using for this demonstration.

Setting up your development environment

Jump to this spot in the video  1:06 If this is your first time setting up your development environment with Cloudinary, we recommend watching our Upload Programmatically tutorial. It will also walk you through how to make your first upload.

Ensure script libraries are installed

Jump to this spot in the video  1:15 Make sure all of our script's libraries are properly installed with a simple npm i command. If you open your package.json file, you can see all of the packages have been listed as dependencies.

Create a basic named transformation

Jump to this spot in the video  1:57 We're using the Node.js SDK create_transformation function to POST to the Admin API's transformations endpoint, and we're passing it our own unique name - in this example, avatar-round.

Run script to create named transformation

Jump to this spot in the video  2:44 Run node create-named-transformation.js to officially create our first named transformation!

Apply named transformation to three assets

Jump to this spot in the video  2:49 Now we will apply the named transformation we just created (avatar-round) to three images in our Cloudinary Media Library (public IDs: person1, person2, person3).

Open a URL and inspect

Jump to this spot in the video  3:22 As you can see, although the image has been given the rounded corners we asked for, the square background remains. The image is still in the original JPEG format, which doesn't support transparency. There are modern formats like AVIF in Chrome and JP2 in Safari that are optimized and support transparency.

Optimizing the file format using f_auto

Jump to this spot in the video  3:57 Let's take a look at this script, which we've called optimize.js. Cloudinary makes it possible to deliver the best, modern format for your browser by using the automatic format feature. This transformation is displayed in the URL as f_auto.

Optimizing the quality using q_auto

Jump to this spot in the video  4:13 While we're at it, let's also add compression with quality auto (or q_auto) for more optimization. Applying quality auto (q_auto) will allow us to get the best compression, while maintaining great quality. You can see in the script that we are creating a chained transformation with an array of transformations.

Run script to optimize the assets

Jump to this spot in the video  4:34 Run optimize.js to optimize the assets. The automatic formatting (f_auto) provides a file format that supports transparency in this case. The automatic quality (q_auto) provides an optimized, compressed quality for the asset.

Inspect optimized assets in Chrome and Safari

Jump to this spot in the video  4:42 Let's see the result in Chrome and Safari. In Chrome, we're seeing an AVIF. Safari is displaying the image as a JP2.

Keep learning

Related topics

If you like this, you might also like...

Upload Programmatically
Use a Cloudinary SDK to upload media assets
Transformation Templates (Presets)
Apply complex crops, optimizations and artistic details with one click
Create Upload Presets
Streamline media uploads using signed upload presets


Cloudinary Academy


Check out the Cloudinary Academy for free self-paced Cloudinary courses on a variety of developer or DAM topics, or register for formal instructor-led courses, either virtual or on-site.


✔️ Feedback sent!

Rate this page: