Image Watermarking is the technique of overlaying a typically small image onto your visuals to safeguard against unauthorized distribution. Optidash provides a versatile set of controls for watermark alignment, geometry, padding, and alpha transparency, ensuring comprehensive customization.

Watermark ID

To apply watermarks to your images, initially, you need to upload watermark images to your Optidash Account. These images are then assigned unique IDs for internal use. Since watermark files are securely stored on our servers, API calls for image watermarking execute more swiftly.

To use an uploaded watermark, simply include a watermark id within a watermark hash in your request:

{
    "watermark": {
        "id": "uD0H0osYN6"
    }
}

Example cURL request for applying a watermark by ID:

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 places the watermark at the center of an image, maintaining its original dimensions and opacity. Let's have a look at a very basic example:

{
    "watermark": {
        "id": "uD0H0osYN6"
    }
}

To adjust the default position, you can specify a gravity parameter with values such as 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 positioning a watermark using gravity, you can define a watermark padding parameter as a positive integer to set the distance between the watermark and the image's edges.

Example for adding padding to a watermark:

{
    "watermark": {
        "id": "uD0H0osYN6",
        "gravity": "bottom-right",
        "padding": 50
    }
}

Watermark Coordinates

For precise watermark placement, specify x and y attributes instead of using gravity, with the origin (0,0 point) 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

To modify the watermark's opacity, include an opacity parameter with a positive floating point number ranging from 0.01 to 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

Resize watermarks by specifying width and/or height parameters within the watermark hash, or by using a scale parameter with a float value from 0.01 to 1.00. Note that watermarks can only be downscaled to prevent quality degradation.

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 the specified dimensions.

{
    "watermark": {
        "id": "uD0H0osYN6",
        "gravity": "top-left",
        "padding": 50,
        "width": 150
    }
}

Watermark Fit Mode

The Optidash Image API, by default, does not alter a watermark's size even if it exceeds the input image dimensions. Activating the fit parameter within the watermark hash instructs the API to downscale larger watermarks to fit within the image boundaries, without upscaling smaller watermarks.

{
    "watermark": {
        "id": "6238ad5f",
        "fit": true
    }
}

Along with the fit parameter you may also specify gravity, padding and opacity values. For instance, if 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 the opacity value to 0.8:

{
    "watermark": {
        "id": "6238ad5f",
        "fit": true,
        "gravity": "top",
        "padding": 10,
        "opacity": 0.8
    }
}