查询令牌余额

  • 按 Key 维度查询剩余额度
  • 走 /api/token/{id} 管理接口
  • unlimited_quota 为真时只看账户余额
GETapi/token/{id}

认证

string必填

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

string必填

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

路径与查询参数

先列出自己的 Key 拿到 id，再按 id 查具体额度。

integer必填

路径参数，Key 的 ID。可从 GET /api/token/ 的返回里取。

string可选

列表接口的模糊搜索，按名称过滤 Key。

integer可选

列表接口的页码，从 1 开始。

integer可选

列表接口的每页条数，上限 100。

响应

返回 Key 对象，额度字段有三个：

{
  "success": true,
  "message": "",
  "data": {
    "id": 12,
    "user_id": 1,
    "name": "prod-key",
    "key": "sk-abcd...wxyz",
    "status": 1,
    "remain_quota": 1500000,
    "unlimited_quota": false,
    "used_quota": 500000,
    "expired_time": -1,
    "model_limits_enabled": false,
    "model_limits": "",
    "group": "default"
  }
}
  • data.remain_quota (integer) — 该 Key 的剩余额度。
  • data.unlimited_quota (boolean) — 为 true 时忽略 remain_quota，只受账户余额约束。
  • data.used_quota (integer) — 该 Key 的累计已用额度。
  • data.expired_time (integer) — 过期时间戳，-1 表示永不过期。
  • data.model_limits_enabled / model_limits — 模型白名单开关与清单。
  • data.status (integer) — 1 启用，2 禁用。

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

说明

额度分为三层：

层级含义
账户余额整个账号的总余额，/api/user/self 的 quota
Key 额度单个 Key 的上限，本接口的 remain_quota
单次请求成本按 token 用量或按次扣费

本接口返回的是 Key 这一层。要看账户层，用查询用户余额。

额度是实时扣减的。并发请求较多时，两次查询之间可能出现较小偏差，这不代表计费错误。

错误码

HTTP含义
200请求成功。Key 不存在时 success 为 false
401令牌缺失、无效，或 New-Api-User 与令牌归属不一致
403该 Key 不属于当前用户

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

使用示例

列出全部 Key

先拿到 id，再逐个查额度。列表接口本身也带 remain_quota，Key 不多时可以一次拿完。

查询单个 Key 的额度

适合做客户端余额预警：拿当前 Key 的 id 查 remain_quota。

在本地算剩余额度

unlimited_quota 为 true 时不要用 remain_quota 做判断，改用账户余额。