更新时间:2025-08-28 GMT+08:00
分享

查询水印模板列表

功能介绍

查询水印模板列表接口,通过指定条件,查询满足条件的水印模板列表。

调用方法

请参见如何调用API

URI

GET /v1/{project_id}/watermark/templates

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

项目ID,获取方法请参考获取项目ID

表2 Query参数

参数

是否必选

参数类型

描述

name

String

水印模板名称

scene

String

区分媒体直播还是云直播,默认云直播,默认查询cloud_live

offset

Integer

偏移量,表示从此偏移量开始查询,offset大于等于0

limit

Integer

每页记录数,取值范围[1,100],默认值10

请求参数

表3 请求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信息。

响应参数

状态码:200

表4 响应Header参数

参数

参数类型

描述

X-request-id

String

此字段携带请求ID号,以便任务跟踪。格式为:request_id-timestamp-hostname(request_id在服务器端生成UUID,timestamp为当前时间戳,hostname为处理当前接口的服务器名称)

表5 响应Body参数

参数

参数类型

描述

total

Integer

总数

template_infos

Array of WatermarkTemplate objects

响应数据

表6 WatermarkTemplate

参数

参数类型

描述

name

String

水印模板名称

type

Integer

水印类型,0图片,1文字,2图文共存

description

String

模板注释

picture_url

String

图片下载路径

校验规则:图片URL长度大于0,最大长度2048,能够正常按URL格式解析,必须是 http 或 https 协议。(OTT 场景限制只支持https)

图片格式: .png/.jpg/.PNG/.JPG结尾

width

Number

1)整数型代表水印图片宽的像素值,范围0或[8,4096],单位px。

2)小数型代表相对输出视频分辨率宽的比率,范围[0,1)

建议宽高只设置一项,另外一项会自适应缩放,避免变形。宽高全部设置为0表示水印图片原始宽高

百分比限制最多保留小数点后4位,width和height 只支持同时为像素或是百分比,不支持一个像素,一个百分比

height

Number

水印图片高,值有两种形式:

1)整数型代表水印图片高的像素值,范围0或[8,4096],单位px。

2)小数型代表相对输出视频分辨率高的比率,范围[0,1)

建议宽高只设置一项,另外一项会自适应缩放,避免变形。宽高全部设置为0表示水印图片原始宽高

百分比限制最多保留小数点后4位,width和height 只支持同时为像素或是百分比,不支持一个像素,一个百分比

location

WatermarkLocation object

水印位置

text

WordWaterMarkInfo object

文字水印信息

scene

String

业务属性,cloud_live:云直播,默认值;media_live:媒体直播,不支持修改

表7 WordWaterMarkInfo

参数

参数类型

描述

format

String

水印文字内容,必填 字幕内容1-64

type为1或2时必填,type为0时非必填

font_color

String

参数校验:首位为#、除#外为6位或8位,每位字符由 0-9、a~f、A~F 组成【务必校验,错误时转码默认白色】

font_size

Integer

字体大小

font

String

字体,缺省值 空,可选值:harmonyRegular(鸿蒙)、douyu2.0(斗鱼追光体)

time_zone

String

时区,【取值参考 UTC-1200 至 UTC+1200,前三位UTC,第四位+或-,五六位表示小时,七八位固定00】

shadow_color

String

缺省值 none,参数校验:首位为#、除#外为6位或8位,每位字符由 0-9、a~f、A~F 组成【务必校验,错误时转码默认黑色】

location

WatermarkLocation object

location位置必填

表8 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

表9 响应Header参数

参数

参数类型

描述

X-request-id

String

此字段携带请求ID号,以便任务跟踪。格式为:request_id-timestamp-hostname(request_id在服务器端生成UUID,timestamp为当前时间戳,hostname为处理当前接口的服务器名称)

表10 响应Body参数

参数

参数类型

描述

error_code

String

错误码

error_msg

String

错误描述

请求示例

GET https://live.hwcloud.com/v1/{project_id}/watermark/templates

响应示例

状态码:200

查询水印模板成功

{
  "total" : 1,
  "template_infos" : [ {
    "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
    }
  } ]
}

状态码:400

参数错误

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

状态码

状态码

描述

200

查询水印模板成功

400

参数错误

错误码

请参见错误码

相关文档