> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询余额

> GET /v1/dashboard/billing/subscription —— 当前账户额度

返回当前账户(或令牌)的余额与配额信息。

## 请求

```bash theme={null}
curl https://openp.ai/v1/dashboard/billing/subscription \
  -H "Authorization: Bearer $OPENPAI_API_KEY"
```

## 响应

```json theme={null}
{
  "object": "billing_subscription",
  "has_payment_method": true,
  "soft_limit_usd": 100.0,
  "hard_limit_usd": 1000.0,
  "system_hard_limit_usd": 1000.0,
  "access_until": 4102444800,
  "plan": {"title": "vip", "id": "vip"}
}
```

字段含义:

| 字段                      | 含义                     |
| ----------------------- | ---------------------- |
| `hard_limit_usd`        | 账户(或令牌)硬性额度上限          |
| `soft_limit_usd`        | 软性额度阈值(触发提醒)           |
| `system_hard_limit_usd` | 系统级硬上限                 |
| `access_until`          | 账户访问截止 Unix 时间(0 表示永久) |
| `plan`                  | 当前分组                   |

## 与 OpenAI 官方差异

OpenPAI 的查询接口兼容 OpenAI 官方旧版结构。
若想得到更细粒度的信息(账户余额、当前令牌已消耗、已用额度等),推荐用 **专用接口**:

```bash theme={null}
# 查询账户级余额(单位:¥)
curl https://openp.ai/api/user/self \
  -H "Authorization: Bearer $OPENPAI_USER_TOKEN"
```

<Note>用户 token 与 API Key(sk-)是两套凭证 —— 用户 token 用于管理后台 API,sk- 用于模型调用。</Note>

## 客户端集成

很多客户端(如 NextChat、ChatBox)会自动调用 `/v1/dashboard/billing/subscription` 与 `/v1/dashboard/billing/usage` 来展示余额。
OpenPAI 同时实现了这两个接口以保证客户端 UI 可正常工作。