Media Optimizer transformations

Media Optimizer provides the ability to transform your media on the fly, optimizing how it is delivered to your end users to achieve the best visually engaging experience.

Transformations overview

In Cloudinary terminology, a transformation is an instruction to change a media file in some way. For example, the format of the media, its type of compression, its dimensions or its visual appearance. In Media Optimizer, transformations never affect the media source itself. They are performed on the fly, and the transformed media is cached for fast delivery.

Cloudinary transformations take the form of parameters that can be chained together, so one transformation can change the media in more than one way. A Programmable Media or DAM Cloudinary account supports all the transformation parameters documented in the transformation reference, however Media Optimizer limits these to ones that can help to improve the delivery of your media - see all the transformations that Media Optimizer supports.

Media Optimizer lets you define named transformations that you can include in your delivery profiles as default (base) transformations, so you don’t need to alter your media URLs. In some cases, however, you may want to add a specific transformation to only one or two URLs and this is possible by adding transformation parameters as a query string, for example:,h_500,c_fit.

Media Optimizer comes with a default Media Optimizer delivery profile that specifies automatic format and automatic quality as default (base) transformations. This means that any media delivered by Media Optimizer is automatically optimized for format and quality out of the box.

Another automatic feature that you may want to use is automatic cropping. You can enable this setting when creating a named transformation and choosing to crop your images to the dimensions that you specify.

You can also create custom transformations within your named transformation, where you can specify any of the supported transformations in URL syntax.

Resizing and cropping

Responsive design and art direction generally requires displaying images and videos at a variety of sizes, often much smaller than the original.

If you deliver full size assets and rely on browser-side resizing (using CSS or HTML width and height attributes), users are forced to download unnecessarily large images and videos. Therefore, assets should always be delivered from the server at their final size.

When you use any of the Cloudinary resizing transformations, the sizing (scaling/cropping) is performed on the server side, and the image or video is always delivered to the browser at the requested size.

Automatic cropping

Currently, Media Optimizer supports automatic cropping only for images.

Cloudinary's intelligent gravity selection capabilities ensure that the most interesting areas of each image are selected as the main focus for the requested crop, not only for photos with faces, but for any content type. Each image is analyzed individually to find the optimal region to include while cropping. Automatically detected faces (or other elements) are, by default, given higher priority while analyzing the image content.

You apply automatic content-aware gravity by setting the gravity transformation parameter to auto (g_auto in URL syntax). If no gravity is specified in a crop, the image is cropped around its center.

Automatic cropping is supported for the fill, lfill, fill_pad, thumb and crop modes.

Here are some examples of using automatic cropping:

Custom transformation: c_fill,g_auto,h_300,w_200

Original image Original Automatic image thumbnail with fill Automatic fill

Custom transformation: c_thumb,g_auto,h_150,w_150

Original Original Automatic image thumbnail Automatic thumbnail

Custom transformation: c_crop,g_auto,h_200,w_200

Original image Original Automatic image thumbnail with crop Automatic crop

Automatic format

There are many formats for encoding images and videos, with some formats better than others at compression and reducing the file size without impairing visual quality. Since different browsers support different image and video formats and codecs, the best solution to optimize delivery time and save bandwidth is to deliver the best format according to the browser used by each of your visitors.

For example, see how the size of this image and video changes according to their formats:

Shoes image delivered with f_auto
Format Size
AVIF 14.6 KB
GIF 98.0 KB
JPEG 33.5 KB
JPEG-2000 21.0 KB
PNG 190.0 KB
WebP 16.1 KB
Format Size
MP4 (H.264) 821 KB
MP4 (HEVC) 520 KB
WebM (VP9) 482 KB

Using the automatic format feature (f_auto in URL syntax), Media Optimizer makes the decision about the best format to deliver based on the requesting browser. For images, if automatic quality is used in conjunction with automatic format, other factors are taken into account in addition to the requesting browser, such as the content of the image.

Automatic quality

Cloudinary's intelligent quality and encoding algorithm analyzes each image or video to decide on the best quality compression level and optimal encoding settings based on the media content and viewing browser, in order to produce the best visual quality while minimizing the file size.

The automatic quality feature (q_auto in URL syntax) can be used to perform automatic quality encoding. Further control of the automatic quality selection is supported as follows:

  • q_auto - The optimal balance between file size and visual quality. By default, this is the same as q_auto:good.
  • q_auto:best - Less aggressive algorithm. Generates bigger files with potentially better visual quality.
  • q_auto:good - Ensures a relatively small file size with good visual quality. Example of a target audience: stock media sites that display images and videos with a high visual quality.
  • q_auto:eco - More aggressive algorithm, which results in smaller files of slightly lower visual quality. Example of a target audience: popular sites and social networks with a huge amount of traffic.
  • q_auto:low - Most aggressive algorithm, which results in the smallest files of low visual quality. Example of a target audience: sites using thumbnail preview videos that then link to higher quality videos.

In addition to the automatic levels of quality, Media Optimizer lets you specify more fine-grained levels, using the URL syntax q_<quality level> in a custom transformation, where <quality level> is a value from 1 to 100.

Examples of the resulting file size when encoding a photograph, using various regular and automatic quality parameter values:

Original Original (569KB) q_80 q_80 (80.3KB) q_auto:best q_auto:best (65.9KB) q_auto:good q_auto:good (56.9KB) q_auto:eco q_auto:eco (45.0KB) q_auto:low q_auto:low (35.0KB)

If you don't specify a quality transformation in your delivery profile, the default quality settings in your account settings are applied when using any other transformation.

Creating a named transformation

A named transformation is a set of image transformations that has been given a custom name for easy reference.

Basic transformations

To create a basic named transformation:

  1. Select the Transformations tab in your Media Optimizer console.
  2. Click Add New.
  3. Enter a name for the transformation following these guidelines:
    • Must contain valid UTF8 characters only
    • Must not contain more than 1024 characters
    • Must not contain any of these characters: \, /, ?, &, #, %, ., ,, <, >
  4. Choose whether to include auto format in the transformation. This option allows Cloudinary to analyze the content of the media and select the best format to deliver based on the user's browser.
  5. Select the level of quality. The higher the quality, the higher the file size. Use one of the auto quality values to let Cloudinary determine the level of compression or encoding to apply.
  6. Select whether to crop or resize the media and enter the required dimensions. If cropping images, you can choose to automatically focus on the most visually interesting part of the image, rather than the center. The crop option uses the fill cropping mode. The resize option performs a simple scale.
  7. Click Save.

Basic transformation form

Custom transformations

To create a custom transformation:

  1. Select the Transformations tab in your Media Optimizer console.
  2. Click New Advanced Transformation from the Add New dropdown.

    New advanced transformation option

  3. Enter a name for the transformation following these guidelines:
    • Must contain valid UTF8 characters only
    • Must not contain more than 1024 characters
    • Must not contain any of these characters: \, /, ?, &, #, %, ., ,, <, >
  4. In the Transformation String field, define a custom transformation in URL syntax, using any of the supported transformations. See Custom transformation example.
  5. Click Save.

Custom transformation form

Custom transformation example

To resize all media to fit a space of 150 x 150 pixels, with black padding, and deliver with automatic format and quality, type: b_black,c_pad,h_150,w_150/f_auto/q_auto.

People walking

Editing a named transformation

To edit a named transformation:

  1. Select the Transformations tab in your Media Optimizer console.
  2. Click the Edit transformation icon for the transformation you want to edit.

    Edit option for a named transformation

  3. Make the required changes and click Save.

When you change a named transformation, assets that have already been delivered using the old transformation settings are not updated unless you invalidate these assets on the cache.

Assigning a transformation to a delivery profile

To set the default (base) transformation of a delivery profile, assign a named transformation to the delivery profile as follows:

  1. Select the Configuration tab in your Media Optimizer console.
  2. Either select an existing delivery profile and select Edit from the kebab menu, or create a new delivery profile by clicking Add New.
  3. Select the transformation from the Base Transformation drop-down.
  4. Enter any other required settings and click Save.

Supported transformations

The following table shows all the transformations that are supported by Media Optimizer.

Not all sub-types of the transformations in the table are supported by Media Optimizer, for example, those requiring subscriptions to add-ons, such as c_imagga_crop and q_jpegmini are not supported.

Transformation Description
ac (audio codec) Sets the audio codec used in a video.
ar (aspect ratio) Sets the desired aspect ratio of an asset.
b (background) Applies a background to empty or transparent areas.
Note: b_auto is not supported.
br (bitrate) Controls the video bitrate.
c (crop/resize) Changes the size of the delivered asset according to the requested dimensions.
cs (color space) Controls the color space used for the delivered image or video.
Note: cmyk is not supported.
d (default image) Specifies a backup placeholder image to be delivered in case the actual requested delivery image or social media picture does not exist.
dl (delay) Controls the time delay between the frames of a delivered animated image.
dpr (DPR) Sets the device pixel ratio (DPR) for the delivered image or video.
e_loop Loops a video or animated image the specified number of times.
e_sharpen Applies a sharpening filter to an image.
f (format) Converts and delivers an asset in the specified format (see Supported media formats).
Use f_auto to deliver the asset in the most optimal format for the requesting browser.
fl_progressive Delivers an image using the progressive (interlaced) format.
fps (FPS) Controls the frames per second of a video.
g (gravity) Determines which part of an asset to focus on, and thus which part of the asset to keep, when any part of the asset is cropped.
Use g_auto to automatically identify the most interesting regions in an image.
Note: g_auto is not supported for video using Media Optimizer.
h (height) Sets the desired height of an asset.
if (if condition) Applies a transformation only if a specified condition is met.
q (quality) Controls the quality of the delivered asset.
Use q_auto to deliver an asset with an automatically determined level of quality.
t (named transformation) Applies a pre-defined named transformation to an asset.
vc (video codec) Sets a specific video codec to use to encode a video.
Use vc_auto to select the best codec based on the output format automatically.
w (width) Sets the desired width of an asset.
Use w_auto to automatically resize an image to match the width available for the image in a responsive layout.
x, y (x & y coordinates) Adjusts the starting location or offset of the corresponding transformation action.
z (zoom) Controls how much of the original image surrounding the face to keep when using face detection.
$ (variable) Defines and assigns values to user defined variables, so you can use the variables as values for other parameters.

Supported media formats

Media Optimizer lets you specify the format in which to deliver your media. The format parameter (f in URL syntax) can take the value of any of the extensions shown in the tables below. To let Media Optimizer determine the best format to deliver, use automatic format.

Supported image formats

The following image formats are supported by Media Optimizer:

Format Extensions
animated GIF .gif
animated PNG .png
animated WebP .webp
AVIF .avif
EPS (Encapsulated PostScript) .ps, .ept, .eps, .eps3
GIF .gif
HEIF .heif, .heic
JPEG .jpg, .jpe, .jpeg
JPEG 2000 .jp2
JPEG XR (JPEG eXtended Range) .wdp, .jxr, .hdp
PNG .png
SVG .svg
WebP .webp

Supported video formats

The following video formats are supported by Media Optimizer:

Format Extensions Default Codec
FLV (Flash Video) flv
MOV mov h264
MKV (Matroska Multimedia Container) mkv
MP4 mp4 h264
OGV (Ogg Video) ogv
WebM webm VP9

Supported audio formats

The following audio formats are supported by Media Optimizer:

Format Extensions
AAC (Advanced Audio Coding) aac
AIFF (Audio Interchange File Format) aiff
M4A m4a
MP3 (MPEG-3) mp3
OGG ogg
WAV (Waveform Audio File Format) wav

✔️ Feedback sent!

Rate this page: