接口功能介绍
用户可在点播模式下通过本接口对媒体库的视频文件进行截屏并设置为封面。
接口约束
本接口的单用户QPS限制为20次/秒。超过限制，API调用会被限流，这可能会影响您的业务，请合理调用。
URI
POST /task/extractFrame
请求体body参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|---|
| videoId | 是 | String | 视频ID。 | 34c71dba-f280-4f5e-a05f-f4daed837fef | |
| time | 否 | Integer | 可选参数，为截屏的时间，如不填，默认使用智能截图，在前100帧内挑选一张最合适的图片作为封面，如传入小数则会自动四舍五入。 | 0 | |
| quality | 否 | Integer | 可选参数，图片质量，1 ~ 31，1表示质量最好，31 质量最差，默认为 2。 | 2 | |
| width | 否 | Integer | 可选参数，宽以及高，可传入其中一个，剩下的会根据源视频进行等比例缩放。 | 1024 | |
| height | 否 | Integer | 可选参数，宽以及高，可传入其中一个，剩下的会根据源视频进行等比例缩放。 | 768 | |
| useDefaultWatermarkTemplate | 否 | Boolean | 可选参数，是否使用水印默认模板，如果不填写默认为 false。 | true | |
| watermarkTemplate | 否 | Long | 可选参数，当 userDefaultWatermarkTemplate 为 true 时无效。当 userDefaultWatermarkTemplate 为 false 或者不传入，watermarkTemplate 也不传入时表示不使用水印。 | 100000000003 |
响应参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|---|
| code | 是 | Integer | 本次请求的结果码。 | 0 | |
| message | 是 | String | 错误文本信息，创建成功时，为空字符串。 | "" | |
| data | 是 | Object | 返回数据。 | data |
表 data
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|---|
| coverUrl | 是 | String | 新封面访问地址 | https://example.gdoss.xstore.ctyun.cn/a4ea36031c3046f7a01742f3fda4e249.jpg |
请求示例
请求体body
{
"videoId": "34c71dba-f280-4f5e-a05f-f4daed837fef",
"time": 0,
"quality": 2,
"width": 1024,
"height": 768,
"useDefaultWatermarkTemplate": true,
"watermarkTemplate": 100000000003
}
响应示例
{
"code": 0,
"message": "",
"data":{
"coverUrl":"https://example.gdoss.xstore.ctyun.cn/a4ea36031c3046f7a01742f3fda4e249.jpg"
}
}
状态码
| Http 状态码 | 状态码信息 | 状态码描述 |
|---|---|---|
| 0 | 表示业务成功 | 表示业务成功 |
| 400 | 请求参数有误 | 请求参数有误 |
| 403 | 用户鉴权失败，用户无操作权限 | 用户鉴权失败，用户无操作权限 |
| 404 | 请求的资源不存在，输入错误的URL | 请求的资源不存在，输入错误的URL |
| 500 | 业务执行异常 | 业务执行异常 |
错误码
OpenAPI错误码请参考 错误码说明。
