Updated on 2024-03-14 GMT+08:00

Modifying a Watermark Template

Function

This API is used to modify a watermark template.

Calling Method

For details, see Calling APIs.

URI

PUT /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 the project ID, see Obtaining a Project ID .

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

User token

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

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

dx

No

String

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

Possible options are:

  • Integer: horizontal offset between the watermark start point and the video vertex, in pixels. Value range: [0, 4096]

  • Decimal: horizontal offset ratio of the watermark start point to the video width. The value range is (0, 1). Up to four decimal places are displayed, for example, 0.9999. If the value contains more than four decimal places, the part behind the fourth decimal place is automatically truncated.

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

dy

No

String

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

  • Possible options are: Integer: vertical offset between the watermark start point and the video vertex, in pixels. The value range is [0, 4096].

  • Decimal: vertical offset ratio of the watermark start point to the video height. The value range is (0, 1). Up to four decimal places are displayed, for example, 0.9999. If the value contains more than four decimal places, the part behind the fourth decimal place is automatically truncated.

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

referpos

No

String

Watermark position.

Possible values:

  • TopRight: upper right corner

  • TopLeft: upper left corner

  • BottomRight: lower right corner

  • BottomLeft: lower left corner

timeline_start

No

String

Watermark start time, which is used together with timeline_duration.

Its value is a digit.

Unit: second

timeline_duration

No

String

Watermark duration, which is used together with timeline_start.

The value ranges from number to ToEND. ToEND indicates that the watermark lasts until the end of the video.

Default value: ToEND

image_process

No

String

Image watermark processing mode. This parameter is valid only when type is set to Image.

The options are as follows:

  • Original: Only simple scaling is performed.

  • Grayed: Image graying is performed.

  • Transparent: The transparency of the original transparent image is retained.

width

No

String

Watermark image width. The options are as follows:

  • Integer: width of a watermark image, in pixels. The value ranges from 8 to 4,096.

  • Decimal: ratio of the width to the width of the output video. The value range is (0, 1). Up to four decimal places are displayed, for example, 0.9999. If the value contains more than four decimal places, the part behind the fourth decimal place is automatically truncated.

height

No

String

Watermark image height. The options are as follows:

  • Integer: height of a watermark image, in pixels. The value ranges from 8 to 4,096.

  • Decimal: ratio of the height to the height of the output video. The value is greater than 0 and less than 1, and can contain up to four decimal places, for example, 0.9999. If the value contains more than four decimal places, the part behind the fourth decimal place is automatically truncated.

base

No

String

Video on which the watermark is overlaid.

Possible values:

  • input: The watermark is overlaid on the input file. After transcoding, the size of the output file is scaled based on the aspect ratio of images.

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

template_id

No

Integer

ID of a watermark template.

template_name

No

String

Watermark template name, which contains a maximum of 64 characters

type

No

String

Watermark type, which can only be set to Image. Text watermark (Text) will be supported later as required.

Response Parameters

Status code: 403

Table 4 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error description

Example Requests

Updates a customized watermark template.

PUT https://{endpoint}/v1/{project_id}/template/watermark

{
  "template_name" : "watermark_1920*1080_10*10_ BottomLeft",
  "type" : "Image",
  "image_process" : "Grayed",
  "width" : "1920",
  "height" : "1080",
  "dx" : "0.1",
  "dy" : "0.1",
  "referpos" : "BottomLeft",
  "timeline_start" : "6",
  "timeline_duration" : "100"
}

Example Responses

Status code: 403

Failed to modify the watermark template.

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

Status Codes

Status Code

Description

204

Watermark template modified successfully.

403

Failed to modify the watermark template.

Error Codes

See Error Codes.