Image Operations / Watermarking
Image Watermarking is a process of adding an additional, usually small image to your visuals in order to prevent them from unauthorized circulation. Optidash gives you multiple options to control watermark alignment, geometry, padding and alpha transparency.
Watermark ID
In order to apply watermarks on your images you must first upload watermarks to your Optidash Account and later only use their unique IDs we assign to them internally. Because watermark files will be securely stored on our machines, API calls requesting image watermarking will be performed substantially faster.
To instruct the API to use an uploaded watermark, simply provide a watermark id
within a watermark
hash:
{
"watermark": {
"id": "uD0H0osYN6"
}
}
An example cURL request of using the Image Fetch method with a watermark ID will look like the following:
curl https://api.optidash.ai/1.0/fetch
--user your-api-key: \
--header "Content-Type: application/json" \
--data '{
"url": "https://www.website.com/image.jpg",
"watermark": {
"id": "uD0H0osYN6"
}
}'
Watermark Position
By default, the API will position the watermark in the center of an image without changing its dimensions or opacity. Let's have a look at a very basic example:
{
"watermark": {
"id": "uD0H0osYN6"
}
}
You may alter the default center position of a watermark by providing a gravity
parameter which takes one of the following: top-left
, top
, top-right
, right
, bottom-right
, bottom
, bottom-left
, left
.
For example, to position a watermark in the top-right corner, set the gravity
value to top-right
:
{
"watermark": {
"id": "uD0H0osYN6",
"gravity": "top-right"
}
}
Watermark Padding
When using a gravity
to position a watermark, you may also specify a watermark padding
parameter which takes a positive integer and describes the distance between the watermark and image boundaries.
Say you'd like to position your watermark in the bottom-right corner and give it a padding of 50px:
{
"watermark": {
"id": "uD0H0osYN6",
"gravity": "bottom-right",
"padding": 50
}
}
Watermark Coordinates
When you know the exact coordinates where you'd like to position your watermark, you may use x
and y
attributes instead of gravity
. The 0,0
point (the origin) is located at the top-left corner of the image.
For example, to position a watermark exactly at x:200
, y:150
:
{
"watermark": {
"id": "uD0H0osYN6",
"x": 200,
"y": 150
}
}
Watermark Opacity
In order to adjust the opacity of the watermark, provide an additional opacity
parameter which takes a positive floating point number in the range 0.01
- 1.00
.
For example, to apply a watermark with 0.75
opacity, positioned in the center, use the following parameters:
{
"watermark": {
"id": "uD0H0osYN6",
"opacity": 0.75
}
}
Watermark Size and Scale
You can downsample your watermarks in two different ways - by specifying width
and/or height
parameters within the watermark
hash, or by specifying a scale
parameter which takes a float in the range 0.01
- 1.00
.
When the scale
parameter is in use, the API will downsample the watermark image by a factor specified by the scale
value. For example, to scale the watermark down to 75% of its original size and position it in the top-left corner with 50px padding:
{
"watermark": {
"id": "uD0H0osYN6",
"gravity": "top-left",
"padding": 50,
"scale": 0.75
}
}
When width
and/or height
parameters are provided, the API will use an auto mode for calculating watermark dimensions meaning the watermark will always be downsampled according to its aspect ratio in a way that it does not exceed specified dimensions.
{
"watermark": {
"id": "uD0H0osYN6",
"gravity": "top-left",
"padding": 50,
"width": 150
}
}
Watermark Fit Mode
By default, the Optidash Image API will not alter the size of a supplied watermark even if its dimensions exceed the dimensions of the input image. By setting the fit
parameter to true
within the watermark
hash, you can instruct the API to downsample larger watermarks to fit entirely within the image boundaries. It's worth noting that due to quality considerations, the API will never upscale smaller watermarks to fit within image bounds.
{
"watermark": {
"id": "6238ad5f",
"fit": true
}
}
Along with the fit
parameter you may also specify gravity
, padding
and opacity
values. Say you'd like to fit a larger watermark, with a padding of 10px
, align it to the top and make it semi-transparent by setting opacity value to 0.8
:
{
"watermark": {
"id": "6238ad5f",
"fit": true,
"gravity": "top",
"padding": 10,
"opacity": 0.8
}
}