OpenMontage 视频翻译指南基于 HeyGen /v2/video_translate 的多语言配音与口型同步实战【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage导读视频翻译Video Translation是指将一段已有视频翻译成目标语言并尽可能保留说话者的口型同步Lip-Sync与音色特征。在 OpenMontage 开源项目AGENTS.md中.claude/skills/video-translate/SKILL.md将这一能力封装为可供 Claude 等 AI Agent 调用的技能只需提供视频 URL 或 HeyGen 视频 ID即可调用 HeyGen 的/v2/video_translate接口完成翻译、配音、口型同步甚至一键产出多语言版本。读完本文你将掌握创建翻译任务、轮询状态、批量翻译、自定义 SRT 与词汇表、以及错误处理与最佳实践的完整实战方案。技能定位与触发条件.claude/skills/video-translate/SKILL.md的 front-matter 定义了该技能的元信息name: video-translate description: | Translate and dub existing videos into multiple languages using HeyGen. Use when: (1) Translating a video into another language, (2) Dubbing video content with lip-sync, (3) Creating multi-language versions of existing videos, (4) Audio-only translation without lip-sync, (5) Working with HeyGens /v2/video_translate endpoint. allowed-tools: mcp__heygen__* metadata: openclaw: requires: env: - HEYGEN_API_KEY primaryEnv: HEYGEN_API_KEYallowed-tools: mcp__heygen__*该技能只允许通过 MCPModel Context Protocol调用 HeyGen 工具Agent 在触发该技能后不应调用其他提供商的接口触发场景被明确定义为五类翻译已有视频、带口型同步的配音、为已有视频创建多语言版本、仅音频翻译不做口型同步、以及直接对接/v2/video_translate端点。在 OpenMontage 整体架构中该技能属于“AI Video (HeyGen)”技能族。skills/INDEX.md的技能索引中heygen一族聚合了heygen、avatar-video、create-video、ai-video-gen、video-translate等技能供生产管线按需装载。身份认证所有请求都需要在 HTTP 头中携带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}在 OpenMontage 仓库中HeyGen 工具链统一以HEYGEN_API_KEY作为准入开关。例如 heygen_video.py 的install_instructions明确要求先设置该环境变量密钥可在 HeyGen 控制台的 API 设置页获取其get_status()方法只有在环境中存在该变量时才返回ToolStatus.AVAILABLE否则该工具直接不可用。同样视频翻译技能的 SKILL.md 在 front-matter 中声明primaryEnv: HEYGEN_API_KEY即该技能唯一必须的环境变量。默认工作流视频翻译的默认流程只有四步比“先生成视频再翻译”的传统路径省去了中间环节——你不需要在 HeyGen 上先创建视频提供视频 URL 或 HeyGen 视频 ID调用POST /v2/video_translate提交目标语言轮询GET /v2/video_translate/{translate_id}直到状态变为completed从返回的 URL 下载翻译后的视频。需要特别说明的是翻译任务的耗时比普通视频生成更长文档建议预留最多 30 分钟maxWaitMs 1800000轮询间隔pollIntervalMs 30000。创建翻译任务请求字段总览字段类型必填说明video_urlstringY*待翻译视频的 URL与video_id二选一video_idstringY*HeyGen 视频 ID与video_url二选一output_languagestringY目标语言代码如es-EStitlestring翻译后视频的名称translate_audio_onlyboolean仅翻译音频、不做口型同步更快speaker_numnumber视频中的说话人数callback_idstring用于 Webhook 追踪的自定义 IDcallback_urlstring完成通知回调地址video_url与video_id必须提供其一。其中callback_id/callback_url适合在异步流水线中启用 Webhook 通知避免持续轮询speaker_num用于多人对话场景帮助模型区分不同说话人详见下文“多说话人视频”。curl 示例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/original-video.mp4, output_language: es-ES, title: Spanish Version }TypeScript 示例interface VideoTranslateRequest { video_url?: string; video_id?: string; output_language: string; title?: string; translate_audio_only?: boolean; speaker_num?: number; callback_id?: string; callback_url?: string; } interface VideoTranslateResponse { error: null | string; data: { video_translate_id: string; }; } async function translateVideo(config: VideoTranslateRequest): Promisestring { const response await fetch(https://api.heygen.com/v2/video_translate, { method: POST, headers: { X-Api-Key: process.env.HEYGEN_API_KEY!, Content-Type: application/json, }, body: JSON.stringify(config), }); const json: VideoTranslateResponse await response.json(); if (json.error) { throw new Error(json.error); } return json.data.video_translate_id; }Python 示例import requests import os def translate_video(config: dict) - str: response requests.post( https://api.heygen.com/v2/video_translate, headers{ X-Api-Key: os.environ[HEYGEN_API_KEY], Content-Type: application/json }, jsonconfig ) data response.json() if data.get(error): raise Exception(data[error]) return data[data][video_translate_id]支持的语言语言代码备注英语美国en-US默认源语言西班牙语西班牙es-ES欧洲西班牙语西班牙语墨西哥es-MX拉丁美洲法语fr-FR标准法语德语de-DE标准德语意大利语it-IT标准意大利语葡萄牙语巴西pt-BR巴西葡萄牙语日语ja-JP标准日语韩语ko-KR标准韩语中文普通话zh-CN简体中文印地语hi-IN标准印地语阿拉伯语ar-SA现代标准阿拉伯语在 OpenMontage 的本地化配音管线中这些语言代码直接对应生产配置。见 localization-dub.yaml管线描述为“Transcript-first localization pipeline for producing translated subtitles, dubbed audio, and optional lip-synced language variants from an existing source video”其 7 个阶段Idea → Script → Scene → Asset → Edit → Compose → Publish由执行制片人Executive Producer统一编排默认预算 3.00 美元、单阶段最多 3 次修订并在翻译准确度、时间轴保持、逐地区一致性上设置质量门quality gates。翻译选项基础翻译带口型同步默认行为翻译音频并自动调整口型。const config { video_url: https://example.com/original.mp4, output_language: es-ES, title: Spanish Translation, };仅音频翻译更快、无口型同步设置translate_audio_only: true。适合无需出镜说话人的内容如旁白、纪录片解说可显著缩短任务耗时。const config { video_url: https://example.com/original.mp4, output_language: es-ES, translate_audio_only: true, };多说话人视频对访谈、播客、多人讨论类视频用speaker_num告知模型说话人数量以获得更准确的说话人分离与口型匹配const config { video_url: https://example.com/interview.mp4, output_language: fr-FR, speaker_num: 2, };高级选项v4 API当需要更精细的控制时可以使用 v4 版翻译接口。相比 v2v4 支持一次调用产出多语言、自定义 SRT、词汇表、品牌音色、画面格式保持等能力interface VideoTranslateV4Request { input_video_id?: string; google_url?: string; output_languages: string[]; // 一次调用产出多种语言 name: string; srt_key?: string; // 自定义 SRT 字幕 instruction?: string; vocabulary?: string[]; // 原样保留的术语 brand_voice_id?: string; speaker_num?: number; keep_the_same_format?: boolean; input_language?: string; enable_video_stretching?: boolean; disable_music_track?: boolean; enable_speech_enhancement?: boolean; srt_role?: input | output; translate_audio_only?: boolean; }一次产出多语言版本将output_languages传入语言数组一次任务即可生成多语言文件const config { input_video_id: original_video_id, output_languages: [es-ES, fr-FR, de-DE], name: Multi-language translations, };自定义词汇表保留专有名词品牌名、产品名、人名等术语不应被直译。通过vocabulary原样保留const config { video_url: https://example.com/product-demo.mp4, output_language: ja-JP, vocabulary: [SuperWidget, Pro Max, TechCorp], };这与 OpenMontage 本地化配音管线中“术语保留term preservation”的检查点一致——localization-dub.yaml 的 Script 阶段产出物包含“Translated script packaging, term preservation”vocabulary正是把术语约束落实到 API 层的机制。自定义 SRT 字幕翻译既可以把你的 SRT 作为输入srt_role: input指定翻译文本来源也可以把 SRT 作为输出srt_role: output生成目标语言字幕文件const config { video_url: https://example.com/video.mp4, output_language: es-ES, srt_key: path/to/custom-subtitles.srt, srt_role: input, };在 OpenMontage 的 avatar-video 技能字幕参考文档 中视频翻译的字幕集成是被显式设计的srt_key指向自定义 SRTsrt_role决定它是输入还是输出使用 HeyGen 翻译时目标语言的字幕会自动随翻译生成无需额外步骤。查询翻译状态提交任务后用返回的translate_id查询进度curlcurl -X GET https://api.heygen.com/v2/video_translate/{translate_id} \ -H X-Api-Key: $HEYGEN_API_KEYTypeScriptinterface TranslateStatusResponse { error: null | string; data: { id: string; status: pending | processing | completed | failed; video_url?: string; message?: string; }; } async function getTranslateStatus(translateId: string): PromiseTranslateStatusResponse[data] { const response await fetch( https://api.heygen.com/v2/video_translate/${translateId}, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! } } ); const json: TranslateStatusResponse await response.json(); if (json.error) { throw new Error(json.error); } return json.data; }状态机共有四种状态pending排队、processing处理中、completed完成此时video_url可用、failed失败message携带原因。这与 OpenMontage 仓库中 HeyGen 相关工具的实现模式一致——例如 poll_heygen() 用指数退避轮询/v1/workflows/executions/{execution_id}对completed提取output.video.video_url对failed/error抛出带错误信息的异常超时则抛出TimeoutError。翻译任务的时间线最长 30 分钟明显长于普通视频生成该轮询函数默认 600 秒超时因此翻译场景需要更宽的maxWaitMs。轮询直至完成由于翻译耗时可能长达 30 分钟官方技能提供了一段可直接复用的轮询封装async function waitForTranslation( translateId: string, maxWaitMs 1800000, pollIntervalMs 30000 ): Promisestring { const startTime Date.now(); while (Date.now() - startTime maxWaitMs) { const status await getTranslateStatus(translateId); switch (status.status) { case completed: return status.video_url!; case failed: throw new Error(status.message || Translation failed); default: console.log(Status: ${status.status}...); await new Promise((r) setTimeout(r, pollIntervalMs)); } } throw new Error(Translation timed out); }关键参数maxWaitMs 180000030 分钟硬超时、pollIntervalMs 3000030 秒轮询间隔。completed立即返回下载地址failed抛出错误其余状态继续等待超时抛出Translation timed out。完整工作流翻译并下载把提交任务、轮询、拿下载地址串起来即可得到开箱即用的完整流程async function translateAndDownload( videoUrl: string, targetLanguage: string ): Promisestring { console.log(Starting translation to ${targetLanguage}...); const translateId await translateVideo({ video_url: videoUrl, output_language: targetLanguage, }); console.log(Translation ID: ${translateId}); console.log(Processing translation...); const translatedVideoUrl await waitForTranslation(translateId); console.log(Translation complete: ${translatedVideoUrl}); return translatedVideoUrl; } const spanishVideo await translateAndDownload( https://example.com/my-video.mp4, es-ES );拿到translatedVideoUrl后用你熟悉的 HTTP 客户端下载到本地即可完成整条链路。批量翻译对一段源视频同时产出多种语言版本可以并行提交多个翻译任务async function translateToMultipleLanguages( sourceVideoUrl: string, targetLanguages: string[] ): PromiseRecordstring, string { const results: Recordstring, string {}; const translatePromises targetLanguages.map(async (lang) { const translateId await translateVideo({ video_url: sourceVideoUrl, output_language: lang, }); return { lang, translateId }; }); const translationJobs await Promise.all(translatePromises); for (const job of translationJobs) { try { const videoUrl await waitForTranslation(job.translateId); results[job.lang] videoUrl; } catch (error) { results[job.lang] error: ${error.message}; } } return results; } const translations await translateToMultipleLanguages( https://example.com/original.mp4, [es-ES, fr-FR, de-DE, ja-JP] );要点先Promise.all并行提交所有任务提交阶段毫秒级完成再串行等待各自的完成结果单个语言失败不会中断其他语言失败项以error: ...字符串记录在结果字典中。这也是 v4output_languages数组的一次调用方案之外、v2 端点的等效批量路径。核心能力清单技能文档明确列出了翻译链路提供的四项核心能力口型同步Lip Sync——自动调整说话人口型以匹配翻译后的音频音色克隆Voice Cloning——翻译后的音频保持原说话人的音色特征音乐轨道控制Music Track Control——通过disable_music_track: true可选地移除背景音乐语音增强Speech Enhancement——通过enable_speech_enhancement: true提升音频质量。前两项默认生效对应 v2 的基础翻译行为后两项是 v4 接口的显式开关。在本地化配音管线里这些开关组合决定了“配音模式”的选择——OpenMontage 的 Scene 阶段要求明确“Dub-mode selection”即针对每条素材决定是否启用口型同步translate_audio_only、是否保留 BGMdisable_music_track等策略。最佳实践技能文档给出的六条实践经验直接决定了翻译质量的上限源视频质量优先——高质量源视频才能产出高质量翻译结果清晰的音频——语音清晰的视频翻译效果更好单人说话效果最佳——单人说话内容的口型与音色一致性最好适中的语速——语速过快的讲话可能影响翻译质量先小样验证——翻译长视频前先用短视频片段试跑预留充足时间——翻译比视频生成更耗时最长 30 分钟。错误处理翻译是长耗时异步任务错误可能出现在提交、轮询、下载任一环节。技能文档提供了一个容错封装async function safeTranslate( videoUrl: string, targetLanguage: string ): Promise{ success: boolean; result?: string; error?: string } { try { const url await translateAndDownload(videoUrl, targetLanguage); return { success: true, result: url }; } catch (error) { if (error.message.includes(quota)) { return { success: false, error: Insufficient credits }; } if (error.message.includes(duration)) { return { success: false, error: Video too long }; } if (error.message.includes(format)) { return { success: false, error: Unsupported video format }; } return { success: false, error: error.message }; } }错误类型与判别词对应关系错误特征词业务含义建议处理quota账户额度不足提示用户充值/等待额度恢复duration视频超长先裁剪分段再翻译format视频格式不支持用 ffmpeg 转码为常见格式其他未知错误原样上报并重试从 OpenMontage 的工程惯例看这类错误分类与工具层的重试策略互相呼应——heygen_video.py 为 HeyGen 工具定义了RetryPolicy(max_retries2, backoff_seconds10.0, retryable_errors[rate_limit, timeout, server_error])即限流、超时、服务端错误三类会自动重试而配额与格式类错误属于“不可重试”的确定性失败应直接返回给上层。在 OpenMontage 中的完整落地视频翻译技能不是孤立脚本而是 OpenMontage 多语言内容生产体系的最后一公里技能层.claude/skills/video-translate/SKILL.md 是 Agent 可装载的能力描述front-matter 声明了依赖、触发条件和允许工具索引层skills/INDEX.md 将video-translate归入heygen技能族与其他 HeyGen 系技能avatar-video、create-video、video-understand等配套使用工具层tools/video/heygen_video.py 与 tools/video/_shared.py 提供了 HeyGen API 的调用与轮询基础设施poll_heygen、upload_image_heygen等翻译技能可直接复用同样的鉴权与轮询模式管线层localization-dub.yaml 是 v2.0 的“逐字稿优先”本地化配音管线7 个 Director 阶段覆盖从范围定义、翻译脚本、配音模式选择、字幕与配音资产生成、逐地区渲染到发布的全流程并设置翻译准确度、时间轴保持、逐地区一致性质量门。对实际生产而言推荐链路是先用video-understand等技能理解源视频内容再用本技能把成品视频批量翻译为多语言版本最后通过 localization-dub 管线的质量门做逐地区验收。这套组合让“一条源视频 → 全球多语言发行”从手工操作变成可复现的 Agent 工作流。【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考