# 阿里云智能媒体服务 - 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*