缩略图任务接口Job-Thumbnail-API
所有文档

          音视频处理 MCP

          缩略图任务接口Job-Thumbnail-API

          缩略图任务接口(Job/Thumbnail API)

          创建缩略图任务

          接口描述

          用户通过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
              }
          上一篇
          媒体信息接口MediaInfo-API
          下一篇
          水印接口Watermark-API