Programmable Media

Transformations on upload

Last updated: Feb-19-2024

Cloudinary's transformations can be used while uploading an asset in one of two ways:

  • Eager transformations: Generate transformed assets during the upload call so that those transformations will already be available for delivery before your users access them for the first time. These transformations are generated in addition to storing the original asset as is. This is especially useful for transformations that can take a while to generate.
  • Incoming transformations: Transform the original asset before storing it in Cloudinary. This can be useful for example to limit images to a maximum resolution or videos to a maximum duration.

Eager transformations

Cloudinary can either transform your assets on demand, when first accessed by your visitors as 'lazy transformations', or during the asset upload process as eager transformations. Eager transformations are generated in addition to storing the original asset as is and you can request multiple eager transformations during a single upload command.

When transforming on demand during delivery, all transformed assets are generated on the fly, stored persistently, cached and delivered through a fast CDN. The time required for generating a transformation depends on various factors: original asset dimensions, asset file size, requested dimensions, applied effects and specific transformations. Once generated for the first time on the first request of a visitor, the transformed asset is henceforth cached and delivered through a fast CDN for all subsequent requests.

The eager approach requires a little planning, but is recommended if you want to make sure that all transformed assets are ready for fast delivery even for the first visitors to your assets. This is especially useful for video transformations, transformations that perform AI analyses, or other asynchronous operations, such as those performed by some Cloudinary add-ons.

For these cases, you can eagerly generate the required transformations during the upload process so all transformed assets will already be available before your users access them for the first time. Eager transformations are also useful in the case that you want to enable Strict Transformations and limit access to dynamic URLs (for more information, see Control access to assets).

Note
New derived assets are created if the URL differs in any way, even if the delivered result is the same. For example:
  • If the order of the transformation parameters changes. For example, w_300,c_scale is considered a different transformation to c_scale,w_300, even though the delivered media looks the same.
  • If the file extension is different. For example, .jpg is considered a different transformation than .jpeg, or a JPEG file with no extension specified, even though a JPEG file is the delivered format in each case.
  • Whether or not the file format is specified as a transformation. For example, specifying f_jpg as a transformation parameter for a JPEG file is considered a different transformation than delivering the same transformation with a .jpg extension, even though a JPEG file is delivered in each case.

The eager parameter accepts either a single transformation or an array of transformations, where each transformation is represented by a hash of transformation parameters.

For details on all available transformation parameters, see the Transformation URL API Reference.

Note
When using the REST API rather than an SDK, the eager parameter receives a list of transformation strings separated with a pipe character (|). Chained transformations are separated with a slash (/). For example, the following eager value will generate 3 transformations:
  • Crop out a 400x400 region centered on the largest detected face
  • Scale down to a width and height of 500 pixels
  • Crop out a 300x300 region with south gravity

For more details, see Uploading with a direct call to the REST API.

The following example uploads the sample.jpg image and then additionally generates two transformed images:

  1. Pad to a width of 400 pixels and height of 300 pixels.
  2. Crop to a width of 260 pixels and a height of 200 pixels with north gravity.

The delivery URLs for these eagerly generated transformations:

You can also generate eager transformations for previously uploaded assets using the explicit API method.

Tip
You can create an upload preset with the eager parameter and apply the preset to the upload.

Using automatic format in eager transformations

Although it is possible to specify f_auto in an eager transformation, doing so does not eagerly generate derived assets for all formats, as the automatic format parameter is converted to the relevant formats on the CDN level based on the requesting browser. Therefore, to ensure you have all format variants available in advance, you need to eagerly generate every possible transformation that could replace f_auto.

As the extension is counted as part of the transformation, it is best practice not to include an extension in your delivery URLs, otherwise you would have to generate eager transformations not only for the f parameter, but also for the extension.

This is an example of a URL using f_auto without an extension:

Thus, instead of generating an eager transformation with f_auto in the URL, you need to generate an eager transformation for each of the formats that are enabled for f_auto on your account. The following example specifies f_avif, f_jp2 and f_webp,fl_awebp, while setting the format parameter (that controls the URL file extension) to an empty string:

Response:

Note
Even for still WebP images, the animated WebP flag is required, to match the parameter replacement performed on the CDN.

To use f_auto for videos, the eagerly generated transformations need to include fetch_format and video_codec, as follows:

Notes
  • If only the fetch_format parameter is specified, without the format parameter, then the URL is automatically generated with a file extension according to the format used when the eager transformation is generated. This results in URLs that differ both in the f parameter and the extension, so it would be impossible to specify one delivery URL using f_auto that would work for all of the eagerly generated transformations. Thus providing the empty value for the format parameter is required.
  • If applying other transformations, you need to include those in your eager transformations too, including the default quality parameter that is applied automatically.
  • Be aware that the order of parameters is important - the request URL that you deliver must exactly match the eagerly generated URL. When using an upload preset or an SDK for the eager generation, parameters within a transformation component are alphabetized, for example, f_mp4,q_auto,vc_h264, or, for newer SDKs, split into different components, for example, vc_h264/f_mp4/q_auto.

Eager asynchronous transformations

You can tell Cloudinary to generate eager transformations in the background by setting the eager_async parameter to true. This is useful when you use direct uploading from the browser and you don't want your users to have to wait for the transformation(s) to finish processing. In addition, you can set the optional eager_notification_url parameter to receive a webhook notification when the transformation generation is completed. For details, see Notifications.

The upload method supports the following parameters for eager asynchronous transformations:

  • eager - A list of transformations to create for the uploaded asset during the upload process, instead of lazily generating them when first accessed by your site's visitors. This option accepts either a single transformation or an array of transformations, where each transformation is represented by a hash of parameters. For details on available transformation parameters, see the Transformation URL API Reference.
  • eager_async - A Boolean value determining whether to generate the eager transformations asynchronously in the background after the file is finished uploading or synchronously as part of the upload call. Default: false.
  • eager_notification_url - An HTTP or HTTPS URL to notify your application (a webhook) when the generation of eager transformations is completed. If a transformation fails for some reason, the response includes "state=failed" and the reason.

For example, the following method will upload the sample.jpg image and then eagerly generate two transformed images as follows:

  1. Pad to a width and height of 300 pixels.
  2. Crop to a width of 160 pixels and a height of 100 pixels with south gravity.

Furthermore, the transformations will be performed asynchronously after the file finishes uploading, with a callback URL to notify your application once the upload is complete and a different callback URL to notify your application once the transformations are complete:

Eager notification response

When the eager transformations are completed, an HTTP POST request will be sent to the eager notification webhook URL you provided, with details about the requested eager transformations including the HTTP and HTTPS URLs for accessing the derived assets. For example:

For more information on Eager notification URLs and responses, see the Notifications documentation.

Incoming transformations

By default, assets uploaded to Cloudinary are stored as-is. During or after the upload, you can generate a variety of derived assets from these originals by asking Cloudinary to apply transformations.

In most cases, you'll probably want to store your originals without any changes. However, in some cases, you may want to modify the original assets before storing them by applying an incoming transformation as part of the upload request. Contrary to eager transformations, incoming transformations are applied before storing the asset in Cloudinary. This is especially useful to normalize user-generated content, for example to limit the resolution size or clip a long video to a maximum duration.

Any supported image or video transformation parameter can be specified for your incoming transformation using the transformation parameter. This parameter accepts either a single transformation or an array of transformations, where each transformation is represented by a hash of transformation parameters.

For details on all available transformation parameters, see the Transformation URL API Reference.

Notes
  • When using the SDK for a dynamically-typed language, the transformation parameters can be specified directly, without explicitly specifying the transformation parameter, as seen for example in the examples below for Node.js, Python, PHP, and Ruby.
  • To ensure that all file and layer data is completely preserved in your stored image, do not apply any incoming transformations when uploading PSD, TIFF or other image formats containing layers.

For example, to limit the dimensions of an uploaded image to a width of 2000 pixels and a height of 1000 pixels:

✔️ Feedback sent!

Rate this page: