Transformation URL API reference

Last updated: Jan-26-2023

So, what do you think?

We're super excited about this totally revamped version of the URL transformation reference, which provides comprehensive syntax details and examples for every supported image and video transformation in one place.

But most important is what you think!

After you've played around, please use the Rate this page option (just below the On this page list) to both rate the page and send us feedback on what you like as well as sharing your ideas for how to make it even better!

The Transformation URL API enables you to deliver media assets, including a large variety of on-the-fly transformations through the use of URL parameters. This reference provides comprehensive coverage of all available URL transformation parameters, including syntax, value details, and examples.

On this page:

Overview

The default Cloudinary asset delivery URL has the following structure:

https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<version>/<public_id_full_path>.<extension>

This reference covers the parameters and corresponding options and values that can be used in the <transformations> element of the URL. It also covers the <extension> element.

For information on other elements of the URL, see Transformation URL syntax.

Important

The transformation names and syntax shown in this reference refer to the URL API.

Depending on the Cloudinary SDK you use, the names and syntax for the same transformation may be different. Therefore, all of the transformation examples in this reference also include the code for generating the example delivery URL from your chosen SDK.

The SDKs additionally provide a variety of helper methods to simplify the building of the transformation URL as well as other built-in capabilities. You can find more information about these in the relevant SDK guides.

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.

See the Transformation Guide for additional guidelines and best practices regarding parameter types.

.<extension>

 

Although not a transformation parameter belonging to the <transformation> element of the URL, the extension of the URL can transform the format of the delivered asset, in the same way as f_<supported format>.

If f_<supported format> or f_<auto> are not specified in the URL, the format is determined by the extension. If no format or extension is specified, then the asset is delivered in its originally uploaded format.

  • If using an SDK to generate your URL, you can control the extension using the format parameter, or by adding the extension to the public ID.
  • If using a raw transformation, for example to define an eager or named transformation, you can specify the extension at the end of the transformation parameters, following a forward slash. For example, c_pad,h_300,w_300/jpg means that the delivery URL has transformation parameters of c_pad,h_300,w_300 and a .jpg extension. c_pad,h_300,w_300/ represents the same transformation parameters, but with no extension.

Note
As the extension is considered to be part of the transformation, be careful when defining eager transformations and transformations that are allowed when strict transformations are enabled, as the delivery URL must exactly match the transformation, including the extension.

a (angle)

 

Rotates or flips an asset by the specified number of degrees or automatically according to its orientation or available metadata. Multiple modes can be applied by concatenating their values with a dot.

Learn more: Rotating images | Rotating videos

<degrees>

 a_<degrees>

Rotates an asset by the specified angle.

See also: Arithmetic expressions

<mode>

 a_<mode>

Rotates an image based on the specified mode.

ac (audio codec)

 ac_<codec value>

Sets the audio codec.

af (audio frequency)

 af_<frequency value>

Controls the audio sampling frequency.

As a qualifier, can be used to preserve the original frequency, overriding the default frequency behavior of vc_auto.

As a qualifier, use with: vc_auto

Learn more: Audio frequency control

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)

Learn more: Setting the resize dimensions

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

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, text overlays and generated waveform images.

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

Learn more: Background color for images | Background color for videos

auto

 b_auto[:<mode>][:<number>][:<direction>][:palette_<color 1>[_..._<color n>]]

A qualifier that automatically selects the background color based on one or more predominant colors in the image, for use with one of the padding crop mode transformations.

Learn more: Content-aware padding

Use with: c_pad | c_lpad | c_mpad | c_fill_pad

blurred

 b_blurred[:<intensity>][:<brightness>]

A qualifier that generates a blurred version of the same video to use as the background with the corresponding padded cropping transformation.

Use with: c_pad | c_fill_pad

Learn more: Pad with blurred video background

bo (border)

 bo_<width>_<style>_<color>

Adds a solid border around an image or video.

As a qualifier, adds a border to an overlay.

Use with: l_<image id> | l_fetch | l_subtitles | l_text | l_video

Learn more: Adding borders

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

Learn more: Bitrate control

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 images | Resizing and cropping videos

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 ocr_text), AI-based automatic region detection or AI-based object 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)

(In rare cases, you may choose to provide only one sizing qualifier)

Optional qualifiers

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

fill

 c_fill

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

(In rare cases, you may choose to provide only one sizing qualifier)

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)

(In rare cases, you may choose to provide only one sizing qualifier)

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)

(In rare cases, you may choose to provide only one sizing qualifier)

imagga_crop

 c_imagga_crop

Requires the Imagga Crop and Scale add-on.
The Imagga Crop and Scale add-on can be used to smartly crop your images based on areas of interest within each specific photo as automatically calculated by the Imagga algorithm.

Required qualifiers

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

Optional qualifiers

ar (aspect_ratio)

imagga_scale

 c_imagga_scale

Requires the Imagga Crop and Scale add-on.
The Imagga Crop and Scale add-on can be used to smartly scale your images based on automatically calculated areas of interest within each specific photo.

Required qualifiers

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

(In rare cases, you may choose to provide only one sizing qualifier)

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)

(In rare cases, you may choose to provide only one sizing qualifier)

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)

(In rare cases, you may choose to provide only one sizing qualifier)

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)

(In rare cases, you may choose to provide only one sizing qualifier)

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)

(In rare cases, you may choose to provide only one sizing qualifier)

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)

(In rare cases, you may choose to provide only one sizing qualifier)

Optional qualifiers

g_<gravity position> | b (background)