文档

SubmitMediaProducingJob - 提交剪辑合成作业

更新时间:

将一个或多个视频、音频、图片、字幕素材合成为成品。可以通过时间线(Timeline)参数直接提交剪辑设置,也可以先创建云剪辑工程,使用工程ID提交剪辑任务。

接口说明

  • 该接口返回合成任务的提交结果,不保证接口返回时视频已合成完毕。合成任务将进入后台排队,异步执行。
  • 云剪辑时间线中引用的素材,既可以是素材库中的媒资,也可以直接引用 OSS 文件,暂不支持外部地址或 CDN 地址。当素材为 OSS 文件时,MediaUrl 仅支持 OSS 地址格式,如:https://your-bucket.oss-region-name.aliyuncs.com/your-object.ext。
  • 视频合成完成后,会自动注册媒资,此时媒资还是分析中状态,当媒资分析完成后,可以根据 MediaId 获取成片时长及分辨率信息。

使用限制

  • 本接口流控值为 30 qps
  • 视频轨、图片轨、字幕轨的轨道数每种均限制最多 100 个。
  • 素材个数无限制,素材文件总大小不能超过 1 TB。
  • 输入或输出 OSS Bucket 所在 Region,必须和使用 IMS 的 Region 保持一致。
  • 当输出为视频时,成片分辨率有以下限制:
    • 宽高都不能小于 128 px。
    • 宽高都不能大于 4096 px。
    • 短边不能大于 2160 px。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
ice:SubmitMediaProducingJob
  • 全部资源
    *

请求参数

名称类型必填描述示例值
ProjectIdstring

剪辑工程 ld。注:ProjectId、Timeline、TemplateId 有且只有一个非空。

xxxxxfb2101cb318xxxxx
Timelinestring

云剪辑任务时间线。具体结构定义,请参见 Timeline 配置说明

{"VideoTracks":[{"VideoTrackClips":[{"MediaId":"****4d7cf14dc7b83b0e801c****"},{"MediaId":"****4d7cf14dc7b83b0e801c****"}]}]}
TemplateIdstring

模板 Id,用于快速低门槛的构建时间线。注:ProjectId、Timeline、TemplateId 有且只有一个非空。当 TemplateId 不为空时,ClipsParam 不能为空。

****96e8864746a0b6f3****
ClipsParamstring

模板对应的素材参数,Json 格式,当 TemplateId 不为空时,ClipsParam 不能为空。具体格式见 普通模板创建及使用高级模板创建及使用

见模板使用文档
ProjectMetadatastring

剪辑工程的元数据信息,Json 格式。具体结构定义参见 ProjectMetadata

{"Description":"剪辑视频描述","Title":"剪辑标题测试"}
OutputMediaTargetstring

输出成品的目标类型。取值:

  • oss-object(客户在阿里云 oss bucket 下的 oss object)

  • vod-media(阿里云 vod 的媒资)

oss-object
OutputMediaConfigstring

输出成品的目标配置,Json 格式。可以设置输出成品的在 OSS 上的 URL,或者 VOD Bucket 中的存储位置。

输出到 OSS 时,输出目标的 MediaURL 必填;输出到 VOD 时,StorageLocation 和 FileName 两个参数必填。

OutputMediaConfig 参数示例

{"MediaURL":"https://example-bucket.oss-cn-shanghai.aliyuncs.com/example.mp4"}
UserDatastring

自定义设置,Json 格式,长度限制为 512 字节。支持自定义回调地址配置

{"NotifyAddress":"http://xx.xx.xxx"}或{"NotifyAddress":"https://xx.xx.xxx"}或{"NotifyAddress":"ice-callback-demo"}
ClientTokenstring

保证请求幂等性。

****12e8864746a0a398****
Sourcestring

剪辑合成请求来源,取值范围:

  • OpenAPI:API 直接请求。

  • AliyunConsole:请求来自于阿里云控制台。

  • WebSDK:请求来自于集成了 WebSDK 的前端页面。

OPENAPI
EditingProduceConfigstring

剪辑合成参数, 参数详情

  • AutoRegisterInputVodMedia:是否需要将您时间线中的 VOD 媒资自动注册至 IMS,默认为 true。

  • OutputWebmTransparentChannel: 是否需要输出视频带透明通道,默认为 false。

  • CoverConfig: 自定义封面图参数。

  • 等......

{ "AutoRegisterInputVodMedia": "true", "OutputWebmTransparentChannel": "true" }
MediaMetadatastring

合成视频的元数据,JSON 格式。具体结构定义,请参见 MediaMetadata

{ "Title":"test-title", "Tags":"test-tags1,tags2" }

OutputMediaConfig 参数示例

示例:输出到 OSS

{
  "MediaURL":"https://my-test-bucket.oss-cn-shanghai.aliyuncs.com/test/xxxxxtest001xxxxx.mp4",
  "Bitrate": 2000,  
  "Width": 800,  
  "Height": 680
}

当输出到 OSS 时,MediaURL 必填。OutputMediaTarget 参数默认值为 "oss-object", 表示输出到 OSS。 其他参数可以选填,其中 Bitrate 用来设置输出成品的码率,通常码率越高越清晰,最大可以设置到 5000。 Width, Height 用来设置成品的分辨率。

OSS URL 的路径格式: https://bucketname.oss-region-name.aliyuncs.com/xxx/yyy.ext

bucketname 是 OSS Bucket 的名称。

oss-region-name.aliyuncs.com 是 OSS 文件的外网 Endpoint,比如上海,北京,杭州的分别是:

oss-cn-shanghai.aliyuncs.com
oss-cn-hangzhou.aliyuncs.com 
oss-cn-beijing.aliyuncs.com

示例:输出到 vod

{ 
  "StorageLocation": "outin-*xxxxxx7d2a3811eb83da00163exxxxxx.oss-cn-shanghai.aliyuncs.com",  
  "FileName": "output.mp4",  
  "Bitrate": 2000,  
  "Width": 800,  
  "Height": 680
}

当输出到 VOD 时, StorageLocation 和 FileName 两个参数必填。OutputMediaTarget 参数设置为 "vod-media", 表示输出到点播 VOD 的存储 Bucket。点播 VOD 可以使用的存储位置可以在 VOD 里面上传媒资后,在媒资的存储地址中看到。

OutputMediaConfig 结构中的参数说明

属性名类型描述
MediaURLString输出的媒资的 URL (当 OutputMediaTarget 的目标为 oss-object 时, 指定 OSS 文件的 HTTP URL 路径), 如:http://xxx-bucket-name.oss-cn-shanghai.aliyuncs.com/OSS 跟调用的服务所在区域相同。
StorageLocationString当 OutputMediaTarget 的目标为 vod-media 时, 指定 storage location 来存储媒资到 VOD;storage location 是 VOD 中的文件存储位置, 不包含 http:// 的前缀, 如:outin-xxxxxx.oss-cn-shanghai.aliyuncs.com。
FileNameString当 OutputMediaTarget 的目标为 vod-media 时,指定 fileName(包含文件后缀,不含路径)作为输出文件名。
WidthInteger输出成品的宽。可以不填,默认值是多个素材的最大宽。
HeightInteger输出成品的高。可以不填,默认值是多个素材的最大高。
BitrateInteger输出成品的码率,单位为 Kbps。可以不填,默认值是多个素材的最高码率。
VodTemplateGroupIdString合成成片输出到 vod,指定 vod 转码模板组。如不需要 VOD 转码,请填写 "VOD_NO_TRANSCODE"。

返回参数

名称类型描述示例值
object

Schema of Response

RequestIdstring

请求 ID。

****36-3C1E-4417-BDB2-1E034F****
ProjectIdstring

剪辑工程 ID。

****b4549d46c88681030f6e****
JobIdstring

合成作业 ID。

****d80e4e4044975745c14b****
MediaIdstring

合成媒资 ID。

****c469e944b5a856828dc2****
VodMediaIdstring

如果视频输出的位置为 vod 时,返回 vod 媒资 id。

****d8s4h75ci975745c14b****

示例

正常返回示例

JSON格式

{
  "RequestId": "****36-3C1E-4417-BDB2-1E034F****",
  "ProjectId": "****b4549d46c88681030f6e****",
  "JobId": "****d80e4e4044975745c14b****",
  "MediaId": "****c469e944b5a856828dc2****",
  "VodMediaId": "****d8s4h75ci975745c14b****"
}

错误码

HTTP status code错误码错误信息
400InvalidParameterThe specified parameter \ is not valid.
404ProjectNotFoundThe specified project not found

访问错误中心查看更多错误码。

变更历史

变更时间变更内容概要操作
2023-11-23OpenAPI 错误码发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    删除错误码:400
    删除错误码:404
2023-04-25OpenAPI 错误码发生变更、OpenAPI 入参发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    删除错误码:400
    删除错误码:404
入参OpenAPI 入参发生变更
    新增入参:MediaMetadata
2021-11-16OpenAPI 错误码发生变更、OpenAPI 入参发生变更、OpenAPI 返回结构发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    删除错误码:400
    删除错误码:404
入参OpenAPI 入参发生变更
    新增入参:EditingProduceConfig
出参OpenAPI 返回结构发生变更
  • 本页导读 (1)
文档反馈