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

# 账号余额查询 API

> 通过 API 查询账号余额，用于在自有系统中展示可用余额和历史消费

## 概述

平台提供专用的账号余额查询接口 `GET /api/user/balance`，返回当前剩余额度和累计已用额度。

<Note>
  此接口使用**个人资料访问令牌**认证，不是模型调用 API Key（`sk-xxx`）。两者用途不同，请勿混淆。
</Note>

余额响应同时包含原始额度字段和展示金额字段。原始额度字段始终以 `quota` 为单位；展示金额只用于前端展示，不改变账号额度、扣费或计费口径。

## 认证方式

在个人资料页生成或重置**个人资料访问令牌**，通过 `Authorization` header 传递：

```bash theme={null}
curl -H "Authorization: Bearer <你的个人资料访问令牌>" \
  https://models.phanedge.cloud/api/user/balance
```

<Warning>
  模型调用 API Key（`sk-xxx` 开头）**无法**访问此接口。请确保使用个人资料访问令牌。
</Warning>

## 响应示例

### 金额展示启用时

```json theme={null}
{
  "success": true,
  "message": "",
  "data": {
    "quota": 1000000,
    "used_quota": 500000,
    "balance_quota": 1000000,
    "quota_unit": "quota",
    "display": {
      "enabled": true,
      "currency": "CNY",
      "balance": 14.0,
      "used": 7.0
    }
  }
}
```

### 金额展示禁用时

```json theme={null}
{
  "success": true,
  "message": "",
  "data": {
    "quota": 1000000,
    "used_quota": 500000,
    "balance_quota": 1000000,
    "quota_unit": "quota",
    "display": {
      "enabled": false
    }
  }
}
```

## 字段说明

| 字段                 | 类型     | 说明                            |
| ------------------ | ------ | ----------------------------- |
| `quota`            | int    | 当前剩余额度（原始值）                   |
| `used_quota`       | int    | 累计已用额度（原始值）                   |
| `balance_quota`    | int    | 当前剩余余额，等于 `quota`             |
| `quota_unit`       | string | 固定值 `"quota"`，标识原始字段单位        |
| `display.enabled`  | bool   | 金额展示是否启用                      |
| `display.currency` | string | 货币标识，跟随个人设置，默认 `"CNY"`（启用时返回） |
| `display.balance`  | float  | 剩余余额金额（启用时返回，6位小数）            |
| `display.used`     | float  | 已用金额（启用时返回，6位小数）              |

<Tip>
  推荐使用 `data.display.balance` 直接展示余额金额；如需原始额度值用于自定义计算，使用 `data.balance_quota`。展示币种可在「个人资料」页面的“额度展示币种”中调整，默认人民币 `CNY`。该设置只影响 `display` 展示字段，不影响原始 quota 数值和实际计费。
</Tip>

## 与其他接口的区别

| 接口                                       | 认证方式                  | 用途                                    |
| ---------------------------------------- | --------------------- | ------------------------------------- |
| `GET /api/user/balance`                  | 个人资料访问令牌              | **推荐** — 专用余额查询                       |
| `GET /api/user/self`                     | 个人资料访问令牌              | 兼容 — 返回完整用户资料（含 `quota`/`used_quota`） |
| `GET /v1/dashboard/billing/subscription` | 模型 API Key (`sk-xxx`) | OpenAI 兼容 — 返回令牌视角额度，非账号余额            |

## 常见问题

<AccordionGroup>
  <Accordion title="个人资料访问令牌在哪里获取？">
    登录平台后，进入「个人资料」页面，点击「生成访问令牌」即可获取。
  </Accordion>

  <Accordion title="为什么用 sk-xxx 调用返回认证失败？">
    `sk-xxx` 是模型调用 API Key，只能用于 `/v1/` 下的模型请求接口。账号余额查询需要使用个人资料访问令牌；用 `sk-xxx` 调用此接口返回认证失败是预期行为。
  </Accordion>

  <Accordion title="展示币种会影响扣费吗？">
    不会。展示币种只影响 `display.currency`、`display.balance` 和 `display.used` 等展示字段。`quota`、`used_quota` 和 `balance_quota` 仍是原始额度值，实际扣费和额度计算不受展示币种影响。
  </Accordion>

  <Accordion title="balance_quota 和 quota 有什么区别？">
    两者值相同。`balance_quota` 是为余额展示场景提供的语义更清晰的字段名。
  </Accordion>

  <Accordion title="display 禁用时如何计算金额？">
    `display.enabled` 为 `false` 时，平台未对外提供可直接展示的金额字段。此时请保留原始 `quota` 值用于额度判断，不要假设站点的金额换算配置。
  </Accordion>
</AccordionGroup>