Placing layers on images

Cloudinary allows you to dynamically add layers to specific locations within your images, where the new layers are added over the base image as overlays, and can also be easily transformed to suit your needs. There are multiple options for adding a new layer to a base image, either an image uploaded to Cloudinary, a remote image, or a text string.

Image layers can also be added as underlays instead, and there are special layer applications for using layers in combination with other Cloudinary transformations.

Here are examples of some popular use cases that you can accomplish using layers (combined with other transformations). Click each image to see the URL parameters applied in each case:

Brand or watermark
your images Hide all
detected faces Add personalized
text Displace images
on products

This page covers the layer syntax and the overlay types you can apply. To learn how to position layers, see Layer placement. For text options, see Text layer options. For transformations and relative sizing, see Transforming layers. For underlays, watermarking, and special effects, see Underlays, watermarking, and special effects.

Layer transformation syntax

In its most simple form, adding a layer over the base image takes following URL syntax:

The layer parameter is in its own URL component and starts the overlay definition (similar to an open bracket). The layer_apply flag is in a separate component that closes the definition (similar to a closing bracket) and instructs Cloudinary to place it.

You can enhance your layer both by controlling where and how it's placed on the base image using gravity, offset and other placement qualifiers, and by applying transformations to the layered asset, using the following general URL syntax.

Authenticated or private layers

You can add image overlays that are set to authenticated or private by modifying the syntax:

• For private layers: l_private:<public_id of layer>
• For authenticated layers: l_authenticated:<public_id of layer>

Image overlays

The default overlay type is an image. For example, adding an overlay of a logo to a base image (l_docs:logo-semi-opaque/fl_layer_apply):

See full syntax: l_<image id> in the Transformation Reference.

Try it out: Layers.

Remote image overlays

Use a remote image (an image not stored in your Cloudinary product environment) as an overlay by adding the fetch (or url for some SDKs) property of the layer parameter ( l_fetch: in URLs) and the base64 encoded URL of the remote image.

The general URL syntax for adding a remote image as an overlay takes the following form:

For example, adding an overlay of the remote image https://res.cloudinary.com/demo/image/upload/logos/cloudinary_icon_white.png to the base image.

See full syntax: l_fetch in the Transformation Reference.

Text overlays

Add a text overlay over the base image with the text property of the layer parameter ( l_text: in URLs). The parameter also requires specifying font family and size (separated with an underscore and followed by a colon), and the text string to display. The general URL syntax for adding a text layer takes the following form:

In addition to the required font and size styling values, you can optionally specify a variety of other CSS-like styling parameters and to further customize your text layers by specifying text color, adding line breaks, emojis and other special characters, and other text layer options.

Cloudinary first generates an image from the text definition and then overlays it like any other image overlay, and thus supports all the same transformations that any image overlay supports.

For example, to overlay the text string "Coffee" in the Arial font with a size of 80 pixels (l_text:Arial_80:Coffee/fl_layer_apply):

See full syntax: l_text in the Transformation Reference.

Try it out: Layers.