OpenMontage 中的 HeyGen API 认证指南X-Api-Key 鉴权、密钥管理与错误处理实践【免费下载链接】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/OpenMontageHeyGen 是 OpenMontage 中的云端数字人AI Avatar视频生成供应商同时作为统一网关开放了 VEO、Sora、Runway、Kling、Seedance 等多个视频生成模型的访问能力。本文基于仓库中的 HeyGen Skill 参考文档.claude/skills/heygen/references/authentication.md系统讲解 HeyGen API 的认证机制——从 API Key 获取、X-Api-Key请求头传递到多语言客户端封装、错误处理与安全最佳实践并对照仓库源码 tools/video/heygen_video.py 与 tools/video/_shared.py 说明其在真实项目中的落地方式。认证机制概览HeyGen 的所有 API 请求都需要认证认证方式是在 HTTP 请求头中携带 API KeyX-Api-Key: 你的 API Key无论调用的是头像列表、视频生成、视频状态查询还是素材上传接口认证方式都是统一的。从仓库实现可以印证这一点在 tools/video/_shared.py 中无论是创建视频任务、轮询任务状态还是上传图片素材都使用了同一个请求头构造模式headers {X-Api-Key: api_key, Content-Type: application/json}例如轮询生成任务状态时headers {X-Api-Key: api_key} url fhttps://api.heygen.com/v1/workflows/executions/{execution_id} response requests.get(url, headersheaders, timeout30)也就是说只要掌握了X-Api-Key的传递方式就可以对接 HeyGen 的全部 REST 端点。获取 API Key获取 API Key 的官方路径如下打开 HeyGen 的 API 设置页面https://app.heygen.com/settings?fromnavAPI按提示登录账号在 API 页面中复制你的 API Key。需要注意的是API Key 与网页版套餐额度是两套体系。仓库的供应商文档 docs/PROVIDERS.md 明确提示需要单独为 API 充值余额prepaid网页版套餐的 Credits 并不能直接用于 API 调用。完整的接入步骤是前往 HeyGen 注册账号进入设置中的 API 区域生成 API Key为 API 账户充值余额将 Key 写入环境变量。环境变量配置API Key 属于敏感凭据推荐通过环境变量管理而不是硬编码进源码。仓库的 Skill 元数据.claude/skills/heygen/SKILL.md也将HEYGEN_API_KEY声明为该 Skill 的必需环境变量。直接在 Shell 中导出export HEYGEN_API_KEYyour-api-key-here写入 .env 文件HEYGEN_API_KEYyour-api-key-hereOpenMontage 项目的根目录示例配置README.md也采用了同样的约定HEYGEN_API_KEYyour-key # HeyGen — VEO, Sora, Runway, Kling via single gateway在 OpenMontage 中HEYGEN_API_KEY是heygen_video工具tools/video/heygen_video.py的可用性开关。工具类通过检查该环境变量决定自身状态def get_status(self) - ToolStatus: return ToolStatus.AVAILABLE if os.environ.get(HEYGEN_API_KEY) else ToolStatus.UNAVAILABLE当 Key 未设置时工具直接返回不可用并给出安装指引Set the HEYGEN_API_KEY environment variable。因此无论你是手动调用 API 还是通过 OpenMontage 的 Agent 体系使用heygen_video工具第一步都是正确配置这个环境变量。发起认证请求curlcurl -X GET https://api.heygen.com/v2/avatars \ -H X-Api-Key: $HEYGEN_API_KEYTypeScript / JavaScriptfetchconst response await fetch(https://api.heygen.com/v2/avatars, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY!, }, }); const { data } await response.json();TypeScript / JavaScriptaxiosimport axios from axios; const client axios.create({ baseURL: https://api.heygen.com, headers: { X-Api-Key: process.env.HEYGEN_API_KEY, }, }); const { data } await client.get(/v2/avatars);Pythonrequestsimport os import requests response requests.get( https://api.heygen.com/v2/avatars, headers{X-Api-Key: os.environ[HEYGEN_API_KEY]} ) data response.json()Pythonhttpximport os import httpx async with httpx.AsyncClient() as client: response await client.get( https://api.heygen.com/v2/avatars, headers{X-Api-Key: os.environ[HEYGEN_API_KEY]} ) data response.json()在 Python 生态中OpenMontage 自身使用的就是requests同步客户端见 tools/video/_shared.py 中的generate_heygen_video与poll_heygen因此如果你希望与仓库保持一致requests是首选。封装可复用的 API 客户端TypeScript 版本参考文档提供了一版完整的 TypeScript 客户端封装统一处理请求头注入、JSON 序列化与错误抛出class HeyGenClient { private baseUrl https://api.heygen.com; private apiKey: string; constructor(apiKey: string) { this.apiKey apiKey; } async requestT(endpoint: string, options: RequestInit {}): PromiseT { const response await fetch(${this.baseUrl}${endpoint}, { ...options, headers: { X-Api-Key: this.apiKey, Content-Type: application/json, ...options.headers, }, }); if (!response.ok) { const error await response.json(); throw new Error(error.message || HTTP ${response.status}); } return response.json(); } getT(endpoint: string): PromiseT { return this.requestT(endpoint); } postT(endpoint: string, body: unknown): PromiseT { return this.requestT(endpoint, { method: POST, body: JSON.stringify(body), }); } } // Usage const client new HeyGenClient(process.env.HEYGEN_API_KEY!); const avatars await client.get(/v2/avatars);要点request方法把X-Api-Key与Content-Type: application/json作为默认请求头同时允许调用方通过options.headers覆盖非 2xx 响应会读取响应体中的error.message并抛出便于上层统一捕获get/post是薄封装业务代码只需关注端点路径与泛型返回类型。Python 版对照OpenMontage 的模块化做法OpenMontage 没有把 HeyGen 封装成通用 HTTP 客户端而是将认证 业务编排拆进了不同函数tools/video/_shared.pygenerate_heygen_video(inputs)读取HEYGEN_API_KEY构造GenerateVideoNode工作流请求发起POST /v1/workflows/executionspoll_heygen(execution_id, api_key, timeout600)带超时与指数退避间隔从 5s 起、每次 ×1.2、上限 30s地轮询GET /v1/workflows/executions/{execution_id}upload_image_heygen(image_path, api_key)先尝试POST /v2/assets/upload获取预签名上传 URL失败时回退到 fal.ai 存储。这种按职责拆分的写法同样值得在自己的 Python 集成代码中借鉴认证信息集中在函数入口解析请求头构造保持单一来源。API 响应格式HeyGen 的所有 API 响应都遵循统一的包装结构interface ApiResponseT { error: null | string; data: T; }成功响应示例以GET /v2/avatars为例{ error: null, data: { avatars: [...] } }错误响应示例{ error: Invalid API key, data: null }在 OpenMontage 源码中可以找到与此对应的解析习惯轮询任务状态时代码从payload.get(data, {})中取出execution_id从data中读取status与output字段并在error存在时抛出异常——这与上述响应结构完全吻合见 tools/video/_shared.py 的generate_heygen_video与poll_heygen。常见认证错误与处理状态码速查状态码错误原因401Invalid API keyAPI Key 缺失或错误403ForbiddenAPI Key 权限不足429Rate limit exceeded请求过于频繁通用错误处理逻辑async function makeRequest(endpoint: string) { const response await fetch(https://api.heygen.com${endpoint}, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! }, }); const json await response.json(); if (!response.ok || json.error) { throw new Error(json.error || HTTP ${response.status}); } return json.data; }这段代码的关键在于双重判定既检查 HTTP 状态码response.ok又检查响应体中的业务级error字段。因为 HeyGen 的部分错误场景下 HTTP 状态码正常但data字段为null且error非空。速率限制与指数退避HeyGen 对 API 请求实施速率限制每个 API Key 适用标准的速率限制部分端点如视频生成限制更严格收到 429 时推荐使用指数退避exponential backoff重试。参考文档给出的 TypeScript 重试实现async function requestWithRetry( fn: () PromiseResponse, maxRetries 3 ): PromiseResponse { for (let i 0; i maxRetries; i) { const response await fn(); if (response.status 429) { const waitTime Math.pow(2, i) * 1000; await new Promise((resolve) setTimeout(resolve, waitTime)); continue; } return response; } throw new Error(Max retries exceeded); }第i次重试前等待2^i秒1s、2s、4s……超过最大次数后抛错。OpenMontage 在工程层面对重试策略做了体系化设计。heygen_video工具tools/video/heygen_video.py声明了重试策略与可重试错误类别retry_policy RetryPolicy(max_retries2, backoff_seconds10.0, retryable_errors[rate_limit, timeout, server_error])同时任务轮询poll_heygen本身就带有超时保护与渐进式轮询间隔5s 起步、×1.2 增长、上限 30s、总超时 600s这与先退避重试、再轮询异步任务的云 API 调用范式是一致的。可以推断OpenMontage 中 429 这类错误会由工具层的重试策略消化而长耗时任务则交给轮询逻辑处理。安全最佳实践绝不在客户端代码中暴露 API Key—— 始终在服务端发起 API 调用。浏览器 / 移动端代码中的 Key 可以被任何用户提取等同于公开了你的账户额度与调用权限。使用环境变量—— 不要把 Key 硬编码进源码或提交到版本库。OpenMontage 的.env与 Skill 元数据约定HEYGEN_API_KEY就是这一实践的标准示范。定期轮换 Key—— 周期性生成新的 API Key 并废弃旧 Key缩小泄露窗口。监控用量—— 定期检查 HeyGen 控制台留意异常调用量或陌生 IP 的访问及时发现潜在泄露。在 OpenMontage 中的完整接入路径将上面的认证知识落地到 OpenMontage整体路径是注册 HeyGen 账号并为 API 单独充值docs/PROVIDERS.md 的 HeyGen 章节在.env中配置HEYGEN_API_KEY通过 Agent 调用heygen_video工具内部走generate_heygen_video→poll_heygen→ 下载成片的完整链路或直接参考 tools/video/_shared.py 的请求构造方式自行对接生成方向可选择veo_3_1、veo3、kling_pro、sora_v2_pro、runway_gen4等多个模型变体完整清单见 tools/video/_shared.py 中的HEYGEN_PROVIDERS常量它们在一次认证下通过同一个X-Api-Key统一访问。需要提醒的是仓库中旧的heygenSkill.claude/skills/heygen/SKILL.md已标记为 Deprecated官方推荐改用聚焦的create-video与avatar-videoSkill但无论使用哪个 Skill底层的认证方式——X-Api-Key请求头与HEYGEN_API_KEY环境变量——完全一致本文的认证实践依然完全适用。【免费下载链接】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），仅供参考
