OpenMontage 中的 HeyGen 音色体系音色枚举、语速音调调节与 SSML 停顿实战指南【免费下载链接】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本篇技术指南围绕 OpenMontage 仓库内 avatar-video 技能体系.claude/skills/avatar-video/中的 HeyGen 音色Voices参考文档展开系统讲解如何通过GET /v2/voices拉取音色清单、解读响应字段、按语言/性别/特性筛选音色以及在POST /v2/video/generate生成数字人视频时如何配置语速speed、音调pitch与break停顿标签并附带仓库源码级的 HeyGen 集成佐证。读完你将掌握一套从选音色到配置语音参数再到多语言/多场景视频的完整实战方案。一、音色在 HeyGen 数字人视频中的角色HeyGen 提供了覆盖多种语言、口音与风格的 AI 音色Voice。音色的核心作用是把你的文本脚本input_text转换为自然流畅的语音并与数字人Avatar的口型、表情联动最终渲染成完整的讲解视频。在 OpenMontage 的 avatar-video 技能默认工作流中音色选取位于第二步见 SKILL.md列出数字人—GET /v2/avatars预览并记下avatar_id与default_voice_id见 avatars.md列出音色如需要—GET /v2/voices选择与数字人性别、语言匹配的音色即本文主题编写脚本— 每个场景一个核心概念见 scripts.md生成视频—POST /v2/video/generate按场景配置数字人、音色、脚本与背景见 video-generation.md轮询完成状态—GET /v2/videos/{video_id}直到completed。所有请求都需要在请求头携带X-Api-Key即设置HEYGEN_API_KEY环境变量。OpenMontage 的工具层同样以该环境变量作为可用性开关在 heygen_video.py 中install_instructions明确指出需要set HEYGEN_API_KEYyour_key_here并在 get_status() 中通过os.environ.get(HEYGEN_API_KEY)判断工具是否可用。二、拉取可用音色清单2.1 curl 方式curl -X GET https://api.heygen.com/v2/voices \ -H X-Api-Key: $HEYGEN_API_KEY2.2 TypeScript 方式interface Voice { voice_id: string; name: string; language: string; gender: male | female; preview_audio: string; support_pause: boolean; emotion_support: boolean; } interface VoicesResponse { error: null | string; data: { voices: Voice[]; }; } async function listVoices(): PromiseVoice[] { const response await fetch(https://api.heygen.com/v2/voices, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! }, }); const json: VoicesResponse await response.json(); if (json.error) { throw new Error(json.error); } return json.data.voices; }2.3 Python 方式import requests import os def list_voices() - list: response requests.get( https://api.heygen.com/v2/voices, headers{X-Api-Key: os.environ[HEYGEN_API_KEY]} ) data response.json() if data.get(error): raise Exception(data[error]) return data[data][voices]提示在 OpenMontage 的 avatar-video 技能中若环境提供了 HeyGen MCP 工具mcp__heygen__*应优先使用 MCP 工具而非直接 HTTP 调用——MCP 工具会自动处理鉴权与请求格式化。而音色/数字人的列表操作按 SKILL.md 的说明通常走直接 API 调用。三、响应格式与字段解读GET /v2/voices返回的 JSON 结构如下{ error: null, data: { voices: [ { voice_id: 1bd001e7e50f421d891986aad5158bc8, name: Sara, language: English, gender: female, preview_audio: https://files.heygen.ai/..., support_pause: true, emotion_support: true }, { voice_id: de8b5d78f2e0485f88d1e9f5c8e7f9a6, name: Paul, language: English, gender: male, preview_audio: https://files.heygen.ai/..., support_pause: true, emotion_support: false } ] } }各字段含义与用途字段类型说明voice_idstring音色唯一标识后续生成视频时在voice.voice_id中引用namestring音色名称如 Sara、Paullanguagestring音色所属语言如 English、Spanishgenderstring音色性别male或femalepreview_audiostring音色试听音频的公开 URL可直接在浏览器打开试听support_pauseboolean是否支持break停顿标签emotion_supportboolean是否支持情绪表达适合讲故事、动态内容四、支持的语言与地区HeyGen 支持多语言、多地区音色以下是常用语言与其对应代码LanguageCodeNotesEnglish (US)en-USMultiple voice optionsEnglish (UK)en-GBBritish accentSpanishes-ESSpain SpanishSpanish (Latin)es-MXMexican SpanishFrenchfr-FRFrance FrenchGermande-DEStandard GermanPortuguesept-BRBrazilian PortugueseChinese (Mandarin)zh-CNSimplified ChineseJapaneseja-JPStandard JapaneseKoreanko-KRStandard KoreanItalianit-ITStandard ItalianDutchnl-NLStandard DutchPolishpl-PLStandard PolishArabicar-SASaudi Arabic选择音色时应结合目标受众的地区口音偏好例如面向美国观众使用en-US面向英国观众使用en-GB。五、在视频生成中使用音色POST /v2/video/generate请求中的video_inputs[].voice对象用于配置语音。voice.type支持text文本转语音、audio自定义音频与silence静音三种模式。5.1 基础用法const videoConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Hello! Welcome to our presentation., voice_id: 1bd001e7e50f421d891986aad5158bc8, }, }, ], };5.2 语速调节通过speed字段调整语速1.0为正常语速合法范围为0.5 - 2.0const videoConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: This is spoken at a faster pace., voice_id: 1bd001e7e50f421d891986aad5158bc8, speed: 1.2, // 1.0 is normal, range: 0.5 - 2.0 }, }, ], };5.3 音调调节通过pitch字段调整音调合法范围为-20到20默认0const videoConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: This has a higher pitch., voice_id: 1bd001e7e50f421d891986aad5158bc8, pitch: 10, // Range: -20 to 20 }, }, ], };从 video-generation.md 的 voice 字段表可以进一步确认speed默认值为1.0范围 0.5–2.0pitch默认值为0范围 -20 到 20当type为text时voice_id与input_text必填。六、用 Break 标签控制停顿HeyGen 支持 SSML 风格的break标签可在脚本中插入精确的停顿让 AI 语音更接近真人节奏。6.1 格式break timeXs/其中X为秒数例如1s、1.5s、0.5s。6.2 格式要求RuleExampleUse seconds with s suffixbreak time1.5s/✓Must have space before tagword break time1s/✓Must have space after tagbreak time1s/ word✓Self-closing tagbreak time1s/✓错误示例wordbreak time1s/word标签前后无空格正确示例word break time1s/ word6.3 应用示例// Single pause const script1 Hello and welcome. break time\1s\/ Let me introduce our product.; // Multiple pauses const script2 First point. break time\1.5s\/ Second point. break time\1s\/ Third point.; // Pause at start (dramatic opening) const script3 break time\0.5s\/ Welcome to our presentation.; // Longer pause for emphasis const script4 And the winner is... break time\2s\/ You!;6.4 完整示例停顿 视频生成const scriptWithPauses Welcome to our product demo. break time1s/ Today Ill show you three key features. break time0.5s/ First, lets look at the dashboard. break time1.5s/ As you can see, its incredibly intuitive. ; const videoConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: scriptWithPauses, voice_id: 1bd001e7e50f421d891986aad5158bc8, }, }, ], };6.5 连续 Break 自动合并多个连续的 break 标签会被自动合并为一次总时长的停顿// These two breaks: Hello break time\1s\/ break time\0.5s\/ world // Are treated as a single 1.5s pause6.6 停顿使用最佳实践用于强调— 在重要观点前加入停顿控制时长— 0.5s 到 2s 是典型范围过长的停顿会显得不自然模拟真人呼吸— 在人类自然换气或停顿的位置插入务必试听— 生成后听一遍确认节奏与语感符合预期。注意并非所有音色都支持break标签选择音色时应优先确认其support_pause字段为true见第三节字段表。脚本设计相关的语速估算约 150 词/分钟与标点对朗读节奏的影响可进一步参考 scripts.md。七、使用自定义音频替代 TTS如果不想用文本转语音也可以直接提供自己的音频文件如真人录音、配音成品让数字人跟随该音频对口型const videoConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: audio, audio_url: https://example.com/my-audio.mp3, }, }, ], };当type为audio时audio_url必填且提供音频的公开可访问 URL。八、音色筛选语言、性别与能力特性拿到完整音色列表后通常需要按业务需求筛选。8.1 按语言筛选function filterByLanguage(voices: Voice[], language: string): Voice[] { return voices.filter((v) v.language.toLowerCase().includes(language.toLowerCase()) ); } const englishVoices filterByLanguage(voices, english); const spanishVoices filterByLanguage(voices, spanish);8.2 按性别筛选function filterByGender(voices: Voice[], gender: male | female): Voice[] { return voices.filter((v) v.gender gender); } const femaleVoices filterByGender(voices, female);8.3 按能力特性筛选function filterByFeatures( voices: Voice[], options: { supportPause?: boolean; emotionSupport?: boolean } ): Voice[] { return voices.filter((v) { if (options.supportPause ! undefined v.support_pause ! options.supportPause) { return false; } if (options.emotionSupport ! undefined v.emotion_support ! options.emotionSupport) { return false; } return true; }); } const expressiveVoices filterByFeatures(voices, { emotionSupport: true });九、音色选择辅助函数将上述筛选条件整合为一个findVoice辅助函数一次性完成语言 性别 停顿 情绪的组合筛选interface VoiceSelectionCriteria { language?: string; gender?: male | female; supportPause?: boolean; emotionSupport?: boolean; } async function findVoice(criteria: VoiceSelectionCriteria): PromiseVoice | null { const voices await listVoices(); const filtered voices.filter((v) { if (criteria.language !v.language.toLowerCase().includes(criteria.language.toLowerCase())) { return false; } if (criteria.gender v.gender ! criteria.gender) { return false; } if (criteria.supportPause ! undefined v.support_pause ! criteria.supportPause) { return false; } if (criteria.emotionSupport ! undefined v.emotion_support ! criteria.emotionSupport) { return false; } return true; }); return filtered[0] || null; } // Usage const voice await findVoice({ language: english, gender: female, emotionSupport: true, });十、多语言视频按场景切换音色HeyGen 支持在同一个视频里为不同场景配置不同语言的音色非常适合全球产品发布、本地化营销等场景const multiLanguageConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Hello! Welcome to our global product launch., voice_id: english_voice_id, }, }, { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Hola! Bienvenidos al lanzamiento global de nuestro producto., voice_id: spanish_voice_id, }, }, ], };video_inputs数组中每个元素即一个场景可分别指定character、voice与background背景详见 video-generation.md。十一、音色与数字人的匹配音色与数字人匹配的质量直接影响成片观感核心原则是保证性别一致、语言一致。11.1 推荐做法使用数字人的默认音色许多数字人带有预先匹配好的default_voice_id官方文档将其视为最佳做法——它保证了性别匹配、口型自然、无需手动配对且经过 HeyGen 的组合测试。// Using v2 API to get avatar with default voice const response await fetch( https://api.heygen.com/v2/avatar_group.list?include_publictrue, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! } } ); const { data } await response.json(); // Find avatar with a default voice const avatar data.avatar_group_list.find((a: any) a.default_voice_id); if (avatar) { const videoConfig { video_inputs: [{ character: { type: avatar, avatar_id: avatar.id }, voice: { type: text, input_text: script, voice_id: avatar.default_voice_id, // Pre-matched voice }, }], }; }数字人的完整列表与default_voice_id获取方式详见 avatars.md。11.2 兜底方案手动按性别匹配如果数字人没有默认音色则手动按性别匹配音色interface AvatarVoicePair { avatarId: string; voiceId: string; gender: male | female; } async function findMatchingAvatarAndVoice( preferredGender?: male | female ): PromiseAvatarVoicePair { const [avatars, voices] await Promise.all([ listAvatars(), listVoices(), ]); // Default to male if no preference const gender preferredGender || male; // Find avatar with matching gender const avatar avatars.find((a) a.gender gender); if (!avatar) { throw new Error(No ${gender} avatar available); } // Find voice with matching gender AND language const voice voices.find( (v) v.gender gender v.language.toLowerCase().includes(english) ); if (!voice) { throw new Error(No ${gender} English voice available); } return { avatarId: avatar.avatar_id, voiceId: voice.voice_id, gender, }; }十二、音色使用最佳实践清单音色性别与数字人匹配— 男声配男性数字人女声配女性数字人音色与内容匹配— 商务内容使用专业感的音色试听音色— 选定前务必播放preview_audio试听考虑地区口音— 音色口音与目标受众所在地区匹配自然语速— 为清晰度调整语速通常控制在 0.9–1.1x善用停顿— 用 SSML break 让语音节奏更自然验证可用性— 使用前始终确认voice_id真实存在调用列表接口核对。十三、仓库源码佐证OpenMontage 中的 HeyGen 集成在 OpenMontage 中HeyGen 的能力被封装为两层技能层skill与工具层tool。13.1 技能层avatar-video 与 heygen本文所依据的音色参考文档是 avatar-video 技能的核心参考之一.claude/skills/avatar-video/references/voices.md同时该技能下还配套了 avatars.md数字人、scripts.md脚本、video-generation.md视频生成等参考文件仓库内另有一份内容相同的音色参考.claude/skills/heygen/references/voices.md供 heygen 技能使用。技能元数据声明了运行前提环境变量HEYGEN_API_KEY见 SKILL.md 的metadata.openclaw.requires。13.2 工具层heygen_video 与共享实现heygen_video.py 定义了HeyGenVideo工具类provider heygen能力为video_generation运行时为 API 模式其 install_instructions 明确提示设置HEYGEN_API_KEYget_status() 在未配置密钥时返回UNAVAILABLE。该工具关注的是 HeyGen 聚合的云端视频生成VEO、Sora、Kling、Runway、Seedance 等 provider 变体定义于 HEYGEN_PROVIDERS与本文的 v2 音色 API 属于 HeyGen 能力的不同面向。_shared.py 中的 poll_heygen() 展示了仓库对 HeyGen 异步任务的轮询实现默认 600 秒超时、起始间隔 5 秒并呈指数退避最大 30 秒状态为completed时提取video_urlfailed/error时抛出异常。这一轮询模式与技能文档中生成视频后轮询直到 completed的建议见 video-status.md相互印证。13.3 认证约定无论技能层还是工具层HeyGen 均使用X-Api-Key请求头进行认证密钥通过HEYGEN_API_KEY环境变量注入。开发调试阶段建议利用test: true测试模式输出带水印、不消耗额度验证配置再切换到正式模式。十四、小结音色是 HeyGen 数字人视频的声线本文从音色枚举curl/TypeScript/Python、响应字段、语言表、speed/pitch 调节、break停顿、自定义音频、筛选与辅助函数、多语言场景到音色与数字人的默认/兜底匹配策略完整覆盖了 voices.md 的核心内容并结合 OpenMontage 的 SKILL.md、heygen_video.py 与 _shared.py 提供了源码级佐证。实际落地时建议始终遵循先列数字人、再选音色、写脚本、生成、轮询的五步工作流并把验证 voice_id、试听 preview_audio、使用默认音色作为质量红线。【免费下载链接】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），仅供参考