# 查询令牌余额
> 按 Key 维度查询剩余额度
> 走 `/api/token/{id}` 管理接口
> `unlimited_quota` 为真时只看账户余额
`GET /api/token/{id}`
## 认证
- `Authorization` (string / 必填) — 账户相关接口走 New-API 的管理通道，需要**系统访问令牌**，与调用模型的 API Key 不是一回事。 在控制台「个人设置 → 安全设置 → 系统访问令牌」生成，请求头写成 `Authorization: Bearer YOUR_ACCESS_TOKEN`。
- `New-Api-User` (string / 必填) — 当前登录用户的 ID。值必须与令牌所属用户一致，否则返回 401。
## 路径与查询参数
先列出自己的 Key 拿到 `id`，再按 `id` 查具体额度。
- `id` (integer / 必填) — 路径参数，Key 的 ID。可从 `GET /api/token/` 的返回里取。
- `keyword` (string / 可选) — 列表接口的模糊搜索，按名称过滤 Key。
- `p` (integer / 可选) — 列表接口的页码，从 `1` 开始。
- `page_size` (integer / 可选) — 列表接口的每页条数，上限 `100`。
## 响应
返回 Key 对象，额度字段有三个：
```json
{
  "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` 禁用。
> **Note:** 
> `quota` 的换算比例由实例配置决定，New-API 默认 `500000` 额度 = `1` 美元。展示时用 `quota / 500000` 得到美元，具体数值以你所在实例的配置为准。
## 说明
额度分为三层：
| 层级 | 含义 |
|---|---|
| 账户余额 | 整个账号的总余额，`/api/user/self` 的 `quota` |
| Key 额度 | 单个 Key 的上限，本接口的 `remain_quota` |
| 单次请求成本 | 按 token 用量或按次扣费 |
本接口返回的是 Key 这一层。要看账户层，用[查询用户余额](user-balance.html)。
> **Note:** 
> 额度是实时扣减的。并发请求较多时，两次查询之间可能出现较小偏差，这不代表计费错误。
## 错误码
| HTTP | 含义 |
|---|---|
| 200 | 请求成功。Key 不存在时 `success` 为 `false` |
| 401 | 令牌缺失、无效，或 `New-Api-User` 与令牌归属不一致 |
| 403 | 该 Key 不属于当前用户 |
更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 使用示例
### 列出全部 Key
先拿到 `id`，再逐个查额度。列表接口本身也带 `remain_quota`，Key 不多时可以一次拿完。
### 查询单个 Key 的额度
适合做客户端余额预警：拿当前 Key 的 `id` 查 `remain_quota`。
### 在本地算剩余额度
`unlimited_quota` 为 `true` 时不要用 `remain_quota` 做判断，改用账户余额。
**查询令牌余额{Check key balance}::cURL**
```
curl --request GET \
  --url 'https://api.oairoute.com/api/token/12' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'New-Api-User: YOUR_USER_ID'
```
**查询令牌余额{Check key balance}::Python**
```
import requests

res = requests.get(
    "https://api.oairoute.com/api/token/12",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "New-Api-User": "YOUR_USER_ID",
    },
)
d = res.json()["data"]
if d["unlimited_quota"]:
    print("无限额度，受账户余额约束")
else:
    print("剩余 %.2f 美元" % (d["remain_quota"] / 500000))
```
**查询令牌余额{Check key balance}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/api/token/12", {
  method: "GET",
  headers: {
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
    "New-Api-User": "YOUR_USER_ID",
  },
});
const { data } = await res.json();
console.log(
  data.unlimited_quota
    ? "unlimited, bound by account balance"
    : `remaining $${(data.remain_quota / 500000).toFixed(2)}`,
);
```
**200 查询令牌余额{Check key balance}**
```
{
  "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"
  }
}
```