音视频转码MCT

    视频转码任务接口Job-Transcoding-API

    创建视频转码任务

    接口描述

    用户通过该接口创建转码任务,支持多视频合并。

    请求(Request)

    • 请求语法:

      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}
    • 请求头域:无特殊Header参数
    • 请求参数:
    字段名称 字段类型 必要性 字段描述 可选值 默认值
    pipelineName String 必选 任务所属的pipelineName - -
    source Object 必选 输入的原始信息的集合 - -
    + sourceKey String 可选 原始文件的BOS Key,即是相对于输入Bucket的文件的相对路径 - -
    + clips Array 可选 待合并的原始视频信息,与上面的sourceKey不可同时指定,数组长度[1,200],用法及限制参考 合并多个视频 - -
    ++ bucket String 可选 原始文件的BOS Bucket(用户必须有该bucket的读权限),若未设置则默认为队列中指定的输入bucket - -
    ++ sourceKey String 必选 原始文件的BOS Key,相对于输入Bucket的文件的相对路径,支持输入为public bucket下的hls(即sourceKey为m3u8文件) - -
    ++ asMasterClip Bool 可选 是否指定该片段作为主分片,即转码分辨率参考该片段。当clips中存在 asMasterClip为true时,对应模板Preset的 video.sizingPolicy 必须为shrinkToFit,此时输出分辨率保持主分片视频宽高比,其他分片参考该分辨率加黑边对齐。 true, false false
    ++ enableLogo Bool 可选 是否允许在该片段添加水印。为空时,如有指定水印,默认该片段添加水印 true, false true
    ++ enableDelogo Bool 可选 是否允许在该片段进行去水印,去水印位置参数为job.target.delogo true, false true
    ++ enableCrop Bool 可选 是否允许在该片段添进行去黑边,去黑边位置参数为job.target.crop true, false true
    ++ startTimeInSecond Number 可选 视频片段的起始时间 大于等于0 NULL(从0s开始)
    ++ durationInSecond Number 可选 视频片段的持续时间 大于等于1 NULL (代表从指定开始时间点到视频结结尾的时长)
    ++ startTimeInMillisecond Number 可选 视频片段的起始时间,单位毫秒,与startTimeInSecond同时指定时优先生效 大于等于0 NULL(代表从0s开始)
    ++ durationInMillisecond Number 可选 视频片段的持续时间,单位毫秒,与durationInSecond同时指定时优先生效 大于等于1 NULL (代表从指定开始时间点到视频结结尾的时长)
    target Object 必选 输出信息的集合 - -
    + targetKey String 必选 目标文件的BOS key,即是相对于输出Bucket的文件的相对路径 - -
    + presetName String 必选 输出处理的模板的presetName - -
    + delogoArea Object 可选 去水印参数,描述水印位置区域。使用delogo去水印功能时,不能指定transmux模式的模板 - -
    ++ x Number 必选 水印区域相对左上角的x(横)坐标,左上角为0 大于等于0 -
    ++ y Number 必选 水印区域相对左上角的y(纵)坐标,左上角为0 大于等于0 -
    ++ width Number 必选 水印区域横向宽度 大于等于1 -
    ++ height Number 必选 水印区域纵向高度 大于等于1 -
    + autoCrop Bool 可选 开启自动剪裁黑边。和crop同时设置时,以crop为准 true、false false
    + crop Object 可选 黑边裁剪参数,描述除去黑边后的有效区域。使用crop去黑边功能时,不能指定transmux模式的模板 - -
    ++ x Number 必选 去黑边后的有效区域相对左上角的x(横)坐标,左上角为0 大于等于0 -
    ++ y Number 必选 去黑边后的有效区域相对左上角的y(纵)坐标,左上角为0 大于等于0 -
    ++ width Number 必选 去黑边后的有效区域横向宽度 大于等于1 -
    ++ height Number 必选 去黑边后的有效区域纵向高度 大于等于1 -
    + watermarkIds Array 可选 水印模版id集合,目前仅支持单个水印。当Job和Preset中同时指定watermarkId(s)时,优先使用Job中设置的watermarkId,以支持更灵活地设置水印 - -
    + inserts Array 选填 待插入(叠加)的内容,类型可以为图片、视频、音频、字幕、文本水印等。audio类型的inserts不能和其他类型inserts共存。不支持同时设置水印和inserts。多clips的任务不可设置inserts。数组最大长度为200 - -
    ++ bucket String 选填 BOS存储上insert文件Bucket,type 为 text 时不可设置,否则必须设置 - -
    ++ key String 选填 BOS存储上insert文件Key,type 为 text 时不可设置,否则必须设置 - -
    ++ type String 必选 insert类型,可选值 video, image, audio, subtitle, text,分别表示视频、图片、音频、字幕、文本水印。其中,video类型支持输入key为MOV等格式,image类型支持输入key为JPG、PNG、APNG等格式,audio类型支持输入key为MP3、AAC等格式,subtitle类型支持输入key为srt等格式 video, image, audio, subtitle, text -
    ++ text String 可选 文本水印内容(当且仅当 type 为 text 时设置) - -
    ++ font Object 可选 字体效果(当且仅当 type 为 subtitle、 text 时设置) - -
    +++ family String 可选 字体系列 STXihei STXihei
    +++ sizeInPoint Number 可选 字体大小 0 ~ 72 0 使用默认大小,即16
    ++ layout Object 可选 显示位置(type为audio时不可设置layout) - -
    +++ verticalAlignment String 可选 垂直对齐方式 top, center, bottom top
    +++ horizontalAlignment String 可选 水平对齐方式 left, center, right left
    +++ verticalOffsetInPixel Number 可选 垂直偏移,该参数仅在verticalAlignment设置为top或bottom时有效,单位:像素 0~3072 0
    +++ horizontalOffsetInPixel Number 可选 水平偏移,该参数仅在horizontalAlignment设置为left或right时有效,单位:像素 0~4096 0
    ++ timeline Object 可选 有效显示起止时间 - -
    +++ startTimeInMillisecond Number 可选 水印、图片、文本水印等的显示起始时间,单位:豪秒 大于等于0 -
    +++ durationInMillisecond Number 可选 水印、图片、文本水印等的显示持续时间,单位:豪秒 大于等于0 -
    • 请求示例:

      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)

    • 响应头域:无特殊Header参数
    • 响应参数:
    字段名称 字段类型 字段描述
    jobId String 系统生成的Job的唯一标示jobId
    • 响应示例:

      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"
      }

    查询指定队列的视频转码任务信息

    接口描述

    查询指定队列下满足一定条件的所有转码任务。

    请求(Request)

    • 请求语法:

      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}
    • 请求头域:无特殊Header参数
    • 请求参数:
    字段名称 字段类型 必要性 字段描述 可选值 默认值
    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/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)

    • 响应头域:无特殊Header参数
    • 响应参数:与[创建视频转码任务/请求/请求参数]保持一致,不返回inserts、crop信息,增加以下字段
    字段名称 字段类型 字段描述
    jobId String 任务的唯一标示
    jobStatus String 任务状态
    error Object job失败时的错误信息,jobStatus == Failed时存在
    + code String 错误码
    + message String 错误原因
    createTime String 任务创建的时间
    startTime 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: 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"
        }

    查询指定视频转码任务

    接口描述

    通过指定jobId查询该任务的信息。

    请求(Request)

    • 请求语法:

      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}
    • 请求头域:无特殊Header参数
    • 请求参数:无
    • 请求示例:

      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)

    • 响应头域:无特殊Header参数
    • 响应参数:与[创建视频转码任务/请求/请求参数]保持一致,不返回inserts、crop信息,增加以下字段
    字段名称 字段类型 字段描述
    jobId String 任务的唯一标示
    jobStatus String 任务状态
    error Object job失败时的错误信息,jobStatus == Failed时存在
    + code String 错误码
    + message String 错误原因
    createTime String 任务创建的时间
    startTime 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-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"
          }
      }

    合并多个视频

    创建转码任务 API 中增加 clips 数组用于支持视频合并,该功能按照 clips 中的先后顺序合并成一个完整视频。

    注意:

    • clips和sourceKey不可共存,通过clips可指定1到200个输入片段。
    • 对模板中三种不同尺寸伸缩策略(Keep,ShrinkToFit / ShrinkToFitBlur,Stretch)的处理和限制: 1. 如果Keep模式,即保持原始的宽高比例

      • 输入:此时合并的多个视频必须具有同样的宽高比例,否则报错。
      • 输出:比较所有输入源视频和模板的宽高,从中选择最小的一组宽高作为输出的宽高。 2. 如果是 ShrinkToFit / ShrinkToFitBlur 模式
      • 输入:无限制
      • 输出:Preset指定的宽高,并保持视频源的宽高比,填充黑边。当指定分片asMasterClip参数(该分片为主分片)时,输出分辨率保持主分片宽高比,其他分片参考输出分辨率填充黑边进行对齐。 3. 如果是Stretch模式
      • 输入:无限制
      • 输出:Preset指定的宽和高,视频拉伸或者收缩。

    keep伸缩模式时的处理策略

    当选择keep伸缩模式时,视频的宽高比保持不变,对视频进行相应的缩放。缩放分以下两种情况:

    1. 输入视频宽高分别小于模板Preset设置的宽高。

      • 处理方式:目标视频保持原始宽高,不进行缩放。
    2. 输入视频宽大于模板的宽或输入视频的高大于模板高。

      • 处理方式:选择缩放比例较小的边进行缩放,使得视频的宽或高等于模板的宽或高。

    常见错误码和错误信息

    转码任务常见的错误码及错误信息如下表所示:

    错误码 错误信息 错误信息(控制台显示)
    PartialOK Partially succeeded. 部分成功
    ParameterError The input parameter is invalid. Please check it. 输入参数错误,请检查输入参数
    InternalError Internal error happened. Please retry or raise one ticket on http://ticket.bce.baidu.com/ if it fails again. 内部错误,请重试;若重试失败,请至"http://ticket.bce.baidu.com/" 提交工单
    SystemCancel System cancelled. Please retry. 系统撤销,请重试
    InputNotSupported The input format is not supported. 输入的数据格式不支持
    OutputNotSupported The output format is not supported. 输出的数据格式不支持
    InvalidInputData The input data is invalid. Please check your input data. 无效的输入数据,请检查您的输入视频是否是有效
    IncompatibleInputData Error when handling the media data. 暂不支持的输入数据,请检查您的输入视频是否是有效
    VideoEncryptError Cannot encrypt video. 视频加密失败
    WatermarkSettingError Watermark extend beyond video border. 水印设置错误,水印图片过大或者位置越界
    IllegalWatermarkUsage Cannot overlay watermark into audio only file. 视频无图像,不允许添加水印
    InvalidWatermark Invlid watermark picture. 水印错误,水印图片格式不正确;若仍失败,请至提交工单
    NotImplemented This feature is not implemented yet. You can raise your requirement on http://ticket.bce.baidu.com/ 尚未实现,您可以提交工单
    TimeOut Task time out. Please retry or raise one ticket on http://ticket.bce.baidu.com/ if it fails again. 任务超时,请重试;若重试失败,请提交工单
    Unknown Unknown error. Please retry or raise one ticket on http://ticket.bce.baidu.com/ if it fails again. 未知错误,请重试;若重试失败,请提交工单
    上一篇
    队列接口Pipeline-API
    下一篇
    模板接口Preset-API