Watermarking

Image Operations / Image Watermarking

On this page:
Intro ▾
{{activeSubMenu.text}} ▾

Image Watermarking is a process of adding an additional, usually small image to your visuals in order to prevent them from unauthorized circulation. Pixaven 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 watermark(s) to your Pixaven 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.pixaven.com/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"
    }
}
Given the input image 750px × 300px
And a watermark ID "uD0H0osYN6"
Apply the watermark on the center of the image

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": "top-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.

Watermarks can never be enlarged as that would lead to visible quality degradation. It's always best to provide the API with larger watermark images and resize/scale them down if needed.

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.

For example, to resize a watermark to a maximum of 150px width and position it in the top-left corner with 50px padding:

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

Watermark Fit Mode

By default, the Pixaven Image API will not alter the size of a supplied watermark even if its dimensions exceed the dimensions of the input image. Let's have a look at the example output produced by the API when watermark size is greater than the image size:

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

Code Examples for Image Watermarking

Below, you'll find examples of how to use the Image Watermarking from the Pixaven API:

<?php

/**
* Instantiate new `$pix` by calling a constructor
*/

$pix = new Pixaven\Pixaven('your-api-key');


/**
* Provide a publicly available image URL with fetch(string) method
* and apply a watermark ID uD0H0osYN6 in the top-right corner,
* with 50px padding and 0.75 opacity
*/

$pix
    ->fetch('https://www.website.com/image.jpg')
    ->watermark(array(
        'id' => 'uD0H0osYN6',
        'gravity' => 'top-right',
        'padding' => 50,
        'opacity' => 0.75
    ))
    ->toJSON(function ($error, $meta) {
        if (!empty($error)) {
            throw new Exception($error);
        }

        /**
        * You'll find the full JSON metadata array within the `$meta` variable.
        * Remember to always check if the `success` property is set to `true`.
        */

        if ($meta['success'] == true) {
            print ($meta['output']['url']);
        } else {
            print ($meta['message']);
        }
    });
/**
* Module dependencies
*/

const Pixaven = require("pixaven");


/**
* Instantiate new `pix` by calling a constructor
*/

const pix = new Pixaven("your-api-key");


/**
* Provide a publicly available image URL with fetch(string) method
* and apply a watermark ID uD0H0osYN6 in the top-right corner,
* with 50px padding and 0.75 opacity
*/

pix
    .fetch("https://www.website.com/image.jpg")
    .watermark({
        id: "uD0H0osYN6",
        gravity: "top-right",
        padding: 50,
        opacity: 0.75
    })
    .toJSON((err, meta) => {
        if (err) {
            return console.log(err);
        }

        /**
        * You'll find the full JSON metadata hash within the `meta` variable.
        * Remember to always check if the `success` property is set to `true`.
        */

        if (meta.success) {
            console.log(meta.output.url);
        } else {
            console.log(meta.message);
        }
    });
##
# Require dependencies

require "pixaven"


##
# Instantiate new `pix` by calling a constructor

pix = Pixaven.new("your-api-key")


##
# Provide a publicly available image URL with fetch(string) method
# and apply a watermark ID uD0H0osYN6 in the top-right corner,
# with 50px padding and 0.75 opacity

err, meta = pix
    .fetch("https://www.website.com/image.jpg")
    .watermark(
        id: "uD0H0osYN6",
        gravity: "top-right",
        padding: 50,
        opacity: 0.75
    )
    .to_json

abort(err) if err


##
# You'll find the full JSON metadata hash within the `meta` variable.
# Remember to always check if the `success` property is set to `true`.

if meta["success"]
    puts meta["output"]["url"]
else
    puts meta["message"]
end
package main

import (
    "fmt"
    "github.com/pixaven/pixaven-go"
)

func main() {

    /**
    * Instantiate new `pix` by calling a constructor
    */

    pix, err := pixaven.NewClient("your-api-key")

    if err != nil {
        panic(err)
    }


    /**
    * Provide a publicly available image URL with Fetch(string) method
    * and apply a watermark ID uD0H0osYN6 in the top-right corner,
    * with 50px padding and 0.75 opacity
    */

    meta, err := pix.
        Fetch("https://www.website.com/image.jpg").
        Watermark(pixaven.P{
            "id": "uD0H0osYN6",
            "gravity": "top-right",
            "padding": 50,
            "opacity": 0.75
        }).
        ToJSON()

    if err != nil {
        panic(err)
    }


    /**
    * You'll find the full JSON metadata hash within the `meta` variable.
    * Remember to always check if the `success` property is set to `true`.
    */

    if meta["success"].(map[string]interface{})["success"].(bool) {
        fmt.Println(meta["output"].(map[string]interface{})["url"])
    } else {
        fmt.Println(meta["message"])
    }
}
##
# Import dependencies

from pixaven import pixaven


##
# Instantiate new `client` by calling a constructor

client = pixaven('your-api-key')


##
# Provide a publicly available image URL with fetch(string) method
# and apply a watermark ID uD0H0osYN6 in the top-right corner,
# with 50px padding and 0.75 opacity

err, meta = (
    client
        .fetch('https://www.website.com/image.jpg')
        .watermark({
            'id': 'uD0H0osYN6',
            'gravity': 'top-right',
            'padding': 50,
            'opacity': 0.75
        })
        .toJSON()
)

if err is not None:
    raise StandardError(err)


##
# You'll find the full JSON metadata hash within the `meta` variable.
# Remember to always check if the `success` property is set to `true`.

if meta['success'] is True:
    print (meta['output']['url'])
else:
    print (meta['message'])
package com.pixaven.examples;

/**
* Import dependencies
*/

import static com.pixaven.OperationConfiguration.settings;
import com.pixaven.Pixaven;
import com.pixaven.Fetch;
import com.pixaven.Response;

public class Watermarking {
    public static void main(String[] args) {

        /**
        * Instantiate new `pix` by calling a constructor
        */

        Pixaven pix = new Pixaven("your-api-key");

        /**
        * Provide a publicly available image URL with fetch(string) method
        * and apply a watermark ID uD0H0osYN6 in a top-right corner,
        * with 50px padding and 0.75 opacity
        */

        final Fetch fetch = pix.fetch("https://www.website.com/image.jpg");

        fetch.watermark(
            settings()
                .set("id", "uD0H0osYN6")
                .set("gravity", "top-right")
                .set("padding", 50)
                .set("opacity", 0.75)
        );

        final Response response = fetch.toJson();

        /**
        * You'll find the full JSON metadata hash within the `Response#getMetadata()` property.
        * Remember to always check if the `Response#successful` property is set to `true`.
        */

        if (response.isSuccessful()) {
            System.out.println(response.getMetadata().getOutput().get("url"));
        } else {
            System.out.println(response.getMessage());
        }
    }
}

We use both proprietary and third-party cookies to improve your browsing experience and to provide you with a better service. By continuing to use this site you consent our use of cookies as described in our Cookie Policy×