Help Center> Media Processing Center> API Reference> Watermark Template APIs> Querying Watermark Templates
View PDF

Querying Watermark Templates

Function

This API is used to query one or more custom watermark templates by template ID or page number.

URI

GET /v1/{project_id}/template/watermark

Table 1 Path parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain a project ID, see Obtaining a Project ID.
Table 2 Query parameters

Parameter

Mandatory

Type

Description

template_id

No

Array

Watermark template ID. A maximum of 10 template IDs can be queried at a time.

page

No

Integer

Page number. If task_id is specified, this parameter is invalid.

Default value: 0.

size

No

Integer

Number of records on each page. If template_id is specified, this parameter is invalid. The value ranges from 1 to 100.

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

User token.

The token is obtained by calling the IAM API used to obtain a user token. The token is the value of X-Subject-Token in the response header.

Authorization

No

String

Authentication information. This parameter is mandatory when AK/SK-based authentication is used.

X-Project_Id

No

String

Project ID. This parameter is mandatory when AK/SK-based authentication is used. It is same as the project ID in path parameters.

X-Sdk-Date

No

String

Time when the request is sent. This parameter is mandatory when AK/SK-based authentication is used.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

total

Integer

Total number of queried watermark templates

templates

Array of WatermarkTemplate objects

Details about queried watermark templates
Table 5 WatermarkTemplate

Parameter

Type

Description

dx

String

Horizontal offset between the start point of the watermark and the vertex of the output video.

  • Integer: horizontal offset between the image start point and the video vertex, in pixelsThe value ranges from 0 to 4,096.

  • Decimal: horizontal offset ratio of the image start point relative to the video widthA maximum of four decimal places are supported, for example, 0.9999.

For example, if the output video width is 1,920 pixels, dx is 0.1, and referpos is TopRight, the horizontal offset between the upper right corner of the watermark and the right vertex of the video is 192.

dy

String

Vertical offset between the start point of the watermark and the vertex of the output video.

  • Integer: vertical offset between the image start point and the video vertex, in pixels.The value ranges from 0 to 4,096.

  • Decimal: vertical offset ratio of the image start point relative to the video heightA maximum of four decimal places are supported, for example, 0.9999.

For example, if the output video height is 1,080 pixels, dy is 0.1, and referpos is TopRight, the vertical offset between the upper right corner of the watermark and the right vertex of the video is 108.

referpos

String

Watermark position.

Possible values are:

  • TopRight: upper right corner

  • TopLeft: upper left cornerBottom

  • Right: lower right corner

  • BottomLeft: lower left corner

timeline_start

String

Watermark start time, which is used together with timeline_duration.

Its value is a digit.

Unit: s

timeline_duration

String

How long the watermark lasts, which is used together with timeline_start.

Its value is a digit greater than or equal to 0.

Default value: ToEND

ToEND indicates that the watermark lasts until the end of the video.

image_process

String

How the image watermark is processed. This parameter is used only when type is set to Image.

Possible values are:

  • Original: simple scaling

  • Grayed: Turn the color image to gray.

  • Transparent: transparent

width

String

Watermark width.

The value can either be a positive integer or a decimal between 0.0 and 1.0.

  • Integer: pixel value of the watermark width (unit: px)The value ranges from 8 to 4,096.

  • Decimal: ratio between the video width and watermark widthA maximum of four decimal places are supported, for example, 0.9999.

height

String

Watermark height.

The value can either be a positive integer or a decimal between 0.0 and 1.0.

  • Integer: pixel value of the watermark height (unit: px)The value ranges from 8 to 4,096.

  • Decimal: ratio between the video height and watermark heightA maximum of four decimal places are supported, for example, 0.9999.

base

String

Video which the watermark is overlaid on.

Possible values are:

  • input: The watermark is overlaid on the input video. The actual size of the output video is scaled proportionally based on the watermark size.

  • output: The watermark is overlaid on the output file.

template_name

String

Name of each queried watermark template

type

String

Watermark type.

Its value is:

Image: image watermark

Status code: 403

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error description

Example Requests

GET https://{endpoint}/v1/{project_id}/templates/watermark?template_id =2743

Example Responses

Status code: 200

Watermark template queried successfully.

{
  "total" : 1,
  "templates" : [ {
    "dx" : 0.1,
    "dy" : 0.1,
    "referpos" : "TopRight",
    "timeline_start" : 0,
    "timeline_duration" : "ToEND",
    "image_process" : "Original",
    "width" : 0.1,
    "height" : 0.1,
    "base" : "input",
    "template_id" : 2743,
    "template_name" : "createWatermarkTemplate1xYcdyUz",
    "type" : "Image"
  } ]
}

Status code: 403

Failed to query the watermark template.

{
  "error_code" : "MPC.10202",
  "error_msg" : "Invalid request parameter."
}

Status Codes

Status Code

Description

200

Watermark template queried successfully.

403

Failed to query the watermark template.

Error Codes

See Error Codes.

Parent topic: Watermark Template APIs