调用SubmitMediaProducingJob提交剪辑合成作品_智能媒体服务(IMS)-阿里云帮助中心

SubmitMediaProducingJob接口主要用于提交一个媒体剪辑合成任务。当用户需要对视频或音频素材进行剪辑、合成或其他形式的后期制作时，可以通过调用此API接口来实现自动化处理。

接口说明

计费说明：视频剪辑按照剪辑合成的成片时长计费，详情请参见视频剪辑。若处理失败，不收取费用。
多样化剪辑能力：当您需要将素材按照个性化创意进行编排和设计时，您需要调用该接口，该接口支持通过灵活的 Timeline 配置，实现复杂的视频剪辑需求。
素材引用规则：云剪辑时间线中引用的素材，既可以是素材库中的媒资，也可以直接引用 OSS 文件，暂不支持外部地址或 CDN 地址。当素材为 OSS 文件时，MediaUrl 仅支持 OSS 地址格式，如：https://your-bucket.oss-region-name.aliyuncs.com/your-object.ext。
异步执行任务：该接口返回合成任务的提交结果，不保证接口返回时视频已合成完毕。合成任务将进入后台排队，异步执行。
任务状态查询：
1. 调用 GetMediaProducingJob ，通过传入 JobId 查询任务状态和结果。
2. 在提交剪辑合成作业时，您可以在请求参数中设置 UserData，将其包含回调地址。当剪辑任务完成或失败时，系统会向该回调地址发送通知，您可以通过处理回调数据来了解任务的状态。
媒资注册与分析：视频合成完成后，会自动注册媒资，此时媒资还是分析中状态，当媒资分析完成后，可以根据 MediaId 获取成片时长及分辨率信息。

使用限制

该接口的流量控制值为 30 QPS（每秒提交任务的请求数）。提交的任务会进入后台排队，以异步方式处理。

说明
如果超出此限制，可能会遇到 "Throttling.User" 错误。详情请参见：提交剪辑任务时遇到“Throttling.User”错误。
提交大量任务（如 1000 条、10000 条）时，系统会动态扩容，但可能会有一定排队时间。
视频轨、图片轨、字幕轨的轨道数每种均限制最多 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		全部资源 ``	无	无

请求参数

名称	类型	必填	描述	示例值

名称	类型	必填	描述	示例值
ProjectId	string	否	剪辑工程 ld。你可调用 CreateEditingProject 接口创建剪辑工程，并获取 ProjectId 提交剪辑任务。注意必须填写 ProjectId、Timeline、TemplateId 三个参数中的一个，剩余两个参数填写为空。	xxxxxfb2101cb318xxxxx
Timeline	string	否	云剪辑任务时间线，当您需要将素材按照视频创意进行编排和特效设计时，可以手动构建 Timeline 参数。时间线主要包含轨道、素材、效果 3 种对象，详情请参见 Timeline 配置说明。更多时间线配置示例请参见最佳实践。注意必须填写 ProjectId、Timeline、TemplateId 三个参数中的一个，剩余两个参数填写为空。	{"VideoTracks":[{"VideoTrackClips":[{"MediaId":"**4d7cf14dc7b83b0e801c"},{"MediaId":"4d7cf14dc7b83b0e801c**"}]}]}
TemplateId	string	否	模板 Id，用于快速低门槛的构建时间线。支持基于普通模板和高级模板的视频剪辑。当使用模板 Id 提交剪辑合成作业时，必须提供 ClipsParam 参数，用于灵活调整或替换模板中的素材。可调用 GetTemplate 获取模板信息。注意必须填写 ProjectId、Timeline、TemplateId 三个参数中的一个，剩余两个参数填写为空。	**96e8864746a0b6f3**
ClipsParam	string	否	模板对应的素材参数，Json 格式，当 TemplateId 不为空时，ClipsParam 不能为空。具体格式见普通模板创建及使用、高级模板创建及使用。	见模板使用文档
ProjectMetadata	string	否	剪辑工程的元数据信息，Json 格式。具体结构定义参见 ProjectMetadata 。	{"Description":"剪辑视频描述","Title":"剪辑标题测试"}
OutputMediaTarget	string	否	输出成品的目标类型。取值： oss-object（客户在阿里云 oss bucket 下的 oss object） vod-media（阿里云 vod 的媒资） S3（S3 协议输出）	oss-object
OutputMediaConfig	string	是	输出成品的目标配置，Json 格式。可以设置输出成品的在 OSS 上的 URL，或者 VOD Bucket 中的存储位置。输出到 OSS 时，输出目标的 MediaURL 必填；输出到 VOD 时，StorageLocation 和 FileName 两个参数必填。 OutputMediaConfig 参数示例。	{"MediaURL":"https://example-bucket.oss-cn-shanghai.aliyuncs.com/example.mp4"}
UserData	string	否	自定义设置，Json 格式，长度限制为 512 字节。支持任务完成回调配置。其中： NotifyAddress 为任务完成的回调 RegisterMediaNotifyAddress 为成片媒资分析完成的回调	{"NotifyAddress":"https://xx.com/xx","RegisterMediaNotifyAddress":"https://xxx.com/xx"}
ClientToken	string	否	保证请求幂等性。从您的客户端生成一个参数值，确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符，且不能超过 64 个字符。	**12e8864746a0a398**
Source	string	否	剪辑合成请求来源，取值范围： OpenAPI：API 直接请求。 AliyunConsole：请求来自于阿里云控制台。 WebSDK：请求来自于集成了 WebSDK 的前端页面。	OPENAPI
EditingProduceConfig	string	否	剪辑合成参数，配置详情请参见 EditingProduceConfig 参数详情。说明 EditingProduceConfig 没有配置封面图片时，则默认使用视频的第一帧作为封面。 AutoRegisterInputVodMedia：是否需要将您时间线中的 VOD 媒资自动注册至 IMS，默认为 true。 OutputWebmTransparentChannel: 是否需要输出视频带透明通道，默认为 false。 CoverConfig: 自定义封面图参数。 ......	{ "AutoRegisterInputVodMedia": "true", "OutputWebmTransparentChannel": "true" }
MediaMetadata	string	否	合成视频的元数据，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 结构中的参数说明

属性名	类型	描述

属性名	类型	描述
MediaURL	String	输出的媒资的 URL （当 OutputMediaTarget 的目标为 oss-object 时，指定 OSS 文件的 HTTP URL 路径）, 如：http://xxx-bucket-name.oss-cn-shanghai.aliyuncs.com/OSS 跟调用的服务所在区域相同。
StorageLocation	String	当 OutputMediaTarget 的目标为 vod-media 时，指定 storage location 来存储媒资到 VOD;storage location 是 VOD 中的文件存储位置，不包含 http:// 的前缀，如：outin-xxxxxx.oss-cn-shanghai.aliyuncs.com。
FileName	String	当 OutputMediaTarget 的目标为 vod-media 时，指定 fileName（包含文件后缀，不含路径）作为输出文件名。
Width	Integer	输出成品的宽。可以不填，默认值是多个素材的最大宽。
Height	Integer	输出成品的高。可以不填，默认值是多个素材的最大高。
Bitrate	Integer	输出成品的码率，单位为 Kbps。可以不填，默认值是多个素材的最高码率，上限为 5000。若还要保留最高素材的码率，需要设置 EditingProduceConfig.KeepOriginMaxBitrate=true，详情请参见 EditingProduceConfig 。
VodTemplateGroupId	String	合成成片输出到 vod，指定 vod 转码模板组。如不需要 VOD 转码，请填写 "VOD_NO_TRANSCODE"。

返回参数

名称	类型	描述	示例值

名称	类型	描述	示例值
	object	Schema of Response
RequestId	string	请求 ID。	**36-3C1E-4417-BDB2-1E034F**
ProjectId	string	剪辑工程 ID。	**b4549d46c88681030f6e**
JobId	string	合成作业 ID。	**d80e4e4044975745c14b**
MediaId	string	合成媒资 ID。	**c469e944b5a856828dc2**
VodMediaId	string	如果视频输出的位置为 vod 时，返回 vod 媒资 id。	**d8s4h75ci975745c14b**

示例

正常返回示例

JSON格式

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

错误码

HTTP status code	错误码	错误信息

HTTP status code	错误码	错误信息
400	InvalidParameter	The specified parameter \ is not valid.
404	ProjectNotFound	The specified project not found

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

变更历史

变更时间	变更内容概要	操作

变更时间	变更内容概要	操作
2023-11-23	OpenAPI 错误码发生变更	查看变更详情
2023-04-25	OpenAPI 错误码发生变更、OpenAPI 入参发生变更	查看变更详情
2021-11-16	OpenAPI 错误码发生变更、OpenAPI 入参发生变更、OpenAPI 返回结构发生变更	查看变更详情