OpenMontage 中 HeyGen 配额与积分管理实战：剩余额度查询、消耗估算与预生成检查

HeyGen 采用基于积分的计费体系，视频生成前若未确认账户配额，请求极可能在生成中途因 quota/credit 耗尽而失败。本文以 OpenMontage 仓库中 create-video Skill 的配额参考文档 为主体，系统讲解 HeyGen 剩余额度查询的 curl / TypeScript / Python 三种姿势、响应格式解析、不同操作的积分消耗规则、生成前的配额预检函数，以及订阅等级与配额错误处理；并结合仓库中 create-video/SKILL.md 与 heygen_video.py 的工程实现，说明在完整 Agent 视频生产链路中如何落地"先查配额、再估消耗、后发起生成"的稳健流程。读完本文，你既能独立编写可靠的配额管理代码，也能理解 OpenMontage 将其作为视频 Skill"基础（Foundation）参考"的原因。

一、配额文档在 OpenMontage 中的位置与定位

在 OpenMontage 仓库中，quota.md 并不是孤立文件，而是多套 HeyGen 相关 Agent Skill 共同引用的"基础参考"（Foundation Reference）：

• .agents/skills/create-video/SKILL.md 的 Reference Files 一节将 quota.md 归入 Foundation，标注为"Credit system and usage limits"（积分体系与用量限制）；
• .agents/skills/heygen/references/quota.md 与 .agents/skills/avatar-video/references/quota.md 均携带相同的内容骨架；
• .claude/skills/create-video/references/quota.md 等镜像副本则用于 Claude Code 侧相同能力的注入。

从 SKILL.md 元信息可知，无论走哪条调用路径，HeyGen 认证都只依赖一个环境变量：HEYGEN_API_KEY。create-video Skill 的元信息中 openclaw.requires.env 明确声明了 HEYGEN_API_KEY 为 primaryEnv，且所有请求都通过 X-Api-Key 请求头携带密钥。配额查询是这些 Skill 工作流的前置保障：一旦 remaining_quota 归零，任何 mcp__heygen__generate_video_agent 调用或 POST /v1/video_agent/generate 直连请求都可能被拒绝。

二、配额体系的本质：先明白扣的是什么

HeyGen 视频生成并非按"次数"或"时长包月"简单计费，而是采用积分（credits）制：每一次生成操作根据其类型、分辨率、时长按不同规则扣减账户积分。配额（quota）即账户中剩余的可用积分总量。

理解配额管理的意义在于 "预防"而非"善后"——在调用生成接口之前就判断余额是否充足，可以有效避免两类问题：

1. 请求被拒：余额不足导致生成请求直接失败（quota exceeded 类错误）；
2. 任务中断：长视频、翻译等耗时任务中途因扣费失败而终止，浪费等待时间。

仓库中 heygen_video 工具也印证了这种对"成本/配额"的关注：它在 tools/video/heygen_video.py 中通过 estimate_cost 计算单次生成的 cost_usd 并写回 ToolResult，同时还通过 tools/cost_tracker.py 对整条生产管线的费用进行跟踪。也就是说，配额管理既是"账户侧"的硬约束，也是"工具侧"成本核算的软约束，二者共同保证 Agent 制视频生产不会产生意料之外的欠费与失败。

三、检查剩余配额（Checking Remaining Quota）

HeyGen 提供统一的配额查询端点，需要携带 API Key：

GET https://api.heygen.com/v2/user/remaining_quota
Header: X-Api-Key: <HEYGEN_API_KEY>

下面给出三种语言的完整调用方式，可直接复制使用。

3.1 curl

curl -X GET "https://api.heygen.com/v2/user/remaining_quota" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

3.2 TypeScript

interface QuotaResponse {
  error: null | string;
  data: {
    remaining_quota: number;
    used_quota: number;
  };
}

const response = await fetch("https://api.heygen.com/v2/user/remaining_quota", {
  headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! },
});

const { data }: QuotaResponse = await response.json();
console.log(`Remaining credits: ${data.remaining_quota}`);

提示：process.env.HEYGEN_API_KEY! 中的非空断言表示该密钥在运行时必然已注入（与 Skill 元信息中 primaryEnv: HEYGEN_API_KEY 的约束一致）；若变量缺失，应先在环境或 .env 中配置，而不是用空字符串发起请求。

3.3 Python

import requests
import os

response = requests.get(
    "https://api.heygen.com/v2/user/remaining_quota",
    headers={"X-Api-Key": os.environ["HEYGEN_API_KEY"]}
)

data = response.json()["data"]
print(f"Remaining credits: {data['remaining_quota']}")

注意 Python 示例直接以 os.environ["HEYGEN_API_KEY"] 取值，KeyError 会在缺少密钥时立刻暴露配置问题，这比静默传空串更适合作为 Agent 或 CI 环境的前置检查。

四、响应格式（Response Format）

配额查询接口返回固定结构，error 与 data 为顶层字段：

{
  "error": null,
  "data": {
    "remaining_quota": 450,
    "used_quota": 50
  }
}

字段语义：

字段	类型	含义
error	null / string	请求出错时的错误信息；成功时为 null
data.remaining_quota	number	当前账户剩余积分（credits）
data.used_quota	number	已消耗的积分总量

remaining_quota + used_quota 可以推算出账户的总配额基数，这在"计算已用百分比"的监控场景（见下文 6.1 节）中非常有用。

五、积分消耗规则（Credit Consumption）

不同类型的操作会扣减不同数量的积分，原文档给出的基准规则如下：

Operation	Credit Cost	Notes
Standard video (1 min)	~1 credit per minute	Varies by resolution
720p video	Base rate	Standard quality
1080p video	~1.5x base rate	Higher quality
Video translation	Varies	Depends on video length
Streaming avatar	Per session	Real-time usage

解读几条关键结论：

• 时长线性：标准视频按分钟线性计费，1 分钟大约消耗 1 credit，这是"预生成配额检查"中做粗估算的基础系数；
• 分辨率加成：1080p 约为 720p 基准的 1.5 倍，即"质量越高、单分钟消耗越大"，与文档中 "Varies by resolution" 的说明一致；
• 实时类按会话：流式虚拟主播（Streaming avatar）不走"每分钟"模型，而是按会话（session）计费，估算时需单独处理；
• 翻译按片长：视频翻译的扣费随输入视频总长度浮动，无法用固定常数预估，只能基于源片长近似。

有趣的是，这种"质量档位→成本系数"的思路在 OpenMontage 的源码中同样存在：在 tools/video/_shared.py 中，estimate_quality_cost 将质量字符串映射为美元估算价（highest→$0.50、high→$0.35、low→$0.15，其余默认 $0.20），并通过 HEYGEN_PROVIDERS 中的 quality/speed 元数据为 veo_3_1、sora_v2、kling_pro 等底层模型加权。虽然它核算的是"单次调用的美元成本"而非"HeyGen 账户积分"，但两者遵循同一个工程原则——在生成前把成本折算成可量化的数字，为决策提供依据。

六、生成前的配额预检（Pre-Generation Quota Check）

原文档明确强调："Always verify sufficient quota before generating videos."（生成视频前务必验证配额充足）。下面的 TypeScript 示例展示了完整的"预检→估算→拦截→放行"模式：

async function generateVideoWithQuotaCheck(videoConfig: VideoConfig) {
  // Check quota first
  const quotaResponse = await fetch(
    "https://api.heygen.com/v2/user/remaining_quota",
    { headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } }
  );

  const { data: quota } = await quotaResponse.json();

  // Estimate required credits (rough estimate: 1 credit per minute)
  const estimatedMinutes = videoConfig.estimatedDuration / 60;
  const requiredCredits = Math.ceil(estimatedMinutes);

  if (quota.remaining_quota < requiredCredits) {
    throw new Error(
      `Insufficient credits. Need ${requiredCredits}, have ${quota.remaining_quota}`
    );
  }

  // Proceed with video generation
  return generateVideo(videoConfig);
}

这段代码的设计要点值得展开：

1. 先查后做：将配额查询放在 generateVideo 之前，用一次廉价的只读 GET 避免一次昂贵的生成调用失败；
2. 按分钟粗估：estimatedDuration / 60 得到预估分钟数，Math.ceil 向上取整（即使时长不足一分钟也至少按 1 分钟算），估算偏保守以留出余量；
3. 不足即抛错：当 remaining_quota < requiredCredits 时立即抛出带上下文信息的异常（需要多少、当前多少），而不是把请求发给远端等待失败；
4. 估算系数可演进：注释明确这是 "rough estimate: 1 credit per minute"，当目标视频超过 720p、或包含翻译/实时场景时，应把第五节中的倍率（如 1080p 的 1.5x）乘进 requiredCredits 再比较。

在 OpenMontage 的编排语境中，这个函数应当挂在 create-video 默认工作流 的 POST /v1/video_agent/generate（或 MCP 工具 mcp__heygen__generate_video_agent）之前执行，与技能中"优化提示词 → 发起生成 → 轮询 GET /v2/videos/{video_id} 获取下载地址"的既有步骤天然衔接。

七、配额管理最佳实践（Quota Management Best Practices）

原文档提供了三条可落地的实践，分别解决"看得到、早预警、不浪费"三个问题。

1. 定期监控用量（Monitor Usage Regularly）

记录剩余量、已用量与已用百分比，便于在日志或监控面板中观察趋势：

async function logQuotaUsage() {
  const response = await fetch(
    "https://api.heygen.com/v2/user/remaining_quota",
    { headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } }
  );

  const { data } = await response.json();

  console.log({
    remaining: data.remaining_quota,
    used: data.used_quota,
    percentUsed: (
      (data.used_quota / (data.remaining_quota + data.used_quota)) *
      100
    ).toFixed(1),
  });
}

注意分母的写法：remaining_quota + used_quota 恰好等于账户配额总量，因此 percentUsed 表示"总配额已消耗百分比"。随着积分不断消耗，remaining_quota 会持续下降，而 used_quota 持续上升，通过百分比比只看绝对余量更能反映配额的健康状态。

2. 设置告警（Set Up Alerts）

低于阈值即触发通知（邮件、Slack 等），把"被动失败"转成"主动补量"：

const QUOTA_WARNING_THRESHOLD = 50;

async function checkQuotaWithAlert() {
  const response = await fetch(
    "https://api.heygen.com/v2/user/remaining_quota",
    { headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } }
  );

  const { data } = await response.json();

  if (data.remaining_quota < QUOTA_WARNING_THRESHOLD) {
    // Send alert (email, Slack, etc.)
    await sendAlert(`Low HeyGen quota: ${data.remaining_quota} credits remaining`);
  }

  return data;
}

QUOTA_WARNING_THRESHOLD = 50 是一个经验阈值：它应当大于一次批量生产可能消耗的积分数，确保告警触发后仍来得及充值或排队，而不是告警与失败同时发生。sendAlert 是一个占位函数，实际接入时替换为你的通知通道。

3. 开发阶段使用测试模式（Use Test Mode for Development）

当接口可用时，优先用测试模式做开发联调，避免消耗真实积分：

const videoConfig = {
  test: true, // Use test mode during development
  video_inputs: [...],
};

// Test videos may have watermarks but don't consume credits

权衡点：测试视频可能带水印且不可商用，但不消耗积分。对于 OpenMontage 这类 Agent 驱动的高频迭代场景（"Video Agent is great for quick iterations"），这能让提示词试错、参数调优全部停留在测试模式中，只在最终生产时切换回正式计费。

八、订阅等级（Subscription Tiers）

不同的订阅等级对应不同的配额额度与功能边界：

Tier	Features
Free	Limited credits, basic features
Creator	More credits, standard avatars
Team	Higher limits, team collaboration
Enterprise	Custom limits, API access, priority support

原文档特别强调了一个对开发者至关重要的结论：API access typically requires Enterprise tier or higher.（API 访问通常需要 Enterprise 或更高等级）。这意味着：

• 如果你通过本文的 /v2/user/remaining_quota、/v1/video_agent/generate 等端点做程序化调用，请先确认当前订阅套餐是否包含 API 权限，否则即使积分充足，请求也会在鉴权阶段被拒绝；
• OpenMontage 仓库中的 heygen_video 工具（tools/video/heygen_video.py）通过检查 HEYGEN_API_KEY 环境变量是否存在来判定工具 AVAILABLE 状态，但"密钥存在"只代表凭据就绪，不代表套餐包含 API 额度——这也是文档建议把配额预检做成硬性前置步骤的原因。

九、配额问题的错误处理（Error Handling for Quota Issues）

当错误已经发生时，需要一套统一的分诊逻辑——识别配额类错误、给出处理建议、并回查当前余额：

async function handleQuotaError(error: any) {
  if (error.message.includes("quota") || error.message.includes("credit")) {
    console.error("Quota exceeded. Consider:");
    console.error("1. Upgrading your subscription");
    console.error("2. Waiting for quota reset");
    console.error("3. Purchasing additional credits");

    // Check current quota
    const quota = await getQuota();
    console.error(`Current remaining: ${quota.remaining_quota}`);
  }

  throw error;
}

要点：

• 关键词匹配：以 quota / credit 作为判别信号，命中后按"升级套餐 / 等待重置 / 购买积分"三条路径给出可操作建议；
• 错误后仍要 re-throw：处理配额提示后继续 throw error，不吞掉异常，保证上层调用链（如 OpenMontage 的 ToolResult 错误返回）能正确感知失败；
• 查询实时余额：用 getQuota() 读取当前 remaining_quota，把"错误发生时的精确余额"一并写入日志，作为后续调度的依据。

这套处理与仓库工具层的容错策略形成互补：在 tools/video/heygen_video.py 中，heygen_video 的 retry_policy 把 rate_limit、timeout、server_error 标记为可重试错误（最多 2 次、退避 10 秒），而 quota/credit 类错误不在重试列表内——因为充值不会在 10 秒退避内自动完成，重试只会加剧失败。这正是"配额错误应快速失败、限流错误可重试"的最佳分工。

十、在 OpenMontage 中的完整落地链路

综合以上各节，把配额管理嵌入 OpenMontage 的 create-video 工作流后，一个稳健的"提示词到视频"链路应为：

1. 凭据就绪：确认 HEYGEN_API_KEY 已注入（对应 SKILL.md 元信息的 primaryEnv 约束，以及 heygen_video.py 中 install_instructions 指向的密钥配置方式）；
2. 配额预检：调用 /v2/user/remaining_quota 读取 remaining_quota，按第五节消耗规则与目标分辨率/时长粗估所需积分，不足即中止（对应第六节 generateVideoWithQuotaCheck）；
3. 监控与告警：批量生产前调用 checkQuotaWithAlert，低于 QUOTA_WARNING_THRESHOLD 时提前通知（对应第七节）；
4. 发起生成：走 MCP 工具 mcp__heygen__generate_video_agent 或直连 POST /v1/video_agent/generate（详情见 video-agent.md）；
5. 轮询状态：以 GET /v2/videos/{video_id} 轮询直至完成并获取下载地址（详情见 video-status.md），开发联调时开启 test: true 避免消耗积分；
6. 失败分诊：遇 quota/credit 类错误执行 handleQuotaError，快速失败并上报余额，交由上层（订阅升级 / 等待重置 / 购买积分）决策。

若你需要对具体主播、逐场景脚本、多场景背景做精确控制，应改走 avatar-video Skill；而无论走哪条 Skill，quota.md 这套"查配额 → 估消耗 → 预检 → 监控 → 分诊"的方法论都同样适用，因为它面对的是同一个 HeyGen 积分账户。在 OpenMontage 的开源实现里，账户侧的积分硬约束与工具侧的 成本估算、重试策略、费用跟踪 共同构成了 Agent 视频生产从"预算"到"结算"的完整闭环。