# 查询余额

> 查询账户余额和额度使用情况。

Canonical URL: https://docs.uniai.tv/balance
Locale: zh-CN

## 1. 接口说明

该接口用于通过普通 API Key 查询：

- 当前 API Key 所属的用户 ID
- 用户账户余额
- 用户余额按站点配置换算后的展示金额
- 当前这把 API Key 的额度信息

该接口使用普通 `sk-...` API Key 调用，不需要用户登录态。

---

## 2. 请求信息

| 项目 | 内容 |
| --- | --- |
| 请求方法 | `GET` |
| 请求路径 | `/api/usage/balance` |
| 鉴权方式 | `Authorization: Bearer sk-xxx` |
| Content-Type | 无请求体，可不传 |

---

## 3. 请求示例

```bash
curl -X GET "https://api.uniai.tv/api/usage/balance" \
  -H "Authorization: Bearer sk-your-api-key"
```

---

## 4. 成功响应示例

```json
{
  "success": true,
  "message": "",
  "data": {
    "object": "api_key_balance",
    "user_id": 1,
    "balance": {
      "quota": 1000000,
      "amount": 14.6,
      "display_amount": "¥14.60",
      "quota_per_unit": 500000,
      "quota_display_type": "CNY",
      "currency_symbol": "¥",
      "exchange_rate": 7.3
    },
    "token": {
      "id": 12,
      "name": "my-key",
      "remain_quota": 100000,
      "used_quota": 5000,
      "total_quota": 105000,
      "unlimited_quota": false,
      "expired_time": -1,
      "status": 1,
      "model_limits_enabled": false,
      "model_limits": {}
    }
  }
}
```

---

## 5. 响应参数说明

### 5.1 顶层参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `success` | boolean | 请求是否成功 |
| `message` | string | 响应消息，成功时通常为空字符串 |
| `data` | object | 响应数据 |

### 5.2 `data` 参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `data.object` | string | 对象类型，固定为 `api_key_balance` |
| `data.user_id` | number | 当前 API Key 所属的用户 ID |
| `data.balance` | object | 用户账户余额信息 |
| `data.token` | object | 当前 API Key 的额度信息 |

### 5.3 `data.balance` 参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `data.balance.quota` | number | 用户账户原始额度，系统内部额度单位 |
| `data.balance.amount` | number | 按站点展示配置换算后的余额金额 |
| `data.balance.display_amount` | string | 格式化后的展示金额，通常包含货币符号 |
| `data.balance.quota_per_unit` | number | 额度换算单位，例如 `500000` 表示 `500000 quota = 1 USD` |
| `data.balance.quota_display_type` | string | 余额展示类型，可能值：`USD`、`CNY`、`CUSTOM`、`TOKENS` |
| `data.balance.currency_symbol` | string | 当前展示货币符号，例如 `$`、`¥`；当展示类型为 `TOKENS` 时为空字符串 |
| `data.balance.exchange_rate` | number | 当前展示币种使用的汇率；`USD` 通常为 `1`，`CNY` 为人民币汇率，`CUSTOM` 为自定义汇率 |

### 5.4 `data.token` 参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `data.token.id` | number | 当前 API Key 的 ID |
| `data.token.name` | string | 当前 API Key 的名称 |
| `data.token.remain_quota` | number | 当前 API Key 剩余额度 |
| `data.token.used_quota` | number | 当前 API Key 已使用额度 |
| `data.token.total_quota` | number | 当前 API Key 总额度，计算方式为 `remain_quota + used_quota` |
| `data.token.unlimited_quota` | boolean | 当前 API Key 是否为无限额度 |
| `data.token.expired_time` | number | 当前 API Key 过期时间戳；`-1` 表示不过期 |
| `data.token.status` | number | 当前 API Key 状态；`1` 表示启用 |
| `data.token.model_limits_enabled` | boolean | 当前 API Key 是否启用模型限制 |
| `data.token.model_limits` | object | 当前 API Key 的模型限制配置；未限制时通常为空对象 `{}` |

---

---

## 6. 错误响应

### 6.1 未传 API Key

HTTP 状态码：`401`

```json
{
  "success": false,
  "message": "Token not provided"
}
```

### 6.2 API Key 不存在或无效

HTTP 状态码：`401`

```json
{
  "success": false,
  "message": "Invalid token"
}
```

### 6.3 API Key 已禁用

HTTP 状态码：`403`

```json
{
  "success": false,
  "message": "Token invalid"
}
```

---

## 7. 调用注意事项

- 必须使用 `Authorization: Bearer sk-xxx` 传入 API Key。
- 返回的是 API Key 所属用户的账户余额，不是上游渠道余额。
- 接口不会返回原始 API Key 字符串。
- 已禁用的 API Key 不能查询余额。
- API Key 已过期或额度耗尽时，仍可查询余额，只要 Key 未禁用且用户未被封禁。
- `amount` 和 `display_amount` 会根据站点当前余额展示配置动态变化。