查询用户余额

  • 返回整个账户的可用余额与已用额度
  • 走 /api/user/self，需要系统访问令牌
  • 与单 Key 额度是两个层级
GETapi/user/self

认证

string必填

账户相关接口走 New-API 的管理通道，需要系统访问令牌，与调用模型的 API Key 不是一回事。在控制台「个人设置 → 安全设置 → 系统访问令牌」生成，请求头写成 Authorization: Bearer YOUR_ACCESS_TOKEN。

string必填

当前登录用户的 ID。值必须与令牌所属用户一致，否则返回 401。

响应

返回当前登录用户的账户信息，余额字段是 quota 与 used_quota：

{
  "success": true,
  "message": "",
  "data": {
    "id": 1,
    "username": "alice",
    "display_name": "Alice",
    "quota": 4210500,
    "used_quota": 789500,
    "request_count": 1579,
    "group": "default",
    "aff_quota": 0,
    "aff_history_quota": 0,
    "created_at": 1757469067,
    "last_login_at": 1763088200
  }
}
  • data.quota (integer) — 当前可用余额，单位是平台额度。
  • data.used_quota (integer) — 累计已用额度，不会因充值清零。
  • data.request_count (integer) — 累计请求次数。
  • data.group (string) — 用户分组，决定可用模型与倍率。
  • data.aff_quota / data.aff_history_quota (integer) — 邀请返利余额与历史返利。
  • success / message (boolean / string) — 通用信封，失败时 success 为 false。

quota 的换算比例由实例配置决定，New-API 默认 500000 额度 = 1 美元。展示时用 quota / 500000 得到美元，具体数值以你所在实例的配置为准。

与 Key 额度的对应关系

账户余额是总池子，每个 API Key 可以从池子里单独划一个上限：

账户余额（本接口 quota）
  ├── Key A 额度（remain_quota）
  └── Key B 额度（remain_quota）

Key 设了上限时，能花的不超过上限；设为无限额度时，受账户余额约束。

错误码

HTTP含义
200请求成功。业务失败时 success 为 false，message 给出原因
401令牌缺失、无效，或 New-Api-User 与令牌归属不一致
403令牌无权访问该接口

更多状态码与重试建议见错误码与限流，常见报错的排查步骤见常见问题。

使用示例

查询账户余额

不带参数时返回整个账号的余额汇总，这是做充值提醒最直接的接口。

只取关键字段

返回里字段较多，实际关心的通常只有可用余额与累计消耗，用 jq 过滤一下更清楚。

curl -s --request GET \
  --url 'https://api.oairoute.com/api/user/self' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "New-Api-User: $USER_ID" \
  | jq '.data | {available: .quota, used: .used_quota, requests: .request_count}'

对照单 Key 额度

账户余额与单个 Key 的额度是两个层级。排查「为什么调用失败」时，两边都查一遍能快速定位是哪一层不够。