尧图网站建设 
HeyGen 虚拟主播Avatar选型与生成实战指南OpenMontage 中的预览、样式与视频生成全流程【免费下载链接】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导读HeyGen 的 Avatar虚拟主播是生成式 AI 视频中的数字主持人你可以直接使用 HeyGen 官方提供的公共主播也可以基于自己的训练素材创建定制主播并通过 v2 API 以avatar_id精确指定主播形象配合文本脚本合成说话人视频。本文以 OpenMontage 仓库中.claude/skills/heygen/references/avatars.md为核心骨架系统讲解从列出主播、预览形象、筛选样式、匹配默认语音到生成单场景/多场景视频的完整链路并结合仓库中tools/video/heygen_video.py、tools/video/_shared.py以及avatar-spokesperson流水线给出源码级印证。读完本文你将掌握如何在 OpenMontage 的项目语境下正确挑选 Avatar、规避常见坑并写出可直接落地的curl/ TypeScript / Python 调用代码。HeyGen Avatars 是什么Avatar 是 HeyGen 生成视频中的 AI 数字主持人。OpenMontage 仓库对这类能力有明确的产品化定位在pipeline_defs/avatar-spokesperson.yaml中avatar-spokesperson流水线被描述为Presenter-led avatar pipeline for spokesperson videos, internal updates, onboarding, sales intros, and short scripted explainers即以数字主持人为锚点、辅助图形保持简单的演示人视频。其编排模式为executive-producer执行制片人并在各阶段设置针对口型同步质量、主持人取景、CTA 落地的质量门禁quality gates。在 API 层面Avatar 分为两类公共 AvatarPublic AvatarsHeyGen 提供的公开主播库任何用户都可用私有/定制 AvatarPrivate/Custom Avatars基于你自己的训练素材创建的主播avatar_id通常以custom_前缀标识。仓库的avatar-spokesperson流水线同样把 Avatar 来源视为关键决策点其idea阶段的成功标准要求brief 明确记录 avatar path、narration source 与输出形态并支持heygen_api / sadtalker / musetalk / stock等多种路径见skills/pipelines/avatar-spokesperson/executive-producer.md。生成前先预览保证主播符合用户偏好Always preview avatars before generating a video to ensure they match user preferences.生成前始终先预览主播确保其符合用户偏好。每个 Avatar 都带有可直接在浏览器打开的预览 URL无需下载即可查看。列出并展示主播预览以下 TypeScript 函数列出前 5 个主播并打印其预览地址async function listAndPreviewAvatars(openInBrowser true): Promisevoid { const response await fetch(https://api.heygen.com/v2/avatars, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! }, }); const { data } await response.json(); for (const avatar of data.avatars.slice(0, 5)) { console.log(\n${avatar.avatar_name} (${avatar.gender})); console.log( ID: ${avatar.avatar_id}); console.log( Preview: ${avatar.preview_image_url}); } // Preview URLs can be opened directly in any browser for (const avatar of data.avatars.slice(0, 3)) { console.log(Open in browser: ${avatar.preview_image_url}); } }预览-生成工作流列出可用主播——获取名称、性别与预览 URL向用户展示预览 URL——分享preview_image_url供视觉确认用户按名称或 ID 选择心仪主播获取主播详情得到default_voice_id用选定的主播生成视频。响应中的预览字段字段说明preview_image_url主播静态形象图JPG公开可访问的 URLpreview_video_url展示主播动画效果的短视频片段两个 URL 均为公开可访问地址查看时无需任何鉴权。列出可用主播curl / TypeScript / Pythoncurlcurl -X GET https://api.heygen.com/v2/avatars \ -H X-Api-Key: $HEYGEN_API_KEYTypeScriptinterface Avatar { avatar_id: string; avatar_name: string; gender: male | female; preview_image_url: string; preview_video_url: string; } interface AvatarsResponse { error: null | string; data: { avatars: Avatar[]; talking_photos: TalkingPhoto[]; }; } async function listAvatars(): PromiseAvatar[] { const response await fetch(https://api.heygen.com/v2/avatars, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! }, }); const json: AvatarsResponse await response.json(); if (json.error) { throw new Error(json.error); } return json.data.avatars; }Pythonimport requests import os def list_avatars() - list: response requests.get( https://api.heygen.com/v2/avatars, headers{X-Api-Key: os.environ[HEYGEN_API_KEY]} ) data response.json() if data.get(error): raise Exception(data[error]) return data[data][avatars]响应格式{ error: null, data: { avatars: [ { avatar_id: josh_lite3_20230714, avatar_name: Josh, gender: male, preview_image_url: https://files.heygen.ai/..., preview_video_url: https://files.heygen.ai/... }, { avatar_id: angela_expressive_20231010, avatar_name: Angela, gender: female, preview_image_url: https://files.heygen.ai/..., preview_video_url: https://files.heygen.ai/... } ], talking_photos: [] } }注意响应中还有talking_photos会说话的照片数组它来自 HeyGen 的 Talking Photo 能力与 Avatar 属于不同的演示者形态。在 OpenMontage 中HeyGen 的鉴权方式统一为X-Api-Key请求头仓库工具tools/video/heygen_video.py的get_status()实现即为存在HEYGEN_API_KEY环境变量才标记为可用其install_instructions也明确提示需在 https://app.heygen.com/settings/api 申请密钥。Avatar 类型公共与定制公共 AvatarPublic AvatarsHeyGen 提供任何人都可以使用的公共主播库// List only public avatars const avatars await listAvatars(); const publicAvatars avatars.filter((a) !a.avatar_id.startsWith(custom_));私有/定制 AvatarPrivate/Custom Avatars由你自己的训练素材创建的定制主播const customAvatars avatars.filter((a) a.avatar_id.startsWith(custom_));关键判别规则avatar_id是否以custom_开头是区分定制与公共主播的可靠信号。Avatar 样式Styles与适用场景Avatar 支持不同的渲染样式样式说明normal全身镜头标准取景closeUp面部特写更具表现力circle圆形取景框内的主播说话人头像voice_only仅音频不渲染视频各样式推荐使用场景使用场景推荐样式全屏演示人视频normal个人化/亲密感内容closeUp画中画叠加Picture-in-Picturecircle小尺寸角落小部件circle播客/纯音频内容voice_only动态图形叠加主播normal或closeUp 透明背景在视频配置中使用样式const videoConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, // normal | closeUp | circle | voice_only }, voice: { type: text, input_text: Hello, world!, voice_id: 1bd001e7e50f421d891986aad5158bc8, }, }, ], };Circle 样式用于说话人头像Circle 样式非常适合叠加合成// Circle avatar for picture-in-picture { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: circle, }, voice: { ... }, background: { type: color, value: #00FF00, // Green for chroma key, or use webm endpoint }, }背景指定为纯绿色#00FF00是为了后续抠像chroma key也可以改用 WebM 端点直接输出透明背景。这与 OpenMontage 中透明/抠像视频用于合成的思路一致——仓库提供tools/video/green_screen_processor.py与tools/video/green_screen_composite.py专门处理绿幕合成而 HeyGen 官方技能文档中也特别强调Transparent video for compositing — see video-generation.md (WebM section)见.claude/skills/heygen/SKILL.md。搜索与过滤主播按性别过滤function filterByGender(avatars: Avatar[], gender: male | female): Avatar[] { return avatars.filter((a) a.gender gender); } const maleAvatars filterByGender(avatars, male); const femaleAvatars filterByGender(avatars, female);按名称搜索function searchByName(avatars: Avatar[], query: string): Avatar[] { const lowerQuery query.toLowerCase(); return avatars.filter((a) a.avatar_name.toLowerCase().includes(lowerQuery) ); } const results searchByName(avatars, josh);Avatar 分组Groups主播按组group组织便于管理。列出主播分组curl -X GET https://api.heygen.com/v2/avatar_group.list?include_publictrue \ -H X-Api-Key: $HEYGEN_API_KEY查询参数参数类型默认值说明include_publicboolfalse是否在结果中包含公共主播TypeScriptinterface AvatarGroupItem { id: string; name: string; created_at: number; num_looks: number; preview_image: string; group_type: string; train_status: string; default_voice_id: string | null; } interface AvatarGroupListResponse { error: null | string; data: { avatar_group_list: AvatarGroupItem[]; }; } async function listAvatarGroups( includePublic true ): PromiseAvatarGroupListResponse[data] { const params new URLSearchParams({ include_public: includePublic.toString(), }); const response await fetch( https://api.heygen.com/v2/avatar_group.list?${params}, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! } } ); const json: AvatarGroupListResponse await response.json(); if (json.error) { throw new Error(json.error); } return json.data; }注意AvatarGroupItem中的train_status字段用于表示定制主播组的训练状态default_voice_id可能为null。获取分组内的主播curl -X GET https://api.heygen.com/v2/avatar_group/{group_id}/avatars \ -H X-Api-Key: $HEYGEN_API_KEY在视频生成中使用 Avatar基础用法const videoConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Welcome to our product demo!, voice_id: 1bd001e7e50f421d891986aad5158bc8, }, }, ], dimension: { width: 1920, height: 1080 }, };character.type固定为avataravatar_id指定主播voice.input_text指定要朗读的文本dimension控制画幅1920×1080 为横屏 1080p。多场景使用不同主播const multiSceneConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Hi, Im Josh. Let me introduce my colleague., voice_id: 1bd001e7e50f421d891986aad5158bc8, }, }, { character: { type: avatar, avatar_id: angela_expressive_20231010, avatar_style: normal, }, voice: { type: text, input_text: Hello! Im Angela. Nice to meet you!, voice_id: 2d5b0e6a8c3f47d9a1b2c3d4e5f60718, }, }, ], };video_inputs数组中的每个元素即一个独立场景可分别指定主播、脚本与配合video-generation.md中的背景配置场景背景。这正是 OpenMontage 中精确控制每场景主播/背景的用途——见.claude/skills/heygen/SKILL.md对 v2/video/generate 的定位Exact script without AI modification、Specific voice_id selection、Different avatars/backgrounds per scene、Precise per-scene timing control。使用主播的默认语音Default Voice很多主播带有预匹配的default_voice_id官方推荐直接使用默认语音而不是手动挑选语音。推荐流程1. GET /v2/avatars → Get list of avatar_ids 2. GET /v2/avatar/{id}/details → Get default_voice_id for chosen avatar 3. POST /v2/video/generate → Use avatar_id default_voice_id获取主播详情v2 APIcurl -X GET https://api.heygen.com/v2/avatar/{avatar_id}/details \ -H X-Api-Key: $HEYGEN_API_KEY响应格式{ error: null, data: { type: avatar, id: josh_lite3_20230714, name: Josh, gender: male, preview_image_url: https://files.heygen.ai/..., preview_video_url: https://files.heygen.ai/..., premium: false, is_public: true, default_voice_id: 1bd001e7e50f421d891986aad5158bc8, tags: [AVATAR_IV] } }premium表示是否高级付费主播is_public表示是否公共主播tags携带主播技术标签如AVATAR_IV表示基于 IV 版本模型。TypeScriptinterface AvatarDetails { type: avatar; id: string; name: string; gender: male | female; preview_image_url: string; preview_video_url: string; premium: boolean; is_public: boolean; default_voice_id: string | null; tags: string[]; } async function getAvatarDetails(avatarId: string): PromiseAvatarDetails { const response await fetch( https://api.heygen.com/v2/avatar/${avatarId}/details, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! } } ); const json await response.json(); if (json.error) { throw new Error(json.error); } return json.data; } // Usage: Get default voice for a known avatar const details await getAvatarDetails(josh_lite3_20230714); if (details.default_voice_id) { console.log(Using ${details.name} with default voice: ${details.default_voice_id}); } else { console.log(${details.name} has no default voice, select manually); }完整示例用任意主播的默认语音生成视频async function generateWithAvatarDefaultVoice( avatarId: string, script: string ): Promisestring { // 1. Get avatar details to find default voice const avatar await getAvatarDetails(avatarId); if (!avatar.default_voice_id) { throw new Error(Avatar ${avatar.name} has no default voice); } // 2. Generate video with the avatars default voice const videoId await generateVideo({ video_inputs: [{ character: { type: avatar, avatar_id: avatar.id, avatar_style: normal, }, voice: { type: text, input_text: script, voice_id: avatar.default_voice_id, }, }], dimension: { width: 1920, height: 1080 }, }); return videoId; }为什么使用默认语音性别必然匹配——主播与语音已预先配对自然的唇形同步——默认语音针对该主播做了优化代码更简单——无需单独拉取并匹配语音质量更好——HeyGen 已测试过该组合。如何选对主播类别、指南与避坑主播类别类别示例最佳用途商务/专业Josh, Angela, Wayne企业视频、产品演示、培训休闲/亲和Lily 及各类生活化主播社交媒体、非正式内容主题/季节性节日主题、Cosplay 主播特定营销活动、季节性内容表现力强Expressive名称中含 expressive 的主播有感染力的叙事、动态内容选型指南商务/专业内容选择着装中性商务休闲或正装的主播避免主题性或季节性主播节日服装、休闲服饰生成前预览确认形象专业结合目标受众的画像人口统计特征选择性别与外形。休闲/社交内容主播选择更灵活特定营销活动可使用主题性主播让主播能量与内容基调匹配。常见错误商务内容使用主题性主播——产品演示里出现节日装扮会显得不专业生成前不预览——务必打开预览 URL 核对形象忽略主播样式——circle样式主播不一定适合全屏演示语音性别不匹配——始终使用default_voice_id或手动保证性别一致。生成前自检清单已在浏览器预览主播图片/视频主播形象与内容基调专业 vs 休闲匹配主播样式normal、closeUp、circle适配视频格式语音性别与主播性别匹配可用时使用default_voice_id这套选型纪律在 OpenMontage 的avatar-spokesperson流水线中有对应体现其executive-producer技能强调对唇形同步质量、主持人取景、音频清晰度、CTA 落地把关并明确警告Uncanny valley: If avatar quality is low, it undermines the entire video. Be honest about tool capabilities.若主播质量低会拖垮整条视频要诚实面对工具能力边界——见skills/pipelines/avatar-spokesperson/executive-producer.md。辅助函数与常用主播 ID按 ID 获取主播async function getAvatarById(avatarId: string): PromiseAvatar | null { const avatars await listAvatars(); return avatars.find((a) a.avatar_id avatarId) || null; }校验主播 IDasync function isValidAvatarId(avatarId: string): Promiseboolean { const avatar await getAvatarById(avatarId); return avatar ! null; }随机获取主播async function getRandomAvatar(gender?: male | female): PromiseAvatar { let avatars await listAvatars(); if (gender) { avatars avatars.filter((a) a.gender gender); } const randomIndex Math.floor(Math.random() * avatars.length); return avatars[randomIndex]; }常用公共主播 ID以下为常用公共主播 ID可用性可能随时间变化Avatar ID名称性别josh_lite3_20230714Josh男angela_expressive_20231010Angela女wayne_20240422Wayne男lily_20230614Lily女使用前务必先调用 list 端点核实主播可用性不要硬编码假设其存在。在 OpenMontage 中落地的工程化视角OpenMontage 对 HeyGen 能力的工程封装可以从三个层面佐证上述 API 用法工具层tools/video/heygen_video.py定义HeyGenVideo工具provider heygen通过HEYGEN_API_KEY环境变量鉴权get_status()在未配置密钥时返回UNAVAILABLE并提供fallback到wan_video等本地方案的降级链路实现层tools/video/_shared.py中的generate_heygen_video()调用https://api.heygen.com/v1/workflows/executionsWorkflow APIGenerateVideoNode节点poll_heygen()以 5 秒起步、1.2 倍退避上限 30 秒的轮询策略等待completed状态超时上限 600 秒upload_image_heygen()则优先走v2/assets/upload预签名上传失败时回退到 fal.ai 存储——这与本文讲解的 v2 头像 API 同属 HeyGen 生态可作为如何将主播视频能力接入自动化流水线的参考实现技能层.claude/skills/heygen/SKILL.md声明该技能已弃用并推荐使用avatar-video面向精确主播/场景控制与create-video面向提示词驱动生成两个聚焦技能其中avatar-video的默认工作流第一步就是GET /v2/avatars→ 挑选主播、预览、记录avatar_id与default_voice_id与本文全流程一一对应。值得注意的边界OpenMontage 的HeyGenVideo工具走的是v1/workflows生成管线面向 VEO、Sora、Kling、Runway、Seedance 等视频生成 provider 的provider_variant路由而本文讲解的v2/avatars/v2/video/generate是主播发言人场景的接口两者都是 HeyGen 平台的正式 API选型时应根据目标AI 生成镜头 vs 数字主持人口播决定走哪条链路。参考文件如需深入可直接阅读 OpenMontage 仓库中的以下文档与源码本文主体来源.claude/skills/heygen/references/avatars.md语音列表与音色参数.claude/skills/heygen/references/voices.md视频生成与多场景配置.claude/skills/heygen/references/video-generation.md状态轮询与下载 URL.claude/skills/heygen/references/video-status.md照片转主播.claude/skills/heygen/references/photo-avatars.md聚焦技能 avatar-video.claude/skills/avatar-video/SKILL.mdHeyGen 工具封装tools/video/heygen_video.pyHeyGen 请求实现与轮询逻辑tools/video/_shared.py发言人流水线定义pipeline_defs/avatar-spokesperson.yaml执行制片人技能质量门禁skills/pipelines/avatar-spokesperson/executive-producer.md【免费下载链接】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），仅供参考 HeyGen 虚拟主播（Avatar）选型与生成实战指南：OpenMontage 中的预览、样式与视频生成全流程
HeyGen 虚拟主播Avatar选型与生成实战指南OpenMontage 中的预览、样式与视频生成全流程【免费下载链接】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导读HeyGen 的 Avatar虚拟主播是生成式 AI 视频中的数字主持人你可以直接使用 HeyGen 官方提供的公共主播也可以基于自己的训练素材创建定制主播并通过 v2 API 以avatar_id精确指定主播形象配合文本脚本合成说话人视频。本文以 OpenMontage 仓库中.claude/skills/heygen/references/avatars.md为核心骨架系统讲解从列出主播、预览形象、筛选样式、匹配默认语音到生成单场景/多场景视频的完整链路并结合仓库中tools/video/heygen_video.py、tools/video/_shared.py以及avatar-spokesperson流水线给出源码级印证。读完本文你将掌握如何在 OpenMontage 的项目语境下正确挑选 Avatar、规避常见坑并写出可直接落地的curl/ TypeScript / Python 调用代码。HeyGen Avatars 是什么Avatar 是 HeyGen 生成视频中的 AI 数字主持人。OpenMontage 仓库对这类能力有明确的产品化定位在pipeline_defs/avatar-spokesperson.yaml中avatar-spokesperson流水线被描述为Presenter-led avatar pipeline for spokesperson videos, internal updates, onboarding, sales intros, and short scripted explainers即以数字主持人为锚点、辅助图形保持简单的演示人视频。其编排模式为executive-producer执行制片人并在各阶段设置针对口型同步质量、主持人取景、CTA 落地的质量门禁quality gates。在 API 层面Avatar 分为两类公共 AvatarPublic AvatarsHeyGen 提供的公开主播库任何用户都可用私有/定制 AvatarPrivate/Custom Avatars基于你自己的训练素材创建的主播avatar_id通常以custom_前缀标识。仓库的avatar-spokesperson流水线同样把 Avatar 来源视为关键决策点其idea阶段的成功标准要求brief 明确记录 avatar path、narration source 与输出形态并支持heygen_api / sadtalker / musetalk / stock等多种路径见skills/pipelines/avatar-spokesperson/executive-producer.md。生成前先预览保证主播符合用户偏好Always preview avatars before generating a video to ensure they match user preferences.生成前始终先预览主播确保其符合用户偏好。每个 Avatar 都带有可直接在浏览器打开的预览 URL无需下载即可查看。列出并展示主播预览以下 TypeScript 函数列出前 5 个主播并打印其预览地址async function listAndPreviewAvatars(openInBrowser true): Promisevoid { const response await fetch(https://api.heygen.com/v2/avatars, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! }, }); const { data } await response.json(); for (const avatar of data.avatars.slice(0, 5)) { console.log(\n${avatar.avatar_name} (${avatar.gender})); console.log( ID: ${avatar.avatar_id}); console.log( Preview: ${avatar.preview_image_url}); } // Preview URLs can be opened directly in any browser for (const avatar of data.avatars.slice(0, 3)) { console.log(Open in browser: ${avatar.preview_image_url}); } }预览-生成工作流列出可用主播——获取名称、性别与预览 URL向用户展示预览 URL——分享preview_image_url供视觉确认用户按名称或 ID 选择心仪主播获取主播详情得到default_voice_id用选定的主播生成视频。响应中的预览字段字段说明preview_image_url主播静态形象图JPG公开可访问的 URLpreview_video_url展示主播动画效果的短视频片段两个 URL 均为公开可访问地址查看时无需任何鉴权。列出可用主播curl / TypeScript / Pythoncurlcurl -X GET https://api.heygen.com/v2/avatars \ -H X-Api-Key: $HEYGEN_API_KEYTypeScriptinterface Avatar { avatar_id: string; avatar_name: string; gender: male | female; preview_image_url: string; preview_video_url: string; } interface AvatarsResponse { error: null | string; data: { avatars: Avatar[]; talking_photos: TalkingPhoto[]; }; } async function listAvatars(): PromiseAvatar[] { const response await fetch(https://api.heygen.com/v2/avatars, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! }, }); const json: AvatarsResponse await response.json(); if (json.error) { throw new Error(json.error); } return json.data.avatars; }Pythonimport requests import os def list_avatars() - list: response requests.get( https://api.heygen.com/v2/avatars, headers{X-Api-Key: os.environ[HEYGEN_API_KEY]} ) data response.json() if data.get(error): raise Exception(data[error]) return data[data][avatars]响应格式{ error: null, data: { avatars: [ { avatar_id: josh_lite3_20230714, avatar_name: Josh, gender: male, preview_image_url: https://files.heygen.ai/..., preview_video_url: https://files.heygen.ai/... }, { avatar_id: angela_expressive_20231010, avatar_name: Angela, gender: female, preview_image_url: https://files.heygen.ai/..., preview_video_url: https://files.heygen.ai/... } ], talking_photos: [] } }注意响应中还有talking_photos会说话的照片数组它来自 HeyGen 的 Talking Photo 能力与 Avatar 属于不同的演示者形态。在 OpenMontage 中HeyGen 的鉴权方式统一为X-Api-Key请求头仓库工具tools/video/heygen_video.py的get_status()实现即为存在HEYGEN_API_KEY环境变量才标记为可用其install_instructions也明确提示需在 https://app.heygen.com/settings/api 申请密钥。Avatar 类型公共与定制公共 AvatarPublic AvatarsHeyGen 提供任何人都可以使用的公共主播库// List only public avatars const avatars await listAvatars(); const publicAvatars avatars.filter((a) !a.avatar_id.startsWith(custom_));私有/定制 AvatarPrivate/Custom Avatars由你自己的训练素材创建的定制主播const customAvatars avatars.filter((a) a.avatar_id.startsWith(custom_));关键判别规则avatar_id是否以custom_开头是区分定制与公共主播的可靠信号。Avatar 样式Styles与适用场景Avatar 支持不同的渲染样式样式说明normal全身镜头标准取景closeUp面部特写更具表现力circle圆形取景框内的主播说话人头像voice_only仅音频不渲染视频各样式推荐使用场景使用场景推荐样式全屏演示人视频normal个人化/亲密感内容closeUp画中画叠加Picture-in-Picturecircle小尺寸角落小部件circle播客/纯音频内容voice_only动态图形叠加主播normal或closeUp 透明背景在视频配置中使用样式const videoConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, // normal | closeUp | circle | voice_only }, voice: { type: text, input_text: Hello, world!, voice_id: 1bd001e7e50f421d891986aad5158bc8, }, }, ], };Circle 样式用于说话人头像Circle 样式非常适合叠加合成// Circle avatar for picture-in-picture { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: circle, }, voice: { ... }, background: { type: color, value: #00FF00, // Green for chroma key, or use webm endpoint }, }背景指定为纯绿色#00FF00是为了后续抠像chroma key也可以改用 WebM 端点直接输出透明背景。这与 OpenMontage 中透明/抠像视频用于合成的思路一致——仓库提供tools/video/green_screen_processor.py与tools/video/green_screen_composite.py专门处理绿幕合成而 HeyGen 官方技能文档中也特别强调Transparent video for compositing — see video-generation.md (WebM section)见.claude/skills/heygen/SKILL.md。搜索与过滤主播按性别过滤function filterByGender(avatars: Avatar[], gender: male | female): Avatar[] { return avatars.filter((a) a.gender gender); } const maleAvatars filterByGender(avatars, male); const femaleAvatars filterByGender(avatars, female);按名称搜索function searchByName(avatars: Avatar[], query: string): Avatar[] { const lowerQuery query.toLowerCase(); return avatars.filter((a) a.avatar_name.toLowerCase().includes(lowerQuery) ); } const results searchByName(avatars, josh);Avatar 分组Groups主播按组group组织便于管理。列出主播分组curl -X GET https://api.heygen.com/v2/avatar_group.list?include_publictrue \ -H X-Api-Key: $HEYGEN_API_KEY查询参数参数类型默认值说明include_publicboolfalse是否在结果中包含公共主播TypeScriptinterface AvatarGroupItem { id: string; name: string; created_at: number; num_looks: number; preview_image: string; group_type: string; train_status: string; default_voice_id: string | null; } interface AvatarGroupListResponse { error: null | string; data: { avatar_group_list: AvatarGroupItem[]; }; } async function listAvatarGroups( includePublic true ): PromiseAvatarGroupListResponse[data] { const params new URLSearchParams({ include_public: includePublic.toString(), }); const response await fetch( https://api.heygen.com/v2/avatar_group.list?${params}, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! } } ); const json: AvatarGroupListResponse await response.json(); if (json.error) { throw new Error(json.error); } return json.data; }注意AvatarGroupItem中的train_status字段用于表示定制主播组的训练状态default_voice_id可能为null。获取分组内的主播curl -X GET https://api.heygen.com/v2/avatar_group/{group_id}/avatars \ -H X-Api-Key: $HEYGEN_API_KEY在视频生成中使用 Avatar基础用法const videoConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Welcome to our product demo!, voice_id: 1bd001e7e50f421d891986aad5158bc8, }, }, ], dimension: { width: 1920, height: 1080 }, };character.type固定为avataravatar_id指定主播voice.input_text指定要朗读的文本dimension控制画幅1920×1080 为横屏 1080p。多场景使用不同主播const multiSceneConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Hi, Im Josh. Let me introduce my colleague., voice_id: 1bd001e7e50f421d891986aad5158bc8, }, }, { character: { type: avatar, avatar_id: angela_expressive_20231010, avatar_style: normal, }, voice: { type: text, input_text: Hello! Im Angela. Nice to meet you!, voice_id: 2d5b0e6a8c3f47d9a1b2c3d4e5f60718, }, }, ], };video_inputs数组中的每个元素即一个独立场景可分别指定主播、脚本与配合video-generation.md中的背景配置场景背景。这正是 OpenMontage 中精确控制每场景主播/背景的用途——见.claude/skills/heygen/SKILL.md对 v2/video/generate 的定位Exact script without AI modification、Specific voice_id selection、Different avatars/backgrounds per scene、Precise per-scene timing control。使用主播的默认语音Default Voice很多主播带有预匹配的default_voice_id官方推荐直接使用默认语音而不是手动挑选语音。推荐流程1. GET /v2/avatars → Get list of avatar_ids 2. GET /v2/avatar/{id}/details → Get default_voice_id for chosen avatar 3. POST /v2/video/generate → Use avatar_id default_voice_id获取主播详情v2 APIcurl -X GET https://api.heygen.com/v2/avatar/{avatar_id}/details \ -H X-Api-Key: $HEYGEN_API_KEY响应格式{ error: null, data: { type: avatar, id: josh_lite3_20230714, name: Josh, gender: male, preview_image_url: https://files.heygen.ai/..., preview_video_url: https://files.heygen.ai/..., premium: false, is_public: true, default_voice_id: 1bd001e7e50f421d891986aad5158bc8, tags: [AVATAR_IV] } }premium表示是否高级付费主播is_public表示是否公共主播tags携带主播技术标签如AVATAR_IV表示基于 IV 版本模型。TypeScriptinterface AvatarDetails { type: avatar; id: string; name: string; gender: male | female; preview_image_url: string; preview_video_url: string; premium: boolean; is_public: boolean; default_voice_id: string | null; tags: string[]; } async function getAvatarDetails(avatarId: string): PromiseAvatarDetails { const response await fetch( https://api.heygen.com/v2/avatar/${avatarId}/details, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! } } ); const json await response.json(); if (json.error) { throw new Error(json.error); } return json.data; } // Usage: Get default voice for a known avatar const details await getAvatarDetails(josh_lite3_20230714); if (details.default_voice_id) { console.log(Using ${details.name} with default voice: ${details.default_voice_id}); } else { console.log(${details.name} has no default voice, select manually); }完整示例用任意主播的默认语音生成视频async function generateWithAvatarDefaultVoice( avatarId: string, script: string ): Promisestring { // 1. Get avatar details to find default voice const avatar await getAvatarDetails(avatarId); if (!avatar.default_voice_id) { throw new Error(Avatar ${avatar.name} has no default voice); } // 2. Generate video with the avatars default voice const videoId await generateVideo({ video_inputs: [{ character: { type: avatar, avatar_id: avatar.id, avatar_style: normal, }, voice: { type: text, input_text: script, voice_id: avatar.default_voice_id, }, }], dimension: { width: 1920, height: 1080 }, }); return videoId; }为什么使用默认语音性别必然匹配——主播与语音已预先配对自然的唇形同步——默认语音针对该主播做了优化代码更简单——无需单独拉取并匹配语音质量更好——HeyGen 已测试过该组合。如何选对主播类别、指南与避坑主播类别类别示例最佳用途商务/专业Josh, Angela, Wayne企业视频、产品演示、培训休闲/亲和Lily 及各类生活化主播社交媒体、非正式内容主题/季节性节日主题、Cosplay 主播特定营销活动、季节性内容表现力强Expressive名称中含 expressive 的主播有感染力的叙事、动态内容选型指南商务/专业内容选择着装中性商务休闲或正装的主播避免主题性或季节性主播节日服装、休闲服饰生成前预览确认形象专业结合目标受众的画像人口统计特征选择性别与外形。休闲/社交内容主播选择更灵活特定营销活动可使用主题性主播让主播能量与内容基调匹配。常见错误商务内容使用主题性主播——产品演示里出现节日装扮会显得不专业生成前不预览——务必打开预览 URL 核对形象忽略主播样式——circle样式主播不一定适合全屏演示语音性别不匹配——始终使用default_voice_id或手动保证性别一致。生成前自检清单已在浏览器预览主播图片/视频主播形象与内容基调专业 vs 休闲匹配主播样式normal、closeUp、circle适配视频格式语音性别与主播性别匹配可用时使用default_voice_id这套选型纪律在 OpenMontage 的avatar-spokesperson流水线中有对应体现其executive-producer技能强调对唇形同步质量、主持人取景、音频清晰度、CTA 落地把关并明确警告Uncanny valley: If avatar quality is low, it undermines the entire video. Be honest about tool capabilities.若主播质量低会拖垮整条视频要诚实面对工具能力边界——见skills/pipelines/avatar-spokesperson/executive-producer.md。辅助函数与常用主播 ID按 ID 获取主播async function getAvatarById(avatarId: string): PromiseAvatar | null { const avatars await listAvatars(); return avatars.find((a) a.avatar_id avatarId) || null; }校验主播 IDasync function isValidAvatarId(avatarId: string): Promiseboolean { const avatar await getAvatarById(avatarId); return avatar ! null; }随机获取主播async function getRandomAvatar(gender?: male | female): PromiseAvatar { let avatars await listAvatars(); if (gender) { avatars avatars.filter((a) a.gender gender); } const randomIndex Math.floor(Math.random() * avatars.length); return avatars[randomIndex]; }常用公共主播 ID以下为常用公共主播 ID可用性可能随时间变化Avatar ID名称性别josh_lite3_20230714Josh男angela_expressive_20231010Angela女wayne_20240422Wayne男lily_20230614Lily女使用前务必先调用 list 端点核实主播可用性不要硬编码假设其存在。在 OpenMontage 中落地的工程化视角OpenMontage 对 HeyGen 能力的工程封装可以从三个层面佐证上述 API 用法工具层tools/video/heygen_video.py定义HeyGenVideo工具provider heygen通过HEYGEN_API_KEY环境变量鉴权get_status()在未配置密钥时返回UNAVAILABLE并提供fallback到wan_video等本地方案的降级链路实现层tools/video/_shared.py中的generate_heygen_video()调用https://api.heygen.com/v1/workflows/executionsWorkflow APIGenerateVideoNode节点poll_heygen()以 5 秒起步、1.2 倍退避上限 30 秒的轮询策略等待completed状态超时上限 600 秒upload_image_heygen()则优先走v2/assets/upload预签名上传失败时回退到 fal.ai 存储——这与本文讲解的 v2 头像 API 同属 HeyGen 生态可作为如何将主播视频能力接入自动化流水线的参考实现技能层.claude/skills/heygen/SKILL.md声明该技能已弃用并推荐使用avatar-video面向精确主播/场景控制与create-video面向提示词驱动生成两个聚焦技能其中avatar-video的默认工作流第一步就是GET /v2/avatars→ 挑选主播、预览、记录avatar_id与default_voice_id与本文全流程一一对应。值得注意的边界OpenMontage 的HeyGenVideo工具走的是v1/workflows生成管线面向 VEO、Sora、Kling、Runway、Seedance 等视频生成 provider 的provider_variant路由而本文讲解的v2/avatars/v2/video/generate是主播发言人场景的接口两者都是 HeyGen 平台的正式 API选型时应根据目标AI 生成镜头 vs 数字主持人口播决定走哪条链路。参考文件如需深入可直接阅读 OpenMontage 仓库中的以下文档与源码本文主体来源.claude/skills/heygen/references/avatars.md语音列表与音色参数.claude/skills/heygen/references/voices.md视频生成与多场景配置.claude/skills/heygen/references/video-generation.md状态轮询与下载 URL.claude/skills/heygen/references/video-status.md照片转主播.claude/skills/heygen/references/photo-avatars.md聚焦技能 avatar-video.claude/skills/avatar-video/SKILL.mdHeyGen 工具封装tools/video/heygen_video.pyHeyGen 请求实现与轮询逻辑tools/video/_shared.py发言人流水线定义pipeline_defs/avatar-spokesperson.yaml执行制片人技能质量门禁skills/pipelines/avatar-spokesperson/executive-producer.md【免费下载链接】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），仅供参考