Job-Thumbnail-API Interface
Last Updated：2020-09-21
Thumbnail Job Interface（Job/Thumbnail API）
Create Thumbnail Mission
Interface description
The user generates thumbnails for the assigned media through Bucket, BOS Key and other configuration information.
Request
-
Request syntax:
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} - Request header: No special Header parameter
- Request parameter(All are requestbody parameters)：
| Field name | Field type | Necessity | Field description | Optional value | Default value |
|---|---|---|---|---|---|
| pipelineName | String | Required | pipelineName of the Job | - | - |
| presetName | String | Optional | Template name of the Job(The duplicate content in template and job is subject to Job) | - | - |
| source | Object | Required | Collection of the input video information | - | - |
| + key | String | Required | The key of BOS of the input video file supports hls under public bucket (that is, key is he m3u8 file) | - | - |
| target | Object | Optional | Collection of the target thumbnail information | - | - |
| + keyPrefix | String | Optional | For the prefix of the key for the BOS of the target thumbnail, when mode=auto/idl/highlight, the target file name is {keyPrefix}; when mode=manual/split/shot, the target file name is {keyPrefix} to load the photo timing | - | {sourceKey} |
| + format | String | Optional | Format of the target thumbnail | jpg、png、mp4、gif、webp | jpg |
| + sizingPolicy | String | Optional | Size scaling policy of target thumbnail Of keep, shrinkToFit and stretch, keep indicates to maintain the width-height ratio of the original video; shrinkToFit indicates to maintain the width-height ratio of the original video and add black edges; stretch indicates to stretch the original video | keep | |
| + widthInPixel | Number | Optional | For the width of the target thumbnail, if the actual resolution of the video is lower than the target one, the actual resolution shall prevail for output | 10 ~ 2000 | 600 |
| + heightInPixel | Number | Optional | For the height of the target thumbnail, if the actual resolution of the video is lower than the target one, the actual resolution shall prevail for output | 10 ~ 2000 | 450 |
| + frameRate | Number | Optional | The frame rate of motion graph is optional only when the format is mp4, gif and webp, and the mode is manual and split | 0.01 ~ 30.0 | 3.0 |
| + gifQuality | String | Optional | The quality of gif is optional only when the format is gif, and the mode is manual and split | high, medium | medium |
| + spriteOutputCfg | Object | Optional | The settings of output parameter of Sprite image are optional only when multiple images are extracted (that is, mode=manual/split), and the output is not a motion graph (https://bce.bdstatic.com/p3m/I18N/images/MCT/API Reference/that is, format=jpg/png-1600671218457.) | - | - |
| ++ rows | Number | Optional | CSS sprites splicing line number | 1 ~ 100 | 10 |
| ++ columns | Number | Optional | Number of spliced lines in Sprite image | 1 ~ 100 | 10 |
| ++ margin | Number | Optional | Width of the outline border, with the unit: px | 1 ~ 1000 | 0 |
| ++ padding | Number | Optional | Width of the outline border, with the unit: px | 1 ~ 1000 | 0 |
| ++ keepCellPic | Bool | Optional | Whether to retain the original drawing of the subgraph | true, false | true |
| ++ spriteKeyTag | String | Optional | The final file name of the tag in the key of the Sprite uploaded to BOS which is used to mark it as a Sprite is {keyPrefix}+{spriteKeyTag}+{Sprite serial number %05d}, and sub-pictures in the Sprite are arranged in the order in the original video. | The length of string ranges from 1 to 100 | "-SPRITE-" |
| capture | Object | Optional | Rules to generate thumbnail | - | - |
| + mode | String | Optional | Mode to generate thumbnail | Of auto, manual, split, shot, idl and highlight mode, the auto mode is to intercept a frame with a high entropy value as a thumbnail by the system automatically; the manual mode is to intercept a thumbnail according to the assigned start and end time as well as interval; the split mode is to intercept a thumbnail according to the assigned start and end time as well as numbers; the shot mode is to intercept frame (it does not support to output video format) automatically according to the scenario switch; the idl mode is to intercept a thumbnail by using Baidu IDL (Institute of Deep Learning) intelligent thumbnail algorithm (it only supports to output jpg, png format); the highlight mode is to generate a 0.5s highlight automatically (currently, it is applicable to short videos with portrait screens, and only outputs video format; it defaults to combined effect of forward and reverse playback) | auto |
| + skipBlackFrame | Boolean | Optional | Whether to skip black frames, only selectable when mode=manual or split | true/false | false |
| + frameNumber | Number | Optional | The number of thumbnail generated is optional only when mode=split | Greater than or equal to 1 | 1 |
| + startTimeInSecond | Number | Optional | The start time to generate thumbnail is optional only when mode=manual or mode=split | Greater than or equal to 0 | 0.0 |
| + endTimeInSecond | Number | Optional | The end time to generate thumbnail is optional only when mode=manual or mode=split, and it shall not be less than the start time | Greater than or equal to 0 | Video duration |
| + intervalInSecond | Number | Optional | The interval to generate thumbnail is optional only when mode=manual | Greater than 0 | 1.0 |
| + minIntervalInSecond | Number | Optional | The minimum interval to generate thumbnail is optional only when mode=split | Greater than 0 | 1.0 |
| + highlightOutputCfg | Object | Optional | The output control parameter under highlight mode is optional only when mode=highlight | - | - |
| ++ durationInSecond | Number | Optional | Intercepted clip duration, unit: Second | 0.1 ~ 7200.0 | 0.25 |
| ++ playbackSpeed | Number | Optional | Playback speed; when the value is less than 1.0, it is decelerated video; when the value is higher than 1.0, it is accelerated video | 0.05 ~ 20.0 | 1.0 |
| ++ frameRate | Number | Optional | Output video frame rate, with the unit of: fps | 0.1 ~ 60.0 | 11.0 |
| ++ reverseConcat | Bool | Optional | Effect of combining forward and reverse broadcast | true, false | true |
| delogoArea | Object | Optional | The watermark removal parameters, describe the watermark position. | - | - |
| + x | Number | Required | The watermark area is opposite to x (horizontal) coordinate of the upper left corner, which is 0 | Greater than or equal to 0 | - |
| + y | Number | Required | The watermark area is opposite to y (vertical) coordinate of the upper left corner, which is 0 | Greater than or equal to 0 | - |
| + width | Number | Required | The horizontal width of the watermark region | Greater than or equal to 1 | - |
| + height | Number | Required | Vertical height of watermark area | Greater than or equal to 1 | - |
| crop | Object | Optional | The black-edge clipping parameters describe the effective area after the black edge is removed (it is not allowed to set crop and shrinkToFit at the same time) | - | - |
| + x | Number | Required | The effective area after the black edge is removed is opposite to x (horizontal) coordinate of the upper left corner, which is 0 | greater than or equal to 0 | - |
| + y | Number | Required | The effective area after the black edge is removed is opposite to y (vertical) coordinate of the upper left corner, which is 0 | greater than or equal to 0 | - |
| + width | Number | Required | Horizontal width of the effective area after the black edge is removed | Greater than or equal to 1 | - |
| + height | Number | Required | Vertical height of the effective area with the black edge removed | Greater than or equal to 1 | - |
-
Request example:
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 } }
Response
- Response header: No special Header parameter
- Response parameter:
| Field name | Field type | Field description |
|---|---|---|
| jobId | String | The unique identification thumbnail for Thumbnail generated by the system |
-
Response example:
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" }
Query the Assigned Thumbnail Jobs
Request
-
Request syntax:
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} - Request header: No special Header parameter
- Request parameter: None
-
Request example:
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
Response
- Response header: No special Header parameter
- Response parameter: Please remain consistent with [Create Thumbnail Templates/Request/Request Parameters], and add the following fields
| Field name | Field type | Field description |
|---|---|---|
| jobId | String | Unique identification of the thumbnail |
| jobStatus | String | Thumbnail generation status |
| target | ||
| + keys | Array | Key set of BOS of target thumbnail |
| createTime | String | Start time of Job |
| endTime | String | End time of Job |
-
Response example:
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 } }
Query the Thumbnail Job Information of the Assigned Pipeline
Request
-
Request syntax:
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} - Request header: No special Header parameter
- Request parameters (all are query parameters):
| Field name | Field type | Necessity | Field description | Optional value | Default value |
|---|---|---|---|---|---|
| pipelineName | String | Required | Name of the queue to which the Job belongs | - | - |
| jobStatus | String | Optional | The status of the selected Jobs | SUCCESS, FAILED, PENDING, RUNNING | - |
| begin | String | Optional | Upper limit for the creation time of Job The start time of Job selected shall be greater than or equal to begin | - | - |
| end | String | Optional | In terms of the lower limit for the creation time of Job, the start time of the Job selected shall be smaller than or equal to end | - | - |
| marker | String | Optional | The requested marker, mark the initial position of the query, and it is jobId here | - | - |
| maxSize | Number | Optional | The maximum number of elements in the Job list returned by this request | 1 ~ 1000 | 1000 |
-
Request example:
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
Response
- Response header: No special Header parameter
- Response parameter: Please remain consistent with [Create Thumbnail Templates/Request/Request Parameters], and add the following fields
| Field name | Field type | Field description |
|---|---|---|
| jobId | String | Unique identification of the thumbnail |
| jobStatus | String | Thumbnail generation status |
| target | ||
| + keys | Array | Key set of BOS of target thumbnail |
| createTime | String | Start time of Job |
| endTime | String | End time of Job |
| marker | String | The requested marker, mark the initial position of the query, and it is jobId here |
| isTruncated | Bool | Indicate whether the returned data are truncated. True indicates that there are data at the end of this page, that is, the data are not returned completely; false represents that this is the last page, that is, all data are returned |
| nextMarker | String | Get the marker value to deliver in the next page (jobId here), which appears only when isTruncated is true (not all the data returns) |
-
Response example:
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 }