366 lines
11 KiB
Markdown
366 lines
11 KiB
Markdown
# 阿里云智能媒体服务 - SubmitMediaProducingJob API文档
|
||
|
||
## 📋 API概述
|
||
|
||
**接口名称：** SubmitMediaProducingJob（提交剪辑合成作业）
|
||
|
||
**服务名称：** Intelligent Media Services (IMS) - 智能媒体服务
|
||
|
||
**API版本：** 2020-11-09
|
||
|
||
### 业务说明
|
||
|
||
`SubmitMediaProducingJob` 是阿里云智能媒体服务的核心API接口，主要用于**提交媒体剪辑合成任务**。当用户需要对视频或音频素材进行剪辑、合成、添加特效、转码等后期制作时，可以通过调用此接口自动完成这些复杂的媒体处理工作。
|
||
|
||
#### 核心业务场景
|
||
|
||
1. **视频剪辑制作**
|
||
- 多个视频片段的拼接合成
|
||
- 添加转场效果和过渡动画
|
||
- 视频片段的裁剪和缩放
|
||
|
||
2. **音视频处理**
|
||
- 音频与视频的同步合成
|
||
- 添加背景音乐和音效
|
||
- 音频混合和音量调节
|
||
|
||
3. **多轨道编辑**
|
||
- 支持视频轨道、音频轨道、字幕轨道
|
||
- 实现复杂的多层编辑效果
|
||
- 视频叠加和水印添加
|
||
|
||
4. **模板化制作**
|
||
- 使用预定义模板快速生成视频
|
||
- 批量内容生产
|
||
- 统一风格的视频输出
|
||
|
||
5. **云端转码**
|
||
- 视频格式转换（MP4、AVI、MOV等）
|
||
- 分辨率和码率调整
|
||
- 自适应码率输出
|
||
|
||
---
|
||
|
||
## 🔐 授权信息
|
||
|
||
| 操作名 | 访问级别 | 资源类型 | 条件键 | 关联操作 |
|
||
|--------|----------|----------|--------|----------|
|
||
| ice:SubmitMediaProducingJob | 写权限 | 所有资源 (`*`) | 无 | 无 |
|
||
|
||
---
|
||
|
||
## 📡 接口调用
|
||
|
||
**请求方法：** POST
|
||
|
||
**调用地址：** `https://ims.ap-southeast-1.aliyuncs.com/`
|
||
|
||
**请求路径：** `/2020-11-09/submitMediaProducingJob`
|
||
|
||
### ⚠️ 重要说明
|
||
|
||
- 此接口仅返回作业**提交结果**，作业提交后将在后台异步处理
|
||
- 时间线中引用的素材可以是媒体库中的资产或OSS对象
|
||
- **不支持**外部URL或CDN URL
|
||
- 生产完成后，输出文件会自动注册为媒体资产
|
||
- 需要先分析媒体资产，才能查询时长和分辨率信息
|
||
|
||
---
|
||
|
||
## 🔒 调用限制
|
||
|
||
| 限制项 | 限制值 | 说明 |
|
||
|--------|--------|------|
|
||
| **QPS限制** | 30次/秒 | 超出限制会返回"Throttling.User"错误 |
|
||
| **视频轨道** | 最多100个 | 每个项目最多可创建100条视频轨道 |
|
||
| **图片轨道** | 最多100个 | 每个项目最多可创建100条图片轨道 |
|
||
| **字幕轨道** | 最多100个 | 每个项目最多可创建100条字幕轨道 |
|
||
| **素材总大小** | 不超过1TB | 项目中所有素材文件的总大小限制 |
|
||
| **输出分辨率** | 128px - 4096px | 宽度和高度都必须在128-4096像素之间 |
|
||
| **视频短边** | 不超过2160px | 视频的短边不能超过2160像素 |
|
||
| **区域限制** | 同一区域 | 素材和输出的OSS桶必须与IMS服务区域一致 |
|
||
|
||
---
|
||
|
||
## 📝 请求参数
|
||
|
||
### 主要参数说明
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| **ProjectId** | string | 否 | 编辑项目的ID | `xxxxxfb2101cb318xxxxx` |
|
||
| **Timeline** | string | 否 | 在线编辑作业的时间线配置 | 详见时间线配置 |
|
||
| **TemplateId** | string | 否 | 模板ID（使用模板快速构建时间线） | `****96e8864746a0b6f3****` |
|
||
| **ClipsParam** | string | 否 | 模板素材参数（JSON格式） | - |
|
||
| **ProjectMetadata** | string | 否 | 编辑项目的元数据（JSON格式） | - |
|
||
| **OutputMediaTarget** | string | 否 | 输出文件类型：`oss-object`/`vod-media`/`S3` | `oss-object` |
|
||
| **OutputMediaConfig** | **Yes** | **是** | 输出文件配置（JSON格式） | 详见配置说明 |
|
||
| **UserData** | string | 否 | 用户自定义数据（最多512字节） | `{"NotifyAddress":"https://..."}` |
|
||
| **ClientToken** | string | 否 | 客户端令牌（确保请求幂等性） | `****12e8864746a0a398****` |
|
||
| **Source** | string | 否 | 请求来源：`OpenAPI`/`AliyunConsole`/`WebSDK` | `OPENAPI` |
|
||
| **EditingProduceConfig** | string | 否 | 编辑制作参数 | 详见配置说明 |
|
||
| **MediaMetadata** | string | 否 | 产出视频的元数据 | `{"Title":"test-title"}` |
|
||
|
||
### 参数组合规则
|
||
|
||
**三选一参数：** `ProjectId`、`Timeline`、`TemplateId` 中必须指定一个，其余两个必须为空。
|
||
|
||
- 如果指定 `ProjectId`：使用现有编辑项目
|
||
- 如果指定 `Timeline`：直接定义时间线
|
||
- 如果指定 `TemplateId`：必须同时指定 `ClipsParam`
|
||
|
||
---
|
||
|
||
## 💾 输出配置示例
|
||
|
||
### 示例1：输出到OSS
|
||
|
||
```json
|
||
{
|
||
"MediaURL": "https://my-test-bucket.oss-cn-shanghai.aliyuncs.com/test/xxxxxtest001xxxxx.mp4",
|
||
"Bitrate": 2000,
|
||
"Width": 800,
|
||
"Height": 680
|
||
}
|
||
```
|
||
|
||
**配置说明：**
|
||
- `MediaURL`：OSS对象URL，格式为 `https://bucketname.oss-region-name.aliyuncs.com/xxx/yyy.ext`
|
||
- `Bitrate`：输出码率（Kbit/s），越高视频越清晰，最大值为5000
|
||
- `Width`/`Height`：输出分辨率，留空则使用输入素材的最大分辨率
|
||
|
||
### 示例2：输出到ApsaraVideo VOD
|
||
|
||
```json
|
||
{
|
||
"StorageLocation": "outin-*xxxxxx7d2a3811eb83da00163exxxxxx.oss-cn-shanghai.aliyuncs.com",
|
||
"FileName": "output.mp4",
|
||
"Bitrate": 2000,
|
||
"Width": 800,
|
||
"Height": 680,
|
||
"VodTemplateGroupId": "VOD_NO_TRANSCODE"
|
||
}
|
||
```
|
||
|
||
**配置说明：**
|
||
- `StorageLocation`：VOD中的存储位置（不含http://前缀）
|
||
- `FileName`：输出文件名（包含扩展名）
|
||
- `VodTemplateGroupId`：VOD转码模板组ID，设为`VOD_NO_TRANSCODE`表示不转码
|
||
|
||
### OutputMediaConfig 参数详解
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| MediaURL | String | 输出文件URL（oss-object类型） |
|
||
| StorageLocation | String | VOD存储位置（vod-media类型） |
|
||
| FileName | String | 输出文件名（vod-media类型） |
|
||
| Width | Integer | 输出宽度（默认：输入素材最大宽度） |
|
||
| Height | Integer | 输出高度（默认：输入素材最大高度） |
|
||
| Bitrate | Integer | 输出码率（默认：输入素材最大码率） |
|
||
| VodTemplateGroupId | String | VOD转码模板组ID |
|
||
|
||
---
|
||
|
||
## 📤 响应参数
|
||
|
||
| 参数名 | 类型 | 描述 | 示例值 |
|
||
|--------|------|------|--------|
|
||
| RequestId | string | 请求ID（唯一标识） | `****36-3C1E-4417-BDB2-1E034F****` |
|
||
| ProjectId | string | 编辑项目ID | `****b4549d46c88681030f6e****` |
|
||
| **JobId** | string | **作业ID（用于查询作业状态）** | `****d80e4e4044975745c14b****` |
|
||
| MediaId | string | 输出文件的媒体资产ID | `****c469e944b5a856828dc2****` |
|
||
| VodMediaId | string | 输出文件在VOD中的媒体资产ID（如适用） | `****d8s4h75ci975745c14b****` |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"RequestId": "****36-3C1E-4417-BDB2-1E034F****",
|
||
"ProjectId": "****b4549d46c88681030f6e****",
|
||
"JobId": "****d80e4e4044975745c14b****",
|
||
"MediaId": "****c469e944b5a856828dc2****",
|
||
"VodMediaId": "****d8s4h75ci975745c14b****"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 EditingProduceConfig 配置
|
||
|
||
用于控制编辑制作过程的参数。
|
||
|
||
```json
|
||
{
|
||
"AutoRegisterInputVodMedia": "true",
|
||
"OutputWebmTransparentChannel": "true",
|
||
"CoverConfig": {
|
||
"CustomThumbnail": "https://example.com/thumb.jpg"
|
||
}
|
||
}
|
||
```
|
||
|
||
**参数说明：**
|
||
- `AutoRegisterInputVodMedia`：是否自动注册时间线中的VOD媒体资产到IMS，默认 `true`
|
||
- `OutputWebmTransparentChannel`：输出视频是否包含Alpha通道（透明度），默认 `false`
|
||
- `CoverConfig`：自定义缩略图配置
|
||
|
||
---
|
||
|
||
## 🚨 错误码
|
||
|
||
| HTTP状态码 | 错误码 | 错误消息 |
|
||
|------------|--------|----------|
|
||
| 400 | InvalidParameter | 参数不合法 |
|
||
| 404 | ProjectNotFound | 指定的项目不存在 |
|
||
| 429 | Throttling.User | 请求频率超过限制（30 QPS） |
|
||
|
||
---
|
||
|
||
## 💡 典型使用场景
|
||
|
||
### 场景1：视频片段拼接
|
||
|
||
```json
|
||
{
|
||
"Timeline": {
|
||
"VideoTracks": [
|
||
{
|
||
"VideoTrackClips": [
|
||
{"MediaId": "****4d7cf14dc7b83b0e801c****"},
|
||
{"MediaId": "****4d7cf14dc7b83b0e801c****"}
|
||
]
|
||
}
|
||
]
|
||
},
|
||
"OutputMediaConfig": {
|
||
"MediaURL": "https://my-bucket.oss-cn-shanghai.aliyuncs.com/output.mp4",
|
||
"Bitrate": 2000
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务场景：** 将两个视频片段无缝拼接成一个完整视频
|
||
|
||
### 场景2：模板化视频生产
|
||
|
||
```json
|
||
{
|
||
"TemplateId": "****template-id****",
|
||
"ClipsParam": {
|
||
"clips": [
|
||
{"MediaId": "****video1****"},
|
||
{"MediaId": "****video2****"}
|
||
]
|
||
},
|
||
"OutputMediaConfig": {
|
||
"MediaURL": "https://my-bucket.oss-cn-shanghai.aliyuncs.com/template-output.mp4"
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务场景：** 使用预定义模板快速生成风格统一的视频内容
|
||
|
||
### 场景3：视频转码并上传VOD
|
||
|
||
```json
|
||
{
|
||
"Timeline": {
|
||
"VideoTracks": [
|
||
{
|
||
"VideoTrackClips": [
|
||
{"MediaId": "****source-video****"}
|
||
]
|
||
}
|
||
]
|
||
},
|
||
"OutputMediaTarget": "vod-media",
|
||
"OutputMediaConfig": {
|
||
"StorageLocation": "outin-xxxxx.oss-cn-shanghai.aliyuncs.com",
|
||
"FileName": "transcoded-video.mp4",
|
||
"Bitrate": 1500,
|
||
"Width": 1920,
|
||
"Height": 1080
|
||
},
|
||
"UserData": {
|
||
"NotifyAddress": "https://your-callback-url.com"
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务场景：** 将视频转码为不同分辨率和码率，并直接上传到VOD系统
|
||
|
||
---
|
||
|
||
## 📊 相关API
|
||
|
||
- **GetMediaProducingJob**：查询媒体剪辑合成作业状态
|
||
- **CancelMediaProducingJob**：取消媒体剪辑合成作业
|
||
- **CreateEditingProject**：创建编辑项目
|
||
|
||
---
|
||
|
||
## 🔗 相关文档
|
||
|
||
- [时间线配置说明](https://www.alibabacloud.com/help/en/ims/developer-reference/timeline-configuration-description)
|
||
- [编辑制作参数说明](https://www.alibabacloud.com/help/en/ims/developer-reference/clip-composition-parameter-description)
|
||
- [模板创建和使用](https://www.alibabacloud.com/help/en/ims/user-guide/create-and-use-a-normal-template)
|
||
- [回调配置](https://www.alibabacloud.com/help/en/ims/use-cases/to-configure-a-callback-when-a-clip-completes)
|
||
- [常见问题FAQ](https://www.alibabacloud.com/help/en/ims/support/intelligent-production-making-faq)
|
||
|
||
---
|
||
|
||
## 📌 注意事项
|
||
|
||
1. **异步处理：** 作业提交后立即返回，任务在后台异步执行
|
||
2. **费用说明：** 按实际处理时长和输出文件大小计费
|
||
3. **配额管理：** 建议使用 `ClientToken` 确保请求幂等性
|
||
4. **回调通知：** 通过 `UserData.NotifyAddress` 设置完成回调通知
|
||
5. **文件大小：** 单次处理的文件总大小建议不超过1GB，超过建议分段处理
|
||
6. **格式支持：** 支持主流视频/音频格式（MP4、AVI、MOV、MP3、AAC等）
|
||
7. **转码速度：** 处理速度取决于输出质量设置，高质量处理时间较长
|
||
|
||
---
|
||
|
||
## 🎯 最佳实践
|
||
|
||
### 1. 幂等性保证
|
||
```javascript
|
||
// 使用ClientToken确保同一请求不会被重复处理
|
||
const clientToken = generateUUID();
|
||
await submitMediaProducingJob({
|
||
ClientToken: clientToken,
|
||
// ... 其他参数
|
||
});
|
||
```
|
||
|
||
### 2. 状态轮询
|
||
```javascript
|
||
// 提交作业后，使用JobId轮询查询状态
|
||
const jobId = response.JobId;
|
||
const status = await getMediaProducingJob({ JobId: jobId });
|
||
```
|
||
|
||
### 3. 错误重试
|
||
```javascript
|
||
// 针对网络错误或限流错误进行指数退避重试
|
||
try {
|
||
await submitMediaProducingJob(params);
|
||
} catch (error) {
|
||
if (error.code === 'Throttling.User') {
|
||
// 等待后重试
|
||
await sleep(1000);
|
||
await submitMediaProducingJob(params);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 资源清理
|
||
```javascript
|
||
// 处理完成后，及时清理不必要的中间文件
|
||
await deleteMediaAssets([tempMediaId1, tempMediaId2]);
|
||
```
|
||
|
||
---
|
||
|
||
*文档版本：v1.0* | *最后更新：2025-11-29*
|