Media Optimizer transformation reference

Cloudinary's Media Optimizer is for targeted Enterprise organizations and simplifies the process to optimize and deliver high-quality media with high performance, low latency and massive scalability.

The Media Optimizer documentation includes:

Guides

References

This page provides a Transformation reference, with comprehensive coverage of all available Media Optimizer transformation parameters, including syntax, value details, and examples.

In Media Optimizer you can use this syntax in two places:

  • When defining custom transformations
  • When specifying transformations to apply to specific media (as query parameters).

Learn more about Media Optimizer transformations.

Example URLs

The URLs provided in the examples on this page show the transformations applied as query parameters, because custom transformations are hidden in the default (base) transformations in your Media Optimizer configuration.

Example URLs on this page take this form:

https://<cloud_name>.mo.cloudinary.net/<path_prefix>/<full_path>/<asset_name>.<extension>?tx=<transformation>

For example:

  • The cloud name is demo-mo-docs.
  • The optimization profile is identified by the path prefix, no_transform. It does not include any default transformations, so the only transformations applied to the assets are the ones specified in the query string following ?tx= (ac_none in the example above).
  • The media source of the images and videos is configured as a Web Address type with URI base: https://cloudinary-devs.github.io/.
    • The path to images is https://cloudinary-devs.github.io/cld-docs-assets/assets/images.
    • The path to videos is https://cloudinary-devs.github.io/cld-docs-assets/assets/videos.

Note
The recommended way to apply transformations using Media Optimizer is via named transformations defined in your optimization profile. The query parameter method shown in these examples is best used for one-off cases.

Parameter types

There are two types of transformation parameters:

  • Action parameters: Parameters that perform a specific transformation on the asset.
  • Qualifier parameters: Parameters that do not perform an action on their own, but rather alter the default behavior or otherwise adjust the outcome of the corresponding action parameter.

On this page:

ac (audio codec)

 ac_<codec value>

Sets the audio codec.

ar (aspect ratio)

 ar_<ratio value>

A qualifier that crops or resizes the asset to a new aspect ratio, for use with a crop/resize mode that determines how the asset is adjusted to the new dimensions.

Use with: c (crop/resize)

See also: h (height) | w (width)

b (background)

 

Applies a background to empty or transparent areas.

<color value>

 b_<color value>

Applies the specified background color on transparent background areas in an image.

Can also be used as a qualifier to override the default background color for padded cropping.

As a qualifier, use with: c_fill_pad | c_lpad | c_mpad | c_pad

br (bitrate)

 br_<bitrate value>[:constant]

Controls the bitrate for audio or video files in bits per second. By default, a variable bitrate (VBR) is used, with this value indicating the maximum bitrate.

Supported for video codecs: h264, h265 (MPEG-4); vp8, vp9 (WebM)
Supported for audio codecs: aac, mp3, vorbis

c (crop/resize)

 

Changes the size of the delivered asset according to the requested width & height dimensions.

Depending on the selected <crop mode>, parts of the original asset may be cropped out and/or the asset may be resized (scaled up or down).

When using any of the modes that can potentially crop parts of the asset, the selected gravity parameter controls which part of the original asset is kept in the resulting delivered file.

Learn more: Resizing and cropping

crop

 c_crop

Extracts the specified size from the original image without distorting or scaling the delivered asset.

By default, the center of the image is kept (extracted) and the top/bottom and/or side edges are evenly cropped to achieve the requested dimensions. You can specify the gravity qualifier to control which part of the image to keep, either as a compass direction (such as south or north_east), one of the special gravity positions (such as faces) or AI-based automatic region detection.

You can also specify a specific region of the original image to keep by specifying x and y qualifiers together with w (width) and h (height) qualifiers to define an exact bounding box. When using this method, and no gravity is specified, the x and y coordinates are relative to the top-left (north-west) corner of the original asset. You can also use percentage based numbers instead of the exact coordinates for x, y, w and h (e.g., 0.5 for 50%). Use this method only when you already have the required absolute cropping coordinates. For example, you might use this if your application allows a user to upload user-generated content, and your application allows the user to manually select a region to crop from the original image, and you pass those coordinates to build the crop URL.

Required qualifiers

Two of the following: w (width) | h (height) | ar (aspect ratio)

Optional qualifiers

g (gravity) | x (x-coordinate) | y (y-coordinate)

fill

 c_fill

Delivers an asset with the exact specified width and height without distorting the asset. This option first scales as much as needed to at least fill both of the specified dimensions. If the requested aspect ratio is different than the original, cropping will occur on the dimension that exceeds the requested size after scaling. You can specify which part of the original asset you want to keep if cropping occurs using the gravity (set to 'center' by default).

Required qualifiers

At least one of the following: w (width) | h (height) | ar (aspect ratio)

Optional qualifiers

g (gravity)

fill_pad

 c_fill_pad

Tries to prevent a "bad crop" by first attempting to use the fill mode, but adding some padding if the algorithm determines that more of the original image needs to be included in the final image, or if more content in specific frames in a video should be shown. Especially useful if the aspect ratio of the delivered asset is considerably different from the original's aspect ratio. Supported only in conjunction with g_auto.

Note
Not supported for animated images.

Required qualifiers

g_auto

    And

Two of the following: w (width) | h (height) | ar (aspect ratio)

Optional qualifiers

b (background)

fit

 c_fit

Scales the asset up or down so that it takes up as much space as possible within a bounding box defined by the specified dimension parameters without cropping any of it. The original aspect ratio is retained and all of the original image is visible.

Required qualifiers

Two of the following: w (width) | h (height) | ar (aspect ratio)

lfill

 c_lfill

The lfill (limit fill) mode is the same as fill but only if the original image is larger than the specified resolution limits, in which case the image is scaled down to fill the specified width and height without distorting the image, and then the dimension that exceeds the request is cropped. If the original dimensions are smaller than the requested size, it is not resized at all. This prevents upscaling. You can specify which part of the original image you want to keep if cropping occurs using the gravity parameter (set to center by default).

Required qualifiers

Two of the following: w (width) | h (height) | ar (aspect ratio)

Optional qualifiers

g (gravity)

limit

 c_limit

Same as the fit mode but only if the original asset is larger than the specified limit (width and height), in which case the asset is scaled down so that it takes up as much space as possible within a bounding box defined by the specified width and height parameters. The original aspect ratio is retained (by default) and all of the original asset is visible. This mode doesn't scale up the asset if your requested dimensions are larger than the original image size.

Required qualifiers

Two of the following: w (width) | h (height) | ar (aspect ratio)

lpad

 c_lpad

The lpad (limit pad) mode is the same as pad but only if the original asset is larger than the specified limit (width and height), in which case the asset is scaled down to fill the specified width and height while retaining the original aspect ratio (by default) and with all of the original asset visible. This mode doesn't scale up the asset if your requested dimensions are bigger than the original asset size. Instead, if the proportions of the original asset do not match the requested width and height, padding is added to the asset to reach the required size. You can also specify where the original asset is placed by using the gravity parameter (set to center by default). Additionally, you can specify the color of the background in the case that padding is added.

Required qualifiers

Two of the following: w (width) | h (height) | ar (aspect ratio)

Optional qualifiers

g_<gravity position> | b (background)

mfit

 c_mfit

The mfit (minimum fit) mode is the same as fit but only if the original image is smaller than the specified minimum (width and height), in which case the image is scaled up so that it takes up as much space as possible within a bounding box defined by the specified width and height parameters. The original aspect ratio is retained (by default) and all of the original image is visible. This mode doesn't scale down the image if your requested dimensions are smaller than the original image's.

Required qualifiers

Two of the following: w (width) | h (height) | ar (aspect ratio)

mpad

 c_mpad

The mpad (minimum pad) mode is the same as pad but only if the original image is smaller than the specified minimum (width and height), in which case the image is unchanged but padding is added to fill the specified dimensions. This mode doesn't scale down the image if your requested dimensions are smaller than the original image's. You can also specify where the original image is placed by using the gravity parameter (set to center by default). Additionally, you can specify the color of the background in the case that padding is added.

Required qualifiers

Two of the following: w (width) | h (height) | ar (aspect ratio)

Optional qualifiers

g_<gravity position> | b (background)

pad

 c_pad

Resizes the asset to fill the specified width and height while retaining the original aspect ratio (by default) and with all of the original asset visible. If the proportions of the original asset do not match the specified width and height, padding is added to the asset to reach the required size. You can also specify where the original asset is placed using the gravity parameter (set to center by default). Additionally, you can specify the color of the background in the case that padding is added.

Required qualifiers

Two of the following: w (width) | h (height) | ar (aspect ratio)

Optional qualifiers

g_<gravity position> | b (background)

scale

 c_scale

Resizes the asset exactly to the specified width and height. All original asset parts are visible, but might be stretched or shrunk if the dimensions you request have a different aspect ratio than the original.

If only width or only height is specified, then the asset is scaled to the new dimension while retaining the original aspect ratio (unless you also include the fl_ignore_aspect_ratio flag).

Required qualifiers

At least one of the following: w (width) | h (height) | ar (aspect ratio)

Optional qualifiers

fl_ignore_aspect_ratio | g_liquid

thumb

 c_thumb

Delivers image thumbnails using either face-detection or custom coordinates. Must always be accompanied by the g (gravity) parameter set to one of the face detection or one of the g_custom values. This cropping mode generates a thumbnail of an image with the exact specified width and height dimensions and with the original proportions retained, but the resulting image might be scaled to fit in the specified dimensions. You can specify the z (zoom) parameter to determine how much to scale the resulting image within the specified width and height.

Required qualifiers

g (gravity) set to one of the face detection or custom special gravity positions.

    And

Two of the following: w (width) | h (height) | ar (aspect ratio)

Optional qualifiers

z (zoom)

cs (color space)

 cs_<color space mode>

Controls the color space used for the delivered image or video. If you don't include this parameter in your transformation, the color space of the original asset is generally retained. In some cases for videos, the color space is normalized for web delivery, unless cs_copy is specified.

dl (delay)

 dl_<time value>

Controls the time delay between the frames of a delivered animated image. (The source asset can be an image or a video.)

dpr (DPR)

 

Sets the device pixel ratio (DPR) for the delivered image or video.

<pixel ratio>

 dpr_<pixel ratio>

Delivers the image or video in the specified device pixel ratio.

Note
When setting a DPR value, you must also include a crop/resize transformation specifying a certain width or height.

Important
When delivering at a DPR value larger than 1, ensure that you also set the desired final display dimensions in your image or video tag. For example, if you set c_scale,h_300/dpr_2.0 in your delivery URL, you should also set height=300 in your image tag. Otherwise, the image will be delivered at 2.0 x the requested dimensions (a height of 600px in this example).

effect: loop

 e_loop[:<additional iterations>]

Loops a video or animated GIF the specified number of times (by default, animated GIFs with resource type image run in an infinite loop).

effect: sharpen

 e_sharpen[:<strength>]

Applies a sharpening filter.

f (format)

 

Converts (if necessary) and delivers an asset in the specified format regardless of the file extension used in the delivery URL.

<supported format>

 f_<supported format>

Converts and delivers an asset in the specified format.

auto

 f_auto

Automatically generates (if needed) and delivers an asset in the optimal format for the requesting browser in order to minimize the file size.

Note
When used in conjunction with automatic quality (q_auto), sometimes the selected format is not the one that minimizes file size, but rather the format that yields the optimal balance between smaller file size and good visual quality.

Learn more: Automatic format

flag: getinfo

  fl_getinfo

Returns metadata of both the input asset and the transformed output asset in JSON instead of delivering a transformed image.

As a qualifier, returns additional data as detailed below.

Note
Currently, you cannot use this flag together with the automatic format transformation.

Use with:

  • g_auto: The returned JSON includes the cropping coordinates recommended by the g_auto algorithm.
  • g_<face-specific-gravity>: The returned JSON includes the coordinates of facial landmarks relative to the top-left corner of the original image.

flag: ignore_aspect_ratio

  fl_ignore_aspect_ratio

A qualifier that adjusts the behavior of scale cropping. By default, when only one dimension (width or height) is supplied, the other dimension is automatically calculated to maintain the aspect ratio. When this flag is supplied together with a single dimension, the other dimension keeps its original value, thus distorting an image by scaling in only one direction.

Use with: c_scale

flag: progressive

  fl_progressive[:<mode>]

Generates a JPG or PNG image using the progressive (interlaced) format. This format allows the browser to quickly show a low-quality rendering of the image until the full quality image is loaded.

fps (FPS)

 fps_<frames per second>[-<maximum frames per second>]

Controls the FPS (Frames Per Second) of a video to ensure that the video (even when optimized) is delivered with an expected FPS level (helps with sync to audio). Can also be specified as a range.

g (gravity)

 

A qualifier that 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. For overlays, this setting determines where to place the overlay.

<compass position>

 g_<compass position>

A qualifier that defines a fixed location within an asset to focus on.

Use with: c_crop | c_fill | c_lfill | c_lpad | c_mpad | c_pad | c_thumb | x, y (x & y coordinates)

<special position>

 g_<special position>

A qualifier that defines a special position within the asset to focus on.

Note
Special positions are not supported for animated images in Media Optimizer.

Use with: c_crop | c_fill | c_lfill | c_scale (for g_liquid only) | c_thumb | x, y (x & y coordinates)

auto

 g_auto[:<algorithm>][:<focal gravity>][:<thumb aggressiveness>]

A qualifier to automatically identify the most interesting regions in the asset, and include in the crop.

Note
Automatic gravity is not supported for animated images. If g_auto is used in an animated image transformation, center gravity is applied, except when c_fill_pad is also specified, in which case an error is returned.

Use with: c_crop - image only | c_fill | c_fill_pad | c_lfill - image only | c_thumb - image only

Learn more: Automatic cropping

h (height)

 h_<height value>

A qualifier that determines the height of a transformed asset.

Use with: c (crop/resize)

See also: w (width) | ar (aspect ratio) | if (if condition)

if (if condition)

 if_[<directive>][_<asset characteristic>_<operator>_<asset characteristic value>]

Applies a transformation only if a specified condition is met.

q (quality)

 q_<quality value>

Controls the quality of the delivered asset. Reducing the quality is a trade-off between visual quality and file size.

<quality level>

 q_<quality level>[:qmax_<quant value>][:<chroma>]

Sets the quality to the specified level.

Caution
A quality level of 100 can increase the file size significantly, particularly for video, as it is delivered lossless and uncompressed.

auto

 q_auto[:<quality type>]

Delivers an asset with an automatically determined level of quality.

Learn more: Automatic quality

t (named transformation)

 t_<transformation name>

Applies a pre-defined named transformation to an image or video.

Learn more: Creating a named transformation

vc (video codec)

 

Sets the video codec to use when encoding a video.

<codec value>

 vc_<codec value>[:<profile>[:<level>][:bframes_<bframes>]]

Sets a specific video codec to use to encode a video. For h264, optionally include the desired profile and level.

auto

 vc_auto

Normalizes and optimizes a video by automatically selecting the most appropriate codec based on the output format.

The settings for each format are:

Format Video codec Profile Quality Audio Codec Audio Frequency
MP4 h264 high auto:good aac 22050
WebM vp9 N/A auto:good vorbis 22050
OGV theora N/A auto:good vorbis 22050

w (width)

 

A qualifier that sets the desired width of an asset using a specified value, or automatically based on the available width.

<width value>

 w_<width value>

A qualifier that determines the width of a transformed asset or an overlay.

Use with: c (crop/resize)

See also: h (height) | ar (aspect ratio) | if (if condition)

responsive

 w_responsive[:fallback-max-width_<desktop max>][;fallback-max-width-mobile_<mobile max>]

Scales down any media that exceeds the maximum width set for desktop devices (including laptops and tablets) or mobile devices (smartphones).

x, y (x & y coordinates)

 x/y_<coordinate value>

A qualifier that adjusts the starting location or offset of the corresponding transformation action.

Use with: c_crop | g_<compass position> | g_<special position>

z (zoom)

 z_<zoom amount>

A qualifier that controls how close to crop to the detected coordinates when using face-detection or custom-coordinates.

Use with: c_crop | c_thumb

Note
  • When used with thumb resize mode, the detected coordinates are scaled to completely fill the requested dimensions and then cropped as needed.
  • When used with the crop resize mode, the zoom qualifier has an impact only if resize dimensions (height and/or width) are not specified. In this case, the crop dimensions are determined by the detected coordinates and then adjusted based on the requested zoom.

$ (variable)

 $<variable name>[_<variable value>]

Defines and assigns values to user defined variables, so you can use the variables as values for other parameters.