Media Optimizer transformation reference

This reference provides 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:

Copy to clipboard
https://demo-mo-docs.mo.cloudinary.net/no_transform/cld-docs-assets/assets/videos/dog.mp4?tx=ac_none
  • 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.

ac (audio codec)

 ac_<codec value>

Sets the audio codec.

Value Type Description
codec value constant Required. The audio codec to use.

Possible values:

  • none: Removes the audio channel.
  • aac: Sets the audio codec to aac (mp4 or flv only).
  • vorbis: Sets the audio codec to vorbis (ogv or webm only).
  • mp3: Sets the audio codec to mp3 (mp4 or flv only).
  • opus: Sets the audio codec to opus (webm only).

Examples

Remove the audio from a video (ac_none):

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)

Value Type Description
ratio value string | float Required. The aspect ratio to apply. Can be set as either:

  • A string value in the form a:b, where a is the width and b is the height (e.g., 16:9).
  • A decimal value representing the width divided by the height (e.g., 0.5).

Examples

  1. Crop an image to an aspect ratio of 1.5 (ar_1.5,c_crop):

    Aspect ratio 1.5

  2. Fill a video to an aspect ratio of 1:1 (ar_1:1,c_fill):

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

Value Type Description
color value string Required. The background color to apply. It can be set as:

  • A 3- or 4-digit RGB/RGBA hex
  • An RGB or RGBA hex triplet or quadruplet (6 or 8 digits).
  • A named color
When specifying any RGB or RGBA value, always prefix the value in the URL with rgb: (without #). For example, b_rgb:FEB61FC2 or b_rgb:999.

When using a named color, specify only the color name. For example b_blue.

Examples

  1. Convert the transparent background of the car_white image to a light-blue color (b_lightblue): Convert the transparent areas of an image to the specified color
  2. Scale to fit an image into a 300X300 square and pad any excess space with a pink background (b_pink):
    green background

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

Value Type Description
bitrate value integer | string Required. The maximum number of bits per second (e.g., 500000). Can also be specified as a string, supporting k and m for kilobits and megabits respectively (e.g., 500k or 1m).
constant keyword If constant is specified, the video or audio file plays with a constant bitrate (CBR) and the default quality setting (or any q (quality) setting explicitly specified) is ignored.

Examples

  1. Set a maximum bitrate of 500000 (br_500000):

  2. Set a constant bitrate of 500k (br_500k:constant):

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)

Example

Crop an image to a width of 200 pixels, a height of 150 pixels, with northwest gravity (c_crop,g_north_west,h_150,w_200):

Image cropped to 100x150 with north west gravity

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)

Examples

  1. Fill to a width and height of 150 pixels (c_fill,h_150,w_150):

    Image filled to a width and height of 150 pixels

  2. Fill to a width and height of 150 pixels with east gravity (c_fill,g_east,h_150,w_150):

    Image filled to a width and height of 150 pixels with east 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)

Example

Deliver an image as a 25x150 image using the fill_pad mode. (b_gray,c_fill_pad,g_auto,h_150,w_25).
Compare this to the same image delivered using the regular fill mode (shown below on the right).

fill_pad fill_pad fill fill

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)

Example

Fit an image within a width and height of 150 pixels (c_fit,h_150,w_150).

fit within 150x150

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)

Example

Limit-fill an image to a width and height of 150 pixels (c_lfill,h_150,w_150):

Image limit-filled to a width and height of 150 pixels

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)

Example

Limit an image to a width and height of 150 pixels (c_limit,h_150,w_150):

Image limited to a width and height of 150 pixels

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)

Example

Limit-pad an image with a green background to a width and height of 150 pixels (b_green,c_lpad,h_150,w_150):

Image limit-padded to a width and height of 250 pixels

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)

Example

Request to fit a large image to a minimum width and height of 20 pixels while retaining the aspect ratio. This results in delivering the original image without resizing it (c_mfit,h_20,w_20):

Image mfit to a width and height of 20 pixels

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)

Examples

  1. Request to pad a large image to a minimum width and height of 20 pixels while retaining the aspect ratio. This results in delivering the original larger image (c_mpad,h_20,w_20): Image minimum padded to a width and height of 20 pixels
  2. Request to pad with a green background, a 100-pixel wide image to a minimum width and height of 150 pixels while retaining the aspect ratio (b_green,c_mpad,h_150,w_150):
    Image minimum padded to a width and height of 150 pixels

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)

Example

Pad an image with a black background to a width and height of 150 pixels (b_black,c_pad,h_150,w_150):

Image padded to a width and height of 150 pixels

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

Examples

  1. Scale to a width of 150 pixels (maintains the aspect ratio by default) (c_scale,w_150):

    Image scaled to a width of 150 pixels

  2. Scale to a width and height of 150 pixels (does not maintain the aspect ratio) (c_scale,h_150,w_150):

    Image scaled to a width and height of 150 pixels

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 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)

Example

Crop an image to a 150x150 thumbnail using face detection (c_thumb,g_face,h_150,w_150):

150x150 thumbnail with face detection

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.

Value Type Description
color space mode constant Required. The color space mode to use when delivering the image or video.

Possible values:

  • sRGB: Renders the image or video in the sRGB color space.
  • tinysrgb: Renders the image or video using Facebook's truncated sRGB color space.
  • no_cmyk: If the original image or video used the CMYK color space, converts it to sRGB.
  • keep_cmyk: Retains the CMYK color space when generating derived images or videos.
  • srgb:truecolor: Image only. Encodes the image as RGB, rather than palette or grayscale. Not applicable when using q_auto.
  • copy: Video only. Retains the original color space of the video. This prevents the color space from being normalized when the video is re-encoded by Cloudinary if another transformation is applied.

Examples

  1. Render an image in the sRGB color space (cs_srgb). Render image in sRGB color space
  2. Render an image in the CMYK color space (cs_keep_cmyk). Retain the CMYK color space when generating a derived image

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.)

Value Type Description
time integer Required. The delay in milliseconds between frames.

Example

Convert a video to an animated image, and apply a delay of 200 milliseconds between frames (dl_200,f_gif).

Deliver an animated image based on a video with a delay between frames of 200 milliseconds

dpr (DPR)

 

Sets the device pixel ratio (DPR) for the delivered image or video using a specified value or automatically based on the requesting device.

<pixel ratio>

 dpr_<pixel ratio>

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

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 h_300,dpr_2 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).

Value Type Description
pixel ratio float Required. A positive value for the device pixel ratio to use when delivering the image or video.

Example

Deliver the image with a dpr of 2.0 (dpr_2.0).

Note
While the code example below shows only the transformation URL, the image tag for the displayed inline image includes a hard-coded height definition in the image tag, to ensure that the doubled-DPR is still delivered within a display of 150px. If you view just the transformed dpr_2 URL outside the image tag, it displays with a height of 300px.

Copy to clipboard
<img title="Deliver the image with a dpr of 2.0" 
    alt="Deliver the image with a dpr of 2.0" 
    style="margin: 0 auto;display: block" 
    src="https://demo-mo-docs.mo.cloudinary.net/no_transform/cld-docs-assets/assets/images/face_top.jpg?tx=dpr_2.0,h_150"
    height="150" 
>

Deliver the image with a dpr of 2.0

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).

Value Type Description
additional iterations integer Required for video. The number of additional times to play the video or animated GIF.

For animated GIFs only, this can be omitted to loop the GIF infinitely.

Example

Play an animated GIF three times (two additional times) (e_loop:2):

Animated GIF of ball on a spring

effect: sharpen

 e_sharpen[:<strength>]

Applies a sharpening filter.

Value Type Description
strength integer The strength of the sharpening filter.

Range: 1 to 2000. Default: 100.

Example

Apply a sharpening filter with a strength of 400 (e_sharpen:400):

Sharpening effect applied to horse image

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.

Value Type Description
supported format string Required. The format to use when delivering the asset.

Possible values: Any supported delivery format as relevant for the file type you are delivering:

Examples

  1. Convert and deliver a JPG image in GIF format (f_gif): image format example
  2. Convert and deliver an MP4 video in webm format (f_webm):

auto

 f_auto

Automatically generates (if needed) and delivers an asset in the most 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

Examples

  1. Deliver the sample.jpg image as a WebP, AVIF or JPEG-2000, depending on the browser (or as a regular JPEG to browsers that support none of the aforementioned formats): Deliver an image with automatic format selection
  2. Deliver the dog.mp4 video as WebM (VP9) to Chrome browsers, MP4 (HEVC) to Safari browsers, or as an MP4 (H.264) to browsers that support neither of the aforementioned formats:

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

Example

Resize the height of an image to 150 pixels, while retaining the original width (c_scale,fl_ignore_aspect_ratio,h_150):

Scale in only one direction

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.

Value Type Description
mode constant Adjusts the rendering of the progressive rendering.

Possible values:

  • progressive:semi For JPG images only. Delivers the progressive image using a smart optimization of the decoding time, compression level and progressive rendering (fewer iterations).
  • progressive:steep: For JPG images only. Delivers a preview very quickly, and in a single later phase, improves the image to the required resolution.
  • progressive:none: - Do not deliver a progressive image.

Default:

  • If used in conjunction with q_auto (or if q_auto is set as the default image quality in your account settings): progressive:semi
  • If used in conjunction with q_<quality level> (or if a specific quality level is set as the default quality in your account settings): progressive:none

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.

Value Type Description
frames per second integer Required. The frames per second for the video. If a maximum frames per second value is also given, then this value is regarded as a minimum value.
maximum frames per second integer The maximum frames per second for the video.

Default: frames per second value.

Example

Set the FPS for a video to between 1 and 5 frames per second (fps_1-5):

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)

Value Type Description
compass position constant Required. The compass direction represents a location in the asset, for example, north_east represents the top right corner.

Possible values: north_east, north, north_west, west, south_west, south, south_east, east, or center.

Default: center.

Example

Crop an image to 150x150 while focusing on the north west (top left) section (c_crop,g_north_west,h_150,w_150):

Crop to 150x150 with north_west gravity

<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)

Value Type Description
special position constant Required. The position to focus on.

Note: The fallback (default) values mentioned below are relevant when setting gravity for cropping modes.

One of the following special positions:

  • cld-decompose_tile - For use on images that are composed of several images (effectively tiled), automatically detect the composite tiles of the image and make the largest tile the focus of the crop (see example).
  • face - Automatically detect the largest face in an image and make it the focus of the transformation. Defaults to north gravity if no face is detected. You can also use face:auto or face:center so that the gravity will default to auto or center if no face is detected.
  • face:center - Same as face gravity, but defaults to center gravity if no face is detected.
  • faces - Same as face gravity, but detects all the faces in an image and uses the rectangle containing all face coordinates as the basis of the transformation. Defaults to north gravity if no faces are detected. You can also use faces:auto or faces:center so that the gravity will default to auto or center if no faces are detected.
  • faces:center - Same as faces gravity, but defaults to center gravity if no face is detected.
  • liquid - uses content-aware liquid rescaling to remove 'seams' of pixels that may zig zag horizontally or vertically through the picture. Must be used with c_scale.
  • xy_center - Set the center of gravity to the given x & y coordinates.

Examples

  1. Crop an image to 150x150 while focusing on the largest face in the image (c_crop,g_face,h_150,w_150):
    Crop to 150x150 with face gravity
  2. Crop a composite image, keeping only the largest tile (c_crop,g_cld-decompose_tile): Crop to the largest tile

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

Value Type Description
algorithm
constant Image only. The algorithm to apply:

  • subject: Applies deep-learning algorithms to identify the subjects of an image that are most likely to attract a person's gaze.
  • classic: Uses a combination of saliency heuristics to automatically detect significant regions in the image.
focal gravity constant Controls which elements are given higher priority for inclusion by the cropping algorithm. This value can be:
  • One of the focal gravity options as specified for special positions (e.g.: face).
  • aoi_<custom coordinates> - an area of interest specified by custom coordinates of the form <top left x>_<top left y>_<width>_<height>.

Appending _avoid to the focal gravity minimizes the likelihood of including the specified gravity option in the crop.

Default: faces.
thumb aggressiveness integer Image only. Relevant only for 'thumb' cropping. The level of aggressiveness of the thumb cropping algorithm between 0 and 100. 100 keeps more of the original image. 0 crops more aggressively and zooms in.

Examples

  1. Automatically crop an image to a square aspect ratio, based on the areas most likely to attract a person's initial gaze. (ar_1:1,c_fill,g_auto:subject):

    Auto cropping to 1:1 aspect ratio

  2. Automatically crop an image to a square aspect ratio while focusing on the largest face in the image (ar_1:1,c_crop,g_auto:face,w_300):

    Auto cropping a to a face

  3. Automatically crop an image using custom coordinates to specify the area of interest to keep (g_auto:aoi_420_230_330_160):

    Auto cropping with custom coordinates

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)

Value Type Description
height value integer | float | constant Required. The height of the asset. Set to:

  • An integer value to set the height to the given number in pixels (e.g., 150 sets the height to exactly 150 pixels).
  • A decimal value to set the height to a multiple of the original dimension (e.g., 0.5 sets the height to half the original width).
  • ih to specify the initial height of the original image.

Examples

  1. Resize the image to a height of 150 pixels while maintaining aspect ratio (c_scale,h_150):

    Resize to a height of 150

  2. Resize the image to 30% of its original size (c_scale,h_0.3):

    Resize to 30% of original height

if (if condition)

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

Applies a transformation only if a specified condition is met.

Value Type Description
asset characteristic constant Required. The parameter representing the image or video characteristic to evaluate (e.g., w).
operator constant Required. The comparison operator for the comparison (e.g., eq for 'equal to', ne for 'not equal to', lt for 'less than', gte for 'greater than or equal to', etc.).
asset characteristic value number | string Required. A hard coded value of the characteristic or a different characteristic (e.g., 300).
directive constant Possible values:

  • else: Specifies an else branch transformation].
  • end: Specifies the end of an if condition.

Examples

  1. Apply a sharpen effect if the width is greater than 300 pixels (if_w_gt_300/e_sharpen:350/if_end):

    Apply a sharpen effect if the width is greater than 300 pixels

  2. Apply a condition if the width is less than or equal to 400 pixels then fill the image to 190x300 and add a sharpen effect, else if the width is greater than 400 pixels then fill the image to 220x180 (if_w_lte_400/c_fill,h_190,w_300/e_sharpen:350/if_else/c_fill,h_220,w_180/if_end):

    Resize and apply a sharpen effect if the width is less than or equal to 400 pixels

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.

Value Type Description
quality level integer Required. The level of quality.

Range: 1 to 100.

quant value integer Videos only. The maximum quantization value, used when transcoding to WEBM (VP8/9). Helps to ensure that the video is not over-quantized.

Range: 1 to 100. Default: 100.

chroma constant The chroma subsampling setting.

Possible values:

  • 420 - forces subsampling
  • 444 - prevents subsampling.

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

Examples

  1. Deliver an image of the highest quality (9.15KB) (q_100): Highest quality image of flowers
  2. Deliver a low quality image (1.48KB) (q_20): Low quality image of flowers
  3. Deliver a 60% quality image while forcing chroma subsampling (1.2KB) (q_60:420): Mid quality image of flowers with chroma subsampling
  4. Transcode the first 30 seconds of a video to WEBM with 70% quality, setting the maximum quantization to 20% (f_webm/q_70:qmax_20):

auto

 q_auto[:<quality type>]

Delivers an asset with an automatically determined level of quality.

Learn more: Automatic quality

Value Type Description
quality type constant The type of automatic quality.

Possible values:

  • best: Ensures the best visual quality, using a less aggressive algorithm
  • good: Ensures optimal visual quality without affecting its perceptual quality
  • eco: Ensures a smaller file size using a more aggressive algorithm
  • low: Ensures the smallest file size using the most aggressive algorithm

Default: good.

Examples

  1. Automatically deliver a high quality image (2.2KB) (q_auto:best): High quality image of flowers
  2. Automatically deliver the optimal quality for an image: the smallest file size without affecting its visual quality (1.9KB) (q_auto:good): Good quality image of flowers
  3. Automatically deliver a good quality image at a lower file size (1.7KB) (q_auto:eco): Mid quality image of flowers
  4. Automatically deliver a small-sized image with low quality (1.5KB) (q_auto:low): Low quality image of flowers

t (named transformation)

 t_<transformation name>

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

Learn more: Creating a named transformation

Value Type Description
transformation name string Required. The name of the pre-defined transformation to use.

Example

Apply the custom_example named transformation to the image (t_custom_example). The underlying transformation is b_black,c_pad,h_150,w_150/f_auto/q_auto:

Flowers with black padding added

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.

Value Type Description
codec value constant Required. The video codec.

Possible values:h264, h265, av1, prores (422HQ),theora, vp8, vp9.

profile constant The profile to use with the h264 codec.

Possible values: baseline, main, high, high444, auto (required when specifying bframes).

Default: high. 1

level constant The level to use with the h264 codec and specified profile.

Possible values: 3.0, 3.1, 4.0, 4.1, 4.2, 5.0, 5.1, 5.2, auto (required when specifying bframes).

Default: 3.1.

bframes constant Whether to include b-frames with the video. Can be disabled for videos with the h265 codec.

Possible values: no.

Default: b-frames are enabled by default so this value should be omitted unless disabling b-frames.

Example

Set the video codec to h264, the profile to baseline and the level to 3.1 (vc_h264:baseline:3.1):

Set the video codec to h265 and disable b-frames (vc_h265:auto:auto:bframes_no):

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
FLV h264 high auto:good aac 22050

Example

Normalize the MP4 video for web with the default settings (vc_auto):


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)

Value Type Description
width value integer | float | constant Required. The width of the asset. Set to:

  • An integer value to set the width to the given number in pixels (e.g., 150 sets the width to exactly 150 pixels).
  • A decimal value to set the width to a multiple of the original dimension (e.g., 0.5 sets the width to half the original width).
  • iw to specify the initial width of the original image.

Examples

  1. Resize the image to a width of 100 pixels while maintaining aspect ratio (c_scale,w_100):

    Resize to a width of 100

  2. Resize the image to 50% of its original width (c_scale,w_0.5):

    Resize to 50% of original width

auto

A qualifier that determines how to automatically resize an image to match the width available for the image in a responsive layout. The parameter can be further customized by overriding the default rounding step.

 w_auto[:<rounding step>][:<fallback width>]

The width is rounded up to the nearest rounding step (every 100 pixels by default) in order to avoid creating extra derived images and consuming too many extra transformations. Only works for certain browsers and when Client-Hints are enabled.

Use with: c_scale

Value Type Description
rounding step integer Sets a new value for the rounding step (e.g.: 50).

Default: 100

fallback width integer The width to use in the case the actual width cannot be retrieved from the Client-Hints header (e.g.: 500).

Default: Not set

Example

The HTML tag to deliver an image automatically scaled to the maximum width available (sizes=100vw) for the image (c_scale,w_auto):

Copy to clipboard
<img 
    src="https://demo-mo-docs.mo.cloudinary.net/no_transform/cld-docs-assets/assets/images/sample.jpg?tx=c_scale,w_auto"
    sizes="100vw"  />

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>

Value Type Description
coordinate value pixels | float (percentage) The starting location or offset for custom-coordinates based cropping. Specify as a number of pixels or as a float value corresponding to a percentage in relation to 1.0. For example 0.8 is equal to a 80%.

Default: 0.

Examples

  1. Crop the image using x and y coordinates to define the starting location (c_crop,h_150,w_150,x_80,y_30). Coordinates based cropping

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.

Value Type Description
zoom amount float (percentage) The amount of zoom to apply when cropping around the detected coordinates of faces or custom regions. Specify as a float value corresponding to a percentage, where 1.0 instructs to crop to the detected coordinates. Values less than one will result in a crop outside the coordinates (zoom out) and values greater than one will crop closer than the coordinates (zoom in). For example 0.8 represents a zoom amount of 80%.

Default: 1.0.

Examples

  1. Generate a 150*150 square thumbnail image using face detection with a zoom amount of 75% (c_thumb,g_face,h_150,w_150,z_0.75). Thumbnail crop with zoom of 75%
  2. Crop the image based on the detected coordinates of the face, but zoom in to 120% (c_crop,g_face,z_1.2). Face detection crop with zoom of 120%

$ (variable)

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

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

Value Type Description
variable name string Required. The name of variable.
variable value constant | float | integer | string Required only when setting a variable. The value of variable.

Example

Set the variables $widthval to 200, and $arval to 0.8 ($widthval_200/$arval_0.8). Then set the aspect ratio parameter to the $arval value and the width parameter to the $widthval value (ar_$arval,...,w_$widthval), with face-based fill cropping:

Set width and aspect ratio using variables

✔️ Feedback sent!

Rate this page: