用 GET /v1/credits 在代码中查询余额

· Hyperouter · 阅读约 3 分钟

请求由预付余额支付，余额不足以覆盖的请求会被拒绝，并返回 402 insufficient_credits。如果你希望在此之前就得知余额偏低，可以主动查询：GET /v1/credits 会返回你的余额，认证方式与其他调用相同，都使用同一个 API 密钥。

调用方式

curl https://api.hyperouter.app/v1/credits \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

响应包含三个字段，均为十进制美元字符串：

字段含义
balance_usd你的余额。
held_usd未完成的请求预扣的金额。
available_usd剩余可用额度。

Hyperouter 会在请求运行之前预扣其最高可能产生的费用，再按实际用量扣费，其余金额释放（计费与限制）。这就是 held_usd 存在的原因：请求进行期间，余额中有一部分不能动用。available_usd 是余额减去预扣金额，也是最值得关注的数字。

这是账户的余额

余额属于账户，而不是密钥，因此同一账户的所有密钥看到的数字都相同。设有额度上限的密钥，即使 available_usd 很大，也可能在达到该上限时被拒绝并返回 402 insufficient_credits。

这些字段是字符串，而不是浮点数。Hyperouter 对金额精确计数，字符串可以在你决定如何解析之前保持精确。在 Python 中，decimal.Decimal 可以直接读取它。在 TypeScript 中，如果少量精度对你无关紧要，可以用 Number(...) 转换后再比较；对于告警阈值来说，确实无关紧要。

缓存

响应带有 Cache-Control: private, no-store，因此遵循该响应头的代理或客户端不会缓存它。请每次都重新读取。

告警每分钟检查一次就足够了。余额只在请求结算和工作人员为充值入账时变化，都不需要更密集的轮询。

低余额告警

一个小脚本，可由 cron 或你已有的任何调度器运行：

import os
import sys
from decimal import Decimal

import requests

THRESHOLD = Decimal("5.00")  # USD; pick your own

res = requests.get(
    "https://api.hyperouter.app/v1/credits",
    headers={"Authorization": f"Bearer {os.environ['HYPEROUTER_API_KEY']}"},
    timeout=10,
)
res.raise_for_status()
credits = res.json()

available = Decimal(credits["available_usd"])
if available < THRESHOLD:
    print(f"Hyperouter balance low: {available} USD available", file=sys.stderr)
    sys.exit(1)

大多数调度器都能把非零退出码转成一条通知。用 TypeScript 实现同样的检查：

const res = await fetch("https://api.hyperouter.app/v1/credits", {
  headers: { Authorization: `Bearer ${process.env.HYPEROUTER_API_KEY}` },
});
if (!res.ok) throw new Error(`credits: HTTP ${res.status}`);

const { available_usd } = await res.json();
if (Number(available_usd) < 5) {
  console.error(`Hyperouter balance low: ${available_usd} USD available`);
  process.exitCode = 1;
}

如果调用本身返回 401，说明密钥缺失、格式错误、不存在或已停用；身份验证错误列出了每种情况。

充值

目前充值为人工处理。请在控制台中提交充值申请，附上金额、付款凭证编号和付款截图。工作人员核对付款后为你的余额入账。每笔充值收取所付金额 5.5% 的手续费，最低 $0.80，因此请把阈值设得足够高，给人工入账留出时间。

下一步

相关文章