On this page

Function
Calling Method
URI
Request Parameters
Response Parameters
Example Requests
Example Responses
Status Codes
Error Codes

Show all

Help Center/ Media Processing Center/ API Reference/ Watermark Template APIs/ Creating a Watermark Template

Creating a Watermark Template

Updated on 2025-03-20 GMT+08:00

Online Debugging

CLI Examples

View PDF

Function

Creates a custom watermark template. A maximum of 100,000 watermark templates can be created by default.

Visible watermarks can be inserted into video content. These watermarks have various applications and content types, such as sponsor or partner logo, quality or certification mark.

A watermark template is a collection of preset parameters used to define key attributes such as the watermark's position and size. Watermark templates streamline the development process of watermarked applications, achieving rapid and consistent watermarking.

A watermark template applies only to image watermarks, not text ones. To add a text watermark, specify the parameter WaterMarks in the API CreateTranscodingTask.
A watermark template only specifies the position and size of the watermark, and does not include the watermark material. The watermark material needs to be added when submitting a media transcoding task.
A watermark template can be created either through the console or by calling the API CreateWatermarkTemplate.

Calling Method

For details, see Calling APIs.

URI

POST /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. (tag:hc,hk) Project ID. For details about how to obtain the project ID, see [Obtaining a Project ID]. (tag:hcso,g42,cmcc)

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
random_time_min	No	Float	Minimum rotation interval, unit: second
random_time_max	No	Float	Maximum rotation interval time, unit: second
image_process	No	String	Image watermarking method. This parameter is valid only when type is set to Image. Options: Original: Only simple scaling is performed. Grayed: Image graying is performed. Transparent: The transparency of the source image is retained. If the source image contains transparent areas, these areas remain transparent after transcoding, allowing the underlying background or image to be displayed. This enables seamless fusion between the image and the background.
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 a watermark is overlaid Options: input: A watermark is overlaid on the input file. The size of the watermark in the transcoded file is scaled based on the aspect ratio of the video. output: A watermark is overlaid on the transcoded file. The size of the watermark in the transcoded file is not scaled based on the aspect ratio of the video.
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: 201

**Table 4** Response body parameters
Parameter	Type	Description
template_id	Integer	ID of each queried watermark template

Status code: 403

**Table 5** Response body parameters
Parameter	Type	Description
error_code	String	Error code
error_msg	String	Error description

Example Requests

Creates a watermark template. A maximum of 100,000 watermark templates can be created by default.

POST 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" : "10",
  "dy" : "10",
  "referpos" : "BottomLeft",
  "timeline_start" : "6",
  "timeline_duration" : "8"
}

Example Responses

Status code: 201

Watermark template created successfully.

{
  "template_id" : 100211
}

Status code: 403

Failed to create a watermark template.

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

Status Codes

Status Code	Description
201	Watermark template created successfully.
403	Failed to create a watermark template.

Error Codes

See Error Codes.

Parent Topic: Watermark Template APIs

Previous topic: Watermark Template APIs

Next topic: Modifying a Watermark Template

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot