OpenMontage 集成 HeyGen 视频模板 API从模板列表到批量个性化视频生成的完整指南【免费下载链接】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 技能参考文档 所讲解的 HeyGen Video Templates视频模板能力模板的列出、详情查询、变量替换与批量个性化视频生成。你将掌握通过 curl、TypeScript 与 Python 三种方式调用v2/templates系列接口的完整流程并理解如何结合变量校验、轮询状态与速率限制在 OpenMontage 的 Agent 化视频生产体系中实现规模化、可复用的视频生成管线。模板机制概述HeyGen 模板Template允许你创建可复用的视频结构其中包含变量占位符variable placeholders。一次定义模板结构后通过替换不同变量即可批量产出内容不同、结构一致的个性化视频——这正是销售触达、客户引导、产品更新、培训与营销投放等场景的核心诉求。从 OpenMontage 的技能架构看模板能力属于 HeyGen 技能.claude/skills/heygen/SKILL.md的高级功能参考文件与 视频生成、视频状态轮询、Webhook 等文档共同构成完整的视频生产知识体系。该技能声明了运行前提环境中必须配置HEYGEN_API_KEY见 SKILL.md 的metadata.openclaw.requires.env。认证与环境准备所有 HeyGen API 请求都需要在 HTTP 头中携带X-Api-Key详见 authentication.md。在 OpenMontage 中这一约定与 HeyGen 视频工具 的可用性判断完全一致该工具的get_status()检查os.environ.get(HEYGEN_API_KEY)未配置时返回ToolStatus.UNAVAILABLE并在install_instructions中提示设置环境变量。export HEYGEN_API_KEYyour-api-key-hereAPI 响应统一采用{ error: null | string, data: T }结构成功时error为null失败时error携带错误信息例如Invalid API key。常见认证错误包括状态码错误原因401Invalid API keyAPI 密钥缺失或错误403Forbidden密钥缺少所需权限429Rate limit exceeded请求过于频繁列出模板Listing Templatescurlcurl -X GET https://api.heygen.com/v2/templates \ -H X-Api-Key: $HEYGEN_API_KEYTypeScriptinterface Template { template_id: string; name: string; thumbnail_url: string; variables: TemplateVariable[]; } interface TemplateVariable { name: string; type: text | image | audio; properties?: { max_length?: number; default_value?: string; }; } interface TemplatesResponse { error: null | string; data: { templates: Template[]; }; } async function listTemplates(): PromiseTemplate[] { const response await fetch(https://api.heygen.com/v2/templates, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! }, }); const json: TemplatesResponse await response.json(); if (json.error) { throw new Error(json.error); } return json.data.templates; }Pythonimport requests import os def list_templates() - list: response requests.get( https://api.heygen.com/v2/templates, headers{X-Api-Key: os.environ[HEYGEN_API_KEY]} ) data response.json() if data.get(error): raise Exception(data[error]) return data[data][templates]响应格式Response FormatGET /v2/templates返回的每个模板对象包含模板 ID、名称、缩略图地址以及变量定义数组。变量是模板的核心生成视频时你提供的变量值必须与这里的name一一对应。{ error: null, data: { templates: [ { template_id: template_abc123, name: Product Announcement, thumbnail_url: https://files.heygen.ai/..., variables: [ { name: product_name, type: text, properties: { max_length: 50 } }, { name: presenter_script, type: text, properties: { max_length: 500 } }, { name: product_image, type: image } ] } ] } }从类型定义看变量包含三类元信息typetext | image | audio决定变量承载的数据种类properties.max_length约束文本变量的最大字符数properties.default_value提供可选默认值。OpenMontage 的 HeyGen 技能 中同样维护了 avatars、voices、backgrounds 等资源类型的类型定义见 avatars.md、backgrounds.md模板变量体系与这些资源体系共享同一套枚举 属性约束的建模思路。获取模板详情Getting Template Detailscurlcurl -X GET https://api.heygen.com/v2/template/{template_id} \ -H X-Api-Key: $HEYGEN_API_KEYTypeScriptasync function getTemplate(templateId: string): PromiseTemplate { const response await fetch( https://api.heygen.com/v2/template/${templateId}, { 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; }获取模板详情是生成视频前的关键一步你需要先确认该模板定义了哪些变量变量名、类型、长度上限才能构造出合法的生成请求。原文档明确指出Thevariablesobject keys must match the templates defined variable names. Check template details to see which variables are defined.从模板生成视频Generating Video from Template请求字段字段类型必填说明variablesobject✓与模板变量匹配的键值对testboolean测试模式带水印、不消耗积分titlestring视频名称便于组织管理callback_idstring用于 Webhook 追踪的自定义 IDcallback_urlstring完成通知的 URL其中test: true是上线前验证流程的免费通道生成结果带水印、不消耗 Credits可用来确认变量映射、文案长度与画面布局是否符合预期。curlcurl -X POST https://api.heygen.com/v2/template/{template_id}/generate \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d { test: false, variables: { product_name: SuperWidget Pro, presenter_script: Introducing our latest innovation!, product_image: https://example.com/product.jpg } }TypeScriptinterface TemplateGenerateRequest { variables: Recordstring, string; // Required test?: boolean; title?: string; callback_id?: string; callback_url?: string; } interface TemplateGenerateResponse { error: null | string; data: { video_id: string; }; } async function generateFromTemplate( templateId: string, variables: Recordstring, string, test: boolean false ): Promisestring { const response await fetch( https://api.heygen.com/v2/template/${templateId}/generate, { method: POST, headers: { X-Api-Key: process.env.HEYGEN_API_KEY!, Content-Type: application/json, }, body: JSON.stringify({ test, variables }), } ); const json: TemplateGenerateResponse await response.json(); if (json.error) { throw new Error(json.error); } return json.data.video_id; }Pythondef generate_from_template(template_id: str, variables: dict, test: bool False) - str: response requests.post( fhttps://api.heygen.com/v2/template/{template_id}/generate, headers{ X-Api-Key: os.environ[HEYGEN_API_KEY], Content-Type: application/json }, json{ test: test, variables: variables } ) data response.json() if data.get(error): raise Exception(data[error]) return data[data][video_id]请求返回的video_id是后续轮询状态与下载视频的唯一凭证。HeyGen 的视频生成是异步的拿到video_id后需要通过GET /v2/videos/{video_id}轮询直至completed完整轮询模式见 video-status.md这一点与 OpenMontage 中 HeyGen 视频工具 的同步封装形成互补——工具层通过generate_heygen_video完成提交 等待 落盘的整链路而模板 API 更适合在 Agent 脚本中自行控制轮询节奏与批量调度。变量类型Variable Types模板变量支持三种类型覆盖了视频中文字、画面、声音三类动态内容文本变量Text Variables用于动态文本内容如客户姓名、产品名、价格、行动号召文案const variables { customer_name: John Smith, product_name: SuperWidget Pro, price: $99.99, cta_text: Order Now!, };文本变量的字数直接影响成片时长。结合 scripts.md 的估算规则正常语速约150 词/分钟即 75 词约 30 秒、300 词约 2 分钟、750 词约 5 分钟。为模板设计文案变量时应把max_length与目标时长对齐。图片变量Image Variables用于动态图片背景、产品图const variables { product_image: https://example.com/product.jpg, logo: https://example.com/logo.png, background: https://example.com/bg.jpg, };图片变量一般要求可公开访问的 URL验证环节会校验 URL 合法性。若需要本地素材可参照 assets.md 先上传再取回托管地址。音频变量Audio Variables用于自定义音频内容const variables { background_music: https://example.com/music.mp3, custom_voiceover: https://example.com/voiceover.mp3, };音频变量让统一模板 差异化配乐/配音成为可能适合需要本地化或品牌化音频的批量场景。批量视频生成Batch Video Generation模板的核心价值在于批量同一结构、不同变量值一次循环产出多条个性化视频。批量时务必加入节流延迟示例中为每次请求间隔 1000ms以避免触发限流429。interface PersonalizationData { name: string; email: string; company: string; customMessage: string; } async function batchGenerateVideos( templateId: string, recipients: PersonalizationData[] ): Promisestring[] { const videoIds: string[] []; for (const recipient of recipients) { const variables { recipient_name: recipient.name, company_name: recipient.company, personalized_message: recipient.customMessage, }; const videoId await generateFromTemplate(templateId, variables); videoIds.push(videoId); // Rate limiting: add delay between requests await new Promise((r) setTimeout(r, 1000)); } return videoIds; } // Usage const recipients [ { name: John Smith, email: johnexample.com, company: Acme Inc, customMessage: Thanks for your interest in our product!, }, { name: Jane Doe, email: janeexample.com, company: Tech Corp, customMessage: Wed love to show you a demo!, }, ]; const videoIds await batchGenerateVideos(template_abc123, recipients);批量场景下的限流处理与 OpenMontage 工具层的重试策略思路一致HeyGen 视频工具 声明了RetryPolicy(max_retries2, backoff_seconds10.0, retryable_errors[rate_limit, timeout, server_error])即对限流、超时、服务端错误进行指数退避重试。在自建批量脚本中可参考 authentication.md 提供的requestWithRetry对 429 使用Math.pow(2, i) * 1000的指数退避实现同等韧性。模板校验Template Validation在提交生成请求前对变量做本地校验可以避免将无效请求发给 API、节省调试成本。校验逻辑覆盖三点必填变量是否存在、文本变量是否超过max_length、图片变量是否为合法 URL。function validateTemplateVariables( template: Template, variables: Recordstring, string ): { valid: boolean; errors: string[] } { const errors: string[] []; for (const templateVar of template.variables) { const value variables[templateVar.name]; // Check if required variable is provided if (!value) { errors.push(Missing required variable: ${templateVar.name}); continue; } // Check text length limits if (templateVar.type text templateVar.properties?.max_length) { if (value.length templateVar.properties.max_length) { errors.push( Variable ${templateVar.name} exceeds max length of ${templateVar.properties.max_length} ); } } // Validate image URLs if (templateVar.type image) { try { new URL(value); } catch { errors.push(Variable ${templateVar.name} is not a valid URL); } } } return { valid: errors.length 0, errors, }; }完整模板工作流Complete Template Workflow将前述步骤串成端到端流程获取模板详情 → 校验变量 → 提交生成 → 轮询完成 → 返回视频 URL。其中waitForVideo来自 video-status.md 的轮询实现。async function createPersonalizedVideo( templateId: string, personalization: Recordstring, string ): Promisestring { // 1. Get template details const template await getTemplate(templateId); console.log(Using template: ${template.name}); // 2. Validate variables const validation validateTemplateVariables(template, personalization); if (!validation.valid) { throw new Error(Validation errors: ${validation.errors.join(, )}); } // 3. Generate video console.log(Generating video...); const videoId await generateFromTemplate(templateId, personalization); console.log(Video ID: ${videoId}); // 4. Wait for completion const videoUrl await waitForVideo(videoId); console.log(Video ready: ${videoUrl}); return videoUrl; } // Usage const videoUrl await createPersonalizedVideo(template_abc123, { customer_name: John Smith, product_name: SuperWidget Pro, offer_details: Get 20% off your first order!, });轮询与超时设置video-status.md 给出关键实操参数视频状态包含pending排队、processing生成中、completed可下载、failed失败典型生成耗时5–15 分钟脚本较长或高峰期可能超过 20 分钟。建议轮询超时设置为15–20 分钟900,000–1,200,000 ms脚本超过 2 分钟语音时长时按 15 分钟预期长视频优先采用保存 video_id、稍后查询的异步模式视频 URL 的有效期有限下载完成后应及时缓存落地生产系统可改用 webhooks.md 的完成通知避免持续轮询。失败处理当状态为failed时响应会携带failure_code如script_too_long与failure_message如 Script too long for selected avatar。轮询函数应读取这些字段抛出可读的错误信息OpenMontage 技能文档将其列为优雅处理生成失败的标准做法。最佳实践Best Practices为灵活性而设计Design for flexibility— 创建模板时使用通用占位符例如product_name、recipient_name而非写死具体品牌名保证模板可跨营销活动复用设定合理上限Set reasonable limits— 为文本变量定义max_length既约束文案长度也为校验环节提供依据校验输入Validate inputs— 生成前检查变量值尤其是必填项、长度与图片 URL 合法性使用测试模式Use test mode— 先用test: true验证模板与变量映射再进入生产生成实现速率限制Implement rate limiting— 批量生成时在请求间加入延迟规避 429缓存模板数据Cache template data— 模板详情相对稳定缓存可减少 API 调用次数错误处理Error handling— 对生成失败做优雅处理读取failure_message给出可操作反馈。典型应用场景Use Cases销售触达Sales outreach— 面向潜在客户的个性化介绍视频变量为姓名、公司、专属优惠客户引导Customer onboarding— 带客户姓名的欢迎视频提升上手体验产品更新Product updates— 动态内容的产品公告替换产品名与演示素材即可复用于每次发版培训Training— 定制化的培训模块按学员或部门替换内容营销投放Marketing campaigns— 定向推广视频按受众分组批量产出。这些场景与 OpenMontage 的 avatar-spokesperson 管线 高度契合——该管线将脚本撰写、数字人口播与批量分发编排为完整的生产流程而模板 API 正是支撑其中统一结构、规模化产出的关键机制。在 OpenMontage 中的落地方式OpenMontage 仓库同时维护了.claude/skills/heygen/与.agents/skills/heygen/两套镜像的技能目录对应不同 Agent 运行时的技能发现机制references/templates.md在两者中保持一致。此外 HeyGen 视频工具注册于 tool_registry.py提供了基于 Prompt 的视频生成封装支持text_to_video与image_to_video两种操作、VEO/Sora/Kling/Runway/Seedance 等多提供商变体并内置成本估算estimate_cost与运行时估算estimate_runtime——当你需要精确的模板化控制时使用本指南的v2/templatesAPI当需要快速、基于提示词的云端生成时可直接调用该工具两者共用HEYGEN_API_KEY这一环境前提。注意仓库中的 HeyGen 技能声明 已标记为DEPRECATED官方推荐迁移到更聚焦的create-video基于提示词的 Video Agent API与avatar-video精确的 Avatar/场景控制v2 API技能。模板 API 参考文档仍保留用于向后兼容在需要结构化模板 变量替换 批量个性化的场景下依然是最直接的方案新项目建议优先评估上述两个新技能的适用性。【免费下载链接】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），仅供参考