余额查询

下面三个接口都用你的 sk- API key 鉴权——和调用 /v1/messages、/v1/chat/completions 用的是同一把 key。其中两个 /v1/dashboard/billing/* 接口对齐 OpenAI 旧版 dashboard 形状,现成的余额查询脚本和反代 UI 不改代码就能用;/api/usage/token/ 是 BUZZ 原生接口,把额度拆成剩余 / 已用 / 总授予三部分。

鉴权

两个接口都需要用户 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": 1,
  "hard_limit_usd": 1,
  "system_hard_limit_usd": 1,
  "access_until": 0
}

2026-06-09 实测,普通限额 token(USD 展示)。三个 limit 字段同值;站点未启用 token 维度统计,所以这里不暴露 token 过期时间,access_until = 0。

响应字段

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": 13.6228
}

2026-06-09 实测(与上面同一个 token)。返回值是"展示单位 × 100",除以 100 即可还原 dashboard 上看到的数字(此处约为已用 $0.136)。

响应字段

GET /api/usage/token/

BUZZ 原生接口,把当前 token 的额度拆成三部分返回——总授予、已用、剩余——不做任何货币换算。返回的是原始 quota 单位(和内部存储的整数一致;除以 QuotaPerUnit,默认 500000,即得美元)。这是查单把 key 剩余额度最直接的方式。

数字来源

• total_granted = token.RemainQuota + token.UsedQuota
• total_used = token.UsedQuota
• total_available = token.RemainQuota
• expires_at = token.ExpiredTime,无过期时强制为 0。
• 无限额度 token:unlimited_quota 为 true,三个额度数字均为 0(没有有限额度可报告)。

请求示例

curl -s 'https://buzzai.cc/api/usage/token/' \
  -H "Authorization: Bearer sk-$BUZZ_TOKEN"

import os, requests

resp = requests.get(
    "https://buzzai.cc/api/usage/token/",
    headers={"Authorization": f"Bearer sk-{os.environ['BUZZ_TOKEN']}"},
    timeout=10,
)
d = resp.json()["data"]
print(d["total_available"] / 500000, "USD 剩余")  # 除以 QuotaPerUnit

const resp = await fetch(
  "https://buzzai.cc/api/usage/token/",
  { headers: { Authorization: `Bearer sk-${process.env.BUZZ_TOKEN}` } },
);
const { data } = await resp.json();
console.log(data.total_available / 500000, "USD 剩余");

实测响应

{
  "code": true,
  "message": "ok",
  "data": {
    "object": "token_usage",
    "name": "claude",
    "total_granted": 500000,
    "total_used": 68114,
    "total_available": 431886,
    "unlimited_quota": false,
    "model_limits_enabled": false,
    "model_limits": {},
    "expires_at": 1781502010
  }
}

2026-06-09 实测。total_granted = total_used + total_available(500000 = 68114 + 431886)。任一字段除以 QuotaPerUnit(500000)即换算成美元——此处约为 $1.00 授予额度下剩余 $0.864。

响应字段

错误码

相关链接

• GET /api/user/self — 完整 profile(也含原始 quota 整数),但用账户 access token + Buzz-User header 鉴权,不是 sk- key
• GET /api/token/ — 管理 sk- token
• 鉴权指南 — access token 与 sk- API key 的区别