Job-Transcoding-API Interface
Create Video Transcoding Mission
Interface description
The user creates the transcoding job through the interface, which supports multi-video combination.
Request
-
Request syntax:
POST /v{version}/job/transcoding 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:
Field name | Field type | Necessity | Field description | Optional value | Default value |
---|---|---|---|---|---|
pipelineName | String | Required | pipelineName of the job | - | - |
source | Object | Required | Collection of the input original information | - | - |
+ sourceKey | String | Optional | BOS Key of the original file is the relative path to the file that is input into the Bucket | - | - |
+ clips | Array | Optional | The original video information to be combined cannot be assigned together with the above-mentioned sourceKey at the same time, the array length ranges [1,200], and please refer to [Combine Multiple Videos](#Combine Multiple Videos) | - | - |
++ bucket | String | Optional | The BOS Bucket of the original file (the user must have the read privileges for that Bucket) defaults to input bucket in assigned in the queue if it is not set. | - | - |
++ sourceKey | String | Required | With respect to the relative path of input Bucket file, the BOS Key of the original file supports to input the hls that is a public bucket (that is, the sourceKey is m3u8 file) | - | - |
++ asMasterClip | Bool | Optional | Whether to assign the fragment as the main clip, meaning the transcoding resolution ratio refers to the clip. When asMasterClip in Clips is true, the video.sizingPolicy of corresponding template Preset must be shrinkToFit; at this point, the output resolution should maintain the main width-height ratio of the main multipart video, with other multipart with reference to the resolution plus black edge alignment. | true, false | false |
++ enableLogo | Bool | Optional | Whether it is allowed to add watermark into the video clip. When it is null, if a watermark is assigned, the watermark is added to the segment by default | true, false | true |
++ enableDelogo | Bool | Optional | Removal of watermark is allowed or not in this segment, and the removal of watermark position parameter is job.target.delogo. | true, false | true |
++ enableCrop | Bool | Optional | Whether it is allowed to remove the black edge for this clip, the parameter for the position of the black edge removal is job.target.crop | true, false | true |
++ startTimeInSecond | Number | Optional | Start time of video clip | Greater than or equal to 0 | NULL (start from 0s) |
++ durationInSecond | Number | Optional | Duration of video clip | Greater than or equal to 1 | NULL(represents the length of time from the assigned start time to the end of the video) |
++ startTimeInMillisecond | Number | Optional | The start time of video clip, in millisecond, shall take effect preferentially when it is assigned in conjunction with startTimeInSecond | Greater than or equal to 0 | NULL (represents to start from 0s) |
++ durationInMillisecond | Number | Optional | Duration of video clip, in millisecond, shall take effect preferentially when it is assigned in conjunction with durationInSecond | Greater than or equal to 1 | NULL(represents the length of time from the assigned start time to the end of the video) |
target | Object | Required | Collection of output information | - | - |
+ targetKey | String | Required | BOS key of target file is the relative path to the file that outputs the Bucket | - | - |
+ presetName | String | Required | PresetName of the template processed by output | - | - |
+ autoDelogo | Boolean | Optional | Automatic watermark removing. | ||
+ delogoMode | String | Optional | Automatic watermark removing mode | Normal, Inpainting | Normal |
+ delogoAreas | Array | Optional | Watermark removed parameters, describe the watermark position, a maximum of 5 can be assigned. When delogo (watermark removal feature) is used, the template of transmux mode cannot be assigned | - | - |
++ 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 | - |
+ autoCrop | Bool | Optional | Enable automatic crop black edging. When it is set with crop at the same time, crop shall prevail | true, false | false. |
+ crop | Object | Optional | The black-edge clipping parameters describe the effective area after the black edge is removed. When using the feature of crop black border removing, transmux mode template cannot be assigned | - | - |
++ 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 | - |
+ watermarkIds | Array | Optional | Watermark template id collection, and the maximum size is 5. When Job and Preset specifies watermarkId(s) at the same time, the watermarkId set in Job is used first to support more flexible watermark settings. | - | - |
+ inserts | Array | Optional | Content to be inserted (overlaid), the type can be picture, video, audio, subtitle and text watermark. The inserts of audio type cannot co-exist with those of other type. It does not support setting watermark and inserts at the same time. You cannot set inserts for jobs with multiple clips. The maximum length of array is 200 | - | - |
++ bucket | String | Optional | Bucket file is inserted to BOS, which cannot be set when the type is text; otherwise, it must be set | - | - |
++ key | String | Optional | The Key file is inserted to BOS, which cannot be set when the type is text; otherwise, it must be set | - | - |
++ type | String | Required | Insert type, optional, and the video, image, audio, subtitle and text represent video, photo, video, subtitle and text watermark respectively. The input key of video type supports MOV format, the input key of image type supports JPG, PNG and APNG formats, the input key of audio type supports MP3 and AAC formats, and the input key of subtitle type supports srt format | video, image, audio, subtitle, text | - |
++ text | String | Optional | Text watermark content (set when and only when the type is text) | - | - |
++ font | Object | Optional | Font effect (set when and only when the type is subtitle or text) | - | - |
+++ family | String | Optional | Font family | STXihei | STXihei |
+++ sizeInPoint | Number | Optional | Font size | 0 ~ 72 | Zero (0) uses the default size, which is 16 |
++ layout | Object | Optional | Display position(Layout cannot be set when the type is audio) | - | - |
+++ verticalAlignment | String | Optional | Vertical alignment method | top, center, bottom | top |
+++ horizontalAlignment | String | Optional | Horizontal alignment | left, center, right | left |
+++ verticalOffsetInPixel | Number | Optional | Vertical offset, the parameter is valid only when verticalAlignment is set to top or bottom, with the unit of: Pixel | 0~3072 | 0 |
+++ horizontalOffsetInPixel | Number | Optional | Horizontal offset, the parameter is valid only when horizontalAlignment is set to left or right, with the unit of Pixel | 0~4096 | 0 |
++ timeline | Object | Optional | Effective display of start and end time | - | - |
+++ startTimeInMillisecond | Number | Optional | Display the start time for watermark, photo, text watermark and others, with the unit of: Millisecond | Greater than or equal to 0 | - |
+++ durationInMillisecond | Number | Optional | The time of duration of the watermarks, images and text watermarks is displayed, with the unit of: Millisecond | Greater than or equal to 0 | - |
-
Request example:
POST /v3/job/transcoding HTTP/1.1 accept-encoding: gzip, deflate x-bce-date: 2015-03-24T13:06:02Z connection: keep-alive accept: */* host: media.bj.baidubce.com x-bce-request-id: 6d0b0a36-2ffe-49d4-9d81-333a9ab9417e content-type: application/json authorization: bce-auth-v1/46bd9968a6194b4bbdf0341f2286ccce/2015-03-24T13:06:02Z/1800/host;x-bce-date/02f64774999996903cffa5ae4d6eef436127a96f581a4e8467497e239d824be8 { "pipelineName": "high_priority_pipe", "source": { "clips": [ { "sourceKey": "input_media1.mp4", "startTimeInSecond": 0, "durationInSecond": 300 }, { "sourceKey": "input_media2.mp4" }, { "sourceKey": "input_media3.mp4" } ] }, "target": { "targetKey": "SampleOutput.mp4", "presetName": "bce.video_mp4_1280x720_1728kbps", "delogoArea": { "x": 10, "y": 20, "width": 200, "height": 150 }, "inserts": [ { "bucket" : "samplebucket", "key" : "samplefolderpath/samplepicture.png", "type": "image", "layout": { "verticalAlignment" : "bottom", "horizontalAlignment" : "left", "verticalOffsetInPixel" : 0, "horizontalOffsetInPixel" : 0, }, "timeline" : { "startTimeInMillisecond" : 5000, "durationInMillisecond" : 65500 } } ] } }
Response
- Response header: No special Header parameter
- Response parameter:
Field name | Field type | Field description |
---|---|---|
jobId | String | The unique mark jobId of the Job generated by the system |
-
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-fczspxdutvmnbamq" }
Query the Video Transcoding job Information of the Assigned Pipeline
Interface description
Query all transcoding jobs that meet certain conditions under the assigned queue.
Request
-
Request syntax:
GET /v{version}/job/transcoding?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 parameter:
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/transcoding?pipelineName=high_priority_pipe&jobStatus=SUCCESS&begin=2015-06-15T08%3A53%3A42Z&end=2015-06-18T08%3A53%3A42Z&marker=job-feumm9etdd5c9gqv&maxSize=2 HTTP/1.1 accept-encoding: gzip, deflate x-bce-date: 2015-03-24T13:37:10Z host: media.bj.baidubce.com accept: */* connection: keep-alive x-bce-request-id: 3807ce30-5264-45f2-9b52-26b78e24a750 content-type: application/json authorization: bce-auth-v1/46bd9968a6194b4bbdf0341f2286ccce/2015-03-24T13:37:10Z/1800/host;x-bce-date/3e1bf9f50ae1fca2d704d61567810dde946fff3ca2e455676455a6f5c8cce596
Response
- Response header: No special Header parameter
- Response parameter: Keep consistent with [Create Video Transcoding jobs/Request/Request Parameters], if inserts and crop information is not returned, the following fields shall be added
Field name | Field type | Field description |
---|---|---|
jobId | String | Unique identification of the request |
jobStatus | String | job status |
error | Object | Error information when job fails, exist when jobStatus==Failed |
+ code | String | Error code |
+ message | String | Cause of error |
createTime | String | job creation time |
startTime | String | Time of the job to process |
endTime | String | The processing time of finishing a 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: 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 { "jobs" : [ { "jobId" : "job-feumm9etdd5c9gqv", "pipelineName" : "createjob_20383", "source" : { "sourceKey" : "jobtest.mp3" }, "target" : { "targetKey" : "jobtest_result.mp3", "presetName" : "bce.audio_mp3_320kbps" }, "jobStatus" : "SUCCESS", "createTime" : "2015-05-19T11:15:58Z", "startTime" : "2015-05-19T11:16:02Z", "endTime" : "2015-05-19T11:16:04Z" }, { "jobId" : "job-feumnkz275ve7eqn", "pipelineName" : "createjob_319293", "source" : { "clips": [ { "sourceKey": "input_media1.mp4", "startTimeInSecond": 0, "durationInSecond": 300 }, { "sourceKey": "input_media2.mp4" }, { "sourceKey": "input_media3.mp4" } ] }, "target" : { "targetKey" : "jobtest_result.mp4", "presetName" : "bce.video_mp4_1280x720_1728kbps", "delogoArea": { "x": 10, "y": 20, "width": 200, "height": 150 }, "watermarkIds":["wmk-hkit7ufxyx733ctw"] }, "jobStatus" : "FAILED", "createTime" : "2015-05-19T11:40:39Z", "startTime" : "2015-05-19T11:40:43Z", "endTime" : "2015-05-19T11:40:45Z", "error" : { "code" : "ParameterError", "message" : "Parameter error" } } ], "marker": "job-feumm9etdd5c9gqv", "isTruncated": true, "nextMarker": "job-gfpj59idrpygsjtw" }
Query the assigned Video Transcoding job
Interface description
Query the information of this job using designated jobld.
Request
-
Request syntax:
GET /v{version}/job/transcoding/{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/transcoding/job-fczspxdutvmnbamq HTTP/1.1 accept-encoding: gzip, deflate x-bce-date: 2015-03-24T13:06:02Z host: media.bj.baidubce.com accept: */* connection: keep-alive x-bce-request-id: 3807ce30-5264-45f2-9b52-26b78e24a750 content-type: application/json authorization: bce-auth-v1/46bd9968a6194b4bbdf0341f2286ccce/2015-03-24T13:06:02Z/1800/host;x-bce-date/02f64774999996903cffa5ae4d6eef436127a96f581a4e8467497e239d824be8
Response
- Response header: No special Header parameter
- Response parameter: Keep consistent with [Create Video Transcoding jobs/Request/Request Parameters], if inserts and crop information is not returned, the following fields shall be added
Field name | Field type | Field description |
---|---|---|
jobId | String | Unique identification of the request |
jobStatus | String | job status |
error | Object | Error information when job fails, exist when jobStatus==Failed |
+ code | String | Error code |
+ message | String | Cause of error |
createTime | String | job creation time |
startTime | String | Time of the job to process |
endTime | String | The processing time of finishing a 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-feuncr26j02713wc", "pipelineName" : "createjob_388070", "source" : { "sourceKey" : "media/info/jobtest.mp3" }, "target" : { "targetKey" : "jobtest_result.mp3", "presetName" : "createjob_388070", "delogoArea": { "x": 10, "y": 20, "width": 200, "height": 150 }, "watermarkIds":["wmk-hkit7ufxyx733ctw"] }, "jobStatus" : "FAILED", "createTime" : "2015-05-19T12:28:39Z", "startTime" : "2015-05-19T12:28:41Z", "endTime" : "2015-05-19T12:28:44Z", "error" : { "code" : "ParameterError", "message" : "Parameter error" } }
Combine Multiple Videos
Add clips array in the API creating transcoding jobs to support the combination of videos, by which a complete video can be combined according to the sequence in Clips.
Note
- The clips and sourceKey cannot co-exist, and you can specify 1 to 200 input clips through clips.
Processing and limitation for the scaling policy of three different scale in the template (Keep, ShinkToFit/ShrinkToBlur, Stretch): 1.If it is Keep mode, it means to keep the original width-height proportion
- Input: Now the multiple videos to be combined should share the same width and height proportion, or an error is reported.
- Output: Compare the width and height of all the input sources and templates, and select the minimum set as the output width and height. 2.If it is ShrinkToFit / ShrinkToFitBlur mode,
- Input: No limitation
- Output: Preset specifies the width and height, and maintain the width-height ratio and fill the black edge. When the parameters of multipart asMasterClip (the multipart is the main multipart), the output resolution maintains the width-to-height ratio of the main multipart, and other multipart shall refer to the output resolution to fill the black edge for alignment. 3.In case of Stretch mode
- Input: No limitation
- Output: Width and height assigned by Present, video stretch or scaling.
Processing Policy at Keep Stretch Mode
When you select keep stretching mode, the width-height ratio of the video remains unchanged to zoom the video correspondingly. Zoom can be divided into the following two cases:
-
The width and height of the input video are smaller than those preset by the template.
- Processing mode: The target video retains its original width and height, without scaling.
-
The input video width is greater than the template width or the input video height is greater than the template height.
- Processing mode: Select the edge with relatively smaller zoom proportion to zoom, so the video width or height equal to the width or height of the template.
Common Error Code and Error Information
Frequent error codes and error information of the transcoding job are showed as follows:
Error code | Error message | Error information (console display) |
---|---|---|
PartialOK | Partially succeeded. | Partly succeed |
ParameterError | The input parameter is invalid. Please check it. | Input parameter error, please inspect the input parameter |
InternalError | Internal error happened. Please retry or raise one ticket on http://ticket.bce.baidu.com/ if it fails again. | Internal error, please try again; if failed, please go to "http://ticket.bce.baidu.com/" to submit a ticket |
SystemCancel | System cancelled. Please retry. | System canceled, please try again. |
InputNotSupported | The input format is not supported. | The input data format is not supported |
OutputNotSupported | The output format is not supported. | The output data format is not supported |
InvalidInputData | The input data is invalid. Please check your input data. | Invalid input data, please check if your input video is valid |
IncompatibleInputData | Error when handling the media data. | Temporarily, the input data are not supported, please check whether your input video is valid |
VideoEncryptError | Cannot encrypt video. | Fail to encrypt the video |
WatermarkSettingError | Watermark extend beyond video border. | Watermark setting error, the watermark photo is too large or its location crosses border |
IllegalWatermarkUsage | Cannot overlay watermark into audio only file. | The video without images is not allowed to add watermarks |
InvalidWatermark | Invlid watermark picture. | Watermark error, the format of the watermark photo is not correct; if failed again, please submit a ticket |
NotImplemented | This feature is not implemented yet. You can raise your requirement on http://ticket.bce.baidu.com/ | It has not been realized yet, you can submit a ticket |
TimeOut | job time out. Please retry or raise one ticket on http://ticket.bce.baidu.com/ if it fails again. | job timeout, please retry; if failed again, please submit a ticket |
Unknown | Unknown error. Please retry or raise one ticket on http://ticket.bce.baidu.com/ if it fails again. | Unknown error, please try again; if you fail again, please submit the ticket |