# 查询用户余额
> 返回整个账户的可用余额与已用额度
> 走 `/api/user/self`，需要系统访问令牌
> 与「查询令牌余额」不同，这里是账户层
`GET /api/user/self`
## 认证
- `Authorization` (string / 必填) — 账户相关接口走 New-API 的管理通道，需要**系统访问令牌**，与调用模型的 API Key 不是一回事。 在控制台「个人设置 → 安全设置 → 系统访问令牌」生成，请求头写成 `Authorization: Bearer YOUR_ACCESS_TOKEN`。
- `New-Api-User` (string / 必填) — 当前登录用户的 ID。值必须与令牌所属用户一致，否则返回 401。
## 响应
返回当前登录用户的账户信息，余额字段是 `quota` 与 `used_quota`：
```json
{
  "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`。
> **Note:** 
> `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 | 令牌无权访问该接口 |
更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 使用示例
### 查询账户余额
不带参数时返回整个账号的余额汇总，这是做充值提醒最直接的接口。
### 只取关键字段
返回里字段较多，实际关心的通常只有可用余额与累计消耗，用 `jq` 过滤一下更清楚。
```bash
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 的额度是两个层级。排查「为什么调用失败」时，两边都查一遍能快速定位是哪一层不够。
## 使用示例
**查询用户余额{Get user balance}::cURL**
```
curl --request GET \
  --url 'https://api.oairoute.com/api/user/self' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'New-Api-User: YOUR_USER_ID'
```
**查询用户余额{Get user balance}::Python**
```
import requests

res = requests.get(
    "https://api.oairoute.com/api/user/self",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "New-Api-User": "YOUR_USER_ID",
    },
)
d = res.json()["data"]
print("可用 %.2f 美元" % (d["quota"] / 500000))
print("已用 %.2f 美元" % (d["used_quota"] / 500000))
```
**查询用户余额{Get user balance}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/api/user/self", {
  method: "GET",
  headers: {
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
    "New-Api-User": "YOUR_USER_ID",
  },
});
const { data } = await res.json();
console.log(`available $${(data.quota / 500000).toFixed(2)}`);
console.log(`used $${(data.used_quota / 500000).toFixed(2)}`);
```
**200 查询用户余额{Get user balance}**
```
{
  "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
  }
}
```