余额怎么查

渊站有三种「余额」，查之前先分清是哪一个。

三种余额

层级	含义	用什么查
账户余额	钱包里的钱，所有 Key 共用	个人访问令牌 → /api/user/self
订阅额度	套餐里剩的额度	个人访问令牌 → /api/subscription/self
密钥余额	某一把 Key 自己的计数器	用这把 Key 本身 → /api/usage/token/

两个很容易搞混的坑

1. API Key 查不了账户余额。 拿 sk- 去调 /api/user/self 会返回 401。
2. 访问令牌查不了密钥余额。 scoped 令牌调 /api/usage/token/ 会被拒绝。

想都查，就得准备两样东西：一把 API Key，加一个个人访问令牌。

一、为什么要个人访问令牌

sk- 密钥是用来调模型的，权限很大但不能查账户信息。

查账户信息需要「个人访问令牌」（PAT），它是另一套东西：

位置：侧边栏 → 安全与访问 → 访问令牌 → 创建访问令牌

创建时必须勾权限，不勾就是 403：

你想查	要勾的权限
账户余额	个人 → 个人资料 → 查看（profile:read）
订阅额度	个人 → 钱包 → 查看（wallet:read）
密钥列表	个人 → API 密钥 → 查看（api_key:read）
用量日志	个人 → 用量 → 查看（usage:read）

令牌以 nap_ 开头，只显示一次。

二、查账户余额

curl https://api.syuan.org/api/user/self \
  -H "Authorization: Bearer nap_你的令牌"

{
  "success": true,
  "data": {
    "id": 380,
    "username": "someone",
    "group": "Gemini",
    "quota": 500000,
    "used_quota": 12345,
    "request_count": 7
  }
}

字段	含义
quota	账户剩余额度
used_quota	历史已用
request_count	累计请求数
group	所属分组，可能是逗号分隔的多个
aff_quota	可提现的邀请返利

换算：500000 额度 = $1。

只要数字的话：

curl -s https://api.syuan.org/api/user/self \
  -H "Authorization: Bearer nap_你的令牌" \
  | jq '{剩余额度: .data.quota, 已用: .data.used_quota, 折合美元: (.data.quota / 500000)}'

三、查某把 Key 的余额

curl https://api.syuan.org/api/usage/token/ \
  -H "Authorization: Bearer sk-你的密钥"

{
  "code": true,
  "data": {
    "name": "doc-key",
    "total_granted": 438889,
    "total_used": 6789,
    "total_available": 432100,
    "unlimited_quota": false,
    "expires_at": 0
  }
}

字段	含义
total_available	这把 Key 剩余
total_used	这把 Key 已用
unlimited_quota	是否无限额度
expires_at	过期时间，0 = 永不过期
model_limits	限制的模型，空 = 不限

这个数不是账户余额

一把 Key 的 total_available 只反映它自己经历过多少消耗，不是账户还有多少钱。

真正能花多少，看账户余额。

四、列出所有 Key

curl 'https://api.syuan.org/api/token/?p=1&page_size=100' \
  -H "Authorization: Bearer nap_你的令牌"

需要 api_key:read 权限。

五、OpenAI 兼容的计费接口

有些第三方客户端会调这两个，也支持：

GET /v1/dashboard/billing/subscription
GET /v1/dashboard/billing/usage

用 sk- 密钥即可。返回的是 OpenAI 那种 hard_limit_usd / total_usage 结构。

什么时候该查哪个

你想知道	查这个
我还有多少钱	/api/user/self 的 quota
我这把 Key 用了多少	/api/usage/token/
我的套餐还剩多少	/api/subscription/self
套餐的窗口限制	同上，看 weekly_window_*

订阅额度的细节在 订阅的实际额度。