In many cases, it's helpful to add text overlays to images. Sharing content on social media, for example, can be more effective with a sharing image including information about the content.

In this post, we'll look at how we can use Cloudinary to add text overlays to images using URL-based APIs.

How do text overlays work with Cloudinary?

Cloudinary has a whole set of APIs to add overlays to images. We can combine those with other transforms to place text anywhere on an image. All of these transformations are added in the URL of our image.

As a simplified example, let's add some text to a picture of a corgi:


Credit: ipet photo

The URL for this image is:

This will display the corgi image at 800px wide because we use the w_800 transform in the URL.

Add a text overlay to an image using Cloudinary

To add text, we're going to add a second transform — transforms in Cloudinary are separated by forward slashes (/) — that tells Cloudinary to add a text overlay using the font Arial at 64pt size:

The change here is this string:

  • l_text: tells Cloudinary that we're going to do a text overlay
  • arial_64: configures the text overlay to use Arial at 64pt
  • Ready%20to%20party is the URL-encoded text we want to display

If we open this URL in a browser, we’ll see the text overlaid on the image:

Corgi with the text “Ready to party” overlaid.

Credit: ipet photo

Position the text overlay on an image using Cloudinary

Our image looks okay, but it would be better if the text wasn't on top of our doggo. Fortunately, Cloudinary allows us to position text using additional transforms.

First, let's set the "gravity" of the text so it's anchored to the bottom-left corner. This is done using directions for whatever reason, so bottom and left are considered south and west.

Add g_south_west to the text overlay transformation section of the URL, separating it with a comma:,l_text:arial_64:Ready%20to%20party/corgi.jpg

Now the image looks like this:

Corgi with the text “Ready to party” overlaid.

Credit: ipet photo

This is better, but now the text is crammed against the edge of the photo — not great.

Add X and Y offsets to text overlays in Cloudinary

We can adjust this by changing the X and Y offsets, though. The offsets start from wherever the gravity is set, so in this case our X offset will be from the left edge and the Y offset will be from the bottom.

These are set as x_40,y_40 in the text overlay transformation section:,x_40,y_40,l_text:arial_64:Ready%20to%20party/corgi.jpg

Now the image is offset from the edge of the image by 40px at the left and bottom:

Corgi with the text “Ready to party” overlaid.

Credit: ipet photo

Almost there!

Set text overlays to wrap at a specified width in Cloudinary

Now let's get the text to wrap so it doesn't overlay the corgi at all. We can do this by setting a width and telling the text to "fit" using the crop settings.

These are set as w_250,c_fit in the transformation section:,x_40,y_40,w_250,c_fit,l_text:arial_64:Ready%20to%20party/corgi.jpg

Now it looks pretty good!

Corgi with the text “Ready to party” overlaid.

Credit: ipet photo

What to do next

To take your text overlays to the next level, try: