用 HeyGen 把已有视频翻译配音成多语言（保留原讲者形象…

当你已有一段成片视频，想让它由同一位讲者用另一种语言「原生」讲述时，用 HeyGen Video Translation 做翻译、配音、口型同步与字幕。

适用场景

解决思路

1. 会话开始时静默选定一种传输方式，全程不混用、不切换、不向用户说明：优先 OpenClaw 插件模式（若 video_generate 暴露 HeyGen 翻译模型）；否则若环境变量 HEYGEN_API_KEY 存在且 `heygen --version` 退出码为 0，用 CLI 模式；否则若可见 `mcp__heygen__*` 工具，用 MCP 模式（OAuth）；否则若 `heygen --version` 退出码为 0，用 CLI 回退模式；都没有则告知用户连接 HeyGen MCP 服务器或安装 CLI：`curl -fsSL https://static.heygen.ai/cli/install.sh | bash` 然后 `heygen auth login`。
2. 进入 Phase 1 前先验证鉴权：MCP 模式由 OAuth 处理无需检查；CLI 模式静默运行 `heygen auth status`，退出码为 0 则继续，非 0 则向用户索要 API key（https://app.heygen.com/settings?nav=API），用 `echo "<key>" | heygen auth login` 持久化到 `~/.heygen/credentials`，再 `heygen auth status` 验证，仍失败则报错停止。
3. 硬性规则：绝不调用 `curl api.heygen.com/...`；MCP 模式只用 `mcp__heygen__*` 工具（翻译未暴露时回退到 CLI）；CLI 模式只用 `heygen ...` 命令，用 `--help` 和 `--request-schema` 发现参数。
4. Phase 1 只问缺失的信息，用用户的语言交流，绝不表单化，每轮最多 1–2 个问题。必问：源视频（公开 URL、本地文件路径或已有 asset_id）；目标语言（开放式提问，不给选择器，让用户自由输入）。
5. 按需询问：讲者人数（默认单人，多人内容必问，人数错误是质量头号杀手）；内容类型（通常从视频推断并确认）；字幕偏好（口播/企业默认开，播客/纯音频默认关，若翻转默认需在 Phase 4 简短说明）；时长灵活性（问「翻译后视频是否必须与原片等长，还是可略长略短」，默认推荐 `enable_dynamic_duration: true`，仅在需要帧级精确时设 false）。
6. 可选询问：术语表/不翻译词（企业或技术内容，用于 proofread 阶段指导）；局部翻译（用户提到片段时记录 `start_time` 和 `end_time` 秒数）；是否在最终渲染前校对字幕（默认关；长视频 >3 分钟、企业品牌内容、法律/医疗/教育高风险、用户母语可读时默认开）。
7. Phase 2 静默执行三项检查。检查 2a 语言校验：MCP 用 `list_video_translation_languages()`，CLI 用 `heygen video-translate languages list | jq -r '.data.languages[]'`，将用户输入与规范字符串（如 "Spanish (Spain)"、"Chinese (Mandarin, Simplified)"、"Arabic (Saudi Arabia)"）大小写不敏感匹配；"Spanish" 默认 "Spanish (Spain)" 并在 Phase 4 确认，"Chinese" 默认 "Chinese (Mandarin, Simplified)"，区域变体做映射（如 "Mexican Spanish" → "Spanish (Mexico)"），无匹配则让用户从最接近选项中选择。
8. 检查 2b 源视频路由：公开 HTTPS URL（无鉴权、HEAD 返回视频 MIME）直接作为 `{type: "url", url: "..."}`；鉴权墙/403/404/HTML 响应则告知用户并索要公开 URL 或本地文件；本地文件用 `heygen asset create --file <path>`（CLI）或 `upload_asset`（MCP）上传（最大 32 MB），用返回的 `asset_id` 作为 `{type: "asset_id", asset_id: "..."}`；已有 HeyGen asset_id 直接传入。
9. 检查 2c 内容画像：口播/讲者（默认）用 `mode: precision`、`enable_speech_enhancement: true`、`enable_caption: true`、`enable_dynamic_duration: true`、`keep_the_same_format: true`；播客/纯音频用 `mode: precision`、`translate_audio_only: true`、`enable_speech_enhancement: true`、`enable_caption: true`；音乐/强配乐用 `mode: precision`、`disable_music_track: true`、`enable_speech_enhancement: true`、`enable_dynamic_duration: true`、`keep_the_same_format: true`；多讲者用口播默认值加 `speaker_num: <count>`（必填不可猜）；企业/品牌用口播默认值加 `brand_voice_id`（若有），并强烈考虑 proofreads。
10. 始终：除非用户明确要求「快」，用 `mode: "precision"`；`enable_dynamic_duration` 按 Phase 1 回答设置，默认 `true`，仅在用户明确需要固定长度时设 `false`；视觉翻译用 `keep_the_same_format: true` 保留源分辨率与码率；`enable_watermark: false`（默认）。
11. Phase 3 静默提交与轮询，仅在每种语言完成、每种语言硬失败、或超过 5 分钟进度检查时发声。标准路径（校对关）：用批量语法按目标语言逐个提交任务，MCP 用 `create_video_translation(video={type, url|asset_id}, output_languages=[...], mode="precision", enable_speech_enhancement=true, enable_caption=true, enable_dynamic_duration=true, keep_the_same_format=true, speaker_num=<n>)`；CLI 用 `heygen video-translate create -d '{"video":{"type":"url","url":"https://..."},"output_languages":["Spanish (Spain)","Japanese (Japan)"]}' --mode precision --enable-speech-enhancement --enable-caption --enable-dynamic-duration --keep-the-same-format --speaker-num 1 --title "<short title>"`，响应每种语言返回一个 `video_translation_id`，全部记录。
12. 轮询：单语言时在 `create` 上加 `--wait` 阻塞至完成；批量时去掉 `--wait` 并逐个轮询 `heygen video-translate get <video-translation-id>`（返回 `{ data: { status: "pending"|"running"|"completed"|"failed", video_url, ... } }`）；节奏为前 3 分钟每 30 秒一次，之后每 60 秒一次；多数 5–15 分钟完成，长视频或批量可能 30+ 分钟；每个翻译硬超时 60 分钟，超过视为卡住并上报。
13. 校对路径（校对开）：`heygen video-translate proofreads create -d '{"video":{"type":"url","url":"https://..."}}' --output-languages "Spanish (Spain)" --mode precision --enable-speech-enhancement --keep-the-same-format --speaker-num 1 --title "<short fileNAME-safe title>"` 创建会话（返回每种语言一个 proofread_id，短时 3–5 分钟）；用 `heygen video-translate proofreads get <proofread-id>` 轮询至 completed 或 failed；用 `heygen video-translate proofreads srt get <proofread-id> > /tmp/srt-resp.json` 获取预签名 URL，`SRT_URL=$(jq -r '.data.srt_url' /tmp/srt-resp.json)`（目标语言，编辑此文件）、`ORIG_URL=$(jq -r '.data.original_srt_url' /tmp/srt-resp.json)`（源语言转录），`curl -s "$SRT_URL" -o /tmp/proofread.srt` 下载。
14. 编辑 `/tmp/proofread.srt`（手工或 sed）修正术语、语域、人名；用 `ASSET_ID=$(heygen asset create --file /tmp/proofread.srt | jq -r '.data.asset_id')` 上传编辑后的 SRT 作为资产（`heygen asset create` 接受 png、jpeg、mp4、webm、mp3、wav、pdf、srt），再 `heygen video-translate proofreads srt update <proofread-id> -d "{\"srt\":{\"type\":\"asset_id\",\"asset_id\":\"$ASSET_ID\"}}"`（回退方案：托管到公开 URL 并用 `{"type":"url","url":"..."}`）；用 `heygen video-translate proofreads generate <proofread-id> --captions` 启动最终渲染（返回 `video_translation_id`）；用 `heygen video-translate get <vid-id>` 轮询翻译至完成（不是 `proofreads get`），`data.video_url` 为最终 mp4。
15. Phase 4 交付：每种完成语言发一条消息，格式如「✅ Spanish (Spain) — <video_url>\n1m 47s, precision mode, captions on.」；失败语言用一行简短说明原因，不主动倾倒重试选项；批量多语言时每完成一个就交付一个，不要等全部完成。
16. 源质量免责声明：翻译无法超越源片。若源片音频闷、快切、面部遮挡严重或分辨率低，口型与音质会退化；在 Phase 2 检测到（或用户提及时）就提前警告，不要在坏结果出现后才说。
17. CLI 模式下每次任务交付后（或中途遇到摩擦时）运行一次 `heygen feedback --rating <1-5> --comment "<what worked, or what broke and what you tried>"`：`--rating` 5=很好、3=有摩擦、1=坏了/不可用；`--comment` 写 bug、过时文档、缺失参数或令人困惑的行为及触发命令。匿名、无需 API key，分析退出时（`HEYGEN_NO_ANALYTICS` 或 `heygen config set analytics false`）自动 no-op；仅 CLI 模式，MCP 或 OpenClaw 插件模式跳过。
18. 讲者人数是质量头号杀手：口播为 1 人；访谈/播客/圆桌要精确计数不可猜，引擎按 `speaker_num` 分离声音，人数错误会导致配音中声音串讲者；用户不确定时让其拖动视频数一数。
19. 提交前做源质量分诊（Phase 2 花 30 秒省 10–30 分钟坏翻译）：看/听源片前约 10 秒，检查音频（语音清晰？背景音乐主导？噪声/嘶声？语音不清则 `enable_speech_enhancement: true`，音乐主导则 `disable_music_track: true`，两者都有则警告质量可能仍偏低）、面部可见性（是否大部分时间在镜头前、正面、光照良好？遮挡、侧脸、快切、低于 720p 都会限制口型质量）、屏幕文字（源语言硬字幕不会被重渲染，会保留在配音输出中；若用户要新语言字幕会有两条字幕轨，建议 `enable_caption: true` 并警告已有硬字幕）。
20. 处理语言对陷阱：音调压缩/膨胀（en→zh、en→ja、en→ko 约短 30%；de→en、ja→en 更长；en→ar/he 通常膨胀），动态时长对这些语言对尤其重要，用户选固定长度时要警告质量下降；语域（ja-JP 敬语、ko-KR 敬语、de-DE Sie vs du、th-TH 皇家/礼貌/随意、id-ID 正式 vs 口语）引擎默认中性正式，源片口语化且用户要匹配语域时在 proofread 中标注或预先警告；RTL 语言（阿拉伯语、希伯来语、乌尔都语、波斯语）字幕右到左，硬字幕可能与源片下三分之一图形碰撞，源片有下三分之一文字或图形时建议纯音频翻译或 proofread 时审查字幕样式；区域变体重要（Spanish (Spain) vs Spanish (Mexico) vs Spanish (Argentina) 词汇、语调、语速差异明显，拉美观众常觉得卡斯蒂利亚西班牙语是外语；葡萄牙语 Portugal vs Brazil、法语 France vs Canada vs Switzerland、阿拉伯语 19 个区域变体同理）；中文特例（"Chinese (Mandarin, Simplified)" 是大陆标准默认，"Chinese (Cantonese, Traditional)" 用于香港/海外粤语社群，"Chinese (Taiwanese Mandarin, Traditional)" 用于台湾，不可互换）。
21. 口型同步上限：稳定正面镜头、面部 ≥720p、干净光照良好、少剪切（长镜头更好）时最佳；侧脸、低头、部分遮挡、快切（<2s 镜头）、低光、运动模糊、低分辨率面部、面部快速移动的大幅手势时退化。源片有这些情况时在 Phase 1/2 警告：「源片有 [X]，口型不会像静态口播那样紧。要继续，还是改用纯音频翻译？」
22. 字幕：`enable_caption: true` 默认把字幕烧进视频（优点：无需单独文件、随处可播；缺点：后续不可编辑、可能与源图形碰撞、字体样式固定）。高风险内容用户可能想重设字幕样式（品牌套件、语言特定字体）时，优先用 proofreads 工作流，它给出可用作 sidecar 字幕文件的 SRT。
23. 纯音频翻译：`translate_audio_only: true` 完全跳过口型同步，用于播客（「视频」是静态图或波形）、之后要重新合成到别的视频的音频、或口型不可能的情况（无面部、源面部质量极差）。输出是音频文件（通常 MP3），告知用户用法：「这是翻译后的音轨，可在剪辑器中合成回原视频，或独立使用。」不要把纯音频当作坏口型的「质量变通」来推销，它是另一种交付物。
24. 成本与时间意识：翻译按源视频时长计费，5 分钟视频翻 5 种语言 = 25 计费分钟。用户批量请求时在 Phase 1 说明时间与成本预期：「5 种语言 × 5 分钟 = 约 25 分钟翻译时间，每个渲染 10–20 分钟。可以吗？」不要报美元数字（价格变动、因套餐而异），只报源分钟数 × 语言数加诚实的渲染时间范围。
25. 失败模式解码：`400` "video URL not accessible" 多为 URL 需鉴权、返回 HTML 或 MIME 错误，索要公开 URL 或本地文件走上传路由；`400` "language not supported" 为字符串未匹配规范语言列表，重跑 `languages list` 并给出最接近匹配；`failed` 且 "audio extraction" 为源片无可听语音、音频严重损坏或编解码错误，确认源片有语音或考虑重编码；`failed` 且 "speaker detection" 为 `speaker_num` 与实际讲者不符或音频太吵，用正确讲者数或 `enable_speech_enhancement: true` 重提；`running` 卡住 >30 分钟为后端队列或偶发停滞，检查状态，给满 60 分钟再上报用户；输出口型差为源面部条件（见口型上限），调整预期或提供纯音频替代；字幕方向错误为 RTL 语言硬字幕与源布局碰撞，改用 proofread + sidecar SRT。
26. 首次用户检测：信号包括问「支持哪些语言？」、不了解口型同步 vs 纯音频、从未用过 HeyGen（无头像、`heygen video-translate list` 无历史翻译）。对首次用户建议先用 30–60 秒测试片段再投入完整视频，可在不消耗长视频翻译的情况下发现源质量问题、音色克隆保真度和口型上限。
27. 路线图（仅被问及时提及）：品牌术语表/不翻译词列表目前通过 proofread 工作流回退自动翻译术语实现，`brand_voice_id` 用于跨翻译的音色一致性而非术语表；自定义 SRT 输入通过 `create` 的 `srt` 字段（企业版）或 `proofreads srt update`（任意套餐），`srt_role: "input"` 把你的字幕应用到源语言，`output` 应用到目标语言字幕；局部翻译用 `start_time`/`end_time` 秒数；多语言批量已支持，向 `--output-languages`（CLI）或 `output_languages` 数组（MCP）传多个值，每种语言返回一个任务 ID；Webhook 回调用 `--callback-url` 和 `--callback-id` 完全跳过轮询，有 webhook 端点且想要事件驱动完成时使用。
28. 最佳实践速记：除非用户明确要求速度否则始终 precision 模式；非显然情况始终确认讲者人数；提交前用规范列表校验语言字符串；对新用户建议短测试片段；源质量是上限，提前说而非事后说；不要过度配置，五种内容画像覆盖约 95% 情况；翻译需要时间，设定 5–30 分钟预期；匹配语域，源片口语化且目标为强语域语言（ja、ko、th、de）时用 proofread；长视频、企业内容、用户母语可读时默认开 proofread；绝不向用户说明传输方式，MCP vs CLI 是内部细节。

适用边界 · 注意事项

• 用户想从零创建新视频（尚无源视频）时——改用 heygen-video 并用目标语言写脚本，heygen-translate 只用于本地化已有源视频。
• 需要创建头像时——改用 heygen-avatar。
• 只需 TTS 合成时——改用 heygen-video 的纯音频输出。
• 只需纯文本翻译时——不适用本技能。