Eager and incoming transformations

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

• Eager transformations: Warm up your cache by generating transformed assets during an upload call or on existing assets so that those transformations will already be available for delivery before your users access them for the first time. When used on upload, these transformations are generated in addition to storing the original asset. This is especially useful for transformations that require a lot of processing or for long videos 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 when uploading or updating an asset, as eager transformations. Eager transformations are used to warm up your cache and are generated in addition to the originally uploaded asset. You can request multiple eager transformations during a single upload command or while updating an existing asset.

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 the processing required for 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. Alternatively, you can generate them for existing assets using the explicit methods. 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).

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.

Eager transformations on upload

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:

Eager transformations on existing assets

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

The most common usage of this method is to eagerly generate transformations for assets that have already been uploaded, either so that they do not need to be generated on the fly when first accessed by users, or because Strict transformations are enabled for your product environment and you cannot create transformed assets on the fly. You can also use this method to pre-generate transformations for remotely fetched assets.

The following example generates transformations for the already uploaded image with a Public ID of docs/camera as follows:

1. Crop to a width and height of 400 pixels including the biggest face detected.
2. Pad to a width of 660 pixels and a height of 400 pixels with a blue background.

The delivery URLs for these eagerly generated transformations:

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, and f_webp,fl_awebp, while setting the format parameter (that controls the URL file extension) to an empty string:

Response:

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

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.

You can specify any supported image or video transformation parameter 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.

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