Using the QuickChart Watermark API

QuickChart provides an API that lets you overlay one image on top of another, creating a watermark or logo on top of an original image.

The API is flexible and allows you to customize the size, position, opacity, and margin of the watermark.

Getting started

The watermark API endpoint is available at It works by taking URLs for two images. There are a number of optional parameters that you can use to customize the images are overlayed.

Here’s a simple example that uses mainImageUrl, markImageUrl, and markRatio parameters:

The above URL instructs the API to overlay markImageUrl on top of mainImageUrl. markRatio ensures that the logo/watermark is resized to fit nicely in the image (taking up 25% of the width).

If you put the URL in an image tag, you’ll see the following:

We've added a batman logo to this puppy's portrait

API options

Parameter Description Default
mainImageUrl URL of original image. Required
markImageUrl URL of image to overlay atop main image. Required
opacity Alpha of mark. 0.0-1.0 1.0
imageWidth Width of final image, in pixels Original image width
imageHeight Height of final image, in pixels Original image height
markWidth Width of mark, in pixels Original mark width
markHeight Height of mark, in pixels Original mark height
markRatio Resize the mark to be some ratio of the original image. 0.0-1.0
position Preset positions. One of:
topMiddle, bottomMiddle, topLeft, middleLeft, bottomLeft, topRight, middleRight, bottomRight, center
positionX X position of mark, in pixels
positionY Y position of mark, in pixels
margin Margin in pixels around the mark when it is auto-positioned.
Applicable when positionX and positionY are not used
5% of original image width

More examples

Let’s take the above image and do some common customizations.

First, let’s suppose move the logo to the bottom left by adding &position=bottomLeft to the URL:

Let’s turn it into a watermark by fading the logo, setting opacity=0.2. And make it larger by setting markRatio=0.5.

Watermarking a chart

The URLs can also be used with the chart API in order to put a logo on a chart. The chart API allows you to create charts by constructing a URL. Take a simple chart image:

Construct a watermark API request that contains the chart image URL and the logo image URL (make sure you URL-encode both URLs):
  ?mainImageUrl=<QuickChart Chart Image URL>
  &markImageUrl=<Logo Image URL>

This produces a composite image:


This API makes it easy to superimpose an image atop another in order to add a logo to an image or create a watermark. It works with any images and offers flexible options to customize your mark’s appearance and position.

Stuck? Have questions? Feature request? Please reach out!

Ian Webster

About the author

Ian Webster is a software engineer and former Googler based in San Mateo, California. He has helped Google, NASA, and governments around the world improve their data pipelines and visualizations. In 2018, Ian created QuickChart, a collection of open-source APIs that support data visualization efforts.

Email · LinkedIn · Twitter