Documentation Index

Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt

Use this file to discover all available pages before exploring further.

Image & Video APIs
Menu

Specifying transformations for a condition

Last updated: Jun-09-2026

A conditional transformation embeds a transformation directly within a condition in your URL or SDK call, using the format if_condition/transformation/if_end. The condition and its transformation are part of the same expression and aren't defined separately. For details on the conditions themselves, see Specifying conditions.

This page covers how to structure the transformation part of the expression, including chained transformations, with worked examples.

On this page:

Conditional transformation syntax

The transformation for a condition should be specified between the condition component and an if_end component in the format:

if_condition/transformation/if_end

For example:

if_ar_lt_1.0/b_darkorange,c_pad,h_300,w_500/if_end

In the following examples, both videos are scaled to a width of 500px. Afterwards, the identical conditional padded-resize transformation shown above is applied to both videos. However, since the condition applies only for portrait videos (those with an aspect ratio less than 1.0) the resizing and padding is applied only to the parrot video below:

Note

Transformation URLs technically support defining both the condition and a single resulting transformation inside a single transformation component (without the need for a closing end_if). However, to avoid ambiguity, the best practice is to always use if and if_end components in your URL as shown above.

  • Some SDKs require this separation and automatically generate URLs in the if...end_if format.
  • A named transformation cannot be placed in the same transformation component as its condition (e.g., if_w_eq_h,t_trans is not supported) and must be specified using the if...if_end format.
  • If you do include both the if condition and the resulting transformation parameters within a single component of the URL, the if condition is evaluated first, regardless of its location within the component and (only) when the condition is true, all transformation parameters specified in that component are applied.

Conditions with chained transformations

You can apply multiple chained transformations to your condition by including the entire chained transformation in between the if and if_end components.

The example below checks whether the video asset's tags include a 'cloudinary' tag. Only in that case, a chained transformation including an image overlay (Cloudinary logo) and a text overlay ('By Cloudinary') are applied. If 'cloudinary' is not one of the tags, no image or text overlay is applied.

Note that this example also includes a scale-down transformation before the beginning of the conditional transformation and a duration trim after the end of the conditional transformation. Those transformations are applied regardless of the true or false result of the condition.

Conditional transformation examples

  • Conditional text overlay based on width: This example limits a video size to a width of 300 pixels using the limit crop mode, and then uses a conditional transformation to add a text caption only to videos whose initial width was wider than 300 and were scaled down (if_iw_gt_300):

  • Conditional resize based on a contextual metadata value: This example resizes a video to a 200*200 square video if it has a contextual metadata key named 'productType' with the value 'shoes'.

  • Conditional image overlay based on tags: This example adds a sale icon to a product video if both the strings 'sale' and 'in_stock' are among the tags assigned to the video:

  • Conditional image overlay based on structured metadata value: This example adds a sale icon to a product video if the stock level of the product is less than 50 (as determined by the value of the numeric structured metadata field with external ID, stock-level, here set as 30):

Note
When you use variable or conditional expressions that include the tags, ctx or md parameters, their values are exposed publicly in the URL. If you want to prevent such values from being exposed, you can disable the Usage of tags/context/metadata in transformation URLs option in the Security Settings (enabled by default). When this setting is disabled, any URL that exposes tags, contextual metadata or structured metadata values will return an error.

Related topics

✔️ Feedback sent!

Rate this page:

one star two stars three stars four stars five stars