• Home
  • blog
  • On-the-Fly Image Overlays using Cloudinary

On-the-Fly Image Overlays using Cloudinary

Image overlay isn’t solely about having the right touch to create an amazing visual. You also need a great tool that simplifies the process. Cloudinary, a cloud-based image and video service for websites and mobile applications, is exactly the tool you need.

How to Overlay Images

First open a free Cloudinary account, if you don’t already have one.  Then upload images, either through the Cloudinary management console or using the API.  Once an image is uploaded to your Cloudinary account it is stored on the cloud as well.

To create an overlay, you simply need to define how you would like to modify your original image within the image delivery URL. According to the directives added to the URL a new derived image is processed on the fly and cached.  The result will be delivered super-fast via content delivery network (CDN). Any subsequent request to the same URL will be delivered from the cache.

Here we show how to put a company logo on a koala. With Cloudinary, this common task becomes an easy job. The koala original image URL is:

The image overlay URL is:,w_200,c_scale/koala.jpg

The URL structure is :

<domain name>/<cloud  name>/<image manipulation parameters>/<image  public-id>.<image format>

The overlay was created by adding the following parameters to the URL:

  • l_<overlay_public_id>
  • w_<width>
  • c_<crop_method>

Be sure to visit the image URLs shown in the examples here, and try them out.

Building the Image URL Using JavaScript

You can build the image URL yourself or use one of Cloudinary SDK libraries. In the following examples, I will use the core JavaScript library, which is pure Java Script, but there is a JQuery plugin, as well.

First you need to include the JavaScript source, which you can download from the cloudinary-core github project.

<script src="<path>/cloudinary-core-shrinkwrap.js"  type="text/javascript"></script>

Next you need to set your account cloud name in the code.  The account name is defined when you register with Cloudinary. In the following examples, the cloud name is “cld-name.”

var cl ={cloud_name: "cld-name"});

Now, I will use the cl variable created here to call to Cloudinary methods. If you prefer to use JQuery, you can find it here.

This is the JavaScript call to build the image URL with the overlay shown:

cl.url("koala", { overlay: "cloudinary_icon", width: 200, crop: "scale" });

The parameters used in this call are the image public_id which is “koala,” the image overlay public_id, which is “cloudinary_icon.” For both, public_id means the name of the image in the Cloudinary media library. The next parameter is width = 200 pixels, which is used to resize the overlay image to be 200 pixel wide. The last parameter is crop which determines the crop mode used to resize the overlay image. The selected “scale” option resizes to the requested width while retaining the original aspect ratio. The result of this call is the “image overlay URL” as previously shown.

Creating Watermarks

A common and basic use case for image overlay is adding a watermark. It is a useful way to protect and copyright your images online. The image we started with already has our icon on it, but perhaps you prefer to add it in a subtler way, such as watermark. Here are the parameters required to do that:

  • Dimensions of the overlay is defined by width and crop sets the crop type.
  • The location to place the overlay is defined by: gravity
  • Visual effects applied on the overlay are: opacity and brightness effect
cl.url("koala", { overlay: "cloudinary_icon", width: 200, crop: "scale", gravity: "south_east", opacity: 50, effect: "brightness:200"});

Image URL:,w_200,c_scale,g_south_east,o_50,e_brightness:200/koala.jpg

Dynamic Text Overlays

Creating dynamic text overlays opens up a world of possibilities. You can easily update banners with the latest deals and promotions. Google fonts are supported by default, but you also can upload custom fonts to your account. For example, announcing on a special sale happening only today.

cl.url("bag", { transformation: [
  {overlay: "text:roboto_60:EXTRA%2010%25%20OFF", color: "white", y: 110}, 
{overlay: "text:roboto_60:SALE%20ENDS%20TODAY", color: "white", y: 200}]});

Image URL: 10%25 OFF,co_white,y_110/l_text:roboto_60:SALE ENDS TODAY,co_white,y_200/bag.jpg

Personalized Text Overlays

Text overlays can be personalized, as well. You can replace the text on the fly in your code using information stored on a cookie, showing each user its own text based on the information gathered from previous site visits. To make sure the text will be seen on any background color it is effective use a border font.

cl.url("gift", {  overlay: " text:arial_80_stroke:Happy%20Birthday%20John", color: "white", gravity: "north", y: 5, border: "2px_solid_black"}); Birthday John,co_white,bo_2px_solid_black,g_north,y_5/gift.jpg

You also have the option to implement it using Cloudinary cookie as a parameter within the image URL. You need to have your own CName setup by Cloudinary and then the URL will be:

http://CNAME/l_text:arial_80_stroke:__cld_attribute1__,co_white,bo_2px_solid_black,g_north,y_5/ gift.jpg

The text shown on the image will be the value of the cookie called __cld_attribute1__

Overlaying Social Profile Pictures

Using Cloudinary you can dynamically fetch the profile picture from social networks (Facebook, Twitter, Instagram, Google+) and use it as the base image or an overlay image.

cl.url ("KermitTheFrog", { type: "twitter_name", transformation: [ 
  { width: 150, crop: "scale"} , 
  { overlay: "instagram_name:realmisspiggy",  width: 150, crop: "scale", x: 150 },
{ border: "3px_solid_black"}]});,c_scale/l_instagram_name:realmisspiggy,w_150,x_150/bo_3px_solid_black/KermitTheFrog.jpg

Face Detectionbased Overlay

In order to create a cool overlay, it is helpful to detect the face in the image, especially if you are planning to reenact the Venice mask carnival, as shown below. The overlay is automatically placed on the eyes that are detected in the image.

cl.url("team.jpg", { transformation: [ 
  { width: 640, crop: "scale",  } , 
{ flags: "region_relative", gravity: "adv_eyes", overlay: "harlequinmask", width: 1.7 }]});,w_640/l_harlequinmask,w_1.7,g_adv_eyes,fl_region_relative/team.jpg

Another option is to automatically pixelate the faces for confidentiality.

cl.url("couple", { width: 640,  crop: "scale", effect: "pixelate_faces:10"});,c_scale,e_pixelate_faces:10/couple.jpg

Image Overlay on Video

Cloudinary also supports video, so the same API enables you to have images, animated gifs and videos interact. You can create an animated gif from several images, capture an image from an animated gif or a video clip, and even overlay an image on a video clip for a defined period of time as shown below.  “run”, } controls: true, poster: cl.url(“run.jpg”, {resource_type: “video”}), transformation: [  { overlay: “candy”, width: 0.4, gravity: “south_west”, start_offset: “5”, end_offset: “7.5” }, { overlay: “candy”, width: 0.4, gravity: “south_east”, start_offset: “8”, end_offset: “12”, angle: “hflip”}]});


This is only the tip of the iceberg, Cloudinary supports a long list of image manipulation options which you can find hereand the same goes for video. In addition, images can be optimized for faster delivery by using features such as automatic format and automatic quality.
Now it is up to you, go ahead and improve your website visuals, as many studies have shown, the millennials prefer images to text anyhow.

(Disclaimer: This post is sponsored by Cloudinary.)