OpenMontage 接入 HeyGen Avatar 视频生成指南：`/v2/video/generate` 单场景与多场景工作流实战

OpenMontage 接入 HeyGen Avatar 视频生成指南/v2/video/generate单场景与多场景工作流实战【免费下载链接】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 中 HeyGen/avatar-video 技能链路的参考文档.agents/skills/heygen/references/video-generation.md同内容亦维护在.agents/skills/avatar-video/references/video-generation.md编写。它系统讲解 HeyGen/v2/video/generate端点的请求字段、单/多场景编排、三种配音输入、状态轮询、透明背景 WebM 合成等完整生产流程并结合仓库中对应的技能定义与源码佐证调用关系。读完本文你将掌握在不依赖本地 GPU 的前提下通过 HeyGen Avatar API 精确生成「指定形象 指定文案 指定音色 逐场景背景」的数字人视频并能把透明背景头像无缝叠加进屏幕录制或 Remotion 合成画面。一、为什么需要 Avatar API 精确生成先看它在本仓库技能体系中的定位在深入字段细节前有必要先厘清仓库里 HeyGen 相关技能的分工。OpenMontage 将 HeyGen 能力拆成了三个技能目录见.agents/skills/heygen/SKILL.mdheygen历史遗留技能Frontmatter 中已明确标记[DEPRECATED]仅作向后兼容保留create-video面向「给定一段描述、让 AI 全自动出片」的 Video Agent / prompt 式生成avatar-video面向「我要让头像 Y 逐字说台词 Z、每个场景换背景」的精确控制路径其默认工作流第一条就是POST /v2/video/generate。技能文档给出了清晰的选用决策表只有当用户明确需要逐字脚本不被打断、指定 voice_id、每场景不同 avatar/background、精确的单场景节奏、批量按规格生成时才走/v2/video/generate这条链路否则优先使用.agents/skills/create-video/SKILL.md。这一点决定了本篇文章的适用范围本指南是精密仪器而非傻瓜相机它服务的是有精确控片需求的生产流程。二、视频输出格式先选对端点端点格式适用场景/v2/video/generateMP4标准推荐——带背景的视频最常见/v1/video.webmWebM透明背景——仅在需要把头像内容叠在别的画面背后时使用绝大多数情况应使用带背景的 MP4。WebM 只在需要透过头像看到背后的内容时使用例如把数字人主播叠加在屏幕录制画面上。透明背景视频的成本更高、兼容面更窄详见下文第八节。三、最基本的视频生成请求curl 起手式以一个最小可运行请求开始先拿到能出片的骨架curl -X POST https://api.heygen.com/v2/video/generate \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal }, voice: { type: text, input_text: Hello! Welcome to HeyGen., voice_id: 1bd001e7e50f421d891986aad5158bc8 } } ], dimension: { width: 1920, height: 1080 } }这个请求的核心逻辑是一个video_inputs条目 一景 「谁来说character 说什么/怎么发声voice 背后是什么background」。请求成功后会返回一个video_id后续靠它轮询状态、取回下载地址见 视频状态轮询。四、请求字段全解/v2/video/generate是异步任务提交语义字段分三层顶层字段、video_inputs[]内的character/voice/background子对象。4.1 顶层字段字段类型必填说明video_inputsarray✓视频输入对象数组可容纳1–50个即最多 50 景dimensionobject视频尺寸{width, height}titlestring视频标题用于账号内组织管理testboolean测试模式输出带水印、不消耗额度captionboolean是否启用自动字幕callback_idstring自定义 ID用于 Webhook 追踪callback_urlstring完成通知回调地址folder_idstring存储目录 ID视频归入指定文件夹4.2video_inputs[].character字段字段类型必填说明typestring✓avatar或talking_photoavatar_idstring✓*Avatar IDtypeavatar时必填talking_photo_idstring✓*照片 IDtypetalking_photo时必填avatar_stylestringnormal、closeUp或circlescalenumber头像缩放系数offsetobject位置偏移{x, y}4.3video_inputs[].voice字段字段类型必填说明typestring✓textTTS、audio上传音频或silence静默voice_idstring✓*音色 IDtypetext时必填input_textstring✓*台词文本typetext时必填audio_urlstring✓*音频 URLtypeaudio时必填durationnumber✓*时长秒数typesilence时必填speednumber语速 0.5–2.0默认 1.0pitchnumber音高 −2020默认 04.4video_inputs[].background字段字段类型必填说明typestringcolor、image或videovaluestring十六进制色值typecolor时使用urlstring图片/视频 URLtypeimage/video时使用fitstringcover或contain背景图片/视频尺寸建议与dimension匹配避免缩放裁切损失构图详见 背景配置 与 画幅与分辨率。4.5 TypeScript 类型定义含必填逻辑// Required fields have no ? - optional fields have ? interface VideoInput { character: { type: avatar | talking_photo; // Required avatar_id?: string; // Required when typeavatar talking_photo_id?: string; // Required when typetalking_photo avatar_style?: normal | closeUp | circle; scale?: number; offset?: { x: number; y: number }; }; voice: { type: text | audio | silence; // Required input_text?: string; // Required when typetext voice_id?: string; // Required when typetext audio_url?: string; // Required when typeaudio duration?: number; // Required when typesilence speed?: number; pitch?: number; }; background?: { type?: color | image | video; value?: string; url?: string; fit?: cover | contain; }; } interface VideoGenerateRequest { video_inputs: VideoInput[]; // Required dimension?: { width: number; height: number }; test?: boolean; title?: string; caption?: boolean; callback_id?: string; callback_url?: string; folder_id?: string; } interface VideoGenerateResponse { error: null | string; data: { video_id: string; }; } async function generateVideo(config: VideoGenerateRequest): Promisestring { const response await fetch(https://api.heygen.com/v2/video/generate, { method: POST, headers: { X-Api-Key: process.env.HEYGEN_API_KEY!, Content-Type: application/json, }, body: JSON.stringify(config), }); const json: VideoGenerateResponse await response.json(); if (json.error) { throw new Error(json.error); } return json.data.video_id; }4.6 Python 等价实现import requests import os def generate_video(config: dict) - str: response requests.post( https://api.heygen.com/v2/video/generate, 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_id]鉴权方式说明以上请求均通过请求头X-Api-Key: $HEYGEN_API_KEY完成鉴权。仓库内该技能的前置条件是在环境中配置HEYGEN_API_KEY见.agents/skills/heygen/SKILL.md的 metadata 声明及 鉴权文档。OpenMontage 的 API 侧封装同样遵循此约定——见 tools/video/heygen_video.py 中install_instructions对HEYGEN_API_KEY的要求。五、完整配置示例与多场景视频5.1 一条请求写满全部字段const fullConfig: VideoGenerateRequest { // Test mode (no credits consumed, watermarked output) test: false, // Video title (for organization) title: Product Demo Video, // Video dimensions dimension: { width: 1920, height: 1080, }, // Video scenes/inputs video_inputs: [ { // Avatar configuration character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, // Voice configuration voice: { type: text, input_text: Welcome to our product demonstration!, voice_id: 1bd001e7e50f421d891986aad5158bc8, speed: 1.0, pitch: 0, }, // Background configuration background: { type: color, value: #FFFFFF, }, }, ], };5.2 多场景一次提交一整支分镜video_inputs数组支持 1–50 个场景条目每一条都是独立的一幕可分别指定头像运镜风格、台词与背景。这比多次生成后拼接更省事也更容易控制节奏——尤其适合开场 → 特性演示 → 收尾式的口播结构const multiSceneConfig { video_inputs: [ // Scene 1: Introduction { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Hello! Today Ill show you three key features., voice_id: 1bd001e7e50f421d891986aad5158bc8, }, background: { type: color, value: #1a1a2e, }, }, // Scene 2: Feature 1 { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: closeUp, }, voice: { type: text, input_text: First, lets look at our dashboard., voice_id: 1bd001e7e50f421d891986aad5158bc8, }, background: { type: image, url: https://example.com/dashboard-bg.jpg, }, }, // Scene 3: Conclusion { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Thanks for watching! Try it today., voice_id: 1bd001e7e50f421d891986aad5158bc8, }, background: { type: color, value: #1a1a2e, }, }, ], dimension: { width: 1920, height: 1080 }, };值得注意的实践点同一 avatar 在多场景间通过avatar_style如normal→closeUp切换景别既能保持人物身份连续又能制造画面的节奏变化——这正符合 avatar-video 技能默认工作流中每场景一概念的编排建议参考 脚本撰写指南。六、两种角色类型与三种配音输入6.1 角色类型标准 Avatar真人数字分身{ character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal } }Talking Photo照片说话——用一张静态人像照片生成会开口的 presenter{ character: { type: talking_photo, talking_photo_id: your_talking_photo_id } }talking_photo_id需预先通过照片头像流程创建参见 照片头像文档。6.2 配音类型text / audio / silenceText-to-Speech最常用——直接喂台词{ voice: { type: text, input_text: Your script here, voice_id: 1bd001e7e50f421d891986aad5158bc8, speed: 1.0, // 0.5 - 2.0 pitch: 0 // -20 to 20 } }Custom Audio自定义音频——配音已由外部工具如仓库 skills 中 ElevenLabs / Fish Audio / Azure TTS 等本地音色管线生成时直接给音频 URLHeyGen 负责做口型同步{ voice: { type: audio, audio_url: https://example.com/your-audio.mp3 } }Silence静默——typesilence配合duration用于需要人物不发声但保持画面/口型自然停顿的场景。七、完整工作流提交 → 轮询 → 下载HeyGen 的视频生成是异步的POST只返回video_id真正的成片需要轮询状态接口GET /v2/videos/{video_id}直到status completed。以下是一套完整的生成→等待→取回 URL代码async function createVideo(script: string, avatarId: string, voiceId: string) { // 1. Generate video console.log(Starting video generation...); const videoId await generateVideo({ video_inputs: [ { character: { type: avatar, avatar_id: avatarId, avatar_style: normal, }, voice: { type: text, input_text: script, voice_id: voiceId, }, background: { type: color, value: #FFFFFF, }, }, ], dimension: { width: 1920, height: 1080 }, }); console.log(Video ID: ${videoId}); // 2. Poll for completion console.log(Waiting for video completion...); const videoUrl await waitForVideo(videoId); console.log(Video ready: ${videoUrl}); return videoUrl; } // Helper function for polling async function waitForVideo(videoId: string): Promisestring { const maxAttempts 60; const pollInterval 10000; // 10 seconds for (let i 0; i maxAttempts; i) { const response await fetch( https://api.heygen.com/v2/videos/${videoId}, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! } } ); const { data } await response.json(); if (data.status completed) { return data.video_url; } else if (data.status failed) { throw new Error(data.failure_message || Video generation failed); } await new Promise((r) setTimeout(r, pollInterval)); } throw new Error(Video generation timed out); }状态接口的四态语义与超时策略在仓库参考文档 视频状态与轮询 中有完整展开pending排队→processing生成中→completed可取件→failed失败含failure_code/failure_message。经验值单支视频通常 5–15 分钟高峰期或长脚本可能超过 20 分钟。因此推荐超时设15–20 分钟即 900,000–1,200,000 ms演讲稿超过 2 分钟时预期 15 分钟以上长视频优先异步检查而非长驻轮询——保存video_id稍后回来查状态。八、错误处理与开发期加速8.1 常见失败的分诊模式async function generateVideoSafe(config: VideoGenerateRequest) { try { const videoId await generateVideo(config); return { success: true, videoId }; } catch (error) { // Common errors if (error.message.includes(quota)) { console.error(Insufficient credits); } else if (error.message.includes(avatar)) { console.error(Invalid avatar ID); } else if (error.message.includes(voice)) { console.error(Invalid voice ID); } else if (error.message.includes(script)) { console.error(Script too long or invalid); } return { success: false, error: error.message }; } }8.2 Test Mode免费试错开关把test: true打开就能以带水印、不消耗额度的方式验证整套配置是否合法、出片节奏是否满意——开发期应当默认开启仅最终出片时关闭const config { test: true, // Watermarked output, no credits consumed video_inputs: [...], };8.3 脚本长度与停顿控制不同套餐对单场景台词长度有限制规划脚本时应先按档位预估套餐档位最大字符数Free~500Creator~1,500Team~3,000Enterprise~5,000想要控制口播节奏可在台词中插入 SSML 风格的break停顿标签const script Welcome to our demo. break time\1s\/ Let me show you the features.;格式break timeXs/其中 X 为秒数如1s、1.5s、0.5s关键约束标签前后必须留有空格word break time1s/ word直接粘连会导致标签不被识别连续多个break会被自动合并为总时长的一次停顿停顿节奏与情感化音色的更多规则见 配音与音色指南。九、生产级工作流自动选用头像默认音色直接硬编码avatar_id/voice_id只适合验证。生产环境中更稳的做法是先列头像 → 取该头像的default_voice_id官方预匹配音色→ 再生成从而避免男像配女声之类的低级错误若头像没有默认音色再按性别人工配对配音指南 给出了完整的配对策略与多语言示例。interface VideoGenerationResult { videoId: string; videoUrl: string; duration: number; avatarId: string; voiceId: string; avatarName: string; } async function generateAvatarVideo( script: string, options: { avatarId?: string; // Specific avatar, or will pick first available width?: number; height?: number; } {} ): PromiseVideoGenerationResult { const { width 1920, height 1080 } options; let { avatarId } options; // 1. List avatars if no specific one provided if (!avatarId) { console.log(Listing available avatars...); const listResponse await fetch(https://api.heygen.com/v2/avatars, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! }, }); const listData await listResponse.json(); if (!listData.data?.avatars?.length) { throw new Error(No avatars available); } avatarId listData.data.avatars[0].avatar_id; } // 2. Get avatar details including default_voice_id console.log(Getting details for avatar: ${avatarId}); const detailsResponse await fetch( https://api.heygen.com/v2/avatar/${avatarId}/details, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! } } ); const { data: avatar } await detailsResponse.json(); if (!avatar.default_voice_id) { throw new Error(Avatar ${avatar.name} has no default voice - select voice manually); } console.log(Using avatar: ${avatar.name} with default voice: ${avatar.default_voice_id}); // 3. Generate video using avatars default voice const videoId await generateVideo({ video_inputs: [{ character: { type: avatar, avatar_id: avatar.id, // from details response avatar_style: normal, }, voice: { type: text, input_text: script, voice_id: avatar.default_voice_id, // pre-matched default voice speed: 1.0, }, background: { type: color, value: #1a1a2e, }, }], dimension: { width, height }, }); console.log(Video ID: ${videoId}); // 3. Wait for completion (20 minute timeout - generation can take 15 min) console.log(Waiting for video generation (typically 5-15 minutes, can be longer)...); const result await waitForVideo( videoId, process.env.HEYGEN_API_KEY!, (status, elapsed) { console.log( [${Math.round(elapsed / 1000)}s] ${status}); }, 1200000 // 20 minute timeout for safety ); return { videoId, videoUrl: result.video_url!, duration: result.duration!, avatarId: avatar.id, voiceId: avatar.default_voice_id, avatarName: avatar.name, }; } // Usage - let it pick an avatar automatically const result await generateAvatarVideo( Hello! Welcome to our product demonstration. ); console.log(Video ready: ${result.videoUrl}); // Or specify a known avatar_id const result2 await generateAvatarVideo( Hello! Welcome to our product demonstration., { avatarId: josh_lite3_20230714 } );十、透明背景视频WebM何时用、怎么用10.1 决策依据别为不需要透明的地方付代价不需要 WebM 的场景请直接用 MP4只需在头像上方叠加动效文字/图形带纯色背景的画中画PiP标准主讲人出镜视频。必须用 WebM 的场景头像叠加在屏幕录制上Loom 风格头像漂浮在视频背景之上需要真实 alpha 通道做合成的场景。端点注意WebM 端点/v1/video.webm的请求结构与/v2/video/generate不同且 WebM仅支持normal与closeUp两种风格——circle圆形风格不支持。想要圆形头像请在后处理阶段Remotion / 视频编辑器做圆形遮罩。10.2 WebM 请求字段字段类型必填说明avatar_pose_idstring✓Avatar 姿势 ID取自 avatar 详情avatar_stylestring✓仅normal或closeUp不支持 circleinput_textstring✓*台词文本不使用input_audio时必填voice_idstring✓*音色 ID与input_text搭配时必填input_audiostring✓*音频 URL不使用input_text时必填dimensionobject{width, height}默认 1280×720二选一约束必须提供input_textvoice_id或input_audio两者不可同时提供。10.3 curl 示例curl -X POST https://api.heygen.com/v1/video.webm \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d { avatar_pose_id: josh_lite3_20230714, avatar_style: normal, input_text: Hello! This video has a transparent background., voice_id: 1bd001e7e50f421d891986aad5158bc8, dimension: { width: 1920, height: 1080 } }10.4 TypeScript 封装interface WebMVideoRequest { avatar_pose_id: string; // Required avatar_style: normal | closeUp; // Required (no circle support) input_text?: string; // Required if not using input_audio voice_id?: string; // Required with input_text input_audio?: string; // Required if not using input_text dimension?: { width: number; height: number }; } async function generateTransparentVideo( script: string, avatarPoseId: string, voiceId: string ): Promisestring { const response await fetch(https://api.heygen.com/v1/video.webm, { method: POST, headers: { X-Api-Key: process.env.HEYGEN_API_KEY!, Content-Type: application/json, }, body: JSON.stringify({ avatar_pose_id: avatarPoseId, // Required avatar_style: normal, // Required: normal or closeUp input_text: script, // Required (with voice_id) voice_id: voiceId, // Required (with input_text) dimension: { width: 1920, height: 1080 }, }), }); const { data } await response.json(); return data.video_id; }10.5 MP4 vs WebM 速查场景格式原因头像上叠加动效文字MP4叠加层在头像之上无需透明标准主讲人视频MP4更简单、兼容性更好Loom 风格头像盖在屏幕录制上WebMnormal/closeUp需要透明后期裁成圆形头像浮于视频内容上WebM需要透出头像背后的内容10.6 生产案例Loom 风格叠加 Remotion 圆形遮罩先生成透明 WebM此处选择closeUp近景更接近真人主播窗效果// Generate avatar with transparent background const videoId await fetch(https://api.heygen.com/v1/video.webm, { method: POST, headers: { X-Api-Key: apiKey, Content-Type: application/json }, body: JSON.stringify({ avatar_pose_id: avatarPoseId, // Required avatar_style: closeUp, // Required: normal or closeUp only input_text: script, // Required (with voice_id) voice_id: voiceId, // Required (with input_text) dimension: { width: 1920, height: 1080 }, }), }).then(r r.json()).then(d d.data.video_id);再在 Remotion 合成里把它作为第二层Video用 CSSborderRadius: 50%圆角遮罩压成悬浮圆窗import { Video, AbsoluteFill } from remotion; export const LoomStyleVideo: React.FC{ screenRecordingUrl: string; avatarWebmUrl: string; } ({ screenRecordingUrl, avatarWebmUrl }) { return ( AbsoluteFill {/* Screen recording as base layer */} Video src{screenRecordingUrl} style{{ width: 100%, height: 100% }} / {/* Avatar with circular mask applied in CSS */} Video src{avatarWebmUrl} style{{ position: absolute, bottom: 20, left: 20, width: 150, height: 150, borderRadius: 50%, // Circular mask overflow: hidden, objectFit: cover, }} / /AbsoluteFill ); };WebM 产物与 MP4 共用同一状态查询端点轮询到completed后video_url指向的将是.webm文件可直接喂给上面的Video src。若想在此基础上叠加字幕/文字层参考 Remotion 集成、字幕 与 文字叠加长任务不轮询而改用回调的见 Webhooks。十一、最佳实践清单可直接对照自检生成前预览头像——下载preview_image_url让用户看到形象后再花钱出片参考 头像选择优先用头像的默认音色——多数 avatar 带官方预匹配的default_voice_id出片自然度最高兜底策略人工按性别配对——无默认音色时保证 avatar 与 voice 的性别一致配音指南先校验输入——生成前确认avatar_id、voice_id真实存在可分别通过/v2/avatars、/v2/voices拉取校验开发期开 test mode——不消耗额度、出片带水印用于全流程联调预留充足的超时——建议 15–20 分钟因为常规生成 10–15 分钟、长脚本更久长视频走异步模式——保存video_id稍后查状态而不是长驻进程干等优雅处理错误——对 quota / avatar / voice / script 四类错误分别分诊监控进度——轮询时输出耗时与状态便于向用户反馈进度精简台词——脚本保持简洁自然利于控制长度与节奏按用途定画幅——YouTube 16:9、短视频 9:16、信息流 1:1720p 草稿/1080p 出片画幅与分辨率。十二、回到仓库Avatar 生成在 OpenMontage 里的源码呼应理解了上面这套 API 契约后再看 OpenMontage 源码中两处 HeyGen 相关实现能帮你把外部 API与本仓库工具体系对应起来其一是 API 侧的工具封装 tools/video/heygen_video.py。它把 HeyGen 作为云端视频生成聚合入口provider heygencapability video_generation通过 tools/video/_shared.py 中的HEYGEN_PROVIDERS将 VEO 3.x、Sora、Kling、Runway、Seedance 等模型暴露为统一provider_variant如veo_3_1、sora_v2_pro、kling_pro并声明了成本估算estimate_quality_cost、运行时长估算、重试策略与无 GPU、纯云端的资源画像ResourceProfile(cpu_cores1, ...)。注意该工具面向的是 HeyGen 的文生视频/图生视频工作流text_to_video/image_to_video与本文讲解的Avatar 精确控片/v2/video/generate是两个不同的能力面——前者聚合视频大模型后者编排数字人出镜。其二是技能侧的编排入口.agents/skills/avatar-video/SKILL.md。它的默认工作流五步为列头像/v2/avatars→按需列音色/v2/voices→ 写脚本 →POST /v2/video/generate→ 轮询/v2/videos/{video_id}。这正是本文全部知识点的落地编排当仓库工具连了mcp__heygen__*MCP 时建议优先使用 MCP 工具完成状态查询、视频列表与删除它们会自动处理鉴权与请求格式化而 Avatar 生成与头像/音色列举按技能约定走直接 API 调用。追溯说明本文引用的.agents/skills/heygen/references/video-generation.md与 .agents/skills/avatar-video/references/video-generation.md 内容完全一致——前者所在的heygen技能已在.agents/skills/heygen/SKILL.md中标注弃用avatar-video精确控片与create-video提示词出片是仓库当前推荐的替代入口。查阅本文提到的头像、音色、状态等补充文档时两份副本均可读建议以avatar-video目录下的为主。结语/v2/video/generate是 HeyGen Avatar 能力中最具制片人思维的一个端点一次请求携带 1–50 个场景逐场景指定人物、台词、音色与背景配合/v1/video.webm的透明通道输出几乎可以覆盖精确口播 → 多景切换 → 叠加合成的全部常规制片需求。掌握字段语义、轮询节奏、test mode 与默认音色策略之后你便可以在 OpenMontage 的 Agent 工作流中把它当作一个高确定性的数字人出镜组件来调用——让 AI 编码助手真正替你完成从脚本到成片的最后一公里。【免费下载链接】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），仅供参考