百度智能云
All Product Document

          Multimedia Cloud Processing

          • Multimedia Cloud Processing
          • >
          • API Reference
          • >
          • Job-Transcoding-API Interface

          Job-Transcoding-API Interface

          Last Updated：2020-09-21

          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:

          1. 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.

          2. 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
          Previous
          Interface Specification
          Next
          Pipeline Interface