feat: 优化

2025-11-30 18:06:54 +08:00
parent 853bedcb23
commit ac803ec03b
9 changed files with 1314 additions and 326 deletions
--- a/docs/ICE_SubmitMediaProducingJob_API.md
+++ b/docs/ICE_SubmitMediaProducingJob_API.md
@@ -0,0 +1,365 @@
+# 阿里云智能媒体服务 - 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*