alibabacloud-video-translation

视频翻译技能

由阿里云 IMS 提供支持的一键视频翻译，支持字幕级和语音级翻译。

---

输入格式要求

重要：不同 API 使用不同的地址格式！

API 地址格式参考

API	地址格式	示例
SubmitIProductionJob（字幕提取）	oss:// 格式	oss://my-bucket/videos/test.mp4
SubmitVideoTranslationJob（视频翻译）	HTTP URL 格式	https://my-bucket.oss-cn-shanghai.aliyuncs.com/videos/test.mp4

要点：字幕提取使用 oss://，视频翻译使用 HTTP URL！

用户输入处理

用户输入类型	处理方式
HTTP URL 格式	视频翻译时直接使用；如需提取字幕，则转换为 oss://
oss:// 格式	提取字幕时直接使用；视频翻译时转换为 HTTP URL
本地视频	必须询问 OSS 上传路径，上传后保存两种格式

格式转换规则

oss:// format ⇄ HTTP URL format

oss://my-bucket/videos/test.mp4
    ⇄
https://my-bucket.oss-cn-shanghai.aliyuncs.com/videos/test.mp4

转换公式：

• oss://<bucket>/<path> → https://<bucket>.oss-<region>.aliyuncs.com/<path>
• HTTP URL 无需签名，直接使用 Bucket 域名格式

本地视频处理流程

User provides local video path
    │
    ├─ AskUserQuestion: "Please provide OSS upload path (format: oss://<bucket>/<path>/<filename>.mp4)"
    │
    ├─ User specifies upload path
    │   ├─ Check if Bucket exists
    │   ├─ Upload file: aliyun oss cp <local_path> <oss_path>
    │   ├─ Save oss:// format → for subtitle extraction
    │   └─ Save HTTP URL format → for video translation
    │
    └─ User does not specify path → STOP, user MUST provide upload path

上传命令：

aliyun oss cp <local_path> oss://<bucket>/<path>/<filename>.mp4

上传后保存两种格式：

Local: /Users/demo/videos/test.mp4
Uploaded to: oss://my-bucket/videos/test.mp4
    ├─ oss:// format: oss://my-bucket/videos/test.mp4 (for subtitle extraction)
    └─ HTTP URL: https://my-bucket.oss-cn-shanghai.aliyuncs.com/videos/test.mp4 (for video translation)

---

执行门控检查清单

严格要求：Agent 必须按阶段顺序执行，当前阶段未通过时不得继续！

阶段 0：环境和凭据检查（硬性门控）

检查项	命令	通过条件	失败处理
CLI 版本	aliyun version	>= 3.3.1	停止，参见 cli-installation-guide.md
凭据状态	aliyun configure list	状态有效	停止，引导完成配置
插件安装	aliyun configure set --auto-plugin-install true	已设置	自动设置

硬性门控：未通过检查前，不得进行任何后续操作！

---

阶段 1：确认翻译模式（阻塞）

AskUserQuestion: "Do you need subtitle translation (translate subtitles only) or speech translation (translate subtitles + replace voiceover)?"

┌─ Subtitle translation → NeedSpeechTranslate: false
└─ Speech translation → NeedSpeechTranslate: true

⚠️ No reply received → STOP, cannot proceed!

不得根据输入类型推断翻译模式！

---

阶段 2：确认字幕处理方式（阻塞）

AskUserQuestion: "Do you need to erase original subtitles from the video? Do you need to burn-in translated subtitles?"

⚠️ No reply received → STOP, cannot proceed!

参数映射：

功能	参数	值
擦除原字幕	DetextArea	"Auto" / 坐标 / 不设置（不擦除）
烧录新字幕	SubtitleConfig	配置对象 / 不设置（不烧录）

---

阶段 3：确认输出路径（非阻塞）

条件	处理方式
用户明确指定	使用用户指定的路径
用户未指定	使用默认路径并告知用户

默认输出规则：

• Bucket：与输入视频相同
• 目录：与输入视频相同
• 文件名：{source}_translated_{random8}.mp4
• 示例：oss://bucket/videos/demo.mp4 → oss://bucket/videos/demo_translated_a1b2c3d4.mp4

不要使用 shell 变量，使用 Python：python3 -c "import random; print(''.join(random.choices('abcdefghijkmnpqrstuvwxyz23456789', k=8)))"

---

阶段 4：确认字幕审核（有条件阻塞）

触发条件	处理方式
用户选择审核字幕	阻塞，必须等待用户确认审核结果
用户不需要审核	非阻塞，继续执行

关键：提取字幕后，必须原样输出内容供用户审核，不要更改格式！

---

场景入口选择器

要点：

1. 用户输入本地视频时，必须先上传到 OSS 并获取 HTTP URL。
2. 用户未提供字幕时，必须询问是否需要提取和审核字幕。

User inputs video
    │
    ├─ Local video?
    │   └─ Yes → AskUserQuestion: "Please provide OSS upload path"
    │       ├─ User provides path → Upload to OSS → Convert to HTTP URL → Continue
    │       └─ User does not provide → STOP
    │
    ├─ oss:// format?
    │   └─ Yes → Inform user to convert to HTTP URL format
    │
    └─ HTTP URL format? → Continue
        │
        ├─ User provides SRT file?
        │   ├─ Yes → Input type = with_subtitle
        │   │   ├─ Translation mode = speech → 【Scenario 4】 ⚠️ MUST ask CustomSrtType
        │   │   └─ Translation mode = subtitle → 【Scenario 3】
        │   │
        │   └─ No → Input type = only_video ⚠️ MUST ask if review needed
        │       │
        │       ├─ AskUserQuestion: "Do you need to extract subtitles for review first, or translate directly?"
        │       │
        │       ├─ Need review → 【Scenario 2】 ⚠️ Phase 4 blocking
        │       │
        │       └─ Direct translation → 【Scenario 1】 (TextSource=OCR_ASR)

场景	名称	阻塞点	TextSource	流程
0	本地视频上传	询问 OSS 上传路径	-	上传→HTTP URL→后续场景
1	直接翻译	阶段 1、2	OCR_ASR	直接提交翻译
2	字幕审核	阶段 1、2、询问字幕审核、阶段 4	SubtitleFile	提取字幕→审核→翻译
3	字幕翻译 + 用户字幕	阶段 1、2	SubtitleFile	使用用户提供的 SRT 直接翻译
4	语音翻译 + 用户字幕	阶段 1、2 + 确认 CustomSrtType	SubtitleFile	确认字幕语言后翻译

场景 0（本地视频）详细流程：

1. AskUserQuestion：“请提供 OSS 上传路径（格式：oss:////.mp4）”
2. 用户指定路径后，执行 aliyun oss cp <local_path> <oss_path>
3. 转换为 HTTP URL：https://<bucket>.oss-<region>.aliyuncs.com/<path>/<filename>.mp4
4. 继续执行后续场景流程

场景 2 详细流程：

1. 询问字幕检测区域（roi 参数）
2. 调用 CaptionExtraction 提取字幕，输入和输出均使用 oss:// 格式
3. 原样输出字幕内容供用户审核
4. 用户确认后，使用审核通过的 SRT 提交翻译

---

参数决策表

决策规则：明确每个参数的处理方式，切勿随意假设！

参数	触发条件	处理方式	默认值	禁止行为
NeedSpeechTranslate	始终	必须询问	无	切勿根据输入推断
NeedFaceTranslate	始终	固定值	false	切勿设为 true
DetextArea	用户选择擦除	必须询问	无	切勿随意设为 Auto
SubtitleConfig	用户选择烧录	可使用默认值	标准样式	切勿跳过确认
TextSource	由场景决定	遵循场景规则	参见场景映射	切勿随意选择
CustomSrtType	场景 4	必须询问	无	切勿随意推断
OutputConfig.MediaURL	输出路径	可使用默认值	默认规则	切勿使用 shell 变量
JobParams.roi	字幕提取	必须询问	[[0.5,1],[0,1]]	切勿随意设为默认值
SourceLanguage	用户指定或可推断	可使用默认值	自动检测	仅中文使用 zh
TargetLanguage	用户指定	可使用默认值	en	其他语言需询问

TextSource 场景映射：

场景	值	说明
1	OCR_ASR	自动检测字幕
2	SubtitleFile	审核通过的 SRT
3、4	SubtitleFile	用户提供的 SRT

CustomSrtType 触发规则：

条件	值
CaptionExtraction 已提取	SourceSrt
用户提供字幕（场景 4）	必须询问：SourceSrt / TargetSrt

---

失败保护机制

硬性限制：语音翻译失败后，切勿自动切换为字幕翻译！

API 错误处理

ErrorCode	处理操作
Forbidden.SubscriptionRequired	参见 ram-policies.md
InvalidParameter	参见 api-parameters.md
InputConfig.Subtitle is invalid	参见 troubleshooting.md
JobFailed	记录 JobId，并询问用户是否需要重试

SRT 格式修复流程

Detect empty subtitle entries → Delete empty entries → Renumber → Upload repaired file → Inform user

详情请参见 troubleshooting.md。

---

CLI 命令模板

重要：提交 API 前，必须参考 api-parameters.md 确认参数格式！

详情请参阅 cli-commands.md。

核心命令：

# Register media asset
aliyun ice register-media-info --input-url "oss://<bucket>/<object>" --media-type video --user-agent AlibabaCloud-Agent-Skills

# Submit subtitle extraction (use OSS path)
aliyun ice submit-iproduction-job \
  --function-name CaptionExtraction \
  --input "Media=oss://<bucket>/<object> Type=OSS" \
  --biz-output "Media=oss://<bucket>/<output>.srt Type=OSS" \
  --job-params '{"lang":"ch","roi":[[0.5,1],[0,1]]}' \
  --force \
  --user-agent AlibabaCloud-Agent-Skills

# Submit video translation
aliyun ice submit-video-translation-job \
  --user-agent AlibabaCloud-Agent-Skills

CLI 格式要点：

• 字幕提取使用命令名称 submit-iproduction-job（小写，以 - 分隔）
• --input 和 --biz-output 格式：以空格分隔的字符串 "Media=... Type=OSS"，而非 JSON
• --job-params 格式：JSON 字符串
• 必须添加 --force 以跳过插件参数验证
• 所有 ICE 命令都必须添加 --user-agent AlibabaCloud-Agent-Skills

---

文档参考

文档	内容
workflow-details.md	4 种场景的详细执行流程
cli-commands.md	CLI 命令模板库
troubleshooting.md	错误处理详情
api-parameters.md	完整的 API 参数文档
ram-policies.md	RAM 权限要求
cli-installation-guide.md	CLI 安装指南

---

关键约束

• 提交 API 前，必须参考 api-parameters.md 确认参数格式
• 所有 ICE CLI 命令都必须添加 --user-agent AlibabaCloud-Agent-Skills
• 字幕提取（SubmitIProductionJob）使用 oss:// 格式
• 视频翻译（SubmitVideoTranslationJob）使用 HTTP URL 格式，无需签名
• 本地视频必须先上传到 OSS，用户必须提供上传路径
• NeedFaceTranslate 必须为 false
• SpeechTranslate 和 SubtitleTranslate 不能同时使用
• InputConfig.Subtitle 必须使用 HTTPS 格式，不得使用 oss://
• 语音翻译 + SRT 输入需要 SpeechTranslate.CustomSrtType
• 不要根据输入类型推断翻译模式

---

任务轮询

强制要求：必须持续轮询任务状态，直到任务完成（State=Finished）或失败（State=Failed），不得提前退出！

任务类型	查询命令	间隔	超时
字幕提取	QueryIProductionJob	30 秒	5 分钟
视频翻译	get-smart-handle-job	30 秒	30 分钟

轮询逻辑：

Loop polling until:
  - State == "Finished" → Return result
  - State == "Failed" → Report error
  - Exceeds 30 minutes → Report TimeoutError

Prohibited: Return after single query / Skip polling and return JobId directly

时间参考（3 分钟视频）：

• 字幕级翻译：3-5 分钟
• 语音级翻译：10-20 分钟

---

结果获取

# Get media asset info
aliyun ice get-media-info --media-id "<MediaId>"

# Generate signed URL (for private Bucket)
aliyun oss sign oss://<bucket>/<object> --timeout 3600

---

文档结束