> ## 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 查询账户余额

> 介绍如何获取老张API系统令牌 AccessToken，并通过余额查询 API 读取 quota、used_quota、请求次数和用户分组，用于余额监控和告警。

## 简短答案

可以通过 `https://api.laozhang.ai/api/user/self` 查询老张API账户余额。调用前需要在账户设置中生成系统令牌 AccessToken，并在请求头中传入 `Authorization`；使用 cURL 时建议加上 `--compressed`，否则 gzip 响应可能显示为乱码。

<Card title="查看完整余额查询 API 文档" icon="book-open" href="/api-capabilities/balance-query">
  如果您正在接入生产监控或需要完整字段说明、错误处理和代码示例，请优先阅读开发者接口文档。
</Card>

## 获取系统令牌（AccessToken）

在调用余额查询接口之前，您需要先获取系统令牌（AccessToken）。

<Steps>
  <Step title="进入账户设置页面">
    登录后访问 [账户设置页面](https://api.laozhang.ai/account/profile)，点击「系统令牌」选项。

    <img src="https://mintcdn.com/laozhangai-edd05f2c/3TifovFJrpEZVEaF/images/balance-query-step1.png?fit=max&auto=format&n=3TifovFJrpEZVEaF&q=85&s=048c552bb80d0b0ab86fb3e67f203971" alt="系统令牌入口" width="1676" height="662" data-path="images/balance-query-step1.png" />
  </Step>

  <Step title="验证账户密码">
    在弹出的对话框中输入您的账户密码进行身份验证。

    <img src="https://mintcdn.com/laozhangai-edd05f2c/3TifovFJrpEZVEaF/images/balance-query-step2.png?fit=max&auto=format&n=3TifovFJrpEZVEaF&q=85&s=83c69a544330742ef3bc9214a1c0bac2" alt="输入密码验证" width="1036" height="658" data-path="images/balance-query-step2.png" />
  </Step>

  <Step title="获取 AccessToken">
    验证成功后，系统会显示您的 AccessToken。请立即复制保存。

    <img src="https://mintcdn.com/laozhangai-edd05f2c/3TifovFJrpEZVEaF/images/balance-query-step3.png?fit=max&auto=format&n=3TifovFJrpEZVEaF&q=85&s=19154f8f706840d45733dfc4047c1971" alt="获取Token结果" width="1020" height="460" data-path="images/balance-query-step3.png" />
  </Step>
</Steps>

<Warning>
  **安全警告**：

  * AccessToken 具有账户完全权限，请妥善保管
  * Token 只在创建时显示一次，无法再次查询
  * 生成新 Token 会使旧 Token 立即失效
  * 切勿在代码中硬编码或提交到公开仓库
</Warning>

## 接口说明

### 接口信息

| 项目     | 说明                                      |
| ------ | --------------------------------------- |
| 接口 URL | `https://api.laozhang.ai/api/user/self` |
| 请求方法   | GET                                     |
| 认证方式   | Authorization Header                    |
| 响应格式   | JSON (gzip 压缩)                          |

### 请求 Headers

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

### 响应字段说明

成功响应示例：

```json theme={null}
{
  "success": true,
  "message": null,
  "data": {
    "username": "your_username",
    "display_name": "Your Name",
    "quota": 24997909,
    "used_quota": 10027091,
    "request_count": 339,
    "group": "svip"
  }
}
```

核心字段：

| 字段名                  | 类型      | 说明                    |
| -------------------- | ------- | --------------------- |
| success              | Boolean | 请求是否成功                |
| message              | String  | 错误信息（成功时为 null）       |
| data.quota           | Integer | 剩余额度（当前可用余额）          |
| data.used\_quota     | Integer | 已使用额度                 |
| data.request\_count  | Integer | 总请求次数                 |
| data.group           | String  | 用户所属组                 |
| data.ModelFixedPrice | Array   | 模型价格列表；只查余额时可以忽略      |
| data.access\_token   | String  | 敏感字段；如果接口返回，请不要写入普通日志 |

<Warning>
  响应可能随账户状态返回更多字段。请只依赖 `quota`、`used_quota`、`request_count`、`group` 等业务需要的核心字段，并允许未知字段存在；如果出现 `access_token` 等敏感字段，不要写入普通日志或告警正文。
</Warning>

### 额度和金额换算

<Tip>
  `quota` 和 `used_quota` 返回的是额度单位。当前余额展示按 `50 万`额度约等于 `1 USD` 换算：

  * 剩余美元余额：`quota ÷ 50 万`
  * 已使用美元额度：`used_quota ÷ 50 万`
  * 历史总额度：`(quota + used_quota) ÷ 50 万`

  例如接口返回 `quota: 24997909`，则剩余余额为 `24997909 ÷ 50 万 = 49.995818`，约等于 `50.00 USD`。

  如果要做告警，建议同时记录原始 `quota` 和换算后的美元金额。模型实际扣费仍以当前模型价格、账户分组、调用日志和控制台展示为准。
</Tip>

## 代码示例

<Tabs>
  <Tab title="cURL">
    **基础请求**（必须添加 `--compressed` 选项）：

    ```bash theme={null}
    curl --compressed 'https://api.laozhang.ai/api/user/self' \
      -H 'Accept: application/json' \
      -H 'Authorization: YOUR_ACCESS_TOKEN' \
      -H 'Content-Type: application/json'
    ```

    <Warning>
      **重要提示**：必须添加 `--compressed` 选项，因为 API 返回 gzip 压缩内容，否则会得到乱码。
    </Warning>
  </Tab>

  <Tab title="cURL 快速测试">
    使用环境变量和 jq 提取核心信息：

    ```bash theme={null}
    export LAOZHANG_TOKEN='YOUR_ACCESS_TOKEN'

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

    `-s` 选项隐藏进度条，`--compressed` 自动解压 gzip 响应。
  </Tab>

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

    # 配置
    url = "https://api.laozhang.ai/api/user/self"
    access_token = "YOUR_ACCESS_TOKEN"  # 替换为你的令牌

    # 请求头
    headers = {
        'Accept': 'application/json',
        'Authorization': access_token,
        'Content-Type': 'application/json'
    }

    # 发送请求
    response = requests.get(url, headers=headers, timeout=10)

    # 检查响应
    if response.status_code == 200:
        data = response.json()
        user_data = data['data']

        # 提取核心信息
        quota = user_data['quota']
        used_quota = user_data['used_quota']
        request_count = user_data['request_count']
        quota_unit_per_usd = 50 * 10000

        # 打印结果
        print(f"剩余额度：{quota:,}")
        print(f"剩余美元余额：{quota / quota_unit_per_usd:.2f} USD")
        print(f"已使用额度：{used_quota:,}")
        print(f"已使用美元额度：{used_quota / quota_unit_per_usd:.2f} USD")
        print(f"请求次数：{request_count:,} 次")
    else:
        print(f"请求失败：HTTP {response.status_code}")
        print(response.text)
    ```

    <Info>
      Python 的 `requests` 库会自动处理 gzip 解压，无需额外配置。
    </Info>
  </Tab>
</Tabs>

## 错误处理

### HTTP 401 - 认证失败

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

**原因**：Authorization 令牌无效或已过期

**解决方法**：检查并更新系统令牌

### HTTP 403 - 权限不足

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

**原因**：当前令牌无权访问该接口

**解决方法**：联系管理员确认权限配置

## 仍然无法查询时

如果接口仍然返回认证失败、乱码、空响应或字段不符合预期，请先确认使用的是系统令牌 AccessToken，而不是普通 API Key。

联系技术支持时，请提供：

* 账号邮箱或用户名
* 请求时间和 HTTP 状态码
* 返回的 `message` 字段或错误截图
* 已打码的请求命令，保留 URL、Header 名称和参数，不要暴露完整 AccessToken
* 是否使用了 `--compressed` 或等效 gzip 解压配置

## 常见问题

<AccordionGroup>
  <Accordion title="quota 字段代表什么？">
    `quota` 字段就是当前的剩余额度（可用余额）。如果 `quota` 为 0 或接近 0，说明账户余额不足，需要及时确认账户额度。
  </Accordion>

  <Accordion title="如何把 quota 换算成金额？">
    当前余额展示按 `50 万`额度约等于 `1 USD` 换算。公式是：剩余美元余额 = `quota ÷ 50 万`，已使用美元额度 = `used_quota ÷ 50 万`。

    例如 `quota: 24997909`，则 `24997909 ÷ 50 万 = 49.995818`，约等于 `50.00 USD`。生产告警建议同时保存原始 `quota` 和换算后的美元金额；模型实际扣费仍以控制台价格页、调用日志和当前账户规则为准。
  </Accordion>

  <Accordion title="curl 命令返回乱码怎么办？">
    **原因**：API 返回 gzip 压缩内容，curl 没有自动解压。

    **解决方案**：添加 `--compressed` 选项：

    ```bash theme={null}
    # 正确
    curl --compressed 'https://api.laozhang.ai/api/user/self' -H 'Authorization: YOUR_TOKEN'

    # 错误（会乱码）
    curl 'https://api.laozhang.ai/api/user/self' -H 'Authorization: YOUR_TOKEN'
    ```
  </Accordion>

  <Accordion title="jq 报错 Invalid numeric literal 怎么办？">
    这通常是因为 curl 没有解压 gzip 内容。添加 `--compressed` 选项即可解决。
  </Accordion>

  <Accordion title="ModelFixedPrice 字段有什么用？">
    该字段返回各个 AI 模型的定价信息。如果您只关心余额信息，可以忽略该字段。
  </Accordion>

  <Accordion title="如何实现余额告警？">
    可以编写定时脚本定期查询余额，当 `quota` 低于设定阈值时发送告警通知（如邮件、Slack、Webhook 等）。
  </Accordion>
</AccordionGroup>

## 相关问题

* 如果需要完整接口参数和接入示例，请查看[余额查询 API](/api-capabilities/balance-query)
* 如果 `quota` 仍有余额但请求失败，请查看[为什么还有余额跑不通？](/faq/balance-insufficient)
* 如果需要核对单次请求的模型、Token 和计费，请查看[如何查看我的调用记录？](/faq/call-logs)
* 如果需要创建或更换 API Key，请查看[API密钥获取与管理](/faq/token-management)

## 注意事项

<CardGroup cols={2}>
  <Card title="安全性" icon="shield">
    * 使用环境变量管理 Token
    * 不要提交到公开仓库
    * 定期更换 Token
  </Card>

  <Card title="请求限制" icon="clock">
    * 设置合理超时时间（推荐 10 秒）
    * 避免过于频繁的查询
    * 建议查询间隔 ≥ 1 分钟
  </Card>

  <Card title="异常处理" icon="triangle-alert">
    * 处理网络异常和超时
    * 处理认证失败情况
    * 记录错误日志便于排查
  </Card>

  <Card title="响应格式" icon="file-code">
    * API 返回 gzip 压缩内容
    * curl 必须添加 `--compressed`
    * requests 库自动处理
  </Card>
</CardGroup>