Creating a Watermark Template
Function
Creates a watermark template. The watermark template takes effect only after a watermark rule is bound.
Calling Method
For details, see Calling APIs.
URI
POST /v1/{project_id}/watermark/templates
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
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. |
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 |
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:
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) |
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. |
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: 201
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.) |
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 |
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:
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) |
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. |
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
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.) |
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Error Code |
error_msg |
String |
Error description |
Example Requests
POST https://{endpoint}/v1/{project_id}/watermark/templates { "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: 201
Watermark template created.
{ "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 creation failed.
{ "error_code" : "LIVE.100011001", "error_msg" : "Request Illegal" }
Status Codes
Status Code |
Description |
---|---|
201 |
Watermark template created. |
400 |
Watermark template creation failed. |
Error Codes
See Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.