heygen-translate

HeyGen 视频翻译

将现有视频翻译并配音成 175+ 种语言。系统会将演讲者的声音克隆成目标语言，将其嘴唇重新同步到新的音频，并返回完整配音的视频。你只需提供源视频和目标语言——引擎会处理转录、翻译、语音克隆、口型同步，以及（可选的）烧录字幕。

这不是新视频生成。原视频中的演讲者、表现、构图和品牌素材都会保留。翻译会叠加在现有内容上。

面向用户的行为

1. 简明扼要。 不要在聊天中罗列翻译 ID、原始 API 负载或状态 JSON。报告结果（视频链接、语言），而不是底层细节。
2. 不要使用内部术语。 不要说“轮询”“video_translation_id”“asset_id”“v3 endpoint”。要说“正在翻译”“快完成了”“你的文件”。
3. 静默轮询。 在后台执行耗时较长的翻译，只在（a）交付结果，（b）停滞超过 5 分钟（更新一次），或（c）发生严重错误时发言。
4. 一个结果，一条消息。 视频完成后，发送链接和一行摘要（目标语言、时长、模式）。不要列出每个 API 字段。
5. 不要说明所用传输方式。 MCP、CLI 和 OpenClaw 插件的选择属于内部事务。在会话开始时静默选择，绝不提及当前使用的是哪一种。
6. 使用用户的语言沟通。 根据用户的第一条消息判断语言。回复、确认和提问都使用该语言。技术 CLI/API 指令保持英文。

API 模式检测

在会话开始时选择一种传输方式。绝不混用、中途切换或说明选择。

按以下顺序检测：

1. OpenClaw 插件模式 — 如果在 OpenClaw 内运行，且 video_generate 工具提供 HeyGen 翻译模型，则优先使用该模式。目前插件可以生成视频，但不直接提供翻译功能——在 HeyGen 通过 video_generate 提供翻译之前，继续尝试下一级。
2. CLI 模式（API 密钥覆盖） — 如果环境中设置了 HEYGEN_API_KEY，且 heygen --version 退出代码为 0，则使用 CLI。存在 API 密钥明确表示用户希望直接访问 API。
3. MCP 模式 — 未设置 HEYGEN_API_KEY，且能看到 HeyGen MCP 工具（mcp__heygen__*）。使用 OAuth 身份验证，并消耗用户套餐中的额度。
4. CLI 模式（回退） — MCP 工具不可用，且 heygen --version 退出代码为 0。通过 heygen auth login 进行身份验证。
5. 两者均不可用 — 只告知用户一次：“要使用此技能，请连接 HeyGen MCP 服务或安装 HeyGen CLI：curl -fsSL https://static.heygen.ai/cli/install.sh | bash，然后运行 heygen auth login。”

Auth 验证（在任何 API 调用之前运行）

检测模式后，在进入 Phase 1 之前，先验证 auth 是否确实可用。这样可以避免花时间收集用户输入，却在提交时遇到 auth 错误。

• MCP 模式： auth 由 OAuth 处理，无需检查。
• CLI 模式： 运行 heygen auth status（静默）。如果退出码为 0，则继续。如果退出码非 0（无密钥、已过期、无效）：
  1. 询问用户：“我需要你的 HeyGen API 密钥才能继续。你可以从 https://app.heygen.com/settings?nav=API 获取，然后粘贴到这里。”
  2. 用户提供密钥后，将其持久化：echo "<key>" | heygen auth login（写入 ~/.heygen/credentials，并在不同会话间保留）。
  3. 验证：heygen auth status。如果仍然失败，则显示错误并停止。

这是一次性设置。heygen auth login 持久化密钥后，后续会话会自动读取。如果 heygen auth status 通过，则不要再次询问。

硬性规则：

• 绝不要调用 curl api.heygen.com/... 此技能中的每项操作都有对应的 CLI 命令，以及（在支持的情况下）MCP 工具。请使用这些工具。
• MCP 模式：只能使用 mcp__heygen__* 工具。 如果 MCP 尚未提供翻译功能，则仅针对翻译操作改用 CLI。不要自行构造原始 HTTP 调用。
• CLI 模式：只能使用 heygen ... 命令。 运行 heygen video-translate --help 和 heygen video-translate <subcommand> --help 以了解参数。使用 --request-schema 查看任何 create 命令的完整 JSON 结构。
• 以下操作同时列出了 MCP 和 CLI 的用法——只阅读与你检测到的模式对应的列。

MCP 工具名称（仅限 MCP 模式）

create_video_translation（单语言）。多语言和校对功能尚未通过 MCP 提供——这些操作改用 CLI。在会话开始时运行 mcp__heygen__* 工具列表，确认当前可用的工具；工具范围可能会变化。

CLI 命令组（仅限 CLI 模式）

heygen video-translate
├── languages list              # supported target languages
├── create                      # submit a translation job (single or batch)
├── get <id>                    # check status / fetch result
├── list                        # list past translations
├── update                      # update job metadata
├── delete                      # delete a job
└── proofreads
    ├── create                  # extract editable subtitles before final render
    ├── get <id>                # check proofread session status
    ├── srt get <id>            # download the extracted SRT
    ├── srt update <id>         # upload edited SRT
    └── generate <id>           # render the final video from approved SRT
heygen asset create --file <path>   # for local source video uploads (max 32 MB)

每条命令都支持 --help。对任何 create 命令使用 --request-schema 查看完整的 JSON 请求体。CLI 输出：标准输出为 JSON；标准错误为 {error:{code,message,hint}} 信封；退出码：0 成功 · 1 API · 2 用法 · 3 auth · 4 超时。在 create 命令中添加 --wait，可等待任务完成（默认超时时间为 20m）。

📖 CLI/MCP 错误 → 操作的详细对应关系 → references/troubleshooting.md

---

默认工作流

此技能分为四个阶段。Phase 1（发现）是唯一需要提问的阶段。Phase 2（提交前检查）保持静默。Phase 3（提交 + 轮询）保持静默。Phase 4（交付）只需发送一条简短消息。

Phase 1 — Discovery       — gather minimum needed inputs from the user
Phase 2 — Pre-flight      — validate language, classify content, set flags
Phase 3 — Submit + Poll   — kick off, background poll, surface only on done/fail
Phase 4 — Deliver         — post the result with one-line summary

阶段 1 — 信息收集

只询问你尚未掌握的信息。使用用户的语言沟通。绝不要运行表单。 每轮最多问一到两个问题。

必需信息（收集齐全前不得继续）：

1. 源视频。 公开 URL、本地文件路径，或上一步生成的 HeyGen asset_id。如果用户尚未提供，请询问：“源视频是什么？可以是 URL、文件路径，或现有的 HeyGen 素材。”
2. 目标语言。 使用用户的语言，以开放式问题询问：“你想将视频翻译成哪种语言？” 不要提供选择列表或预设选项——让用户自由填写。他们可能需要一种或多种语言，或特定地区的变体。接受用户提供的内容，并在阶段 2 根据标准语言列表进行验证。

重要信息（未提供时询问，并采用合理默认值）：

3. 说话人数。 默认一位说话者，也是大多数用户的情况。人数不明确时询问一次：“视频中有几位不同的说话者？” 说话人数错误是导致质量下降的头号原因——说话者混淆会导致翻译过程中声音互换。多人内容不要跳过此问题。
4. 内容类型。 通常无需询问——根据视频推断并确认。以下五种类型涵盖约 95% 的情况。只有确实无法判断时才询问。
5. 字幕偏好。 对于出镜讲话和企业内容，默认开启；对于播客／仅音频内容，默认关闭。如果更改默认设置，请在阶段 4 简要说明。
6. 时长是否可调整。 询问：“翻译后的视频需要与原视频时长完全一致，还是可以稍长或稍短？允许调整通常会让效果更自然——翻译后的语音有足够时间以舒适的语速说完，而不必加速或压缩。” 默认建议：允许调整（enable_dynamic_duration: true）。只有用户需要逐帧精确的时间（例如与时间线、广告时段或外部音轨同步）时，才设为 false。

可选信息（仅在相关时询问）：

7. 术语表／不翻译的词语。 对于企业或技术内容，询问：“有没有需要保留原文的产品名称、公司名称或术语？” HeyGen 目前不支持强制术语表，因此当准确性要求较高时，这些信息将作为校对步骤（阶段 3-校对）的参考。
8. 部分翻译。 如果用户提到具体片段（“只翻译片头”“从 1:30 到 4:00”），请以秒为单位记录 start_time 和 end_time。
9. 最终渲染前是否校对？ 默认关闭（更快、所需审批更少）。以下情况默认开启：长视频（超过 3 分钟）、企业／品牌内容、高风险的法律／医疗／教育内容，以及用户能够母语阅读的语言（便于他们核对）。询问：“要在最终渲染前检查并编辑字幕吗？大约需要多花 5 分钟，但可以修正术语错误。”

📖 语言区域组合注意事项（正式程度、从右向左语言、声调压缩、口型同步上限）→ references/language-locale-guide.md

阶段 2 — 预检

静默进行。不向用户展示闲聊内容。按顺序执行三项检查。

检查 2a：语言验证。

MCP： list_video_translation_languages()（如果已提供）。否则使用命令行。 命令行： heygen video-translate languages list | jq -r '.data.languages[]'

列表包含精确字符串（"Spanish (Spain)"、"Chinese (Mandarin, Simplified)"、"Arabic (Saudi Arabia)"）。将用户输入与这些精确字符串进行不区分大小写的匹配。如果用户说“Spanish”，默认选择“Spanish (Spain)”，并在阶段 4 确认。如果用户说“Chinese”，默认选择“Chinese (Mandarin, Simplified)”。如果用户指定了地区（“Mexican Spanish”），则映射为“Spanish (Mexico)”。如果没有匹配项：请用户从最接近的选项中选择。

检查 2b：源视频路由。

用户提供的源	路由
公共 HTTPS URL（无需身份验证，且在 HEAD 请求中返回视频 MIME 类型）	直接作为 {type: "url", url: "..."} 传入
有身份验证限制的 URL、403、404 或 HTML 响应	告知用户，并请其提供公共 URL 或本地文件
本地文件路径	使用 heygen asset create --file <path>（命令行）或 upload_asset（MCP）上传。最大 32 MB。将返回的 asset_id 用作 {type: "asset_id", asset_id: "..."}
现有 HeyGen asset_id	直接作为 {type: "asset_id", asset_id: "..."} 传入

📖 资源路由边缘情况（超大文件、预签名 URL、有身份验证限制的来源）→ references/asset-routing.md

检查 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。强烈建议此配置使用校对。

始终遵循：

• 除非用户明确要求“fast”/“quick”/“speed”，否则使用 mode: "precision"。
• enable_dynamic_duration：根据用户在阶段 1 对时长灵活性问题的回答设置。默认值为 true（推荐）——让译制语音自然舒展，而不是硬塞进源视频的精确时长。只有用户明确需要固定时长输出时才设为 false。音调压缩使灵活调整尤为重要，适用于 en→zh、en→ja、en→ko（亚洲语言时长更短）；de→en、ja→en（时长更长）；ar/he/ur（从右向左书写 + 语域变化）。
• 对于视觉内容翻译，设置 keep_the_same_format: true——保留源视频的分辨率和比特率，使配音视频与原视频的编码相匹配。
• enable_watermark: false（默认值）。

阶段 3 — 提交 + 轮询

静默进行。后台处理。仅在以下情况向用户反馈：(a) 每种语言处理完成；(b) 每种语言发生严重失败；(c) 超过 5 分钟时进行进度检查。

分支：

• 标准路径（proofread = OFF）：提交翻译，后台轮询，交付。
• 校对路径（proofread = ON）：创建校对会话 → 下载 SRT → 用户编辑或由你协助编辑 → 上传已编辑的 SRT → 生成最终版本 → 后台轮询 → 交付。

标准路径

使用批处理语法为每种目标语言提交一个任务（--output-languages 接受多个语言）。

MCP （撰写本文时仅支持单种语言）：

create_video_translation(
  video={type, url|asset_id},
  output_languages=["Spanish (Spain)"],
  mode="precision",
  enable_speech_enhancement=true,
  enable_caption=true,
  enable_dynamic_duration=true,
  keep_the_same_format=true,
  speaker_num=<n>,           # only when known multi-speaker
)

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。请记录所有 ID。

轮询（静默、在后台运行）：

仅处理一种语言时，使用 create 上的 --wait 等待任务完成。批处理时，去掉 --wait 并轮询每个 ID：

# CLI mode polling (background)
heygen video-translate get <video-translation-id>
# Returns { data: { status: "pending"|"running"|"completed"|"failed", video_url, ... } }

轮询频率：前 3 分钟每 30 秒一次，之后每 60 秒一次。大多数翻译会在 5–15 分钟内完成；有些情况（视频较长、批量处理多种语言）需要 30 分钟以上。每项翻译的硬性超时为 60 分钟——超过此时限后，请视为卡住并反馈问题。

MCP 对应方法： get_video_translation(id)（如果已提供）。否则，请改用 CLI 进行轮询。

📖 后台轮询模式（不要在前台轮询／特定于执行框架的说明）→ references/troubleshooting.md#polling

校对路径

对于高风险内容，请先进行校对会话，让用户在引擎生成最终渲染结果前审核／编辑翻译后的字幕。

# 1. Create proofread session — returns proofread_ids (one per language)
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>"
# → status: processing  (3–5 min for short videos)

# 2. Poll until completed (or failed + failure_message)
heygen video-translate proofreads get <proofread-id>
# → status: completed

# 3. Fetch presigned URLs for editable + original SRTs
heygen video-translate proofreads srt get <proofread-id> > /tmp/srt-resp.json
SRT_URL=$(jq -r '.data.srt_url'          /tmp/srt-resp.json)  # target-lang, edit this
ORIG_URL=$(jq -r '.data.original_srt_url' /tmp/srt-resp.json) # source-lang transcript
curl -s "$SRT_URL" -o /tmp/proofread.srt

# 4. Edit /tmp/proofread.srt by hand or sed (glossary, register, names)
#    See references/proofreads-workflow.md for the full edit playbook.

# 5. Upload the edited SRT as an asset, then reference it by asset_id.
#    `heygen asset create` accepts srt (png, jpeg, mp4, webm, mp3, wav, pdf, srt).
#    Fallback: host at a public URL and use {"type":"url","url":"..."}.
ASSET_ID=$(heygen asset create --file /tmp/proofread.srt | jq -r '.data.asset_id')
heygen video-translate proofreads srt update <proofread-id> \
  -d "{\"srt\":{\"type\":\"asset_id\",\"asset_id\":\"$ASSET_ID\"}}"

# 6. Kick off final render — returns a video_translation_id
heygen video-translate proofreads generate <proofread-id> --captions
# → {"data":{"video_translation_id":"<vid-id>","status":"processing"}}

# 7. Poll the translation to completion (NOT proofreads get — graduates here)
heygen video-translate get <vid-id>
# → status: running → completed; data.video_url has the final mp4

📖 何时要求校对、常见 SRT 编辑、术语表规范 → references/proofreads-workflow.md

第 4 阶段 — 交付

每种已完成的语言发送一条消息。格式：

✅ 西班牙语（西班牙）— <video_url> 1 分 47 秒，精准模式，已开启字幕。

如果某种语言失败：用一行简短说明原因（参见故障排查参考）。除非用户提出要求，否则不要向用户罗列重试选项。如果用户批量处理了多种语言，请在每种语言完成时分别交付——不要等到全部完成后才开始发送。

源素材质量免责声明。 翻译无法改善源素材。如果源素材存在音频模糊、镜头切换过快、面部严重遮挡或分辨率较低等情况，口型同步和语音质量都会下降。在第 2 阶段发现这些情况（或用户提及）时，请提前告知。不要等到结果不理想后才说明。

反馈报告（CLI 模式）

交付翻译后——或者过程中遇到阻碍时——每项任务运行一次：

heygen feedback --rating <1-5> --comment "<what worked, or what broke and what you tried>"

• --rating：5 = 效果很好 · 3 = 遇到阻碍但完成了 · 1 = 失败／无法使用。
• --comment：填写任何 Bug、过时文档、缺失标志或令人困惑的行为，并说明触发问题的命令或流程。

此操作匿名、无需 API 密钥，并且在用户选择退出分析（HEYGEN_NO_ANALYTICS 或 heygen config set analytics false）时不会执行。这是 CLI 团队主要的信号渠道——如果任务静默完成，他们就无法获得任何反馈。**仅限 CLI 模式：**在 MCP 或 OpenClaw 插件模式下跳过此操作（这些模式通过 MCP／插件界面处理，而该界面没有反馈命令）。

---

内置专业知识

以上默认设置涵盖了常见情况。以下决策体现了这项技能与通用 API 封装工具的区别。请在工作流中将其作为判断依据，而不是照本宣科的检查清单。

说话人数是影响质量的头号因素

对于访谈式视频：1 位说话者。对于采访／播客／圆桌讨论：准确统计人数，不要猜测。引擎通过 speaker_num 区分声音；人数错误会导致配音输出中的声音串到其他说话者身上。如果用户不确定，请让他们拖动视频进度条并统计人数。

源质量分诊（提交前执行）

在第 2 阶段花 30 秒进行分诊，可节省 10–30 分钟的无效翻译工作。观看/收听源内容的前约 10 秒，并检查：

• **音频：**语音是否清晰？背景音乐是否过于突出？是否有噪声/嘶声？→ 如果语音不清晰，默认设置 enable_speech_enhancement: true。如果音乐过于突出，设置 disable_music_track: true。如果两者都有，请提醒用户：无论使用什么标志，质量都可能较低。
• **面部可见度：**说话者的大部分时间是否面向镜头、正面出镜且光线充足？→ 严重遮挡（太阳镜、手挡在脸上）、仅有侧脸镜头、镜头切换过快或人脸分辨率低于 720p，都会限制唇形同步质量。
• **屏幕文字：**源视频中是否带有内嵌字幕？→ 这些字幕不会重新渲染。在配音输出中，它们仍会保留源语言。如果用户想要新语言的字幕，他们会有两条字幕轨道——建议设置 enable_caption: true，并提醒用户注意已有的内嵌字幕。

语言区域组合注意事项

• 时长压缩/扩展。 en→zh、en→ja、en→ko 通常会缩短约 30%；de→en、ja→en 会变长；en→ar/he 通常会扩展。动态时长（第 1 阶段的时长灵活性问题）对这些组合尤其重要——如果不开启，en→zh 听起来会不自然地变慢（为了适应比实际长 30% 的时间线，语音会被挤压）。如果用户选择固定时长输出，请提醒他们，高压缩率的语言组合会导致质量下降。
• 正式程度/语体。 ja-JP（敬语/keigo）、ko-KR（敬语）、de-DE（Sie 与 du 的区别）、th-TH（皇室用语/礼貌/随意）、id-ID（正式与口语）——引擎默认选择中性正式的语体。如果源内容较为口语化，而用户希望目标语言匹配其语体，请在校对时标记，或提前提醒用户，译文听起来会比原文略正式。
• 从右向左书写的语言。 阿拉伯语、希伯来语、乌尔都语、波斯语——字幕会从右向左渲染。内嵌字幕可能会与源视频画面下方的字幕条图形在不该出现的一侧发生重叠。如果源视频下方有屏幕文字或图形，建议仅进行音频翻译，或在校对时检查字幕样式。
• 地区变体很重要。 西班牙（西班牙）语、西班牙（墨西哥）语和西班牙（阿根廷）语在词汇、语调和语速方面都有明显差异。拉丁美洲受众常会觉得卡斯蒂利亚西班牙语很陌生。默认采用用户指定的受众地区；如果未指定西班牙语的地区，请询问一次。葡萄牙语（葡萄牙与巴西）、法语（法国、加拿大与瑞士）和阿拉伯语（有 19 种地区变体）也同样如此。
• **特别说明普通话。**对于中国大陆受众，“Chinese (Mandarin, Simplified)”是标准默认选项。香港/海外粤语社群适用“Chinese (Cantonese, Traditional)”。台湾适用“Chinese (Taiwanese Mandarin, Traditional)”。这些选项不可互换。

📖 完整的语言区域组合表（含语体说明和已知差异）→ references/language-locale-guide.md

唇形同步效果上限

唇形同步在以下情况下效果最佳：

• 稳定的正面镜头
• 人脸分辨率 ≥720p
• 面部清晰且光线充足
• 镜头切换较少（长镜头效果更好）

唇形同步在以下情况下效果会下降：

• 侧脸镜头、低头镜头、面部部分遮挡
• 快速剪辑（镜头时长 <2s）
• 光线昏暗、运动模糊或人脸分辨率较低
• 频繁做大幅手势，导致面部快速移动

如果用户的源视频存在这些情况，请在第 1/2 阶段提醒他们：“提醒一下——源视频中有 [X]，所以唇形同步效果不会像固定机位的对话镜头那么贴合。您仍想继续吗？还是改为仅进行音频翻译？”

字幕：内嵌字幕与外挂字幕

enable_caption: true 默认会在视频中生成内嵌字幕。优点：无需单独文件，任何地方都能播放。缺点：之后无法编辑，可能会与源视频图形重叠，字体/样式固定。对于用户可能想重新设置字幕样式（品牌套件、特定语言字体）的重要内容，建议采用校对工作流——该工作流会提供 SRT 文件，可用作外挂字幕文件。

仅音频翻译

translate_audio_only: true 会完全跳过口型同步。适用于：

• 播客（“视频”是静态图像或波形）
• 之后要重新合成到其他视频中的音频
• 任何无法进行口型同步的情况（没有人脸，或源视频中的人脸质量很差）

输出为音频文件（通常为 MP3）。请告知用户如何使用：“这会生成一条翻译后的音轨。你可以在编辑器中将它重新合成到原视频上，也可以单独使用。”不要把仅音频翻译宣传为糟糕口型同步的“质量补救方案”——它是另一种交付内容。

费用与时间说明

翻译费用按源视频时长计算。将一段 5 分钟的视频翻译成 5 种语言 = 25 分钟的计费时长。用户请求批量翻译时，应在阶段 1 说明时间和费用预期：“5 种语言 × 5 分钟 = 约 25 分钟的翻译时间。每种语言的渲染需要 10–20 分钟。这样可以吗？”

不要报具体金额（价格会变动，并且因套餐而异）。请说明源视频分钟数 × 语言数量，以及诚实的渲染时间范围。

故障模式解读

常见错误响应 → 通俗易懂的原因 → 下一步操作：

症状	可能原因	解决方法
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 语言的内嵌字幕与源视频布局冲突	改用校对 + 单独的 SRT 字幕文件

📖 完整的错误 → 操作对照表，包括身份验证和资源上传错误 → references/troubleshooting.md

---

首次使用用户检测

表明用户不熟悉 HeyGen 翻译的迹象：

• 询问“支持哪些语言？”
• 不知道口型同步和仅音频翻译的区别
• 从未使用过 HeyGen（没有头像，也没有在 heygen video-translate list 中查到以往的翻译记录）

对于首次使用的用户，建议先测试一段 30–60 秒的短片段，再决定是否处理完整视频。这样可以在翻译长视频之前，发现源视频质量问题、语音克隆还原度和口型同步上限。

源视频质量免责声明（交付时逐字使用）

当源视频质量处于临界水平时：

“提醒一下——源视频存在[音频模糊／光线昏暗／切换过快／背景音乐过强／等]问题。翻译引擎无法改善源视频质量，因此配音可能也会受这些问题影响。要继续吗？也可以先修复源视频，或先用短片段进行测试。”

不要等到效果不佳后才提出此事。应在阶段 2 提出。

第 2 阶段 / 路线图（仅在被问及时提及）

目前通过 proofreads 工作流支持度最高，但尚未提供一等标志：

• 品牌术语表 / 不翻译列表。 在校对时通过还原 SRT 中自动翻译的术语来注入。brand_voice_id 标志用于保持不同翻译的声音一致性，而非术语表。
• 自定义 SRT 输入。 create 中的 srt 字段支持此功能（Enterprise 计划），也可通过 proofreads srt update 用于任何计划。使用 srt_role: "input" 可将你自己的字幕应用于源语言；使用 output 可将其应用为目标语言字幕。
• 部分翻译。 使用以秒为单位的 start_time / end_time。适用于“只翻译 2:00–4:00 这两分钟”。
• 多语言批处理。 已支持——向 --output-languages（CLI）传入多个值，或向 output_languages 数组（MCP）传入多个值。每种语言会返回一个任务 ID。
• Webhook 回调。 --callback-url 和 --callback-id 可完全跳过轮询。若你有 Webhook 端点并希望以事件驱动的方式完成任务，可使用此功能。

最佳实践（简版）

1. 始终使用精确模式，除非用户明确要求提速。
2. 对于不明显的情况，始终确认说话人数。
3. 提交前，根据规范列表验证语言字符串。
4. 建议新用户使用短测试片段。
5. 源内容的质量决定上限——要提前说明，而不是事后再说。
6. 不要过度配置——五种内容配置可覆盖约 95% 的情况。
7. 翻译需要时间——预计需要 5–30 分钟。
8. 匹配语体——如果源内容较口语化，而目标语言对语体要求较高（ja、ko、th、de），请进行校对。
9. 以下情况默认开启校对：长视频、企业内容、用户母语所属语言。
10. 切勿描述传输方式。 MCP 与 CLI 属于内部细节。