If you want a permanent watermark on your videos or recorded live streams, api.video allows you to upload a custom logo or message for your video. You must add the watermark when you upload your video, and after you've added it, it's permanent. If you make a mistake you will have to re-upload your video.

Associated API reference documentation

Watermarks

Choose an api.video client

The clients offered by api.video include:

Installation

To install your selected client, do the following:

go get github.com/apivideo/api.video-go-client

composer require api-video/php-api-client

npm install @api.video/nodejs-client --save

...or with yarn: 
  
yarn add @api.video/nodejs-client

pip install api.video

Using Nuget
  
Install-Package ApiVideo

Retrieve your API key

You'll need your API key to get started. You can sign up for one here: Get your api.video API key!. Then do the following:

Log in to the api.video dashboard.
From the list of choices on the left, make sure you are on API Keys
You will always be able to choose to use your Sandbox API key. If you want to use the Production API key instead, enter your credit card information.
Grab the key you want, and you're ready to get started!

Upload a watermark

To upload a watermark for a video, you must upload it at the same time as the video's upload. You open your file in binary and upload the watermark to the watermark endpoint. Now the image is available for use on your video. Retrieve the watermark ID from the response.

The next step is to prepare your video for upload. Uploading a video takes two steps, so you'll create the container for your video, then use the video ID to upload your video. In the create container step, include your watermark details, as shown in video_creation_payload.

When you create a watermark, you can indicate its position, size, and transparency. For more details about the available choices, see the Watermarks endpoint documentation.

curl --request POST \
     --url https://ws.api.video/watermarks \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MDUyNzEuOTEyODMsIm5iZiI6MTY0MjgwNTI3MS45MTI4MywiZXhwIjoxNjQyODA4ODcxLjkxMjgzLCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.jTiB29R_sg5dqCDBU8wrnz7GRJsCzfVeLVTX-XSctS024B9OmGsuY139s2ua1HzrT63sqkBB1QshrjZbkDLVxSrs0-gt-FaM2bgvCC0lqK1HzEUL4vN2OqPPuM8R2pruj0UdGVaifGqmyfehKcHxuNr0ijGmGIMwSXkabECbXCxm7LraRCgmlobHepuXcUPeUKzKxN5LwPSO1onD684S0FtUUYbVMq9Ik7V8UznbpOjmFaknIZowKKlCkTmgKcyLSq7IaPJd7UuDJVXJDiC49oImEInrjx1xuFbyoBz_wkZlwcgk9GjksTeSz4xzBLcyzVgCwGP2hs8_BtdslXXOrA' \
     --header 'Content-Type: multipart/form-data' \
     --form [email protected]

package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build()
        
    file := os.NewFile(1234, "some_file") // *os.File | The .jpg or .png image to be added as a watermark.

    
    res, err := client.Watermarks.UploadFile(file)

    // you can also use a Reader instead of a File:
    // client.Watermarks.Upload(fileName, fileReader)

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `Watermarks.Upload``: %v\n", err)
    }
    // response from `Upload`: Watermark
    fmt.Fprintf(os.Stdout, "Response from `Watermarks.Upload`: %v\n", res)
}

const ApiVideoClient = require('@api.video/nodejs-client');

(async () => {
    try {
        const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" });

        const file = 'BINARY_DATA_HERE'; // The .jpg or .png image to be added as a watermark.

        // Watermark
        const result = await client.watermarks.upload(file);
        console.log(result);
    } catch (e) {
        console.error(e);
    }
})();

import apivideo
from apivideo.apis import WatermarksApi
from apivideo.apis import VideosApi
from apivideo.model.video import Video
from apivideo.model.bad_request import BadRequest
from pprint import pprint

client = apivideo.AuthenticatedApiClient("your API key here")

client.connect()

watermarks_api = WatermarksApi(client)

file = open('your_watermark_here.png', 'rb') # file_type | The .jpg or .png image to be added as a watermark.

api_response = watermarks_api.upload(file)        
pprint(api_response)
pprint(api_response['watermark_id'])

watermark_id = api_response['watermark_id']

videos_api = VideosApi(client)

video_creation_payload = {
    "title":"Sample video",
    "description": "Show a watermarked video",
    "watermark": {
        "id": watermark_id,
        "top":"20px",
        "left":"20px",
        "opacity":"70%",
    },
}
api_response = videos_api.create(video_creation_payload)
video_id = api_response["video_id"]

file = open("video_to_watermark.mp4", "rb")

video_response = videos_api.upload(video_id, file)
print("Uploaded Video", video_response)

List all watermarks

To list all available watermarks, send a GET request to the watermarks endpoint.

curl --request GET \
     --url https://ws.api.video/watermarks \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MDk2MzIuNTQ2MDg5LCJuYmYiOjE2NDI4MDk2MzIuNTQ2MDg5LCJleHAiOjE2NDI4MTMyMzIuNTQ2MDg5LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.J0cMjE7DNwTGvu3cprGpg5R5IHVDHip80ruWaCN57e9jDoJ4FK51Zkk2ynxhb1SqvutYi-hpnmOzqbPUFPjspLjTVbn0sUskKvGRst2gO2vNllHtIzNTlKKLMA_Sa_zi7hK5_XfuNod-B0SqeH106oAqe1FWkZjc7PMuqOzKS3dIqih0PczsbBQWWgQ3Fh-LtHxVVmdY_egq9i-t1fD5JCD812CHAK1HsxpAkpcAmpJptomORbq72tmEmgFfFUEJ8lalROM2_7ZDLvCdHxDYpA6_j5Z6k1y6Z_OjOsLg_mmiFymAT-DpUib2oOQyj2efIMo-OvdfNJhQRAcUMAUZyw'

package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build()
    req := apivideosdk.WatermarksApiListRequest{}
    
    req.SortBy("createdAt") // string | Allowed: createdAt. You can search by the time watermark were created at.
    req.SortOrder("asc") // string | Allowed: asc, desc. asc is ascending and sorts from A to Z. desc is descending and sorts from Z to A.
    req.CurrentPage(int32(2)) // int32 | Choose the number of search results to return per page. Minimum value: 1 (default to 1)
    req.PageSize(int32(30)) // int32 | Results per page. Allowed values 1-100, default is 25. (default to 25)

    res, err := client.Watermarks.List(req)
    

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `Watermarks.List``: %v\n", err)
    }
    // response from `List`: WatermarksListResponse
    fmt.Fprintf(os.Stdout, "Response from `Watermarks.List`: %v\n", res)
}

const ApiVideoClient = require('@api.video/nodejs-client');

(async () => {
    try {
        const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" });

        const sortBy = 'createdAt'; // Allowed: createdAt. You can search by the time watermark were created at.
        const sortOrder = 'asc'; // Allowed: asc, desc. asc is ascending and sorts from A to Z. desc is descending and sorts from Z to A.
        const currentPage = '2'; // Choose the number of search results to return per page. Minimum value: 1
        const pageSize = '30'; // Results per page. Allowed values 1-100, default is 25.

        // WatermarksListResponse
        const result = await client.watermarks.list({ sortBy, sortOrder, currentPage, pageSize })
        console.log(result);
    } catch (e) {
        console.error(e);
    }
})();

# List all watermarks 
import apivideo
from apivideo.apis import WatermarksApi
from apivideo.exceptions import ApiAuthException

api_key = "your api key here"

client = apivideo.AuthenticatedApiClient(api_key)

# If you'd rather use the sandbox environment:
# client = apivideo.AuthenticatedApiClient(api_key, production=False)

client.connect()

watermark_api = WatermarksApi(client)

# List all watermark details
response = watermark_api.list()
print(response)

Add a watermark to a video using a watermark ID

You can add a watermark to a video after you have uploaded the watermark. To add the watermark, the video must not yet be uploaded yet. Once you upload the watermark, retrieve the watermark ID and prepare your video. Uploading a video (when you don't use the delegated method, and you cannot add a watermark with the delegated upload method) is a two step process. First, you create a video container and retrieve the video ID. Then, you upload your video into the container using the video ID. You add your watermark in the container creation step, as shown in the code sample:

curl --request POST \
     --url https://ws.api.video/videos \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MDk2MzIuNTQ2MDg5LCJuYmYiOjE2NDI4MDk2MzIuNTQ2MDg5LCJleHAiOjE2NDI4MTMyMzIuNTQ2MDg5LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.J0cMjE7DNwTGvu3cprGpg5R5IHVDHip80ruWaCN57e9jDoJ4FK51Zkk2ynxhb1SqvutYi-hpnmOzqbPUFPjspLjTVbn0sUskKvGRst2gO2vNllHtIzNTlKKLMA_Sa_zi7hK5_XfuNod-B0SqeH106oAqe1FWkZjc7PMuqOzKS3dIqih0PczsbBQWWgQ3Fh-LtHxVVmdY_egq9i-t1fD5JCD812CHAK1HsxpAkpcAmpJptomORbq72tmEmgFfFUEJ8lalROM2_7ZDLvCdHxDYpA6_j5Z6k1y6Z_OjOsLg_mmiFymAT-DpUib2oOQyj2efIMo-OvdfNJhQRAcUMAUZyw' \
     --header 'Content-Type: application/json' \
     --data '
{
     "public": true,
     "panoramic": false,
     "mp4Support": true,
     "watermark": {
          "id": "watermark_1Bhes1otLhmPPNenUDyvHV"
     },
     "source": "https://cdn.api.video/vod/vi2qyv9Ma7UFyTOexm3JSmD2/mp4/1080/source.mp4",
     "title": "Video with a watermark"
}
'

import apivideo
from apivideo.api import videos_api
from apivideo.model.video_creation_payload import VideoCreationPayload
from apivideo.model.bad_request import BadRequest
from apivideo.model.video import Video
from pprint import pprint

# Enter a context with an instance of the API client
with apivideo.AuthenticatedApiClient(__API_KEY__) as api_client:
    # Create an instance of the API class
    api_instance = videos_api.VideosApi(api_client)
    video_creation_payload = VideoCreationPayload(
        title="Maths video",
        description="A video about string theory.",
        source="https://www.myvideo.url.com/video.mp4",
        public=True,
        panoramic=False,
        mp4_support=True,
        player_id="pl45KFKdlddgk654dspkze",
        tags=["maths", "string theory", "video"],
        metadata=[
            Metadata(
                key="Color",
                value="Green",
            ),
        ],
        clip=VideoClip(
            start_timecode="8072",
            end_timecode="8072",
        ),
        watermark=VideoWatermark(
            id="watermark_1BWr2L5MTQwxGkuxKjzh6i",
            top="10px",
            left="10px",
            bottom="10px",
            right="10px",
            width="50%",
            height="50%",
            opacity="70%",
        ),
    ) # VideoCreationPayload | video to create

    # example passing only required values which don't have defaults set
    try:
        # Create a video
        api_response = api_instance.create(video_creation_payload)
        pprint(api_response)
    except apivideo.ApiException as e:
        print("Exception when calling VideosApi->create: %s\n" % e)

Delete a watermark

To delete a watermark, send the unique watermark ID to the watermarks endpoint. Deletion is permanent, you will not be able to retrieve your watermark after completing this request.

curl --request DELETE \
     --url https://ws.api.video/watermarks/watermark_1BhfLVwM8eEdaN9XFSnxCS \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MDk2MzIuNTQ2MDg5LCJuYmYiOjE2NDI4MDk2MzIuNTQ2MDg5LCJleHAiOjE2NDI4MTMyMzIuNTQ2MDg5LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.J0cMjE7DNwTGvu3cprGpg5R5IHVDHip80ruWaCN57e9jDoJ4FK51Zkk2ynxhb1SqvutYi-hpnmOzqbPUFPjspLjTVbn0sUskKvGRst2gO2vNllHtIzNTlKKLMA_Sa_zi7hK5_XfuNod-B0SqeH106oAqe1FWkZjc7PMuqOzKS3dIqih0PczsbBQWWgQ3Fh-LtHxVVmdY_egq9i-t1fD5JCD812CHAK1HsxpAkpcAmpJptomORbq72tmEmgFfFUEJ8lalROM2_7ZDLvCdHxDYpA6_j5Z6k1y6Z_OjOsLg_mmiFymAT-DpUib2oOQyj2efIMo-OvdfNJhQRAcUMAUZyw'

const ApiVideoClient = require('@api.video/nodejs-client');

(async () => {
    try {
        const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" });

        const watermarkId = 'watermark_1BWr2L5MTQwxGkuxKjzh6i'; // The watermark ID for the watermark you want to delete.

        // void
        const result = await client.watermarks.delete(watermarkId);
        console.log(result);
    } catch (e) {
        console.error(e);
    }
})();

# Delete a watermark using its ID
import apivideo
from apivideo.apis import WaterkmarksApi
from apivideo.exceptions import ApiAuthException

api_key = "your api key here"
watermark = "your watermark ID here"

client = apivideo.AuthenticatedApiClient(api_key)

# If you'd rather use the sandbox environment:
# client = apivideo.AuthenticatedApiClient(api_key, production=False)

client.connect()

watermarks_api = WatermarksApi(client)

# Delete the watermark
response = watermarks_api.delete(watermark)
print(response)