Updated on 2025-08-13 GMT+08:00

Modifying a Watermark Template

Function

Modifies a watermark template. The modification takes effect immediately.

Calling Method

For details, see Calling APIs.

URI

PUT /v1/{project_id}/watermark/templates/{id}

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

id

Yes

String

Template ID, which is returned after the template is created.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

User token. This parameter is mandatory when token authentication is used. The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Authorization

No

String

Authentication information. This parameter is mandatory for AK/SK authentication.

X-Sdk-Date

No

String

Time when the request is sent. This parameter is mandatory for AK/SK authentication.

X-Project-Id

No

String

Project ID. This parameter is mandatory for AK/SK authentication.

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

name

Yes

String

Watermark template name

type

No

Integer

Watermark type. 0: image; 1: text; 2: image and text

description

No

String

Template comment

picture_url

No

String

Image download path

Verification rule: An image URL can contain up to 2,048 characters, should be parsed properly, and use the HTTP or HTTPS protocol. (In the OTT scenario, only HTTPS is supported.)

Image format: The file name extension must be .png, .jpg, .PNG, or .JPG.

width

No

Number

  1. Integer: width of a watermark image, in pixels. The value can be 0 or range from 8 to 4,096.

  2. Decimal: ratio of the watermark width to the output video width. The value range is [0, 1).

You are advised to set either the width or height, as the other side will automatically adapt to avoid distortion. If both the width and height are set to 0, the original width and height of the watermark image are used.

The percentage can contain a maximum of four decimal places. The width and height must be both in pixels or both in percentage.

height

No

Number

Watermark image height. Options:

  1. Integer: height of a watermark image, in pixels. The value can be 0 or range from 8 to 4,096.

  2. Decimal: ratio of the watermark height to the output video height. The value range is [0, 1).

You are advised to set either the width or height, as the other side will automatically adapt to avoid distortion. If both the width and height are set to 0, the original width and height of the watermark image are used.

The percentage can contain a maximum of four decimal places. The width and height must be both in pixels or both in percentage.

location

No

WatermarkLocation object

Watermark position

text

No

WordWaterMarkInfo object

Text watermark information

scene

No

String

Service attribute. cloud_live: Cloud Live (default); media_live: Media Live (cannot be modified)

Table 4 WordWaterMarkInfo

Parameter

Mandatory

Type

Description

format

Yes

String

Watermark text content, which contains 1 to 64 characters.

This parameter is mandatory when type is set to 1 or 2 and is optional when type is set to 0.

font_color

No

String

Parameter verification: The first character is #, and the number of other characters is 6 or 8. Characters can contain digits (0–9), uppercase letters (A–F), and lowercase letters (a–f). [Verification is mandatory. If the verification fails, information will be displayed in white.]

font_size

No

Integer

Font size

font

No

String

Font. The default value is empty. The options are harmonyRegular and douyu2.0.

time_zone

No

String

Time zone. [The value ranges from UTC-1200 to UTC+1200. The first three characters are UTC, the fourth character is + or -, the fifth and sixth characters indicate the hour, and the seventh and eighth characters are fixed to 00.]

shadow_color

No

String

The default value is none. Parameter verification: The first character is #, and the number of other characters is 6 or 8. Characters can contain digits (0–9), uppercase letters (A–F), and lowercase letters (a–f). [Verification is mandatory. If the verification fails, information will be displayed in black.]

location

Yes

WatermarkLocation object

location is mandatory.

Table 5 WatermarkLocation

Parameter

Mandatory

Type

Description

location

No

String

Watermark position. The options are TOPLEFT (upper left), TOPRIGHT (upper right), BOTTOMLEFT (lower left), BOTTOMRIGHT (lower right), and RANDOM (random). If RANDOM is used, the watermark will randomly appear on the upper left, upper right, lower left, or lower right of the video.

x_offset

No

Number

Horizontal offset between the watermark and the output video.

Options:

(1) An integer indicates the offset pixel. The value ranges from 1 to 4,096, in pixels.

(2) A decimal indicates the ratio of the horizontal offset to the output video width. The value range is [0, 1).

The percentage can contain a maximum of four decimal places.

y_offset

No

Number

Vertical offset between the watermark and the output video.

Options:

(1) An integer indicates the offset pixel. The value ranges from 1 to 4,096, in pixels.

(2) A decimal indicates the ratio of the vertical offset to the output video height. The value range is [0, 1).

The percentage can contain a maximum of four decimal places.

Response Parameters

Status code: 200

Table 6 Response header parameters

Parameter

Type

Description

X-request-id

String

Request ID for task tracing. Format: request_id-timestamp-hostname. (request_id is the UUID generated on the server. timestamp is the current timestamp. hostname is the name of the server that handles the current request.)

Table 7 Response body parameters

Parameter

Type

Description

name

String

Watermark template name

type

Integer

Watermark type. 0: image; 1: text; 2: image and text

description

String

Template comment

picture_url

String

Image download path

Verification rule: An image URL can contain up to 2,048 characters, should be parsed properly, and use the HTTP or HTTPS protocol. (In the OTT scenario, only HTTPS is supported.)

Image format: The file name extension must be .png, .jpg, .PNG, or .JPG.

width

Number

  1. Integer: width of a watermark image, in pixels. The value can be 0 or range from 8 to 4,096.

  2. Decimal: ratio of the watermark width to the output video width. The value range is [0, 1).

You are advised to set either the width or height, as the other side will automatically adapt to avoid distortion. If both the width and height are set to 0, the original width and height of the watermark image are used.

The percentage can contain a maximum of four decimal places. The width and height must be both in pixels or both in percentage.

height

Number

Watermark image height. Options:

  1. Integer: height of a watermark image, in pixels. The value can be 0 or range from 8 to 4,096.

  2. Decimal: ratio of the watermark height to the output video height. The value range is [0, 1).

You are advised to set either the width or height, as the other side will automatically adapt to avoid distortion. If both the width and height are set to 0, the original width and height of the watermark image are used.

The percentage can contain a maximum of four decimal places. The width and height must be both in pixels or both in percentage.

location

WatermarkLocation object

Watermark position

text

WordWaterMarkInfo object

Text watermark information

scene

String

Service attribute. cloud_live: Cloud Live (default); media_live: Media Live (cannot be modified)

Table 8 WordWaterMarkInfo

Parameter

Type

Description

format

String

Watermark text content, which contains 1 to 64 characters.

This parameter is mandatory when type is set to 1 or 2 and is optional when type is set to 0.

font_color

String

Parameter verification: The first character is #, and the number of other characters is 6 or 8. Characters can contain digits (0–9), uppercase letters (A–F), and lowercase letters (a–f). [Verification is mandatory. If the verification fails, information will be displayed in white.]

font_size

Integer

Font size

font

String

Font. The default value is empty. The options are harmonyRegular and douyu2.0.

time_zone

String

Time zone. [The value ranges from UTC-1200 to UTC+1200. The first three characters are UTC, the fourth character is + or -, the fifth and sixth characters indicate the hour, and the seventh and eighth characters are fixed to 00.]

shadow_color

String

The default value is none. Parameter verification: The first character is #, and the number of other characters is 6 or 8. Characters can contain digits (0–9), uppercase letters (A–F), and lowercase letters (a–f). [Verification is mandatory. If the verification fails, information will be displayed in black.]

location

WatermarkLocation object

location is mandatory.

Table 9 WatermarkLocation

Parameter

Type

Description

location

String

Watermark position. The options are TOPLEFT (upper left), TOPRIGHT (upper right), BOTTOMLEFT (lower left), BOTTOMRIGHT (lower right), and RANDOM (random). If RANDOM is used, the watermark will randomly appear on the upper left, upper right, lower left, or lower right of the video.

x_offset

Number

Horizontal offset between the watermark and the output video.

Options:

(1) An integer indicates the offset pixel. The value ranges from 1 to 4,096, in pixels.

(2) A decimal indicates the ratio of the horizontal offset to the output video width. The value range is [0, 1).

The percentage can contain a maximum of four decimal places.

y_offset

Number

Vertical offset between the watermark and the output video.

Options:

(1) An integer indicates the offset pixel. The value ranges from 1 to 4,096, in pixels.

(2) A decimal indicates the ratio of the vertical offset to the output video height. The value range is [0, 1).

The percentage can contain a maximum of four decimal places.

Status code: 400

Table 10 Response header parameters

Parameter

Type

Description

X-request-id

String

Request ID for task tracing. Format: request_id-timestamp-hostname. (request_id is the UUID generated on the server. timestamp is the current timestamp. hostname is the name of the server that handles the current request.)

Table 11 Response body parameters

Parameter

Type

Description

error_code

String

Error Code

error_msg

String

Error description

Example Requests

PUT https://{endpoint}/v1/{project_id}/watermark/templates/e89b76xxxxxx3425ui80af501cdxxxxxx

{
  "name" : "MyWatermarkTemplate",
  "type" : 0,
  "description" : "my demo template",
  "picture_url" : "http://example.com/picture",
  "width" : 0.1,
  "height" : 0.1,
  "location" : {
    "location" : "TOPLEFT",
    "x_offset" : 20,
    "y_offset" : 10
  }
}

Example Responses

Status code: 200

Watermark template modified.

{
  "name" : "string",
  "type" : 1,
  "description" : "string",
  "picture_url" : "string",
  "width" : 4096,
  "height" : 4096,
  "location" : {
    "location" : "string",
    "x_offset" : 4096,
    "y_offset" : 4096
  }
}

Status code: 400

Watermark template modification failed.

{
  "error_code" : "LIVE.100011001",
  "error_msg" : "Request Illegal"
}

Status Codes

Status Code

Description

200

Watermark template modified.

400

Watermark template modification failed.

Error Codes

See Error Codes.