余额查询

BUZZ 暴露两个 OpenAI 风格的 dashboard billing 接口,让大量基于 OpenAI /dashboard/billing/* 的余额查询脚本和反代 UI 不改一行代码就能跑起来。返回的数字会按站点配置的展示单位输出。

鉴权

两个接口都需要用户 API token(从 BUZZ 控制台创建的 sk- 前缀 key)。走的是和 /v1/messages、/v1/chat/completions 同一条 relay token 鉴权链。

不需要 Buzz-User header,token 自身已绑定持有者。

QuotaDisplayType:数字怎么算出来的

BUZZ 内部统一以原始 quota 整数存储,只在响应这两个接口时换算成可读数字。换算规则取决于站点的 QuotaDisplayType 设置:

这意味着 subscription 响应里的 soft_limit_usd 和 usage 响应里的 total_usage 未必是美元。字段名为了 OpenAI 兼容性保留,但实际单位以站点展示设置为准。请把单位当成 opaque,与控制台展示的货币保持一致。

GET /v1/dashboard/billing/subscription

返回该 token(或者站点未启用 token 维度统计时返回该用户)的"剩余 + 已用"配额,按"信用额度"形态输出。这是大多数余额查询脚本轮询的路径。

数字来源

• 站点启用 token 维度统计 时:quota = token.RemainQuota + token.UsedQuota,access_until = token.ExpiredTime。
• 否则:quota = user.Quota + user.UsedQuota,access_until = 0。
• token 为无限额度时,响应数字会被覆写为 100000000。
• token 无过期时间时,access_until 强制为 0。

请求示例

curl -s 'https://buzzai.cc/v1/dashboard/billing/subscription' \
  -H "Authorization: Bearer sk-$BUZZ_TOKEN"

import os, requests

resp = requests.get(
    "https://buzzai.cc/v1/dashboard/billing/subscription",
    headers={"Authorization": f"Bearer sk-{os.environ['BUZZ_TOKEN']}"},
    timeout=10,
)
data = resp.json()
print(data["soft_limit_usd"], data["access_until"])

const resp = await fetch(
  "https://buzzai.cc/v1/dashboard/billing/subscription",
  { headers: { Authorization: `Bearer sk-${process.env.BUZZ_TOKEN}` } },
);
const data = await resp.json();
console.log(data.soft_limit_usd, data.access_until);

实测响应

{
  "object": "billing_subscription",
  "has_payment_method": true,
  "soft_limit_usd": 1234.622754,
  "hard_limit_usd": 1234.622754,
  "system_hard_limit_usd": 1234.622754,
  "access_until": 0
}

2026-05-26 实测,使用普通限额 token。三个 limit 字段同值;access_until = 0 对应无过期时间的 token。

响应字段

GET /v1/dashboard/billing/usage

返回当前 token(或用户)的累计已用配额。OpenAI 原始接口按时间段查询;BUZZ 这版返回的是单一累计数,忽略任何 query 参数。

数字来源

• 站点启用 token 维度统计 时:quota = token.UsedQuota。
• 否则:quota = GetUserUsedQuota(userId)。
• 同样按 QuotaDisplayType 换算得到 amount。
• 最终结果再乘 100:total_usage = amount * 100。源码注释把这个单位写成"0.01 dollar",即美元展示时是"美分"。CNY 展示时单位就是"分 × 汇率";Tokens 展示时是"token × 100"。

请求示例

curl -s 'https://buzzai.cc/v1/dashboard/billing/usage' \
  -H "Authorization: Bearer sk-$BUZZ_TOKEN"

import os, requests

resp = requests.get(
    "https://buzzai.cc/v1/dashboard/billing/usage",
    headers={"Authorization": f"Bearer sk-{os.environ['BUZZ_TOKEN']}"},
    timeout=10,
)
total_cents = resp.json()["total_usage"]
print(f"used: {total_cents / 100:.2f}")  # 除以 100 还原成展示单位

const resp = await fetch(
  "https://buzzai.cc/v1/dashboard/billing/usage",
  { headers: { Authorization: `Bearer sk-${process.env.BUZZ_TOKEN}` } },
);
const { total_usage } = await resp.json();
console.log(`used: ${(total_usage / 100).toFixed(2)}`);

实测响应

{
  "object": "list",
  "total_usage": 117621.9826
}

2026-05-26 实测。返回值是"展示单位 × 100",除以 100 即可还原 dashboard 上看到的数字。

响应字段

错误码

相关链接

• GET /api/user/self — 拿原始 quota 整数加 group / 邀请字段
• GET /api/token/ — 管理 sk- token
• 鉴权指南