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
    }
}