将一个或多个视频、音频、图片、字幕素材合成为成品。可以通过时间线(Timeline)参数直接提交剪辑设置,也可以先创建云剪辑工程,使用工程ID提交剪辑任务。
接口说明
- 该接口返回合成任务的提交结果,不保证接口返回时视频已合成完毕。合成任务将进入后台排队,异步执行。
- 云剪辑时间线中引用的素材,既可以是素材库中的媒资,也可以直接引用OSS文件,暂不支持外部地址或CDN地址。当素材为OSS文件时,MediaUrl仅支持OSS地址格式,如:https://your-bucket.oss-region-name.aliyuncs.com/your-object.ext。
- 视频合成完成后,会自动注册媒资,此时媒资还是分析中状态,当媒资分析完成后,可以根据MediaId获取成片时长及分辨率信息。
使用限制
- 视频轨、图片轨轨道数无限制,字幕轨限制最多100个。
- 素材个数无限制,素材文件总大小不能超过1 TB。
- 输入或输出OSS Bucket所在Region,必须和使用IMS的Region保持一致。
- 当输出为视频时,成片分辨率有以下限制:
- 宽高都不能小于128 px。
- 宽高都不能大于4096 px。
- 短边不能大于2160 px。
调试
您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。
授权信息
请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
ProjectId | string | 否 | 剪辑工程ld。注:ProjectId、Timeline、TemplateId有且只有一个非空。 | xxxxxfb2101cb318xxxxx |
Timeline | string | 否 | 时间线,描述素材按照视频创意进行编排和特效设计的结果。Json格式。具体结构定义参见Timeline配置说明。注:ProjectId、Timeline、TemplateId有且只有一个非空。 | {"VideoTracks":[{"VideoTrackClips":[{"MediaId":"****4d7cf14dc7b83b0e801c****"},{"MediaId":"****4d7cf14dc7b83b0e801c****"}]}]} |
TemplateId | string | 否 | 模板Id,用于快速低门槛的构建时间线。注:ProjectId、Timeline、TemplateId有且只有一个非空。当TemplateId不为空时,ClipsParam不能为空。 | ****96e8864746a0b6f3**** |
ClipsParam | string | 否 | 见模板使用文档 | |
ProjectMetadata | string | 否 | 剪辑工程的元数据信息,Json格式。具体结构定义参见ProjectMetadata。 | {"Description":"剪辑视频描述","Title":"剪辑标题测试"} |
OutputMediaTarget | string | 否 | 输出成品的目标类型。取值:
| oss-object |
OutputMediaConfig | string | 是 | 输出成品的目标配置,Json格式。可以设置输出成品的在OSS 上的URL,或者VOD Bucket 中的存储位置。 输出到OSS时,输出目标的 MediaURL 必填;输出到VOD 时,StorageLocation 和 FileName 两个参数必填。 | {"MediaURL":"https://example-bucket.oss-cn-shanghai.aliyuncs.com/example.mp4"} |
UserData | string | 否 | 自定义设置,Json格式,长度限制为512字节。支持自定义回调地址配置。 | {"NotifyAddress":"http://xx.xx.xxx"}或{"NotifyAddress":"https://xx.xx.xxx"}或{"NotifyAddress":"ice-callback-demo"} |
ClientToken | string | 否 | 保证请求幂等性。 | ****12e8864746a0a398**** |
Source | string | 否 | 剪辑合成请求来源,取值范围:
| OPENAPI |
EditingProduceConfig | string | 否 | 剪辑合成参数, 参数详情。
| { "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。可以不填,默认值是多个素材的最高码率。 |
VodTemplateGroupId | String | 合成成片输出到vod,指定vod转码模板组。如不需要VOD转码,请填写 "VOD_NO_TRANSCODE"。 |
返回参数
示例
正常返回示例
JSON
格式
{
"RequestId": "****36-3C1E-4417-BDB2-1E034F****",
"ProjectId": "****b4549d46c88681030f6e****",
"JobId": "****d80e4e4044975745c14b****",
"MediaId": "****c469e944b5a856828dc2****",
"VodMediaId": "****d8s4h75ci975745c14b****"
}
错误码
HTTP status code | 错误码 | 错误信息 |
---|---|---|
400 | InvalidParameter | The specified parameter \ is not valid. |
404 | ProjectNotFound | The specified project not found |
访问错误中心查看更多错误码。
变更历史
变更时间 | 变更内容概要 | 操作 | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
2023-04-25 | OpenAPI 错误码发生变更,OpenAPI 入参发生变更 | 看变更集 | ||||||||||||
| ||||||||||||||
2021-11-16 | OpenAPI 错误码发生变更,OpenAPI 入参发生变更,OpenAPI 返回结构发生变更 | 看变更集 | ||||||||||||
|