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

Layer placement

Last updated: Jul-28-2026

This page covers how to position and arrange layers on videos. For the layer syntax itself, see Layer syntax. For transformations and relative sizing, see Transforming layers.

The fl_layer_apply flag

The fl_layer_apply component not only acts as the closing bracket for the layer, but is also used to include any options that will control how the layer is placed on the base video, and any details regarding the relationship between the overlay element and the base video.

Note
Some Cloudinary SDKs use layer apply flags as described, and any placement qualifiers must also be the last component of the layer transformation. However some of the Cloudinary SDKs don't use a specific layer apply flag. Instead, when the SDK generates the transformation URL from your code, it automatically adds the fl_layer_apply flag together with placement qualifiers based on the transformation hierarchy in your SDK code.

Positioning layers with gravity

To determine the position of the new layer, you can add the gravity parameter to define the location to place the layer within the base video ('center' by default). The gravity parameter is added in the same component as the layer_apply flag.

For example, to add an image overlay to the base video with gravity set to west (l_lotus_layer/fl_layer_apply,g_west):

To fine-tune the exact location of the layer, you can offset the overlay from the focus of gravity by also adding the x and y coordinate offset parameters. These parameters accept either integer values representing the number of pixels to adjust the overlay position in the horizontal or vertical directions, or decimal values representing a percentage-based offset relative to the containing video (e.g., 0.2 for an offset of 20%).

For example, to place a text overlay at a vertical distance of 5% from the top of the video (l_text:Roboto_400:Paradise/fl_layer_apply,g_north,y_0.05):


The direction of x and y depends on the compass position:

Compass position Positive x Positive y Negative x Negative y
center, north_west, north, west right down left up
north_east, east left down right up
south_east left up right down
south, south_west right up left down

Tip
See the Positioning with Gravity interactive demo to experiment with gravity and coordinate parameters.


Related topics

✔️ Feedback sent!

Rate this page:

one star two stars three stars four stars five stars