Skip to main content

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:   ?   &   &markRatio=0.25

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
We've added a batman logo to this puppy's portrait

API options

mainImageUrlURL of original image. Required
markImageUrlURL of image to overlay atop main image. Required
opacityAlpha of mark. 0.0-1.01.0
imageWidthWidth of final image, in pixelsOriginal image width
imageHeightHeight of final image, in pixelsOriginal image height
markWidthWidth of mark, in pixelsOriginal mark width
markHeightHeight of mark, in pixelsOriginal mark height
markRatioResize the mark to be some ratio of the original image. 0.0-1.0
positionPreset positions. One of:
topMiddle, bottomMiddle, topLeft, middleLeft, bottomLeft, topRight, middleRight, bottomRight, center
positionXX position of mark, in pixels
positionYY position of mark, in pixels
marginMargin in pixels around the mark when it is auto-positioned.
Applicable when positionX and positionY are not used
5% of original image width

POST endpoint

The above parameters can be used in a POST request. Here is an example JSON body:

"mainImageUrl": "",
"markImageUrl": "",
"markRatio": 0.25

You can pack it into a POST request like so:

curl -X POST -H "Content-Type: application/json" -d '{
"mainImageUrl": "",
"markImageUrl": "",
"markRatio": 0.25

The response will be a watermarked image.

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>   &markRatio=0.5   &position=center

This produces a composite image:

:::info Image size is limited to 1 MB for Community (free) requests, 10 MB for paid requests. :::


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