> ## 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/user/self

> 为监控脚本和余额告警读取老张API账户的剩余额度、已用额度与请求次数：获取 AccessToken、调用 /api/user/self，并把额度换算为美元。

用系统令牌 AccessToken 调用余额查询接口，可以读取老张API账户的剩余额度、已用额度和请求次数，适合接入后台监控、余额告警、账务排查脚本和内部运营面板。

| 项目 | 内容 |
| - | - |
| 接口 | `GET https://api.laozhang.ai/api/user/self` |
| 认证 | 系统令牌 AccessToken |
| 主要字段 | 剩余额度 `quota`、已使用额度 `used_quota`、累计请求次数 `request_count`、账户分组 `group` |
| 换算 | 50 万额度约等于 1 USD，见[额度与金额计算](#额度与金额计算) |

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

## 获取 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="验证账户密码">
    在弹出的对话框中输入账户密码并点击「获取」。生成新的 AccessToken 可能使旧 Token 失效，仍在使用旧 Token 的脚本需要同步更新。

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

  <Step title="复制并保存">
    AccessToken 只在创建时显示，之后无法再次查看，请立即复制到安全位置。

    <img src="https://mintcdn.com/laozhangai-edd05f2c/U7sDYRC-3BXM2ZfO/images/balance-query-step3.png?fit=max&auto=format&n=U7sDYRC-3BXM2ZfO&q=85&s=60c64bb31e6c842fab5444aee22ef695" alt="复制新生成的 AccessToken" width="1020" height="460" data-path="images/balance-query-step3.png" />
  </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 参数，也不需要请求体。

## 响应说明

### 成功响应示例

```json theme={null}
{
  "success": true,
  "message": null,
  "data": {
    "id": 12345,
    "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`。

余额展示可以按上述公式计算；模型实际扣费仍要以当前模型价格、令牌分组、调用日志和控制台展示为准，计费规则见[计费说明](/pricing)。

生产告警建议同时保存原始 `quota` 和换算后的美元金额，避免后续排查时丢失精度。

## 代码示例

以下示例从环境变量 `LAOZHANG_ACCESS_TOKEN` 读取 AccessToken。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    export LAOZHANG_ACCESS_TOKEN="替换为你的 AccessToken"

    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="替换为你的 AccessToken"

    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 -m pip install requests`。

    ```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">
    保存为 `.mjs` 文件，使用内置 `fetch` 的 Node.js 18 或更高版本运行。

    ```javascript theme={null}
    const token = process.env.LAOZHANG_ACCESS_TOKEN;
    if (!token) {
      throw new Error("请先设置环境变量 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` 为空、令牌复制不完整、令牌已失效（例如之后又生成了新的 AccessToken），或误用了调用模型的 API Key。

### HTTP 403 - 权限不足

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

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

### 响应乱码或 jq 报错

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

## 监控接入建议

老张API目前不提供可以依赖的余额告警通知。需要在余额不足前收到提醒时，用本接口自建定时检查。下面的脚本在剩余金额低于阈值时以状态码 1 退出：

```python theme={null}
import os
import sys
import requests

THRESHOLD_USD = float(os.environ.get("LAOZHANG_ALERT_USD", "20"))

response = requests.get(
    "https://api.laozhang.ai/api/user/self",
    headers={"Authorization": os.environ["LAOZHANG_ACCESS_TOKEN"]},
    timeout=10,
)
response.raise_for_status()
remaining_usd = response.json()["data"]["quota"] / 500000

if remaining_usd < THRESHOLD_USD:
    print(f"余额 {remaining_usd:.2f} 美元，低于 {THRESHOLD_USD} 美元")
    sys.exit(1)
```

把它交给 cron 或监控系统，每 10–30 分钟运行一次，非零退出时发送通知，例如：

```bash theme={null}
*/10 * * * * /usr/bin/python3 /opt/check_balance.py || /opt/notify.sh
```

cron 默认不读取你的 shell 环境变量，需要在脚本或 crontab 中提供 `LAOZHANG_ACCESS_TOKEN`。接入时注意：

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

## 相关文档

* cURL 乱码、401 以及 AccessToken 与 API Key 的区别：[怎样通过 API 查询老张API账户余额？](/faq/balance-query-api)
* 余额仍然充足但请求失败：[为什么还有余额但调用失败？](/faq/balance-insufficient)
* 核对单次请求的模型、用量和计费：[如何查看和使用调用日志？](/faq/call-logs)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.