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

# 余额查询

> 用 API Key 一条命令查剩余额度，不用登录控制台

想在脚本、程序或者别的工具里看看还剩多少钱？用你的 API Key 调一个接口就行。不用登录控制台，查询本身也不扣费。

只需要两样东西：

| 项目 | 值 |
| - | - |
| API Key | 在 [ruoli.dev](https://ruoli.dev) 控制台「令牌」页复制 |
| 查询地址 | `https://ruoli.dev/api/usage/token/` |

## 查询余额

把下面命令里的 `sk-你的KEY` 换成你自己的 Key，然后运行：

```bash curl theme={null}
curl https://ruoli.dev/api/usage/token/ \
  -H "Authorization: Bearer sk-你的KEY"
```

```python Python theme={null}
import requests

KEY = "sk-你的KEY"
resp = requests.get(
    "https://ruoli.dev/api/usage/token/",
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=15,
)
data = resp.json()["data"]

# 有 user_quota 就看账户余额，否则看令牌余额
quota = data.get("user_quota", data)["total_available"]
print(f"剩余 ¥{quota / 500000:.2f}")
```

```javascript JavaScript theme={null}
// Node.js 18 及以上
const KEY = "sk-你的KEY";

const resp = await fetch("https://ruoli.dev/api/usage/token/", {
  headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await resp.json();

// 有 user_quota 就看账户余额，否则看令牌余额
const quota = (data.user_quota ?? data).total_available;
console.log(`剩余 ¥${(quota / 500000).toFixed(2)}`);
```

> [!WARNING]
>
> 地址最后的 `/` 不要漏掉，完整写成 `https://ruoli.dev/api/usage/token/`。

## 看懂返回结果

返回示例（数字是举例）：

```json theme={null}
{
  "code": true,
  "message": "ok",
  "data": {
    "object": "token_usage",
    "name": "我的令牌",
    "total_granted": 10000000,
    "total_used": 2500000,
    "total_available": 7500000,
    "unlimited_quota": false,
    "model_limits": {},
    "model_limits_enabled": false,
    "expires_at": 0,
    "user_quota": {
      "total_available": 42000000,
      "total_used": 18000000
    }
  }
}
```

| 字段 | 意思 |
| - | - |
| `total_available` | 这个令牌还能用的额度 |
| `total_used` | 这个令牌已经用掉的额度 |
| `total_granted` | 这个令牌的总额度（剩余 + 已用） |
| `unlimited_quota` | `true` 表示令牌不设上限，用的是账户余额 |
| `expires_at` | 过期时间（秒级时间戳），`0` 表示永不过期 |
| `user_quota` | 整个账户的余额和已用额度。令牌开启「允许查询用户额度」后才会出现 |

所有额度数字**除以 500000** 就是人民币：

```
剩余金额（元） = total_available ÷ 500000
例：7500000 ÷ 500000 = ¥15.00
```

## 无限额度令牌怎么看余额

> [!WARNING]
>
> **令牌是「无限额度」时，按令牌查出来的剩余是负数。**
>
> 无限额度的令牌没有自己的上限，每次调用直接扣账户余额，所以 `total_available` 只是「0 减去已用」，看不出真实余额。

想看账户的真实余额，给这个令牌开一下权限：

**1. 打开令牌设置**

登录 [ruoli.dev](https://ruoli.dev)，进入「令牌」页面，编辑要查询的令牌。

**2. 开启「允许查询用户额度」**

打开 **允许查询用户额度**，保存。

**3. 重新查询**

再运行一次上面的命令，看返回里的 `data.user_quota.total_available`，除以 500000 就是账户余额。

> [!NOTE]
>
> 这个开关只影响查询接口能不能看到账户余额，不会改变令牌的额度和调用权限。

## 在第三方客户端里显示余额

很多聊天客户端和余额查询小工具，用的是 OpenAI 的老式账单接口。在客户端里把 API 地址填成 `https://ruoli.dev`、Key 填你的令牌，一般就能直接显示余额。

它们调用的是下面两个接口，你也可以自己查：

```bash theme={null}
# 总额度（元）
curl https://ruoli.dev/v1/dashboard/billing/subscription \
  -H "Authorization: Bearer sk-你的KEY"

# 已用（分）
curl https://ruoli.dev/v1/dashboard/billing/usage \
  -H "Authorization: Bearer sk-你的KEY"
```

| 接口 · 字段 | 意思 |
| - | - |
| subscription · `hard_limit_usd` | 令牌总额度，单位已经是**元**（字段名里的 usd 是沿用 OpenAI 的叫法）。无限额度令牌固定显示 `100000000` |
| usage · `total_usage` | 令牌已用金额，单位是**分** |

```
剩余（元） = hard_limit_usd − total_usage ÷ 100
```

> [!NOTE]
>
> 这两个接口只按令牌统计。令牌是无限额度时，请改用上面的 `/api/usage/token/` 并开启「允许查询用户额度」。

## 常见报错

> [accordion] 返回 401 Invalid token
>
> Key 复制错了、已被删除、已禁用或已过期。回到控制台「令牌」页确认状态，重新复制完整的 `sk-` 开头字符串。

> [accordion] 令牌设置了 IP 白名单
>
> 查询也要从白名单里的 IP 发出，否则会被拒绝。

> [accordion] 返回的是网页或 301 跳转
>
> 检查地址：用 `https`，路径结尾带 `/`，完整写成 `https://ruoli.dev/api/usage/token/`。

> [accordion] 能不能放进程序里定时查？
>
> 可以，但查询接口有频率限制，几分钟查一次就够了。


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