sion/sionrui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ac803ec03b4054d7e6db52ae2da356a0808b694a
sionrui/docs/ICE_SubmitMediaProducingJob_API.md
sion123 ac803ec03b feat: 优化
2025-11-30 18:06:54 +08:00

11 KiB
Raw Blame History

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

{
  "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

{
  "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****

响应示例

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

🔧 EditingProduceConfig 配置

用于控制编辑制作过程的参数。

{
  "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：视频片段拼接

{
  "Timeline": {
    "VideoTracks": [
      {
        "VideoTrackClips": [
          {"MediaId": "****4d7cf14dc7b83b0e801c****"},
          {"MediaId": "****4d7cf14dc7b83b0e801c****"}
        ]
      }
    ]
  },
  "OutputMediaConfig": {
    "MediaURL": "https://my-bucket.oss-cn-shanghai.aliyuncs.com/output.mp4",
    "Bitrate": 2000
  }
}

业务场景： 将两个视频片段无缝拼接成一个完整视频

场景2：模板化视频生产

{
  "TemplateId": "****template-id****",
  "ClipsParam": {
    "clips": [
      {"MediaId": "****video1****"},
      {"MediaId": "****video2****"}
    ]
  },
  "OutputMediaConfig": {
    "MediaURL": "https://my-bucket.oss-cn-shanghai.aliyuncs.com/template-output.mp4"
  }
}

业务场景： 使用预定义模板快速生成风格统一的视频内容

场景3：视频转码并上传VOD

{
  "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：创建编辑项目

🔗 相关文档

📌 注意事项

  1. 异步处理： 作业提交后立即返回，任务在后台异步执行
  2. 费用说明： 按实际处理时长和输出文件大小计费
  3. 配额管理： 建议使用 ClientToken 确保请求幂等性
  4. 回调通知： 通过 UserData.NotifyAddress 设置完成回调通知
  5. 文件大小： 单次处理的文件总大小建议不超过1GB，超过建议分段处理
  6. 格式支持： 支持主流视频/音频格式（MP4、AVI、MOV、MP3、AAC等）
  7. 转码速度： 处理速度取决于输出质量设置，高质量处理时间较长

🎯 最佳实践

1. 幂等性保证

// 使用ClientToken确保同一请求不会被重复处理
const clientToken = generateUUID();
await submitMediaProducingJob({
  ClientToken: clientToken,
  // ... 其他参数
});

2. 状态轮询

// 提交作业后，使用JobId轮询查询状态
const jobId = response.JobId;
const status = await getMediaProducingJob({ JobId: jobId });

3. 错误重试

// 针对网络错误或限流错误进行指数退避重试
try {
  await submitMediaProducingJob(params);
} catch (error) {
  if (error.code === 'Throttling.User') {
    // 等待后重试
    await sleep(1000);
    await submitMediaProducingJob(params);
  }
}

4. 资源清理

// 处理完成后，及时清理不必要的中间文件
await deleteMediaAssets([tempMediaId1, tempMediaId2]);

文档版本：v1.0 | 最后更新：2025-11-29

Reference in New Issue View Git Blame Copy Permalink