抽帧任务接口
更新时间：2022-10-10
创建缩略图任务
接口描述
用户通过Bucket，BOS Key以及其他配置信息为指定媒体生成缩略图。
请求（Request）
-
请求语法：
POST /v{version}/job/thumbnail HTTP/1.1 accept-encoding: gzip, deflate x-bce-date: {utc-date-string} connection: keep-alive accept: */* host: media.bj.baidubce.com x-bce-request-id: {bce-request-id} content-type: application/json authorization: {bce-authorization-string} - 请求头域：无特殊Header参数
- 请求参数（均为requestbody参数）：
| 字段名称 | 字段类型 | 必要性 | 字段描述 | 可选值 | 默认值 |
|---|---|---|---|---|---|
| pipelineName | String | 必选 | 任务所属的pipelineName | - | - |
| presetName | String | 可选 | 任务的模板名称（模板和job中重复内容以job中为准） | - | - |
| source | Object | 必选 | 输入视频信息的集合 | - | - |
| + sourceBucket | String | 可选 | 输入视频文件的BOS Bucket（用户必须有该bucket的读权限） | - | 队列中指定的输入bucket |
| + key | String | 必选 | 输入视频文件的BOS Key，支持public bucket下的hls（即key为m3u8文件） | - | - |
| target | Object | 可选 | 目标缩略图信息的集合 | - | - |
| + targetBucket | String | 可选 | 目标缩略图的BOS Bucket | - | 队列中指定的输出bucket |
| + keyPrefix | String | 可选 | 目标缩略图的BOS Key的前缀，mode=auto/idl/highlight 时目标文件名为 {keyPrefix}，mode=manual/split/shot 时目标文件名为 {keyPrefix}加截图时间点 | - | {sourceKey} |
| + format | String | 可选 | 目标缩略图的格式 | jpg、png、mp4、gif、webp | jpg |
| + sizingPolicy | String | 可选 | 目标缩略图的尺寸伸缩策略 | keep、shrinkToFit、stretch，keep表示保持原始视频宽高比，shrinkToFit表示保持原始视频宽高比并加黑边，stretch表示拉伸原始视频 | keep |
| + widthInPixel | Number | 可选 | 目标缩略图的宽，如果视频实际分辨率低于目标分辨率则按照实际分辨率输出 | 10 ~ 2000 | 600 |
| + heightInPixel | Number | 可选 | 目标缩略图的高，如果视频实际分辨率低于目标分辨率则按照实际分辨率输出 | 10 ~ 2000 | 450 |
| + frameRate | Number | 可选 | 动图的帧率，仅当format为mp4、gif、webp且mode为manual、split时可选 | 0.01 ~ 30.0 | 3.0 |
| + gifQuality | String | 可选 | gif的质量，仅当format为gif且mode为manual、split时可选 | high, medium | medium |
| + spriteOutputCfg | Object | 可选 | 雪碧图输出参数设置，仅当抽取多图（即mode=manual/split）,且输出为非动图（即format=jpg/png）时可选 | - | - |
| ++ rows | Number | 可选 | 雪碧图拼接行数 | 1 ~ 100 | 10 |
| ++ columns | Number | 可选 | 雪碧图拼接列数 | 1 ~ 100 | 10 |
| ++ margin | Number | 可选 | 外框宽度，单位：px | 1 ~ 1000 | 0 |
| ++ padding | Number | 可选 | 外框宽度，单位：px | 1 ~ 1000 | 0 |
| ++ keepCellPic | Bool | 可选 | 是否保留子图原图 | true, false | true |
| ++ spriteKeyTag | String | 可选 | 上传BOS的雪碧图的key中用于标记为雪碧图的tag，最终文件名为 {keyPrefix}+{spriteKeyTag}+{雪碧图序号%05d}，雪碧图中子图按照原视频中的顺序排列 | 字符串长度范围为1 ~ 100 | "-SPRITE-" |
| capture | Object | 可选 | 生成缩略图的规则 | - | - |
| + mode | String | 可选 | 生成缩略图的模式 | auto、manual、split、shot、idl、highlight，auto模式是系统自动截取熵值较高的一帧作为缩略图，manual模式是根据指定的起止时间和间隔时间截取缩略图，split模式是根据指定的起止时间和张数截取缩略图，shot模式根据场景切换自动截取画面(不支持输出视频格式)，idl模式时使用百度IDL（Institute of Deep Learning）智能缩略图算法截取缩略图（仅支持输出jpg、png格式），highlight模式自动生成一个0.5s的精彩片段（目前仅适用于竖屏小视频，只支持输出视频格式，默认为正播反播合并效果） | auto |
| + skipBlackFrame | Boolean | 可选 | 是否跳过黑帧，仅当mode=manual或split时可选 | true/false | false |
| + frameNumber | Number | 可选 | 生成缩略图的张数，仅当mode=split时可选 | 大于等于1 | 1 |
| + startTimeInSecond | Number | 可选 | 生成缩略图的开始时间，当mode=manual或split时可选 | 大于等于0 | 0.0 |
| + endTimeInSecond | Number | 可选 | 生成缩略图的结束时间，当mode=manual或split时可选，且不得小于start time | 大于等于0 | 视频时长 |
| + intervalInSecond | Number | 可选 | 生成缩略图的间隔时间，仅当mode=manual时可选 | 大于0 | 1.0 |
| + minIntervalInSecond | Number | 可选 | 生成缩略图的最小间隔时间，仅当mode=split时可选 | 大于0 | 1.0 |
| + highlightOutputCfg | Object | 可选 | highlight 模式下输出控制参数，仅当mode=highlight时可选 | - | - |
| ++ durationInSecond | Number | 可选 | 截取片段时长，单位：秒 | 0.1 ~ 7200.0 | 0.25 |
| ++ playbackSpeed | Number | 可选 | 回放速度，值低于1.0时为减速视频，高于1.0时为加速视频 | 0.05 ~ 20.0 | 1.0 |
| ++ frameRate | Number | 可选 | 输出视频帧率，单位：fps | 0.1 ~ 60.0 | 11.0 |
| ++ reverseConcat | Bool | 可选 | 正播反播合并效果 | true, false | true |
| delogoArea | Object | 可选 | 去水印参数，描述水印位置区域。 | - | - |
| + x | Number | 必选 | 水印区域相对左上角的x（横）坐标，左上角为0 | 大于等于0 | - |
| + y | Number | 必选 | 水印区域相对左上角的y（纵）坐标，左上角为0 | 大于等于0 | - |
| + width | Number | 必选 | 水印区域横向宽度 | 大于等于1 | - |
| + height | Number | 必选 | 水印区域纵向高度 | 大于等于1 | - |
| delogoAreas | Array | 可选 | 去多个水印参数，描述水印位置区域。不可与delogoArea同时指定 | - | - |
| + x | Number | 必选 | 水印区域相对左上角的x（横）坐标，左上角为0 | 大于等于0 | - |
| + y | Number | 必选 | 水印区域相对左上角的y（纵）坐标，左上角为0 | 大于等于0 | - |
| + width | Number | 必选 | 水印区域横向宽度 | 大于等于1 | - |
| + height | Number | 必选 | 水印区域纵向高度 | 大于等于1 | - |
| crop | Object | 可选 | 黑边裁剪参数，描述除去黑边后的有效区域（不可同时设置crop和shrinkToFit） | - | - |
| + x | Number | 必选 | 去黑边后的有效区域相对左上角的x（横）坐标，左上角为0 | 大于等于0 | - |
| + y | Number | 必选 | 去黑边后的有效区域相对左上角的y（纵）坐标，左上角为0 | 大于等于0 | - |
| + width | Number | 必选 | 去黑边后的有效区域横向宽度 | 大于等于1 | - |
| + height | Number | 必选 | 去黑边后的有效区域纵向高度 | 大于等于1 | - |
-
请求示例：
POST /v3/job/thumbnail HTTP/1.1 accept-encoding: gzip, deflate x-bce-date: 2015-03-24T13:08:44Z host: media.bj.baidubce.com accept: */* connection: keep-alive x-bce-request-id: d97c57d0-ca44-4d1c-bfeb-941a92440968 content-type: application/json authorization: bce-auth-v1/46bd9968a6194b4bbdf0341f2286ccce/2015-03-24T13:08:44Z/1800/host;x-bce-date/7e21c9cf1e4e2cc6921a407a388fe98df122c53b9f509043d841be76eb09a1f9 { "pipelineName": "high_priority_pipe", "source": { "key": "samplefolderpath/samplevideo.mp4" }, "target": { "keyPrefix": "sampleoutputfolderpath/samplethumbnail-", "format": "jpg", "sizingPolicy": "keep", "widthInPixel": "600", "heightInPixel": "450" }, "capture": { "mode": "manual", "startTimeInSecond": "20", "endTimeInSecond": "50", "intervalInSecond": "10" }, "delogoArea": { "x": 10, "y": 20, "width": 200, "height": 150 } }
响应（Reponse）
- 响应头域：无特殊Header参数
- 响应参数：
| 字段名称 | 字段类型 | 字段描述 |
|---|---|---|
| jobId | String | 系统生成的Thumbnail的唯一标示thumbnailId |
-
响应示例：
HTTP/1.1 200 OK Transfer-Encoding: chunked x-bce-request-id: d97c57d0-ca44-4d1c-bfeb-941a92440968 Cache-Control: no-cache Server: BWS Date: Tue, 24 Mar 2015 13:34:07 GMT Content-Type: application/json;charset=UTF-8 { "jobId":"job-lsdspxdastsmnbam" }
查询指定缩略图任务
请求（Request）
-
请求语法：
GET /v{version}/job/thumbnail/{jobId} HTTP/1.1 accept-encoding: gzip, deflate x-bce-date: {utc-date-string} host: media.bj.baidubce.com accept: */* connection: keep-alive x-bce-request-id: {bce-request-id} content-type: application/json authorization: {bce-authorization-string} - 请求头域：无特殊Header参数
- 请求参数：无
-
请求示例：
GET /v3/job/thumbnail/job-lsdspxdastsmnbam HTTP/1.1 accept-encoding: gzip, deflate x-bce-date: 2015-03-24T13:08:44Z host: media.bj.baidubce.com accept: */* connection: keep-alive x-bce-request-id: 6bae5cb3-97d1-4b1a-b8b6-0ad577c1d481 content-type: application/json authorization: bce-auth-v1/46bd9968a6194b4bbdf0341f2286ccce/2015-03-24T13:08:44Z/1800/host;x-bce-date/7e21c9cf1e4e2cc6921a407a388fe98df122c53b9f509043d841be76eb09a1f9
响应（Reponse）
- 响应头域：无特殊Header参数
- 响应参数：与[创建缩略图任务/请求/请求参数]保持一致，增加以下字段
| 字段名称 | 字段类型 | 字段描述 |
|---|---|---|
| jobId | String | 缩略图的唯一标识 |
| jobStatus | String | 缩略图生成状态 |
| target | ||
| + keys | Array | 目标缩略图的BOS的Key的集合 |
| createTime | String | 任务开始时间 |
| endTime | String | 任务完成时间 |
-
响应示例：
HTTP/1.1 200 OK Transfer-Encoding: chunked x-bce-request-id: 6bae5cb3-97d1-4b1a-b8b6-0ad577c1d481 Cache-Control: no-cache Server: BWS Date: Tue, 24 Mar 2015 13:34:07 GMT Content-Type: application/json;charset=UTF-8 { "jobId": "job-lsdspxdastsmnbwx", "jobStatus": "success", "pipelineName": "high_priority_pipe", "source": { "key": "samplefolderpath/samplevideo.mp4" }, "target": { "keyPrefix": "sampleoutputfolderpath/samplethumbnail-", "keys": [ "sampleoutputfolderpath/samplethumbnail-00020000.jpg", "sampleoutputfolderpath/samplethumbnail-00030000.jpg", "sampleoutputfolderpath/samplethumbnail-00040000.jpg", "sampleoutputfolderpath/samplethumbnail-00050000.jpg" ], "format": "jpg", "sizingPolicy": "keep", "widthInPixel": "600", "heightInPixel": "450" }, "capture": { "mode": "manual", "startTimeInSecond": "20", "endTimeInSecond": "50", "intervalInSecond": "10" }, "delogoArea": { "x": 10, "y": 20, "width": 200, "height": 150 } }
查询指定队列的缩略图任务信息
请求（Request）
-
请求语法：
GET /v{version}/job/thumbnail?pipelineName={pipelineName}&jobStatus={jobStatus}&begin={begin}&end={end}}&marker={marker}&maxSize={maxSize} HTTP/1.1 accept-encoding: gzip, deflate x-bce-date: {utc-date-string} host: media.bj.baidubce.com accept: */* connection: keep-alive x-bce-request-id: {bce-request-id} content-type: application/json authorization: {bce-authorization-string} - 请求头域：无特殊Header参数
- 请求参数（均为query参数）：
| 字段名称 | 字段类型 | 必要性 | 字段描述 | 可选值 | 默认值 |
|---|---|---|---|---|---|
| pipelineName | String | 必选 | 任务所属的队列名 | - | - |
| jobStatus | String | 可选 | 所选任务的状态 | SUCCESS, FAILED, PENDING, RUNNING | - |
| begin | String | 可选 | 任务创建时间的上限。所选任务开始时间要大于等于begin | - | - |
| end | String | 可选 | 任务创建时间的下限，所选任务开始时间要小于等于end | - | - |
| marker | String | 可选 | 本次请求的marker，标记查询的起始位置，此处为jobId | - | - |
| maxSize | Number | 可选 | 本次请求返回的任务列表的最大元素个数 | 1 ~ 1000 | 1000 |
-
请求示例：
GET /v3/job/thumbnail?pipelineName=high_priority_pipe&jobStatus=SUCCESS&begin=2015-06-15T08%3A53%3A42Z&end=2015-06-19T08%3A53%3A42Z&marker=job-feumm9etdd5c9gqv HTTP/1.1 accept-encoding: gzip, deflate x-bce-date: 2015-03-24T13:08:44Z host: media.bj.baidubce.com accept: */* connection: keep-alive x-bce-request-id: d97c57d0-ca44-4d1c-bfeb-941a92440968 content-type: application/json authorization: bce-auth-v1/46bd9968a6194b4bbdf0341f2286ccce/2015-03-24T13:08:44Z/1800/host;x-bce-date/7e21c9cf1e4e2cc6921a407a388fe98df122c53b9f509043d841be76eb09a1f9
响应（Reponse）
- 响应头域：无特殊Header参数
- 响应参数：与[创建缩略图任务/请求/请求参数]保持一致，增加以下字段
| 字段名称 | 字段类型 | 字段描述 |
|---|---|---|
| jobId | String | 缩略图的唯一标识 |
| jobStatus | String | 缩略图生成状态 |
| target | ||
| + keys | Array | 目标缩略图的BOS的Key的集合 |
| createTime | String | 任务开始时间 |
| endTime | String | 任务完成时间 |
| marker | String | 本次请求的marker，标记查询的起始位置，此处为jobId |
| isTruncated | Bool | 指明返回数据是否被截断。true表示本页后面还有数据，即数据未全部返回；false表示已是最后一页，即数据已全部返回 |
| nextMarker | String | 获取下一页所需要传递的marker值（此处为jobId），仅当isTruncated为true时（数据未全部返回）出现 |
-
响应示例：
HTTP/1.1 200 OK Transfer-Encoding: chunked x-bce-request-id: d97c57d0-ca44-4d1c-bfeb-941a92440968 Cache-Control: no-cache Server: BWS Date: Tue, 24 Mar 2015 13:34:07 GMT Content-Type: application/json;charset=UTF-8 { "thumbnails": [ { "createTime" : "2015-05-19T11:15:58Z", "endTime" : "2015-05-19T11:16:04Z", "jobId": "job-fgcivp49gvnggqq8", "jobStatus": "success", "pipelineName": "high_priority_pipe", "source": { "key": "samplefolderpath/samplevideo.mp4" }, "target": { "keyPrefix": "sampleoutputfolderpath/samplethumbnail-", "keys": [ "sampleoutputfolderpath/samplethumbnail-00045000.jpg" ], "format": "jpg", "sizingPolicy": "keep", "widthInPixel": "600", "heightInPixel": "450" }, "capture": { "mode": "manual", "startTimeInSecond": "45", "endTimeInSecond": "50", "intervalInSecond": "10" } }, { "createTime" : "2015-05-19T109:15:58Z", "endTime" : "2015-05-19T09:35:04Z", "jobId": "job-lsdspxdastsmnbwx", "jobStatus": "success", "pipelineName": "high_priority_pipe", "source": { "key": "samplefolderpath/samplevideo.mp4" }, "target": { "keyPrefix": "sampleoutputfolderpath/samplethumbnail", "keys": [ "sampleoutputfolderpath/samplethumbnail.jpg" ], "format": "jpg", "sizingPolicy": "shrinkToFit", "widthInPixel": "800", "heightInPixel": "600" }, "capture": { "mode": "auto" } }, { "createTime" : "2015-05-19T109:14:58Z", "endTime" : "2015-05-19T09:35:04Z", "jobId": "job-lsdspxiwpxsmnber", "jobStatus": "running", "pipelineName": "high_priority_pipe", "source": { "key": "samplefolderpath/samplevideo.mp4" }, "target": { "keyPrefix": "samplefolderpath/samplevideo", "format": "jpg", "sizingPolicy": "keep", "widthInPixel": "1280", "heightInPixel": "450" }, "capture": { "mode": "auto" } }, { "createTime" : "2015-05-19T109:10:58Z", "endTime" : "2015-05-19T09:35:04Z", "jobId": "job-lsdspxiwpxsmnbeq", "jobStatus": "failed", "pipelineName": "high_priority_pipe", "source": { "key": "samplefolderpath/samplevideo.mp4" }, "target": { "keyPrefix": "samplefolderpath/samplethumbnail-", "format": "jpg", "sizingPolicy": "keep", "widthInPixel": "1280", "heightInPixel": "450" }, "capture": { "mode": "manual", "startTimeInSecond": "10" }, "error": { "code": "InvalidInputData", "message": "The input data is invalid, please ..." } } ], "marker": "job-fgcivp49gvnggqq8", "isTruncated": false }