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

# 余额查询 API

> 通过系统令牌 AccessToken 查询老张API账户的 quota、used_quota、request_count 与用户分组，用于开发者监控、余额告警和账务排查。

## 接口概述

余额查询 API 用于读取当前账户的剩余额度、已使用额度、请求次数和用户分组。它适合接入后台监控、余额告警、账务排查脚本和内部运营面板。

<Info>
  此接口使用系统令牌 AccessToken 认证，不是普通模型调用用的 API Key。AccessToken 权限更高，生产环境请放在服务端密钥管理系统或环境变量中，不要下发到浏览器或客户端 App。
</Info>

## 获取 Authorization

<Steps>
  <Step title="进入账户设置">
    登录 [老张API 控制台](https://api.laozhang.ai/account/profile)，打开账户设置页面。
  </Step>

  <Step title="打开系统令牌">
    在账户设置中选择「系统令牌」，按页面提示进行密码验证。
  </Step>

  <Step title="保存 AccessToken">
    令牌生成后请立即复制到安全位置。生成新令牌后，旧令牌可能立即失效。
  </Step>
</Steps>

<Warning>
  不要在代码仓库、前端页面、日志、截图或工单里暴露完整 AccessToken。向技术支持排查时，只保留 Header 名称、请求时间、HTTP 状态码和已打码的令牌片段即可。
</Warning>

## 接口信息

| 项目     | 说明                                      |
| ------ | --------------------------------------- |
| 接口 URL | `https://api.laozhang.ai/api/user/self` |
| 请求方法   | `GET`                                   |
| 认证方式   | `Authorization` Header                  |
| 请求参数   | 无                                       |
| 响应格式   | JSON；使用 cURL 时建议加 `--compressed`        |

## 请求说明

### 请求 Headers

| Header 名称       | 必填 | 说明                         |
| --------------- | -- | -------------------------- |
| `Authorization` | 是  | 系统令牌 AccessToken，直接填写令牌字符串 |
| `Accept`        | 否  | 建议设置为 `application/json`   |
| `Content-Type`  | 否  | 建议设置为 `application/json`   |

### 请求参数

此接口不需要 Query 参数，也不需要请求体。生产代码中不要把余额阈值、告警渠道或业务标签拼到接口 URL 上；这些应保存在你的监控系统配置里。

## 响应说明

### 成功响应示例

```json theme={null}
{
  "success": true,
  "message": null,
  "data": {
    "id": 19489,
    "username": "demo_user",
    "display_name": "demo_user",
    "role": 1,
    "status": 1,
    "email": "",
    "quota": 24997909,
    "used_quota": 10027091,
    "request_count": 339,
    "group": "svip",
    "ModelFixedPrice": []
  }
}
```

### 核心响应字段

| 字段名                    | 类型            | 说明                  |
| ---------------------- | ------------- | ------------------- |
| `success`              | Boolean       | 请求是否成功              |
| `message`              | String / null | 错误信息；成功时通常为 `null`  |
| `data.username`        | String        | 用户名                 |
| `data.display_name`    | String        | 显示名称                |
| `data.quota`           | Integer       | 当前剩余额度，适合做告警阈值      |
| `data.used_quota`      | Integer       | 已使用额度               |
| `data.request_count`   | Integer       | 累计请求次数              |
| `data.group`           | String        | 当前账户分组              |
| `data.ModelFixedPrice` | Array         | 模型价格列表；只查余额时可以忽略    |
| `data.access_token`    | String        | 敏感字段；如果返回，请不要写入普通日志 |

<Tip>
  接口可能随账户状态返回更多字段。开发时请只依赖业务需要的核心字段，并允许响应中出现未知字段，避免因为新增字段导致解析失败。
</Tip>

## 额度与金额计算

接口返回的 `quota` 单位是「额度」，不是直接的美元金额。当前余额展示按以下规则换算：

| 计算项     | 公式                            | 示例                                            |
| ------- | ----------------------------- | --------------------------------------------- |
| 剩余美元余额  | `quota ÷ 50 万`                | `24997909 ÷ 50 万 = 49.995818`，约等于 `50.00 USD` |
| 已使用美元额度 | `used_quota ÷ 50 万`           | `10027091 ÷ 50 万 = 20.054182`，约等于 `20.05 USD` |
| 历史总额度   | `(quota + used_quota) ÷ 50 万` | 示例约等于 `70.05 USD`                             |

也就是说，`50 万`额度约等于 `1 USD`。如果接口返回 `quota: 24997909`，用户当前可用余额约为 `50.00 USD`。

<Tip>
  余额展示可以按上述公式计算；模型实际扣费仍要以当前模型价格、账户分组、调用日志和控制台展示为准。生产告警建议同时保存原始 `quota` 和换算后的美元金额，避免后续排查时丢失精度。
</Tip>

## 代码示例

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    export LAOZHANG_ACCESS_TOKEN='YOUR_ACCESS_TOKEN'

    curl --compressed -s 'https://api.laozhang.ai/api/user/self' \
      -H 'Accept: application/json' \
      -H "Authorization: ${LAOZHANG_ACCESS_TOKEN}" \
      -H 'Content-Type: application/json'
    ```

    `--compressed` 会让 cURL 自动处理 gzip 响应。如果少了这个选项，终端可能显示乱码，`jq` 也可能报 `Invalid numeric literal`。
  </Tab>

  <Tab title="jq 提取">
    ```bash theme={null}
    export LAOZHANG_ACCESS_TOKEN='YOUR_ACCESS_TOKEN'

    curl --compressed -s 'https://api.laozhang.ai/api/user/self' \
      -H 'Accept: application/json' \
      -H "Authorization: ${LAOZHANG_ACCESS_TOKEN}" \
      -H 'Content-Type: application/json' | \
      jq '.data | {
        quota,
        remaining_usd: (.quota / (50 * 10000)),
        used_quota,
        used_usd: (.used_quota / (50 * 10000)),
        request_count,
        group
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import requests

    token = os.environ["LAOZHANG_ACCESS_TOKEN"]
    response = requests.get(
        "https://api.laozhang.ai/api/user/self",
        headers={
            "Accept": "application/json",
            "Authorization": token,
            "Content-Type": "application/json",
        },
        timeout=10,
    )
    response.raise_for_status()

    payload = response.json()
    account = payload["data"]
    quota_unit_per_usd = 50 * 10000

    print("quota:", account["quota"])
    print("remaining_usd:", round(account["quota"] / quota_unit_per_usd, 2))
    print("used_quota:", account["used_quota"])
    print("used_usd:", round(account["used_quota"] / quota_unit_per_usd, 2))
    print("request_count:", account["request_count"])
    print("group:", account.get("group"))
    ```

    Python `requests` 会自动处理 gzip 解压。
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const token = process.env.LAOZHANG_ACCESS_TOKEN;

    const response = await fetch("https://api.laozhang.ai/api/user/self", {
      method: "GET",
      headers: {
        Accept: "application/json",
        Authorization: token,
        "Content-Type": "application/json",
      },
    });

    if (!response.ok) {
      throw new Error(`Balance query failed: HTTP ${response.status}`);
    }

    const payload = await response.json();
    const account = payload.data;
    const quotaUnitPerUsd = 50 * 10000;

    console.log({
      quota: account.quota,
      remaining_usd: Number((account.quota / quotaUnitPerUsd).toFixed(2)),
      used_quota: account.used_quota,
      used_usd: Number((account.used_quota / quotaUnitPerUsd).toFixed(2)),
      request_count: account.request_count,
      group: account.group,
    });
    ```
  </Tab>
</Tabs>

## 错误响应

### HTTP 401 - 认证失败

```json theme={null}
{
  "success": false,
  "message": "Unauthorized"
}
```

常见原因是 `Authorization` 为空、令牌复制不完整、令牌已失效，或误用了普通 API Key。

### HTTP 403 - 权限不足

```json theme={null}
{
  "success": false,
  "message": "Forbidden"
}
```

常见原因是当前令牌无权访问账户信息接口，或账户状态需要人工确认。

### 响应乱码或 jq 报错

如果 cURL 返回乱码，或 `jq` 报 `Invalid numeric literal`，通常是 gzip 响应没有被解压。请确认命令包含 `--compressed`。

## 监控接入建议

* 用环境变量或密钥管理服务保存 `LAOZHANG_ACCESS_TOKEN`
* 设置合理超时时间，例如 10 秒
* 避免高频轮询；一般余额监控不需要秒级请求
* 告警里记录 `quota`、换算后的 `remaining_usd`、`used_quota`、`request_count`、请求时间和 HTTP 状态码
* 不要在日志中记录完整 `Authorization`、`access_token` 或账户敏感字段

## 相关文档

* 如果只想看常见问题版说明，请查看[如何通过 API 查询账户余额](/faq/balance-query-api)
* 如果余额仍然充足但请求失败，请查看[为什么还有余额跑不通？](/faq/balance-insufficient)
* 如果需要核对单次请求的模型、Token 和计费，请查看[如何查看我的调用记录？](/faq/call-logs)