Placing layers on images
Last updated: Dec-28-2022
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:

your images

detected faces

text

on products
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 is 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.
l_<public_id of layer>/<optional layer transformations>/fl_layer_apply,<optional placement qualifiers>
Image overlays
The default overlay type is an image. For example, adding an overlay of the image called cloudinary_icon_blue to a base image (l_cloudinary_icon_blue/fl_layer_apply
):

- If the public ID of an image includes slashes (e.g., the public ID of an image is
animals/dog
), replace the slashes with colons when using the image as an overlay (e.g., the public ID of the overlay image becomesanimals:dog
when used as an overlay). - When delivering public images, you can only add images overlays that are also set as public assets. Assets set to
authenticated
orprivate
using theaccess_mode
parameter can also only use public images as overlays. See the Media access control documentation for more details on delivering private and authenticated assets.
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:
l_fetch:<URL of overlay>/<optional transformations>/fl_layer_apply,<optional placement qualifiers>
For example, adding an overlay of the remote image https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png
to the base image.
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setOverlay("fetch:aHR0cHM6Ly9yZXMuY2xvdWRpbmFyeS5jb20vZGVtby9pbWFnZS91cGxvYWQvbG9nb3MvY2xvdWRpbmFyeV9mdWxsX2xvZ29fd2hpdGVfc21hbGwucG5n").chain() .setFlags("layer_apply")).generate("sample.jpg")!, cloudinary: cloudinary)

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:
l_text:<text styling options>/<optional transformations>/fl_layer_apply,<optional placement qualifiers>
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 "Flowers" in the Arial font with a size of 80 pixels (l_text:Arial_80:Flowers/fl_layer_apply
):

Layer placement
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 image, and any details regarding the relationship between the overlay element and the base image.
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 image ('center' by default). The gravity
parameter is added in the same component as the layer_apply
flag.
For example, to add an overlay of the image called cloudinary_icon_white
to the base image with gravity set to west (l_cloudinary_icon_white/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 image (e.g., 0.2 for an offset of 20%).
For example, to place a text overlay at a vertical distance of 5% from the bottom of the image (l_text:Times_100:Welcome/fl_layer_apply,g_south,y_0.05
):

Overlays on special positions
The gravity parameter can also be set to a custom region within an image, which becomes the focus when placing the overlay. These 'special positions' are locations within the image that are either automatically detected by Cloudinary (e.g., a face), custom coordinates that were previously specified (e.g., as part of the image upload method), or detected by one of the Cloudinary add-ons (e.g., eyes or text within the image).
For a full list of all the special positions available to use for placing overlays with the gravity parameter, see the <special position> section in the transformation reference guide.
For example:
Add an overlay of the
golden_star
image over all faces detected in thecouple
image:url:Ruby (cloudinary 1.x):PHP (cloudinary_php 2.x):PHP (cloudinary_php 1.x (legacy)):Python (cloudinary 1.x):Node.js (cloudinary 1.x):Java (cloudinary 1.x):JS (@cloudinary/url-gen 1.x):JS (cloudinary-core 2.x (legacy)):jQuery (cloudinary-jquery 2.x):React (@cloudinary/react 1.x):React (cloudinary-react 1.x):Vue.js (@cloudinary/vue 1.x):Vue.js (cloudinary-vue 1.x (legacy)):Angular (@cloudinary/ng 1.x):Angular (@cloudinary/angular-5.x 1.x (legacy)):.NET (CloudinaryDotNet 1.x):iOS (cloudinary 3.x):Android (cloudinary-android 1.x):Kotlin (kotlin-url-gen 1.x):Flutter (cloudinary_flutter 0.x):Dart (cloudinary_dart 0.x):Use the OCR Text Detection and Extraction add-on to add an overlay with your site's contact information that covers any detected text in an uploaded image:
url:Ruby (cloudinary 1.x):PHP (cloudinary_php 2.x):PHP (cloudinary_php 1.x (legacy)):Python (cloudinary 1.x):Node.js (cloudinary 1.x):Java (cloudinary 1.x):JS (@cloudinary/url-gen 1.x):// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sale_sign.jpg").overlay( source( image("call_text").transformation( new Transformation().resize(scale().width(1.1).regionRelative()) ) ).position(new Position().gravity(focusOn(ocr()))) );
JS (cloudinary-core 2.x (legacy)):jQuery (cloudinary-jquery 2.x):React (@cloudinary/react 1.x):// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sale_sign.jpg").overlay( source( image("call_text").transformation( new Transformation().resize(scale().width(1.1).regionRelative()) ) ).position(new Position().gravity(focusOn(ocr()))) );
React (cloudinary-react 1.x):Vue.js (@cloudinary/vue 1.x):// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sale_sign.jpg").overlay( source( image("call_text").transformation( new Transformation().resize(scale().width(1.1).regionRelative()) ) ).position(new Position().gravity(focusOn(ocr()))) );
Vue.js (cloudinary-vue 1.x (legacy)):Angular (@cloudinary/ng 1.x):// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sale_sign.jpg").overlay( source( image("call_text").transformation( new Transformation().resize(scale().width(1.1).regionRelative()) ) ).position(new Position().gravity(focusOn(ocr()))) );
Angular (@cloudinary/angular-5.x 1.x (legacy)):.NET (CloudinaryDotNet 1.x):iOS (cloudinary 3.x):imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setOverlay("call_text").chain() .setFlags("region_relative").setWidth(1.1).setCrop("scale").chain() .setFlags("layer_apply").setGravity("ocr_text")).generate("sale_sign.jpg")!, cloudinary: cloudinary)
Android (cloudinary-android 1.x):Kotlin (kotlin-url-gen 1.x):Flutter (cloudinary_flutter 0.x):Dart (cloudinary_dart 0.x):
You may also want to position an overlay ensuring that it avoids a special position. See Position overlays avoiding detected faces for an example of how to achieve this.
- When gravity is set to one of the special position values, and no special position is detected in the image, then no overlay is placed at all.
- Instead of specifying an absolute width for overlays, you can use the fl_region_relative flag to place each overlay relative to the size of each detected region.
Layer overflow behavior
By default, if a layer (image or text) has a larger width or height than the base image, the delivered image canvas is resized to display the entire layer. If you want to ensure that the delivered size will never be larger than the base image, you can use the fl_no_overflow
flag in the same component as the layer_apply
flag.
For example, the no_overflow
flag prevents the logo overlay from extending the canvas of the base image (c_scale,w_400/l_cloudinary_icon_blue/fl_layer_apply,fl_no_overflow
):

Layer transformations
You can apply resizing and other transformation options on your overlays just like any other asset delivered from Cloudinary. You can apply multiple (chained) transformations to overlays by adding them in separate components before the layer_apply
component. All chained transformations, until a transformation component that includes the layer_apply
flag, are applied on the last added overlay or underlay instead of applying them on the base asset (the layer_apply
flag closes the layer, similar to a closing bracket).
For example:
Adding an overlay of the image called
cloudinary_icon_blue
, scaled down to 50% of its original width and made into a watermark by reducing the opacity to 70% and increasing the brightness to 50% using thebrightness
effect. The transformed image is then placed as a layer in the top-right corner of the base image (l_cloudinary_icon_blue/c_scale,w_0.5/o_70/e_brightness:50/fl_layer_apply,g_north_east
):url:Ruby (cloudinary 1.x):PHP (cloudinary_php 2.x):(new ImageTag('sample.jpg')) ->overlay(Overlay::source( Source::image("cloudinary_icon_blue") ->transformation((new Transformation()) ->resize(Resize::scale()->width(0.5)) ->adjust(Adjust::opacity(70)) ->adjust(Adjust::brightness()->level(50))) ) ->position((new Position()) ->gravity( Gravity::compass( Compass::northEast())) ) );
PHP (cloudinary_php 1.x (legacy)):Python (cloudinary 1.x):Node.js (cloudinary 1.x):Java (cloudinary 1.x):JS (@cloudinary/url-gen 1.x):// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sample.jpg").overlay( source( image("cloudinary_icon_blue").transformation( new Transformation() .resize(scale().width(0.5)) .adjust(opacity(70)) .adjust(brightness().level(50)) ) ).position(new Position().gravity(compass("north_east"))) );
JS (cloudinary-core 2.x (legacy)):jQuery (cloudinary-jquery 2.x):React (@cloudinary/react 1.x):// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sample.jpg").overlay( source( image("cloudinary_icon_blue").transformation( new Transformation() .resize(scale().width(0.5)) .adjust(opacity(70)) .adjust(brightness().level(50)) ) ).position(new Position().gravity(compass("north_east"))) );
React (cloudinary-react 1.x):Vue.js (@cloudinary/vue 1.x):// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sample.jpg").overlay( source( image("cloudinary_icon_blue").transformation( new Transformation() .resize(scale().width(0.5)) .adjust(opacity(70)) .adjust(brightness().level(50)) ) ).position(new Position().gravity(compass("north_east"))) );
Vue.js (cloudinary-vue 1.x (legacy)):<cld-image public-id="sample.jpg" > <cld-transformation :overlay="cloudinary_icon_blue" /> <cld-transformation width="0.5" crop="scale" /> <cld-transformation opacity="70" /> <cld-transformation effect="brightness:50" /> <cld-transformation flags="layer_apply" gravity="north_east" /> </cld-image>
Angular (@cloudinary/ng 1.x):// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sample.jpg").overlay( source( image("cloudinary_icon_blue").transformation( new Transformation() .resize(scale().width(0.5)) .adjust(opacity(70)) .adjust(brightness().level(50)) ) ).position(new Position().gravity(compass("north_east"))) );
Angular (@cloudinary/angular-5.x 1.x (legacy)):<cl-image public-id="sample.jpg" > <cl-transformation overlay="cloudinary_icon_blue"> </cl-transformation> <cl-transformation width="0.5" crop="scale"> </cl-transformation> <cl-transformation opacity="70"> </cl-transformation> <cl-transformation effect="brightness:50"> </cl-transformation> <cl-transformation flags="layer_apply" gravity="north_east"> </cl-transformation> </cl-image>
.NET (CloudinaryDotNet 1.x):iOS (cloudinary 3.x):imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setOverlay("cloudinary_icon_blue").chain() .setWidth(0.5).setCrop("scale").chain() .setOpacity(70).chain() .setEffect("brightness:50").chain() .setFlags("layer_apply").setGravity("north_east")).generate("sample.jpg")!, cloudinary: cloudinary)
Android (cloudinary-android 1.x):Kotlin (kotlin-url-gen 1.x):cloudinary.image { publicId("sample.jpg") overlay(Overlay.source( Source.image("cloudinary_icon_blue") { transformation(Transformation { resize(Resize.scale() { width(0.5F) }) adjust(Adjust.opacity(70)) adjust(Adjust.brightness() { level(50) }) }) }) { position(Position() { gravity( Gravity.compass( Compass.northEast())) }) }) }.generate()
Flutter (cloudinary_flutter 0.x):cloudinary.image('sample.jpg').transformation(Transformation() .overlay(Overlay.source( Source.image("cloudinary_icon_blue") .transformation(new Transformation() .resize(Resize.scale().width(0.5)) .adjust(Adjust.opacity(70)) .adjust(Adjust.brightness().level(50))) ) .position(Position() .gravity( Gravity.compass( Compass.northEast())) ) ));
Dart (cloudinary_dart 0.x):cloudinary.image('sample.jpg').transformation(Transformation() .overlay(Overlay.source( Source.image("cloudinary_icon_blue") .transformation(new Transformation() .resize(Resize.scale().width(0.5)) .adjust(Adjust.opacity(70)) .adjust(Adjust.brightness().level(50))) ) .position(Position() .gravity( Gravity.compass( Compass.northEast())) ) ));
The base image is scaled to a width of 500 pixels before adding the
woman
image as an overlay, where the overlay image is automatically cropped to include only the detected face and then scaled to a width of 150 pixels (c_scale,w_500/l_woman/c_crop,g_face/c_scale,w_150/fl_layer_apply
):url:Ruby (cloudinary 1.x):PHP (cloudinary_php 2.x):PHP (cloudinary_php 1.x (legacy)):Python (cloudinary 1.x):Node.js (cloudinary 1.x):Java (cloudinary 1.x):JS (@cloudinary/url-gen 1.x):// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sample.jpg") .resize(scale().width(500)) .overlay( source( image("woman").transformation( new Transformation() .resize(crop().gravity(focusOn(face()))) .resize(scale().width(150)) ) ) );
JS (cloudinary-core 2.x (legacy)):jQuery (cloudinary-jquery 2.x):React (@cloudinary/react 1.x):// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sample.jpg") .resize(scale().width(500)) .overlay( source( image("woman").transformation( new Transformation() .resize(crop().gravity(focusOn(face()))) .resize(scale().width(150)) ) ) );
React (cloudinary-react 1.x):Vue.js (@cloudinary/vue 1.x):// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sample.jpg") .resize(scale().width(500)) .overlay( source( image("woman").transformation( new Transformation() .resize(crop().gravity(focusOn(face()))) .resize(scale().width(150)) ) ) );
Vue.js (cloudinary-vue 1.x (legacy)):Angular (@cloudinary/ng 1.x):// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sample.jpg") .resize(scale().width(500)) .overlay( source( image("woman").transformation( new Transformation() .resize(crop().gravity(focusOn(face()))) .resize(scale().width(150)) ) ) );
Angular (@cloudinary/angular-5.x 1.x (legacy)):<cl-image public-id="sample.jpg" > <cl-transformation width="500" crop="scale"> </cl-transformation> <cl-transformation overlay="woman"> </cl-transformation> <cl-transformation gravity="face" crop="crop"> </cl-transformation> <cl-transformation width="150" crop="scale"> </cl-transformation> <cl-transformation flags="layer_apply"> </cl-transformation> </cl-image>
.NET (CloudinaryDotNet 1.x):iOS (cloudinary 3.x):imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setWidth(500).setCrop("scale").chain() .setOverlay("woman").chain() .setGravity("face").setCrop("crop").chain() .setWidth(150).setCrop("scale").chain() .setFlags("layer_apply")).generate("sample.jpg")!, cloudinary: cloudinary)
Android (cloudinary-android 1.x):Kotlin (kotlin-url-gen 1.x):cloudinary.image { publicId("sample.jpg") resize(Resize.scale() { width(500) }) overlay(Overlay.source( Source.image("woman") { transformation(Transformation { resize(Resize.crop() { gravity( Gravity.focusOn( FocusOn.face())) }) resize(Resize.scale() { width(150) }) }) })) }.generate()
Flutter (cloudinary_flutter 0.x):cloudinary.image('sample.jpg').transformation(Transformation() .resize(Resize.scale().width(500)) .overlay(Overlay.source( Source.image("woman") .transformation(new Transformation() .resize(Resize.crop() .gravity( Gravity.focusOn( FocusOn.face())) ) .resize(Resize.scale().width(150))) )));
Dart (cloudinary_dart 0.x):cloudinary.image('sample.jpg').transformation(Transformation() .resize(Resize.scale().width(500)) .overlay(Overlay.source( Source.image("woman") .transformation(new Transformation() .resize(Resize.crop() .gravity( Gravity.focusOn( FocusOn.face())) ) .resize(Resize.scale().width(150))) )));
Multiple overlays
Multiple overlays can easily be added as chained transformations to an aset. The following example adds both image and text overlays to the base image as follows:
- An overlay of an image called
couple
, cropped to a 120x150 ellipse that includes only the detected faces (l_couple/c_crop,g_faces,h_150,w_120/r_max/fl_layer_apply
). - An overlay of an image called
cloudinary_icon_white
with a relative width of 80% of the base image and an opacity of 50% and a brightness of 100 (l_cloudinary_icon_white/c_scale,fl_relative,w_0.8/o_50/e_brightness:100/fl_layer_apply
). - The text string "Sample" in bold 'Impact' font with a size of 40 pixels, placed at a distance of 20 pixels from the bottom of the base image (
l_text:impact_40_bold:Sample/fl_layer_apply,g_south,y_20
).
cl_image_tag("sample.jpg", :transformation=>[ {:overlay=>"couple"}, {:gravity=>"faces", :height=>150, :width=>120, :crop=>"crop"}, {:radius=>"max"}, {:flags=>"layer_apply", :gravity=>"north_east"}, {:overlay=>"cloudinary_icon_white"}, {:flags=>"relative", :width=>0.8, :crop=>"scale"}, {:opacity=>50}, {:effect=>"brightness:100"}, {:flags=>"layer_apply"}, {:overlay=>{:font_family=>"impact", :font_size=>40, :font_weight=>"bold", :text=>"Sample"}}, {:flags=>"layer_apply", :gravity=>"south", :y=>20} ])
(new ImageTag('sample.jpg')) ->overlay(Overlay::source( Source::image("couple") ->transformation((new Transformation()) ->resize(Resize::crop()->width(120) ->height(150) ->gravity( Gravity::focusOn( FocusOn::faces())) ) ->roundCorners(RoundCorners::max())) ) ->position((new Position()) ->gravity( Gravity::compass( Compass::northEast())) ) ) ->overlay(Overlay::source( Source::image("cloudinary_icon_white") ->transformation((new Transformation()) ->resize(Resize::scale()->width(0.8) ->relative() ) ->adjust(Adjust::opacity(50)) ->adjust(Adjust::brightness()->level(100))) )) ->overlay(Overlay::source( Source::text("Sample",(new TextStyle("impact",40)) ->fontWeight( FontWeight::bold()) )) ->position((new Position()) ->gravity( Gravity::compass( Compass::south())) ->offsetY(20)) );
cl_image_tag("sample.jpg", array("transformation"=>array( array("overlay"=>"couple"), array("gravity"=>"faces", "height"=>150, "width"=>120, "crop"=>"crop"), array("radius"=>"max"), array("flags"=>"layer_apply", "gravity"=>"north_east"), array("overlay"=>"cloudinary_icon_white"), array("flags"=>"relative", "width"=>"0.8", "crop"=>"scale"), array("opacity"=>50), array("effect"=>"brightness:100"), array("flags"=>"layer_apply"), array("overlay"=>array("font_family"=>"impact", "font_size"=>40, "font_weight"=>"bold", "text"=>"Sample")), array("flags"=>"layer_apply", "gravity"=>"south", "y"=>20) )))
CloudinaryImage("sample.jpg").image(transformation=[ {'overlay': "couple"}, {'gravity': "faces", 'height': 150, 'width': 120, 'crop': "crop"}, {'radius': "max"}, {'flags': "layer_apply", 'gravity': "north_east"}, {'overlay': "cloudinary_icon_white"}, {'flags': "relative", 'width': "0.8", 'crop': "scale"}, {'opacity': 50}, {'effect': "brightness:100"}, {'flags': "layer_apply"}, {'overlay': {'font_family': "impact", 'font_size': 40, 'font_weight': "bold", 'text': "Sample"}}, {'flags': "layer_apply", 'gravity': "south", 'y': 20} ])
cloudinary.image("sample.jpg", {transformation: [ {overlay: "couple"}, {gravity: "faces", height: 150, width: 120, crop: "crop"}, {radius: "max"}, {flags: "layer_apply", gravity: "north_east"}, {overlay: "cloudinary_icon_white"}, {flags: "relative", width: "0.8", crop: "scale"}, {opacity: 50}, {effect: "brightness:100"}, {flags: "layer_apply"}, {overlay: {font_family: "impact", font_size: 40, font_weight: "bold", text: "Sample"}}, {flags: "layer_apply", gravity: "south", y: 20} ]})
cloudinary.url().transformation(new Transformation() .overlay(new Layer().publicId("couple")).chain() .gravity("faces").height(150).width(120).crop("crop").chain() .radius("max").chain() .flags("layer_apply").gravity("north_east").chain() .overlay(new Layer().publicId("cloudinary_icon_white")).chain() .flags("relative").width(0.8).crop("scale").chain() .opacity(50).chain() .effect("brightness:100").chain() .flags("layer_apply").chain() .overlay(new TextLayer().fontFamily("impact").fontSize(40).fontWeight("bold").text("Sample")).chain() .flags("layer_apply").gravity("south").y(20)).imageTag("sample.jpg");
cloudinary.imageTag('sample.jpg', {transformation: [ {overlay: new cloudinary.Layer().publicId("couple")}, {gravity: "faces", height: 150, width: 120, crop: "crop"}, {radius: "max"}, {flags: "layer_apply", gravity: "north_east"}, {overlay: new cloudinary.Layer().publicId("cloudinary_icon_white")}, {flags: "relative", width: "0.8", crop: "scale"}, {opacity: 50}, {effect: "brightness:100"}, {flags: "layer_apply"}, {overlay: new cloudinary.TextLayer().fontFamily("impact").fontSize(40).fontWeight("bold").text("Sample")}, {flags: "layer_apply", gravity: "south", y: 20} ]}).toHtml();
$.cloudinary.image("sample.jpg", {transformation: [ {overlay: new cloudinary.Layer().publicId("couple")}, {gravity: "faces", height: 150, width: 120, crop: "crop"}, {radius: "max"}, {flags: "layer_apply", gravity: "north_east"}, {overlay: new cloudinary.Layer().publicId("cloudinary_icon_white")}, {flags: "relative", width: "0.8", crop: "scale"}, {opacity: 50}, {effect: "brightness:100"}, {flags: "layer_apply"}, {overlay: new cloudinary.TextLayer().fontFamily("impact").fontSize(40).fontWeight("bold").text("Sample")}, {flags: "layer_apply", gravity: "south", y: 20} ]})
<Image publicId="sample.jpg" > <Transformation overlay="couple" /> <Transformation gravity="faces" height="150" width="120" crop="crop" /> <Transformation radius="max" /> <Transformation flags="layer_apply" gravity="north_east" /> <Transformation overlay="cloudinary_icon_white" /> <Transformation flags="relative" width="0.8" crop="scale" /> <Transformation opacity="50" /> <Transformation effect="brightness:100" /> <Transformation flags="layer_apply" /> <Transformation overlay={{fontFamily: "impact", fontSize: 40, fontWeight: "bold", text: "Sample"}} /> <Transformation flags="layer_apply" gravity="south" y="20" /> </Image>
<cld-image public-id="sample.jpg" > <cld-transformation :overlay="couple" /> <cld-transformation gravity="faces" height="150" width="120" crop="crop" /> <cld-transformation radius="max" /> <cld-transformation flags="layer_apply" gravity="north_east" /> <cld-transformation :overlay="cloudinary_icon_white" /> <cld-transformation flags="relative" width="0.8" crop="scale" /> <cld-transformation opacity="50" /> <cld-transformation effect="brightness:100" /> <cld-transformation flags="layer_apply" /> <cld-transformation :overlay="{fontFamily: 'impact', fontSize: 40, fontWeight: 'bold', text: 'Sample'}" /> <cld-transformation flags="layer_apply" gravity="south" y="20" /> </cld-image>
<cl-image public-id="sample.jpg" > <cl-transformation overlay="couple"> </cl-transformation> <cl-transformation gravity="faces" height="150" width="120" crop="crop"> </cl-transformation> <cl-transformation radius="max"> </cl-transformation> <cl-transformation flags="layer_apply" gravity="north_east"> </cl-transformation> <cl-transformation overlay="cloudinary_icon_white"> </cl-transformation> <cl-transformation flags="relative" width="0.8" crop="scale"> </cl-transformation> <cl-transformation opacity="50"> </cl-transformation> <cl-transformation effect="brightness:100"> </cl-transformation> <cl-transformation flags="layer_apply"> </cl-transformation> <cl-transformation overlay="text:impact_40_bold:Sample"> </cl-transformation> <cl-transformation flags="layer_apply" gravity="south" y="20"> </cl-transformation> </cl-image>
cloudinary.Api.UrlImgUp.Transform(new Transformation() .Overlay(new Layer().PublicId("couple")).Chain() .Gravity("faces").Height(150).Width(120).Crop("crop").Chain() .Radius("max").Chain() .Flags("layer_apply").Gravity("north_east").Chain() .Overlay(new Layer().PublicId("cloudinary_icon_white")).Chain() .Flags("relative").Width(0.8).Crop("scale").Chain() .Opacity(50).Chain() .Effect("brightness:100").Chain() .Flags("layer_apply").Chain() .Overlay(new TextLayer().FontFamily("impact").FontSize(40).FontWeight("bold").Text("Sample")).Chain() .Flags("layer_apply").Gravity("south").Y(20)).BuildImageTag("sample.jpg")
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setOverlay("couple").chain() .setGravity("faces").setHeight(150).setWidth(120).setCrop("crop").chain() .setRadius("max").chain() .setFlags("layer_apply").setGravity("north_east").chain() .setOverlay("cloudinary_icon_white").chain() .setFlags("relative").setWidth(0.8).setCrop("scale").chain() .setOpacity(50).chain() .setEffect("brightness:100").chain() .setFlags("layer_apply").chain() .setOverlay("text:impact_40_bold:Sample").chain() .setFlags("layer_apply").setGravity("south").setY(20)).generate("sample.jpg")!, cloudinary: cloudinary)
MediaManager.get().url().transformation(new Transformation() .overlay(new Layer().publicId("couple")).chain() .gravity("faces").height(150).width(120).crop("crop").chain() .radius("max").chain() .flags("layer_apply").gravity("north_east").chain() .overlay(new Layer().publicId("cloudinary_icon_white")).chain() .flags("relative").width(0.8).crop("scale").chain() .opacity(50).chain() .effect("brightness:100").chain() .flags("layer_apply").chain() .overlay(new TextLayer().fontFamily("impact").fontSize(40).fontWeight("bold").text("Sample")).chain() .flags("layer_apply").gravity("south").y(20)).generate("sample.jpg");
cloudinary.image { publicId("sample.jpg") overlay(Overlay.source( Source.image("couple") { transformation(Transformation { resize(Resize.crop() { width(120) height(150) gravity( Gravity.focusOn( FocusOn.faces())) }) roundCorners(RoundCorners.max()) }) }) { position(Position() { gravity( Gravity.compass( Compass.northEast())) }) }) overlay(Overlay.source( Source.image("cloudinary_icon_white") { transformation(Transformation { resize(Resize.scale() { width(0.8F) relative() }) adjust(Adjust.opacity(50)) adjust(Adjust.brightness() { level(100) }) }) })) overlay(Overlay.source( Source.text("Sample",TextStyle("impact",40) { fontWeight( FontWeight.bold()) })) { position(Position() { gravity( Gravity.compass( Compass.south())) offsetY(20) }) }) }.generate()

Nesting layers
Layers can be nested within layers. Each layer must have its own layer and layer_apply
components, and the inner layer must be closed before the outer one, like with any nested programming statement.
For example, adding another cloudinary_icon_blue
image as an overlay to the first (black and white) overlay:
cl_image_tag("sample.jpg", :transformation=>[ {:width=>500, :crop=>"scale"}, {:overlay=>"cloudinary_icon_blue"}, {:width=>150, :crop=>"scale"}, {:effect=>"blackwhite"}, {:overlay=>"cloudinary_icon_blue"}, {:width=>50, :crop=>"scale"}, {:flags=>"layer_apply"}, {:flags=>"layer_apply", :gravity=>"north_east"} ])
(new ImageTag('sample.jpg')) ->resize(Resize::scale()->width(500)) ->overlay(Overlay::source( Source::image("cloudinary_icon_blue") ->transformation((new Transformation()) ->resize(Resize::scale()->width(150)) ->effect(Effect::blackwhite()) ->overlay(Overlay::source( Source::image("cloudinary_icon_blue") ->transformation((new Transformation()) ->resize(Resize::scale()->width(50))) ))) ) ->position((new Position()) ->gravity( Gravity::compass( Compass::northEast())) ) );
cl_image_tag("sample.jpg", array("transformation"=>array( array("width"=>500, "crop"=>"scale"), array("overlay"=>"cloudinary_icon_blue"), array("width"=>150, "crop"=>"scale"), array("effect"=>"blackwhite"), array("overlay"=>"cloudinary_icon_blue"), array("width"=>50, "crop"=>"scale"), array("flags"=>"layer_apply"), array("flags"=>"layer_apply", "gravity"=>"north_east") )))
CloudinaryImage("sample.jpg").image(transformation=[ {'width': 500, 'crop': "scale"}, {'overlay': "cloudinary_icon_blue"}, {'width': 150, 'crop': "scale"}, {'effect': "blackwhite"}, {'overlay': "cloudinary_icon_blue"}, {'width': 50, 'crop': "scale"}, {'flags': "layer_apply"}, {'flags': "layer_apply", 'gravity': "north_east"} ])
cloudinary.image("sample.jpg", {transformation: [ {width: 500, crop: "scale"}, {overlay: "cloudinary_icon_blue"}, {width: 150, crop: "scale"}, {effect: "blackwhite"}, {overlay: "cloudinary_icon_blue"}, {width: 50, crop: "scale"}, {flags: "layer_apply"}, {flags: "layer_apply", gravity: "north_east"} ]})
cloudinary.url().transformation(new Transformation() .width(500).crop("scale").chain() .overlay(new Layer().publicId("cloudinary_icon_blue")).chain() .width(150).crop("scale").chain() .effect("blackwhite").chain() .overlay(new Layer().publicId("cloudinary_icon_blue")).chain() .width(50).crop("scale").chain() .flags("layer_apply").chain() .flags("layer_apply").gravity("north_east")).imageTag("sample.jpg");
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sample.jpg").resize(scale().width(500)).overlay( source( image("cloudinary_icon_blue").transformation( new Transformation() .resize(scale().width(150)) .effect(blackwhite()) .overlay( source( image("cloudinary_icon_blue").transformation( new Transformation().resize(scale().width(50)) ) ) ) ) ).position(new Position().gravity(compass("north_east"))) );
cloudinary.imageTag('sample.jpg', {transformation: [ {width: 500, crop: "scale"}, {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue")}, {width: 150, crop: "scale"}, {effect: "blackwhite"}, {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue")}, {width: 50, crop: "scale"}, {flags: "layer_apply"}, {flags: "layer_apply", gravity: "north_east"} ]}).toHtml();
$.cloudinary.image("sample.jpg", {transformation: [ {width: 500, crop: "scale"}, {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue")}, {width: 150, crop: "scale"}, {effect: "blackwhite"}, {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue")}, {width: 50, crop: "scale"}, {flags: "layer_apply"}, {flags: "layer_apply", gravity: "north_east"} ]})
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sample.jpg").resize(scale().width(500)).overlay( source( image("cloudinary_icon_blue").transformation( new Transformation() .resize(scale().width(150)) .effect(blackwhite()) .overlay( source( image("cloudinary_icon_blue").transformation( new Transformation().resize(scale().width(50)) ) ) ) ) ).position(new Position().gravity(compass("north_east"))) );
<Image publicId="sample.jpg" > <Transformation width="500" crop="scale" /> <Transformation overlay="cloudinary_icon_blue" /> <Transformation width="150" crop="scale" /> <Transformation effect="blackwhite" /> <Transformation overlay="cloudinary_icon_blue" /> <Transformation width="50" crop="scale" /> <Transformation flags="layer_apply" /> <Transformation flags="layer_apply" gravity="north_east" /> </Image>
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sample.jpg").resize(scale().width(500)).overlay( source( image("cloudinary_icon_blue").transformation( new Transformation() .resize(scale().width(150)) .effect(blackwhite()) .overlay( source( image("cloudinary_icon_blue").transformation( new Transformation().resize(scale().width(50)) ) ) ) ) ).position(new Position().gravity(compass("north_east"))) );
<cld-image public-id="sample.jpg" > <cld-transformation width="500" crop="scale" /> <cld-transformation :overlay="cloudinary_icon_blue" /> <cld-transformation width="150" crop="scale" /> <cld-transformation effect="blackwhite" /> <cld-transformation :overlay="cloudinary_icon_blue" /> <cld-transformation width="50" crop="scale" /> <cld-transformation flags="layer_apply" /> <cld-transformation flags="layer_apply" gravity="north_east" /> </cld-image>
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("sample.jpg").resize(scale().width(500)).overlay( source( image("cloudinary_icon_blue").transformation( new Transformation() .resize(scale().width(150)) .effect(blackwhite()) .overlay( source( image("cloudinary_icon_blue").transformation( new Transformation().resize(scale().width(50)) ) ) ) ) ).position(new Position().gravity(compass("north_east"))) );
<cl-image public-id="sample.jpg" > <cl-transformation width="500" crop="scale"> </cl-transformation> <cl-transformation overlay="cloudinary_icon_blue"> </cl-transformation> <cl-transformation width="150" crop="scale"> </cl-transformation> <cl-transformation effect="blackwhite"> </cl-transformation> <cl-transformation overlay="cloudinary_icon_blue"> </cl-transformation> <cl-transformation width="50" crop="scale"> </cl-transformation> <cl-transformation flags="layer_apply"> </cl-transformation> <cl-transformation flags="layer_apply" gravity="north_east"> </cl-transformation> </cl-image>
cloudinary.Api.UrlImgUp.Transform(new Transformation() .Width(500).Crop("scale").Chain() .Overlay(new Layer().PublicId("cloudinary_icon_blue")).Chain() .Width(150).Crop("scale").Chain() .Effect("blackwhite").Chain() .Overlay(new Layer().PublicId("cloudinary_icon_blue")).Chain() .Width(50).Crop("scale").Chain() .Flags("layer_apply").Chain() .Flags("layer_apply").Gravity("north_east")).BuildImageTag("sample.jpg")
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setWidth(500).setCrop("scale").chain() .setOverlay("cloudinary_icon_blue").chain() .setWidth(150).setCrop("scale").chain() .setEffect("blackwhite").chain() .setOverlay("cloudinary_icon_blue").chain() .setWidth(50).setCrop("scale").chain() .setFlags("layer_apply").chain() .setFlags("layer_apply").setGravity("north_east")).generate("sample.jpg")!, cloudinary: cloudinary)
MediaManager.get().url().transformation(new Transformation() .width(500).crop("scale").chain() .overlay(new Layer().publicId("cloudinary_icon_blue")).chain() .width(150).crop("scale").chain() .effect("blackwhite").chain() .overlay(new Layer().publicId("cloudinary_icon_blue")).chain() .width(50).crop("scale").chain() .flags("layer_apply").chain() .flags("layer_apply").gravity("north_east")).generate("sample.jpg");
cloudinary.image { publicId("sample.jpg") resize(Resize.scale() { width(500) }) overlay(Overlay.source( Source.image("cloudinary_icon_blue") { transformation(Transformation { resize(Resize.scale() { width(150) }) effect(Effect.blackwhite()) overlay(Overlay.source( Source.image("cloudinary_icon_blue") { transformation(Transformation { resize(Resize.scale() { width(50) }) }) })) }) }) { position(Position() { gravity( Gravity.compass( Compass.northEast())) }) }) }.generate()
cloudinary.image('sample.jpg').transformation(Transformation() .resize(Resize.scale().width(500)) .overlay(Overlay.source( Source.image("cloudinary_icon_blue") .transformation(new Transformation() .resize(Resize.scale().width(150)) .effect(Effect.blackwhite()) .overlay(Overlay.source( Source.image("cloudinary_icon_blue") .transformation(new Transformation() .resize(Resize.scale().width(50))) ))) ) .position(Position() .gravity( Gravity.compass( Compass.northEast())) ) ));
cloudinary.image('sample.jpg').transformation(Transformation() .resize(Resize.scale().width(500)) .overlay(Overlay.source( Source.image("cloudinary_icon_blue") .transformation(new Transformation() .resize(Resize.scale().width(150)) .effect(Effect.blackwhite()) .overlay(Overlay.source( Source.image("cloudinary_icon_blue") .transformation(new Transformation() .resize(Resize.scale().width(50))) ))) ) .position(Position() .gravity( Gravity.compass( Compass.northEast())) ) ));

The first image layer has a transformation that changes its size and applies a black and white effect. The second layer is also resized, and then is closed and placed by the first (inner) fl_layer_apply
. Since no gravity was specified for that later, it's placed in the center of the first overlay. Then the outer layer apply closes and places the entire layer (including its nested layer) and positions it in the northeast corner.
Relative layer sizing
By default, whenever you apply relative resize transformations to your overlay, the overlay image is resized relative to its own original size. However, you can use one of the following flags to resize relative to other elements.
Sizing relative to the base image
You can add the relative
flag (fl_relative
in URLs) to specify that percentage-based width & height parameters of overlays (e.g., w_0.5) are relative to the size of the base image instead of to the original size of the overlaying image itself.
For example, to add an overlay of the image called cloudinary_icon_blue
, where the overlay is resized to 80% of the width of the base image (l_cloudinary_icon_blue/c_scale,fl_relative,w_0.8/fl_layer_apply
):

Sizing relative to the detected region
You can add the region_relative
flag (fl_region_relative
in URLs) to instruct Cloudinary to size your layers relative to the regions detected by the specified gravity type.
- The region can be detected faces (
g_face
,g_faces
), detected OCR text regions (g_ocr_text
) or pre-defined custom regions (g_custom
). - This flag must be used in conjunction with a relative (decimal value) width or height qualifier.
For example, to hide all the faces in an image by covering them with an emoji overlay, where each overlay is sized at 1.3x (130%) of each detected face (l_happy_smiley/c_scale,fl_region_relative,w_1.3/fl_layer_apply,g_faces
):
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("rollercoaster.jpg").overlay( source( image("happy_smiley").transformation( new Transformation().resize(scale().width(1.3).regionRelative()) ) ).position(new Position().gravity(focusOn(faces()))) );
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("rollercoaster.jpg").overlay( source( image("happy_smiley").transformation( new Transformation().resize(scale().width(1.3).regionRelative()) ) ).position(new Position().gravity(focusOn(faces()))) );
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("rollercoaster.jpg").overlay( source( image("happy_smiley").transformation( new Transformation().resize(scale().width(1.3).regionRelative()) ) ).position(new Position().gravity(focusOn(faces()))) );
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("rollercoaster.jpg").overlay( source( image("happy_smiley").transformation( new Transformation().resize(scale().width(1.3).regionRelative()) ) ).position(new Position().gravity(focusOn(faces()))) );
<cl-image public-id="rollercoaster.jpg" > <cl-transformation overlay="happy_smiley"> </cl-transformation> <cl-transformation flags="region_relative" width="1.3" crop="scale"> </cl-transformation> <cl-transformation flags="layer_apply" gravity="faces"> </cl-transformation> </cl-image>
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setOverlay("happy_smiley").chain() .setFlags("region_relative").setWidth(1.3).setCrop("scale").chain() .setFlags("layer_apply").setGravity("faces")).generate("rollercoaster.jpg")!, cloudinary: cloudinary)
cloudinary.image { publicId("rollercoaster.jpg") overlay(Overlay.source( Source.image("happy_smiley") { transformation(Transformation { resize(Resize.scale() { width(1.3F) regionRelative() }) }) }) { position(Position() { gravity( Gravity.focusOn( FocusOn.faces())) }) }) }.generate()
cloudinary.image('rollercoaster.jpg').transformation(Transformation() .overlay(Overlay.source( Source.image("happy_smiley") .transformation(new Transformation() .resize(Resize.scale().width(1.3) .regionRelative() )) ) .position(Position() .gravity( Gravity.focusOn( FocusOn.faces())) ) ));
cloudinary.image('rollercoaster.jpg').transformation(Transformation() .overlay(Overlay.source( Source.image("happy_smiley") .transformation(new Transformation() .resize(Resize.scale().width(1.3) .regionRelative() )) ) .position(Position() .gravity( Gravity.focusOn( FocusOn.faces())) ) ));

Text layer options
Text layers can be customized in a variety of ways, such as applying CSS-like styles, adding line breaks, applying special characters, custom fonts, and more.
Styling parameters
In addition to the required font family and font size values of the text layer, a variety of optional CSS-like styles are supported, such as decoration, alignment, letter spacing and more. For a full list, see the Styling parameters table in the reference guide.
The Cloudinary SDK helper methods support supplying the values as an array of mapped values or as a serialized string of values. For example, in Ruby (other frameworks use similar syntax):
overlay: { text: 'Hello World', font_family: 'Arial', font_size: 18, font_weight: 'bold', font_style: 'italic', letter_spacing: 4 }
For example, to overlay the text string "Flowers" in Verdana bold with a size of 75 pixels, underlined, and with 14 pixels spacing between the letters: l_text:verdana_75_bold_underline_letter_spacing_14:Flowers
:
cl_image_tag("flowers.jpg", array("transformation"=>array( array("width"=>500, "crop"=>"scale"), array("overlay"=>array("font_family"=>"Verdana", "font_size"=>75, "font_weight"=>"bold", "text_decoration"=>"underline", "letter_spacing"=>14, "text"=>"Flowers")), array("flags"=>"layer_apply") )))
cloudinary.url().transformation(new Transformation() .width(500).crop("scale").chain() .overlay(new TextLayer().fontFamily("Verdana").fontSize(75).fontWeight("bold").textDecoration("underline").letterSpacing(14).text("Flowers")).chain() .flags("layer_apply")).imageTag("flowers.jpg");
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text( "Flowers", new TextStyle("Verdana", 75) .fontWeight("bold") .textDecoration("underline") .letterSpacing(14) ) ) );
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text( "Flowers", new TextStyle("Verdana", 75) .fontWeight("bold") .textDecoration("underline") .letterSpacing(14) ) ) );
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text( "Flowers", new TextStyle("Verdana", 75) .fontWeight("bold") .textDecoration("underline") .letterSpacing(14) ) ) );
<cld-image public-id="flowers.jpg" > <cld-transformation width="500" crop="scale" /> <cld-transformation :overlay="{fontFamily: 'Verdana', fontSize: 75, fontWeight: 'bold', textDecoration: 'underline', letterSpacing: 14, text: 'Flowers'}" /> <cld-transformation flags="layer_apply" /> </cld-image>
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text( "Flowers", new TextStyle("Verdana", 75) .fontWeight("bold") .textDecoration("underline") .letterSpacing(14) ) ) );
<cl-image public-id="flowers.jpg" > <cl-transformation width="500" crop="scale"> </cl-transformation> <cl-transformation overlay="text:Verdana_75_bold_underline_letter_spacing_14:Flowers"> </cl-transformation> <cl-transformation flags="layer_apply"> </cl-transformation> </cl-image>
cloudinary.Api.UrlImgUp.Transform(new Transformation() .Width(500).Crop("scale").Chain() .Overlay(new TextLayer().FontFamily("Verdana").FontSize(75).FontWeight("bold").TextDecoration("underline").LetterSpacing(14).Text("Flowers")).Chain() .Flags("layer_apply")).BuildImageTag("flowers.jpg")
MediaManager.get().url().transformation(new Transformation() .width(500).crop("scale").chain() .overlay(new TextLayer().fontFamily("Verdana").fontSize(75).fontWeight("bold").textDecoration("underline").letterSpacing(14).text("Flowers")).chain() .flags("layer_apply")).generate("flowers.jpg");

Text color
You can control the color of the text overlay by adding the color
property (co
in URLs).
Opaque colors can be set as an RGB hex triplet (e.g., co_rgb:3e2222
), a 3-digit RGB hex (e.g., co_rgb:777
) or a named color (e.g., co_green
). By default, if the color property is omitted, the text has a black color.
For example, adding the text string "Cool text" in Times bold with a size of 90 pixels at a distance of 20 pixels from the bottom of the base image, in yellow text (FFFF00):
(new ImageTag('flowers.jpg')) ->resize(Resize::scale()->width(500)) ->overlay(Overlay::source( Source::text("Cool%20text",(new TextStyle("Times",90)) ->fontWeight( FontWeight::bold()) ) ->textColor(Color::rgb("FFFF00")) ) ->position((new Position()) ->gravity( Gravity::compass( Compass::south())) ->offsetY(20)) );
cl_image_tag("flowers.jpg", array("transformation"=>array( array("width"=>500, "crop"=>"scale"), array("color"=>"#FFFF00", "overlay"=>array("font_family"=>"Times", "font_size"=>90, "font_weight"=>"bold", "text"=>"Cool%2520text")), array("flags"=>"layer_apply", "gravity"=>"south", "y"=>20) )))
cloudinary.url().transformation(new Transformation() .width(500).crop("scale").chain() .color("#FFFF00").overlay(new TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%2520text")).chain() .flags("layer_apply").gravity("south").y(20)).imageTag("flowers.jpg");
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text( "Cool%20text", new TextStyle("Times", 90).fontWeight("bold") ).textColor("#FFFF00") ).position( new Position() .gravity(compass("south")) .offsetY(20) ) );
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text( "Cool%20text", new TextStyle("Times", 90).fontWeight("bold") ).textColor("#FFFF00") ).position( new Position() .gravity(compass("south")) .offsetY(20) ) );
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text( "Cool%20text", new TextStyle("Times", 90).fontWeight("bold") ).textColor("#FFFF00") ).position( new Position() .gravity(compass("south")) .offsetY(20) ) );
<cld-image public-id="flowers.jpg" > <cld-transformation width="500" crop="scale" /> <cld-transformation color="#FFFF00" :overlay="{fontFamily: 'Times', fontSize: 90, fontWeight: 'bold', text: 'Cool%2520text'}" /> <cld-transformation flags="layer_apply" gravity="south" y="20" /> </cld-image>
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text( "Cool%20text", new TextStyle("Times", 90).fontWeight("bold") ).textColor("#FFFF00") ).position( new Position() .gravity(compass("south")) .offsetY(20) ) );
<cl-image public-id="flowers.jpg" > <cl-transformation width="500" crop="scale"> </cl-transformation> <cl-transformation color="#FFFF00" overlay="text:Times_90_bold:Cool%2520text"> </cl-transformation> <cl-transformation flags="layer_apply" gravity="south" y="20"> </cl-transformation> </cl-image>
cloudinary.Api.UrlImgUp.Transform(new Transformation() .Width(500).Crop("scale").Chain() .Color("#FFFF00").Overlay(new TextLayer().FontFamily("Times").FontSize(90).FontWeight("bold").Text("Cool%2520text")).Chain() .Flags("layer_apply").Gravity("south").Y(20)).BuildImageTag("flowers.jpg")
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setWidth(500).setCrop("scale").chain() .setColor("#FFFF00").setOverlay("text:Times_90_bold:Cool%2520text").chain() .setFlags("layer_apply").setGravity("south").setY(20)).generate("flowers.jpg")!, cloudinary: cloudinary)
MediaManager.get().url().transformation(new Transformation() .width(500).crop("scale").chain() .color("#FFFF00").overlay(new TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%2520text")).chain() .flags("layer_apply").gravity("south").y(20)).generate("flowers.jpg");
cloudinary.image { publicId("flowers.jpg") resize(Resize.scale() { width(500) }) overlay(Overlay.source( Source.text("Cool%20text",TextStyle("Times",90) { fontWeight( FontWeight.bold()) }) { textColor(Color.rgb("FFFF00")) }) { position(Position() { gravity( Gravity.compass( Compass.south())) offsetY(20) }) }) }.generate()

You can also use a 4-digit or 8-digit RGBA hex quadruplet for the color, where the 4th hex value represents the alpha (opacity) value (e.g., co_rgb:3e222240
results in 25% opacity).
The example below uses the same text string "Cool text" in Times bold with a size of 90 pixels at a distance of 20 pixels from the bottom of the base image, in yellow text, but this time with an opacity of 50% (FFFF0080):
(new ImageTag('flowers.jpg')) ->resize(Resize::scale()->width(500)) ->overlay(Overlay::source( Source::text("Cool%20text",(new TextStyle("Times",90)) ->fontWeight( FontWeight::bold()) ) ->textColor(Color::rgb("FFFF0080")) ) ->position((new Position()) ->gravity( Gravity::compass( Compass::south())) ->offsetY(20)) );
cl_image_tag("flowers.jpg", array("transformation"=>array( array("width"=>500, "crop"=>"scale"), array("color"=>"#FFFF0080", "overlay"=>array("font_family"=>"Times", "font_size"=>90, "font_weight"=>"bold", "text"=>"Cool%2520text")), array("flags"=>"layer_apply", "gravity"=>"south", "y"=>20) )))
cloudinary.url().transformation(new Transformation() .width(500).crop("scale").chain() .color("#FFFF0080").overlay(new TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%2520text")).chain() .flags("layer_apply").gravity("south").y(20)).imageTag("flowers.jpg");
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text( "Cool%20text", new TextStyle("Times", 90).fontWeight("bold") ).textColor("#FFFF0080") ).position( new Position() .gravity(compass("south")) .offsetY(20) ) );
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text( "Cool%20text", new TextStyle("Times", 90).fontWeight("bold") ).textColor("#FFFF0080") ).position( new Position() .gravity(compass("south")) .offsetY(20) ) );
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text( "Cool%20text", new TextStyle("Times", 90).fontWeight("bold") ).textColor("#FFFF0080") ).position( new Position() .gravity(compass("south")) .offsetY(20) ) );
<cld-image public-id="flowers.jpg" > <cld-transformation width="500" crop="scale" /> <cld-transformation color="#FFFF0080" :overlay="{fontFamily: 'Times', fontSize: 90, fontWeight: 'bold', text: 'Cool%2520text'}" /> <cld-transformation flags="layer_apply" gravity="south" y="20" /> </cld-image>
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text( "Cool%20text", new TextStyle("Times", 90).fontWeight("bold") ).textColor("#FFFF0080") ).position( new Position() .gravity(compass("south")) .offsetY(20) ) );
<cl-image public-id="flowers.jpg" > <cl-transformation width="500" crop="scale"> </cl-transformation> <cl-transformation color="#FFFF0080" overlay="text:Times_90_bold:Cool%2520text"> </cl-transformation> <cl-transformation flags="layer_apply" gravity="south" y="20"> </cl-transformation> </cl-image>
cloudinary.Api.UrlImgUp.Transform(new Transformation() .Width(500).Crop("scale").Chain() .Color("#FFFF0080").Overlay(new TextLayer().FontFamily("Times").FontSize(90).FontWeight("bold").Text("Cool%2520text")).Chain() .Flags("layer_apply").Gravity("south").Y(20)).BuildImageTag("flowers.jpg")
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setWidth(500).setCrop("scale").chain() .setColor("#FFFF0080").setOverlay("text:Times_90_bold:Cool%2520text").chain() .setFlags("layer_apply").setGravity("south").setY(20)).generate("flowers.jpg")!, cloudinary: cloudinary)
MediaManager.get().url().transformation(new Transformation() .width(500).crop("scale").chain() .color("#FFFF0080").overlay(new TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%2520text")).chain() .flags("layer_apply").gravity("south").y(20)).generate("flowers.jpg");
cloudinary.image { publicId("flowers.jpg") resize(Resize.scale() { width(500) }) overlay(Overlay.source( Source.text("Cool%20text",TextStyle("Times",90) { fontWeight( FontWeight.bold()) }) { textColor(Color.rgb("FFFF0080")) }) { position(Position() { gravity( Gravity.compass( Compass.south())) offsetY(20) }) }) }.generate()

Multi-line text
You can manually break lines of text by separating each line of text with the newline character (%0A). For example, adding the text string "Cool text" in Verdana bold with a size of 50 pixels at a distance of 10 pixels from the left border of the base image, where each word appears on a new line:
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text("Cool%0Atext", new TextStyle("Verdana", 50).fontWeight("bold")) ).position( new Position() .gravity(compass("west")) .offsetX(10) ) );
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text("Cool%0Atext", new TextStyle("Verdana", 50).fontWeight("bold")) ).position( new Position() .gravity(compass("west")) .offsetX(10) ) );
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text("Cool%0Atext", new TextStyle("Verdana", 50).fontWeight("bold")) ).position( new Position() .gravity(compass("west")) .offsetX(10) ) );
// This SDK requires imports from @cloudinary/url-gen. Learn more in the SDK docs. new CloudinaryImage("flowers.jpg").resize(scale().width(500)).overlay( source( text("Cool%0Atext", new TextStyle("Verdana", 50).fontWeight("bold")) ).position( new Position() .gravity(compass("west")) .offsetX(10) ) );
<cl-image public-id="flowers.jpg" > <cl-transformation width="500" crop="scale"> </cl-transformation> <cl-transformation overlay="text:Verdana_50_bold:Cool%250Atext"> </cl-transformation> <cl-transformation flags="layer_apply" gravity="west" x="10"> </cl-transformation> </cl-image>
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setWidth(500).setCrop("scale").chain() .setOverlay("text:Verdana_50_bold:Cool%250Atext").chain() .setFlags("layer_apply").setGravity("west").setX(10)).generate("flowers.jpg")!, cloudinary: cloudinary)
cloudinary.image { publicId("flowers.jpg") resize(Resize.scale() { width(500) }) overlay(Overlay.source( Source.text("Cool%0Atext",TextStyle("Verdana",50) { fontWeight( FontWeight.bold()) })) { position(Position() { gravity( Gravity.compass( Compass.west())) offsetX(10) }) }) }.generate()

Auto-line breaks
Cloudinary can also automatically wrap your text into multiple lines based on a specified maximum width for the text string. To do this, apply the fit
crop mode to the text layer and specify the width
to use for word wrapping. This setting tells Cloudinary to automatically wrap the actual text content onto a new line once the width is reached.
c_fit
(Called textFit
in the latest major version of some SDKs) is the only 'resize' option that can be used as a qualifier of text overlays.For example, to add a long text string in bold Neucha font with a size of 26 pixels to the base image that wraps at a width of 400 pixels:
cl_image_tag("flowers.jpg", :transformation=>[ {:width=>500, :crop=>"scale"}, {:overlay=>{:font_family=>"Neucha", :font_size=>26, :font_weight=>"bold", :text=>"Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."}, :width=>400, :crop=>"fit"}, {:flags=>"layer_apply"} ])
(new ImageTag('flowers.jpg')) ->resize(Resize::scale()->width(500)) ->overlay(Overlay::source( Source::text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.",(new TextStyle("Neucha",26)) ->fontWeight( FontWeight::bold()) ) ->textFit( TextFit::size(400)) ));
cl_image_tag("flowers.jpg", array("transformation"=>array( array("width"=>500, "crop"=>"scale"), array("overlay"=>array("font_family"=>"Neucha", "font_size"=>26, "font_weight"=>"bold", "text"=>"Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."), "width"=>400, "crop"=>"fit"), array("flags"=>"layer_apply") )))
CloudinaryImage("flowers.jpg").image(transformation=[ {'width': 500, 'crop': "scale"}, {'overlay': {'font_family': "Neucha", 'font_size': 26, 'font_weight': "bold", 'text': "Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."}, 'width': 400, 'crop': "fit"}, {'flags': "layer_apply"} ])
cloudinary.image("flowers.jpg", {transformation: [ {width: 500, crop: "scale"}, {overlay: {font_family: "Neucha", font_size: 26, font_weight: "bold", text: "Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."}, width: 400, crop: "fit"}, {flags: "layer_apply"} ]})
cloudinary.url().transformation(new Transformation() .width(500).crop("scale").chain() .overlay(new TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.")).width(400).crop("fit").chain() .flags("layer_apply")).imageTag("flowers.jpg");
cloudinary.imageTag('flowers.jpg', {transformation: [ {width: 500, crop: "scale"}, {overlay: new cloudinary.TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."), width: 400, crop: "fit"}, {flags: "layer_apply"} ]}).toHtml();
$.cloudinary.image("flowers.jpg", {transformation: [ {width: 500, crop: "scale"}, {overlay: new cloudinary.TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."), width: 400, crop: "fit"}, {flags: "layer_apply"} ]})
<Image publicId="flowers.jpg" > <Transformation width="500" crop="scale" /> <Transformation overlay={{fontFamily: "Neucha", fontSize: 26, fontWeight: "bold", text: "Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."}} width="400" crop="fit" /> <Transformation flags="layer_apply" /> </Image>
<cld-image public-id="flowers.jpg" > <cld-transformation width="500" crop="scale" /> <cld-transformation :overlay="{fontFamily: 'Neucha', fontSize: 26, fontWeight: 'bold', text: 'Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.'}" width="400" crop="fit" /> <cld-transformation flags="layer_apply" /> </cld-image>
<cl-image public-id="flowers.jpg" > <cl-transformation width="500" crop="scale"> </cl-transformation> <cl-transformation overlay="text:Neucha_26_bold:Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat." width="400" crop="fit"> </cl-transformation> <cl-transformation flags="layer_apply"> </cl-transformation> </cl-image>
cloudinary.Api.UrlImgUp.Transform(new Transformation() .Width(500).Crop("scale").Chain() .Overlay(new TextLayer().FontFamily("Neucha").FontSize(26).FontWeight("bold").Text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.")).Width(400).Crop("fit").Chain() .Flags("layer_apply")).BuildImageTag("flowers.jpg")
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setWidth(500).setCrop("scale").chain() .setOverlay("text:Neucha_26_bold:Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.").setWidth(400).setCrop("fit").chain() .setFlags("layer_apply")).generate("flowers.jpg")!, cloudinary: cloudinary)
MediaManager.get().url().transformation(new Transformation() .width(500).crop("scale").chain() .overlay(new TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.")).width(400).crop("fit").chain() .flags("layer_apply")).generate("flowers.jpg");
cloudinary.image { publicId("flowers.jpg") resize(Resize.scale() { width(500) }) overlay(Overlay.source( Source.text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.",TextStyle("Neucha",26) { fontWeight( FontWeight.bold()) }) { textFit( TextFit.size(400)) })) }.generate()

When using the fit
(textFit
in some SDKs) crop mode, you must specify a width for your text overlay, but height is optional. Line breaks are applied as needed to achieve the requested width and/or height rectangle.
The specified font size of your overlay stays as is, even if the resulting text overlay height exceeds the height of its hosting image. So, if you don't limit the overlay height, the height of the image expands to accommodate large texts:
cl_image_tag("flowers.jpg", :transformation=>[ {:width=>500, :crop=>"scale"}, {:overlay=>{:font_family=>"Neucha", :font_size=>26, :font_weight=>"bold", :text=>"Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."}, :width=>400, :crop=>"fit"}, {:flags=>"layer_apply"} ])
(new ImageTag('flowers.jpg')) ->resize(Resize::scale()->width(500)) ->overlay(Overlay::source( Source::text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat. Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.",(new TextStyle("Neucha",26)) ->fontWeight( FontWeight::bold()) ) ->textFit( TextFit::size(400)) ));
cl_image_tag("flowers.jpg", array("transformation"=>array( array("width"=>500, "crop"=>"scale"), array("overlay"=>array("font_family"=>"Neucha", "font_size"=>26, "font_weight"=>"bold", "text"=>"Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."), "width"=>400, "crop"=>"fit"), array("flags"=>"layer_apply") )))
CloudinaryImage("flowers.jpg").image(transformation=[ {'width': 500, 'crop': "scale"}, {'overlay': {'font_family': "Neucha", 'font_size': 26, 'font_weight': "bold", 'text': "Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."}, 'width': 400, 'crop': "fit"}, {'flags': "layer_apply"} ])
cloudinary.image("flowers.jpg", {transformation: [ {width: 500, crop: "scale"}, {overlay: {font_family: "Neucha", font_size: 26, font_weight: "bold", text: "Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."}, width: 400, crop: "fit"}, {flags: "layer_apply"} ]})
cloudinary.url().transformation(new Transformation() .width(500).crop("scale").chain() .overlay(new TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.")).width(400).crop("fit").chain() .flags("layer_apply")).imageTag("flowers.jpg");
cloudinary.imageTag('flowers.jpg', {transformation: [ {width: 500, crop: "scale"}, {overlay: new cloudinary.TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."), width: 400, crop: "fit"}, {flags: "layer_apply"} ]}).toHtml();
$.cloudinary.image("flowers.jpg", {transformation: [ {width: 500, crop: "scale"}, {overlay: new cloudinary.TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."), width: 400, crop: "fit"}, {flags: "layer_apply"} ]})
<Image publicId="flowers.jpg" > <Transformation width="500" crop="scale" /> <Transformation overlay={{fontFamily: "Neucha", fontSize: 26, fontWeight: "bold", text: "Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."}} width="400" crop="fit" /> <Transformation flags="layer_apply" /> </Image>
<cld-image public-id="flowers.jpg" > <cld-transformation width="500" crop="scale" /> <cld-transformation :overlay="{fontFamily: 'Neucha', fontSize: 26, fontWeight: 'bold', text: 'Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.'}" width="400" crop="fit" /> <cld-transformation flags="layer_apply" /> </cld-image>
<cl-image public-id="flowers.jpg" > <cl-transformation width="500" crop="scale"> </cl-transformation> <cl-transformation overlay="text:Neucha_26_bold:Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat." width="400" crop="fit"> </cl-transformation> <cl-transformation flags="layer_apply"> </cl-transformation> </cl-image>
cloudinary.Api.UrlImgUp.Transform(new Transformation() .Width(500).Crop("scale").Chain() .Overlay(new TextLayer().FontFamily("Neucha").FontSize(26).FontWeight("bold").Text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.")).Width(400).Crop("fit").Chain() .Flags("layer_apply")).BuildImageTag("flowers.jpg")
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setWidth(500).setCrop("scale").chain() .setOverlay("text:Neucha_26_bold:Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.").setWidth(400).setCrop("fit").chain() .setFlags("layer_apply")).generate("flowers.jpg")!, cloudinary: cloudinary)
MediaManager.get().url().transformation(new Transformation() .width(500).crop("scale").chain() .overlay(new TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.")).width(400).crop("fit").chain() .flags("layer_apply")).generate("flowers.jpg");
cloudinary.image { publicId("flowers.jpg") resize(Resize.scale() { width(500) }) overlay(Overlay.source( Source.text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat. Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.",TextStyle("Neucha",26) { fontWeight( FontWeight.bold()) }) { textFit( TextFit.size(400)) })) }.generate()

If you do limit the height of your overlay, any text that does not fit within the space defined is cut and an ellipsis (...
) is added to the end of the text string to indicate that the text was truncated.
To define a maximum height for the multi-line text add the height
parameter in addition to width
in the 'resize' transformation of your text layer:
cl_image_tag("flowers.jpg", :transformation=>[ {:width=>500, :crop=>"scale"}, {:overlay=>{:font_family=>"Neucha", :font_size=>26, :font_weight=>"bold", :text=>"Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."}, :width=>400, :height=>250, :crop=>"fit"}, {:flags=>"layer_apply"} ])
(new ImageTag('flowers.jpg')) ->resize(Resize::scale()->width(500)) ->overlay(Overlay::source( Source::text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat. Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.",(new TextStyle("Neucha",26)) ->fontWeight( FontWeight::bold()) ) ->textFit( TextFit::size(400)->height(250)) ));
cl_image_tag("flowers.jpg", array("transformation"=>array( array("width"=>500, "crop"=>"scale"), array("overlay"=>array("font_family"=>"Neucha", "font_size"=>26, "font_weight"=>"bold", "text"=>"Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."), "width"=>400, "height"=>250, "crop"=>"fit"), array("flags"=>"layer_apply") )))
CloudinaryImage("flowers.jpg").image(transformation=[ {'width': 500, 'crop': "scale"}, {'overlay': {'font_family': "Neucha", 'font_size': 26, 'font_weight': "bold", 'text': "Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."}, 'width': 400, 'height': 250, 'crop': "fit"}, {'flags': "layer_apply"} ])
cloudinary.image("flowers.jpg", {transformation: [ {width: 500, crop: "scale"}, {overlay: {font_family: "Neucha", font_size: 26, font_weight: "bold", text: "Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."}, width: 400, height: 250, crop: "fit"}, {flags: "layer_apply"} ]})
cloudinary.url().transformation(new Transformation() .width(500).crop("scale").chain() .overlay(new TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.")).width(400).height(250).crop("fit").chain() .flags("layer_apply")).imageTag("flowers.jpg");
cloudinary.imageTag('flowers.jpg', {transformation: [ {width: 500, crop: "scale"}, {overlay: new cloudinary.TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."), width: 400, height: 250, crop: "fit"}, {flags: "layer_apply"} ]}).toHtml();
$.cloudinary.image("flowers.jpg", {transformation: [ {width: 500, crop: "scale"}, {overlay: new cloudinary.TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."), width: 400, height: 250, crop: "fit"}, {flags: "layer_apply"} ]})
<Image publicId="flowers.jpg" > <Transformation width="500" crop="scale" /> <Transformation overlay={{fontFamily: "Neucha", fontSize: 26, fontWeight: "bold", text: "Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat."}} width="400" height="250" crop="fit" /> <Transformation flags="layer_apply" /> </Image>
<cld-image public-id="flowers.jpg" > <cld-transformation width="500" crop="scale" /> <cld-transformation :overlay="{fontFamily: 'Neucha', fontSize: 26, fontWeight: 'bold', text: 'Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.'}" width="400" height="250" crop="fit" /> <cld-transformation flags="layer_apply" /> </cld-image>
<cl-image public-id="flowers.jpg" > <cl-transformation width="500" crop="scale"> </cl-transformation> <cl-transformation overlay="text:Neucha_26_bold:Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat." width="400" height="250" crop="fit"> </cl-transformation> <cl-transformation flags="layer_apply"> </cl-transformation> </cl-image>
cloudinary.Api.UrlImgUp.Transform(new Transformation() .Width(500).Crop("scale").Chain() .Overlay(new TextLayer().FontFamily("Neucha").FontSize(26).FontWeight("bold").Text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.")).Width(400).Height(250).Crop("fit").Chain() .Flags("layer_apply")).BuildImageTag("flowers.jpg")
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setWidth(500).setCrop("scale").chain() .setOverlay("text:Neucha_26_bold:Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.").setWidth(400).setHeight(250).setCrop("fit").chain() .setFlags("layer_apply")).generate("flowers.jpg")!, cloudinary: cloudinary)
MediaManager.get().url().transformation(new Transformation() .width(500).crop("scale").chain() .overlay(new TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.%0D%0A%0D%0ALorem%2520ipsum%2520dolor%2520sit%2520amet%2520consectetur%2520adipisicing%2520elit%2520sed%2520do%2520eiusmod%2520tempor%2520incididunt%2520ut%2520labore%2520et%2520dolore%2520magna%2520aliqua.%2520Ut%2520enim%2520ad%2520minim%2520veniam%2520quis%2520nostrud%2520exercitation%2520ullamco%2520laboris%2520nisi%2520ut%2520aliquip%2520ex%2520ea%2520commodo%2520consequat.")).width(400).height(250).crop("fit").chain() .flags("layer_apply")).generate("flowers.jpg");
cloudinary.image { publicId("flowers.jpg") resize(Resize.scale() { width(500) }) overlay(Overlay.source( Source.text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat. Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.",TextStyle("Neucha",26) { fontWeight( FontWeight.bold()) }) { textFit( TextFit.size(400) { height(250) }) })) }.generate()

You can also set text alignment and line spacing values to further control the text's appearance. Other resize parameters can be applied as an action over the entire overlay (before the fl_layer_apply) to resize the resulting the text-image overlay as a whole after it's created.
For example, to add a long text string in center aligned bold Times font with a size of 14 pixels to the base image, that wraps at a width of 200 pixels and is limited to a height of 150 pixels; and then rotate the text by 9 degrees and set 30 pixels from the north border to better align with the underlying image: