Video Translation (HeyGen) 用于将已有视频翻译并配音成多种语言，保留唇形同步和自然的语音特征。该工具通过 HeyGen API 工作，用户提供视频 URL 或 HeyGen 视频 ID 即可，无需先在 HeyGen 平台上创建视频。
【用途】 将现有视频翻译成另一种语言，或对视频内容进行配音。典型场景包括多语言内容分发、视频本地化、访谈或产品演示视频的翻译等。
【鉴权】 所有请求都需要 X-Api-Key 请求头，通过环境变量 HEYGEN_API_KEY 设置。
示例：
curl -X POST "https://api.heygen.com/v2/video_translate"
-H "X-Api-Key: $HEYGEN_API_KEY"
-H "Content-Type: application/json"
-d '{"video_url": "https://example.com/video.mp4", "output_language": "es-ES"}'
【默认工作流】
- 提供视频 URL 或 HeyGen 视频 ID
- 调用 POST /v2/video_translate 并指定目标语言
- 轮询 GET /v2/video_translate/{translate_id} 直到状态为 completed
- 从返回的 URL 下载翻译后的视频
【创建翻译任务】 请求字段：
- video_url（string）：要翻译的视频 URL（与 video_id 二选一）
- video_id（string）：HeyGen 视频 ID（与 video_url 二选一）
- output_language（string，必填）：目标语言代码，如 "es-ES"
- title（string）：翻译后视频的名称
- translate_audio_only（boolean）：仅音频、无唇形同步（更快）
- speaker_num（number）：视频中说话人数量
- callback_id（string）：用于 webhook 跟踪的自定义 ID
- callback_url（string）：完成通知的 URL
video_url 或 video_id 必须至少提供一个。
请求示例见文档中的 curl、TypeScript 与 Python 代码（包含 VideoTranslateRequest、VideoTranslateResponse 接口定义及 translateVideo / translate_video 函数）。
【支持的输出语言】 英语（美国）en-US（默认源语言）、西班牙语（西班牙）es-ES、西班牙语（墨西哥）es-MX、法语 fr-FR、德语 de-DE、意大利语 it-IT、葡萄牙语（巴西）pt-BR、日语 ja-JP、韩语 ko-KR、中文（普通话）zh-CN、印地语 hi-IN、阿拉伯语 ar-SA。
【翻译选项】
- 基础翻译（含唇形同步）
- 仅音频翻译（更快、无唇形同步）
- 多说话人视频（设置 speaker_num）
【v4 API 高级选项】 接口 VideoTranslateV4Request 支持：
- input_video_id、google_url
- output_languages（string[]，一次调用输出多种语言）
- name（必填）
- srt_key（自定义 SRT 字幕）
- instruction、vocabulary（需保留原样的术语）、brand_voice_id
- speaker_num、keep_the_same_format、input_language
- enable_video_stretching、disable_music_track、enable_speech_enhancement
- srt_role（"input" | "output"）、translate_audio_only
示例涵盖多语言输出、自定义术语表、自定义 SRT 字幕等配置。
【检查翻译状态】 调用 GET /v2/video_translate/{translate_id}，返回状态包括 pending、processing、completed、failed，以及 video_url、message。文档给出了 TypeScript 的 TranslateStatusResponse 接口与 getTranslateStatus 函数。
【轮询完成】 翻译耗时比标准视频生成更长，最多允许 30 分钟。文档提供了 waitForTranslation 函数（默认 maxWaitMs 1800000、pollIntervalMs 30000），在 completed 时返回 video_url，在 failed 时抛出错误。
【完整工作流与批量翻译】 文档提供了 translateAndDownload 函数串联创建任务与轮询，以及 translateToMultipleLanguages 函数并行翻译到多种语言并汇总结果。
【特性】
- 唇形同步：自动调整说话人的嘴唇动作以匹配翻译后的音频
- 声音克隆：翻译后的音频匹配原说话人的声音特征
- 音乐轨控制：可通过 disable_music_track: true 移除背景音乐
- 语音增强：可通过 enable_speech_enhancement: true 提升音频质量
【最佳实践】
- 源视频质量影响结果，建议使用高质量源视频
- 音频清晰、语音清楚的视频翻译效果更好
- 单说话人内容效果最佳
- 语速过快可能影响质量
- 建议先用较短的片段测试，再翻译长视频
- 预留额外时间：翻译耗时较长（最多 30 分钟）
【错误处理】 文档提供了 safeTranslate 函数示例，针对错误信息中分别包含 quota、duration、format 的情况，可分别识别为额度不足、视频过长、不支持的视频格式，其余错误返回原始信息。具体错误码与配额限制暂未提供。
【限制】 关于具体价格、计费额度、并发限制、支持的视频格式与时长上限、平台可用性等信息，资料中暂未提供。