功能描述
创建视频截图模板。
授权说明
服务开通
使用该功能需提前开通数据万象,并绑定存储桶。详情请参见 绑定存储桶。
使用该功能需提前通过控制台或接口开通媒体处理服务 。详情请参见 开通媒体处理服务。
使用限制
请求
请求示例
POST /template HTTP/1.1Host: <BucketName-APPID>.ci.<Region>.myqcloud.comDate: <GMT Date>Authorization: <Auth String>Content-Length: <length>Content-Type: application/xml<body>
说明
请求头
请求体
该请求操作的实现需要有如下请求体。
<Request><Tag>Snapshot</Tag><Name>TemplateName</Name><Snapshot><Mode>Interval</Mode><Width>1280</Width><Height>960</Height><Start>0</Start><TimeInterval>0.5</TimeInterval><Count>10</Count><SnapshotOutMode>OnlySprite</SnapshotOutMode><SpriteSnapshotConfig><Color>Aquamarine</Color><Columns>3</Columns><Lines>3</Lines></SpriteSnapshotConfig></Snapshot></Request>
具体数据描述如下:
节点名称(关键字) | 父节点 | 描述 | 类型 | 是否必选 |
Request | 无 | 保存请求的容器 | Container | 是 |
Container 类型
Request
的具体数据描述如下:节点名称(关键字) | 父节点 | 描述 | 类型 | 是否必选 |
Tag | Request | 模板类型:Snapshot | String | 是 |
Name | Request | 模板名称,仅支持中文、英文、数字、_、-和*,长度不超过 64 | String | 是 |
Snapshot | Request | 截图参数 | Container | 是 |
Container 类型
Snapshot
的具体数据描述如下:节点名称(关键字) | 父节点 | 描述 | 类型 | 默认值 | 是否必选 |
Mode | Request.Snapshot | 截图模式 值范围:{Interval, Average, KeyFrame} Interval 表示间隔模式,Start,TimeInterval,Count参数生效。当设置 Count,未设置 TimeInterval 时,表示截取所有帧,共Count张图片 Average 表示平均模式,Start,Count参数生效。表示从Start开始到视频结束,按平均间隔截取共Count张图片 KeyFrame 表示关键帧模式 | String | Interval | 否 |
Start | Request.Snapshot | 开始时间 [0 视频时长] 单位为秒 支持 float 格式,执行精度精确到毫秒 | String | 0 | 否 |
TimeInterval | Request.Snapshot | 截图时间间隔 (0 3600] 单位为秒 支持 float 格式,执行精度精确到毫秒 | String | 无 | 否 |
Count | Request.Snapshot | 截图数量,取值范围 (0,10000] | String | 无 | 是 |
Width | Request.Snapshot | 宽 值范围:[128,4096] 单位:px 若只设置 Width 时,按照视频原始比例计算 Height | String | 视频原始宽度 | 否 |
Height | Request.Snapshot | 高 值范围:[128,4096] 单位:px 若只设置 Height 时,按照视频原始比例计算 Width | String | 视频原始高度 | 否 |
CIParam | Request.Snapshot | String | 无 | 否 | |
IsCheckCount | Request.Snapshot | 是否强制检查截图个数。使用自定义间隔模式截图时,视频时长不够截取 Count 个截图,可以转为平均截图模式截取 Count 个截图 | String | false | 否 |
IsCheckBlack | Request.Snapshot | 是否开启黑屏检测,取值 true、false | String | false | 否 |
BlackLevel | Request.Snapshot | 截图黑屏检测参数 当 IsCheckBlack=true 时有效 值参考范围[30,100],表示黑色像素的占比值,值越小,黑色占比越小 Start>0,参数设置无效,不做过滤黑屏 Start =0 参数有效,截帧的开始时间为第一帧非黑屏开始 | String | 空 | 否 |
PixelBlackThreshold | Request.Snapshot | 截图黑屏检测参数 当 IsCheckBlack=true 时有效 判断像素点是否为黑色点的阈值,取值范围:[0,255] | String | 空 | 否 |
SnapshotOutMode | Request.Snapshot | 截图输出模式参数 OnlySnapshot:仅输出截图模式 OnlySprite:仅输出雪碧图模式 SnapshotAndSprite:输出截图与雪碧图模式 | String | OnlySnapshot | 否 |
SpriteSnapshotConfig | Request.Snapshot | 雪碧图输出配置 | Container | 无 | 否 |
Container 类型 Snapshot.SpriteSnapshotConfig 的具体数据描述如下:
节点名称(关键字) | 父节点 | 描述 | 类型 | 默认值 | 是否必选 |
CellWidth | Request.Snapshot.SpriteSnapshotConfig | 单图宽度 值范围:[8,4096] 单位:px | String | 截图宽度 | 否 |
CellHeight | Request.Snapshot.SpriteSnapshotConfig | 单图高度 值范围:[8,4096] 单位:px | String | 截图高度 | 否 |
Padding | Request.Snapshot.SpriteSnapshotConfig | 雪碧图内边距大小 值范围:[0,1024] 单位:px | String | 0 | 否 |
Margin | Request.Snapshot.SpriteSnapshotConfig | 雪碧图外边距大小 值范围:[0,1024] 单位:px | String | 0 | 否 |
Color | Request.Snapshot.SpriteSnapshotConfig | String | 无 | 是 | |
Columns | Request.Snapshot.SpriteSnapshotConfig | 雪碧图列数,值范围:[1,10000] | String | 无 | 是 |
Lines | Request.Snapshot.SpriteSnapshotConfig | 雪碧图行数,值范围:[1,10000] | String | 无 | 是 |
ScaleMethod | Request.Snapshot.SpriteSnapshotConfig | 雪碧图缩放模式 DirectScale: 指定宽高缩放 MaxWHScaleAndPad: 指定最大宽高缩放填充 MaxWHScale: 指定最大宽高缩放 主动设置 CellWidth 和CellHeight 时生效 | String | DirectScale | 否 |
响应
响应头
响应体
该响应体返回为 application/xml 数据,包含完整节点数据的内容展示如下:
<Response><RequestId>NTk0MjdmODlfMjQ4OGY3XzYzYzhf****</RequestId><Template><Tag>Snapshot</Tag><Name>TemplateName</Name><TemplateId>t1f16e1dfbdc994105b31292d45710642a</TemplateId><BucketId>test-1234567890</BucketId><Category>Custom</Category><Snapshot><Mode>Interval</Mode><Width>1280</Width><Height>960</Height><Start>0</Start><TimeInterval>0.5</TimeInterval><Count>10</Count><SnapshotOutMode>OnlySprite</SnapshotOutMode><SpriteSnapshotConfig><Color>Aquamarine</Color><Columns>3</Columns><Lines>3</Lines></SpriteSnapshotConfig></Snapshot><CreateTime>2020-08-05T11:35:24+0800</CreateTime><UpdateTime>2020-08-31T16:15:20+0800</UpdateTime></Template></Response>
具体的数据内容如下:
节点名称(关键字) | 父节点 | 描述 | 类型 |
Response | 无 | 保存结果的容器 | Container |
Container 节点
Response
的内容:节点名称(关键字) | 父节点 | 描述 | 类型 |
Template | Response | 保存结果的容器 | Container |
RequestId | Response | 请求的唯一 ID | String |
Container 节点
Template
的内容:节点名称(关键字) | 父节点 | 描述 | 类型 |
Tag | Response | 模板类型,Snapshot | String |
Name | Response | 模板名字 | String |
TemplateId | Response | 模板 ID | String |
UpdateTime | Response | 更新时间 | String |
CreateTime | Response | 创建时间 | String |
Snapshot | Response | 详细的模板参数,同 Request.Snapshot | Container |
错误码
实际案例
请求
POST /template HTTP/1.1Authorization: q-sign-algorithm=sha1&q-ak=AKIDZfbOAo7cllgPvF9cXFrJD0a1ICvR****&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=28e9a4986df11bed0255e97ff90500557e0ea057Host: test-1234567890.ci.ap-beijing.myqcloud.comContent-Length: 1666Content-Type: application/xml<Request><Tag>Snapshot</Tag><Name>TemplateName</Name><Snapshot><Mode>Interval</Mode><Width>1280</Width><Height>960</Height><Start>0</Start><TimeInterval>0.5</TimeInterval><Count>10</Count><SnapshotOutMode>OnlySprite</SnapshotOutMode><SpriteSnapshotConfig><Color>Aquamarine</Color><Columns>3</Columns><Lines>3</Lines></SpriteSnapshotConfig></Snapshot></Request>
响应
HTTP/1.1 200 OKContent-Type: application/xmlContent-Length: 100Connection: keep-aliveDate: Thu, 14 Jul 2022 12:37:29 GMTServer: tencent-cix-ci-request-id: NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc=<Response><RequestId>NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc=</RequestId><Template><Tag>Snapshot</Tag><Name>TemplateName</Name><TemplateId>t1f16e1dfbdc994105b31292d45710642a</TemplateId><BucketId>test-1234567890</BucketId><Category>Custom</Category><Snapshot><Mode>Interval</Mode><Width>1280</Width><Height>960</Height><Start>0</Start><TimeInterval>0.5</TimeInterval><Count>10</Count><SnapshotOutMode>OnlySprite</SnapshotOutMode><SpriteSnapshotConfig><Color>Aquamarine</Color><Columns>3</Columns><Lines>3</Lines></SpriteSnapshotConfig></Snapshot><CreateTime>2020-08-05T11:35:24+0800</CreateTime><UpdateTime>2020-08-31T16:15:20+0800</UpdateTime></Template></Response>