视频转码任务接口
更新时间：2024-08-12
创建视频转码任务
接口描述
用户通过该接口创建转码任务，支持多视频合并。
请求（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 | 必选 | 输出信息的集合 | - | - |
| + targetBucket | String | 可选 | 目标文件的输出BOS bucket | - | 队列中指定的输出bucket |
| + targetKey | String | 必选 | 目标文件的BOS key，即是相对于输出Bucket的文件的相对路径 | - | - |
| + presetName | String | 必选 | 输出处理的模板的presetName | - | - |
| + jobCfg | Object | 选填 | 转码任务配置。 | ||
| ++ notification | String | 选填 | 通知地址，http地址，且不可为localhost。 | ||
| + autoDelogo | Boolean | 选填 | 自动去水印。 | ||
| + delogoMode | String | 选填 | 自动去水印模式 | Normal, Inpainting | Normal |
| + delogoArea | Object | 可选 | 手动去水印位置设置参数，描述水印位置区域。注：使用delogo去水印功能时，不能指定transmux模式的模板；同时设置autoDelogo时，默认优先自动去水印模式。 | - | - |
| ++ x | Number | 必选 | 水印区域相对左上角的x（横）坐标，左上角为0 | 大于等于0 | - |
| ++ y | Number | 必选 | 水印区域相对左上角的y（纵）坐标，左上角为0 | 大于等于0 | - |
| ++ width | Number | 必选 | 水印区域横向宽度 | 大于等于1 | - |
| ++ height | Number | 必选 | 水印区域纵向高度 | 大于等于1 | - |
| + delogoAreas | Array | 可选 | 手动去水印多个水印位置区域设置参数，至多指定5个。使用delogo去水印功能时，不能指定transmux模式的模板，不可与delogoArea同时指定 | - | - |
| ++ 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集合，最大size 5。当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 | - |
| +digitalWmTextContent | String | 可选 | 需嵌入的数字水印文字内容 | 字符数<=100, 支持中英文及标点符号(如需嵌入中文请选择v1及以上版本算法) | - |
| +digitalWmImageBucket | String | 可选 | (仅算法0支持图片)需嵌入的数字水印图片的Bos Bucket | - | - |
| +digitalWmImageKey | String | 可选 | (仅算法0支持图片)需嵌入的数字水印图片的Bos Key | - | - |
| +digitalWmSecretKeyId | String | 可选 | 数字水印密钥模板ID，密钥用于对水印加密嵌入，提取水印需提供正确密钥 | 需从用户已创建的数字水印密钥模板选择，生效优先级高于转码模板中的密钥 | - |
| +digitalWmAlgVersion | Number | 可选 | 算法版本号 | 0 ~ 2 | 0 |
| +digitalWmStrength | Number | 可选 | (算法1、2有效)数字水印嵌入强度，对同一算法，强度越高则抗攻击能力越强，隐蔽性越差 | 0 ~ 1 | 0.5 |
-
请求示例：
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伸缩模式时，视频的宽高比保持不变，对视频进行相应的缩放。缩放分以下两种情况：
-
输入视频宽高分别小于模板Preset设置的宽高。
- 处理方式：目标视频保持原始宽高，不进行缩放。
-
输入视频宽大于模板的宽或输入视频的高大于模板高。
- 处理方式：选择缩放比例较小的边进行缩放，使得视频的宽或高等于模板的宽或高。
常见错误码和错误信息
转码任务常见的错误码及错误信息如下表所示：
| 错误码 | 错误信息 | 错误信息(控制台显示) |
|---|---|---|
| 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. | 未知错误，请重试；若重试失败，请提交工单 |