文档首页/ 视频直播 Live/ 云直播API参考/ 直播水印管理/ 创建水印规则
更新时间：2025-09-11 GMT+08:00
在线调试
CLI示例
查看PDF
分享

创建水印规则

功能介绍

创建水印规则接口，必须先创建水印模板

调用方法

请参见如何调用API。

URI

POST /v1/{project_id}/watermark/rules

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

项目ID，获取方法请参考获取项目ID。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

否

String

用户Token，使用Token鉴权方式时必填。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。

Authorization

否

String

使用AK/SK方式认证时必填，携带的鉴权信息。

X-Sdk-Date

否

String

使用AK/SK方式认证时必填，请求的发生时间。

X-Project-Id

否

String

使用AK/SK方式认证时必填，携带项目ID信息。
表3 请求Body参数

参数

是否必选

参数类型

描述

rule_name

否

String

水印规则名称，如果不填会使用默认名称。默认名称的构造规则为“域名:应用名:流名”，示例“example.com:live:stream”。

template_id

是

String

水印模板ID，只包含数字字母中划线，创建模板时生成

domain

是

String

域名

app

否

String

APP名。须知：云直播场景是可选配置，媒体直播场景为必选配置。

stream

否

String

流名OTT场景下，可以不填

location

否

WatermarkLocation object

水印位置

channel_id

否

String

OTT场景使用，填对应频道的频ID

transcode_template_name

否

String

OTT场景时，填频道对应的转码模板名称
表4 WatermarkLocation

参数

是否必选

参数类型

描述

location

否

String

水印位置。

包含如下选项：

  • TOPLEFT：左上

  • TOPRIGHT：右上

  • BOTTOMLEFT：左下

  • BOTTOMRIGHT：右下

  • RANDOM：随机模式，图片水印将随机在视频流的左上、右上、左下、右下四个位置展示。

x_offset

否

Number

水印相对输出视频的水平偏移量。

说明：值有两种形式：

1）整数型代表偏移像素，范围[1，4096]，单位px。

2）小数型代表水平偏移量与输出分辨率宽的比率，范围[0，1)

百分比限制最多保留小数点后4位

y_offset

否

Number

水印相对输出视频的垂直偏移量

说明: 值有两种形式：

1）整数型代表偏移像素，范围[1，4096]，单位px。

2）小数型代表垂直偏移量与输出分辨率高的比率，范围[0，1)

百分比限制最多保留小数点后4位

响应参数

状态码：201

表5 响应Header参数

参数

参数类型

描述

X-request-id

String

此字段携带请求ID号，以便任务跟踪。格式为：request_id-timestamp-hostname（request_id在服务器端生成UUID，timestamp为当前时间戳，hostname为处理当前接口的服务器名称）
表6 响应Body参数

参数

参数类型

描述

rule_name

String

水印规则名称，如果不填会使用默认名称。默认名称的构造规则为“域名:应用名:流名”，示例“example.com:live:stream”。

template_id

String

水印模板ID，只包含数字字母中划线，创建模板时生成

domain

String

域名

app

String

APP名。须知：云直播场景是可选配置，媒体直播场景为必选配置。

stream

String

流名OTT场景下，可以不填

location

WatermarkLocation object

水印位置

channel_id

String

OTT场景使用，填对应频道的频ID

transcode_template_name

String

OTT场景时，填频道对应的转码模板名称
表7 WatermarkLocation

参数

参数类型

描述

location

String

水印位置。

包含如下选项：

  • TOPLEFT：左上

  • TOPRIGHT：右上

  • BOTTOMLEFT：左下

  • BOTTOMRIGHT：右下

  • RANDOM：随机模式，图片水印将随机在视频流的左上、右上、左下、右下四个位置展示。

x_offset

Number

水印相对输出视频的水平偏移量。

说明：值有两种形式：

1）整数型代表偏移像素，范围[1，4096]，单位px。

2）小数型代表水平偏移量与输出分辨率宽的比率，范围[0，1)

百分比限制最多保留小数点后4位

y_offset

Number

水印相对输出视频的垂直偏移量

说明: 值有两种形式：

1）整数型代表偏移像素，范围[1，4096]，单位px。

2）小数型代表垂直偏移量与输出分辨率高的比率，范围[0，1)

百分比限制最多保留小数点后4位

状态码：400

表8 响应Header参数

参数

参数类型

描述

X-request-id

String

此字段携带请求ID号，以便任务跟踪。格式为：request_id-timestamp-hostname（request_id在服务器端生成UUID，timestamp为当前时间戳，hostname为处理当前接口的服务器名称）
表9 响应Body参数

参数

参数类型

描述

error_code

String

错误码

error_msg

String

错误描述

请求示例

POST https://{endpoint}/v1/{project_id}/watermark/rules

{
  "template_id" : "70b76xxxxxx34253880af501cdxxxxxx",
  "domain" : "push.example.com",
  "app" : "live",
  "stream" : "watermarkStream",
  "location" : {
    "location" : "TOPLEFT",
    "x_offset" : 20,
    "y_offset" : 10
  }
}

响应示例

状态码：201

创建水印规则操作成功

{
  "rule_name" : "string",
  "template_id" : "string",
  "domain" : "string",
  "app" : "string",
  "stream" : "string",
  "location" : {
    "location" : "string",
    "x_offset" : 4096,
    "y_offset" : 4096
  }
}

状态码：400

创建水印规则操作失败

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

状态码

状态码

描述

201

创建水印规则操作成功

400

创建水印规则操作失败

错误码

请参见错误码。

父主题： 直播水印管理