API 余额查询教程：用 API Key 查剩余余额和用量（/v1/usage 接口）
更新于
想在自己的程序、脚本或监控里查 API 快连账户还剩多少余额？不用登录控制台，用平时调模型的 API Key 请求一下 /v1/usage 接口就行，还能顺带看到这把 Key 今天和累计用了多少、按天和按模型的用量。这篇给出网页查询、curl、Python、Node.js 四种查法，以及返回结果每个字段的意思。
GET https://apikl.ai/v1/usage，请求头带上 Authorization: Bearer 你的API Key，返回结果里的 balance 就是账户剩余余额。查询不扣费；不想写代码，直接打开 API Key 用量查询页 粘贴 Key 即可。| 项目 | 内容 |
|---|---|
| 接口地址 | https://apikl.ai/v1/usage（直连线路换成 https://dc.apikl.ai/v1/usage） |
| 请求方法 | GET |
| 鉴权 | Authorization: Bearer 你的API Key，也支持 x-api-key 请求头 |
| 余额字段 | balance（账户余额，所有 Key 共用） |
| 会不会扣费 | 不会。查询不调用模型，也不会出现在使用记录里 |
方法一：网页查询（不用写代码）
- 打开 API Key 用量查询页（
https://apikl.ai/key-usage），不用登录。 - 在输入框粘贴你的 API Key（
sk-开头），点「查询」。 - 页面会显示钱包余额、这把 Key 今天和累计的请求数、token 用量和消费金额，以及按天、按模型的明细。
页面上写明「您的 Key 仅在浏览器本地处理，不会被存储」：查询是你的浏览器直接请求上面的接口，Key 不会保存在页面上。用公共电脑查完记得关掉页面。
方法二：用接口查询
把下面示例里的 sk-你的密钥 换成你自己的 API Key。用哪个分组的 Key 都可以，余额是整个账户共用的。
curl
Python（requests）
先安装：pip install requests。密钥建议放在环境变量里，不要写死在代码中。
MyApp/1.0），否则可能被拦截并返回 error code: 1010。用 requests、curl 不受影响。Node.js（18 及以上，自带 fetch）
保存成 balance.mjs，运行 APIKL_KEY=sk-你的密钥 node balance.mjs（Windows PowerShell 先运行 $env:APIKL_KEY="sk-你的密钥"，再运行 node balance.mjs）。
返回结果怎么看
一把普通的 Key（没有单独设置额度上限）返回的结果大致如下（只列出常用字段，数字仅作示例）：
| 字段 | 意思 |
|---|---|
balance | 账户剩余余额，和控制台显示的余额是同一个数。一个账户下所有 Key 共用这一个余额 |
remaining | 剩余可用金额。普通 Key 等于 balance；Key 设了额度上限时是这把 Key 剩余的额度（见下一节） |
unit | 固定写 USD，是程序的通用写法，不用管。金额数值和控制台一致，按控制台显示的余额理解即可 |
mode | unrestricted 表示这把 Key 没有单独设额度上限，花的是账户余额；quota_limited 表示设了额度上限 |
isValid | 这把 Key 当前是否有效 |
usage.today / usage.total | 这把 Key今天、累计的请求数、各类 token 数和金额。actual_cost 是实际扣费，cost 是按原价计算的金额 |
usage.rpm / usage.tpm | 这把 Key 最近每分钟的请求数、token 数 |
daily_usage | 这把 Key 按天的用量，默认最近 30 天 |
model_stats | 这把 Key 按模型汇总的用量，默认最近 30 天 |
可选参数
| 参数 | 作用 | 示例 |
|---|---|---|
days | daily_usage 返回最近几天，1–90，默认 30 | ?days=7 |
timezone | daily_usage 按哪个时区分天 | ?timezone=Asia/Shanghai |
start_date / end_date | model_stats 的统计日期范围，格式 YYYY-MM-DD，默认最近 30 天 | ?start_date=2026-10-01&end_date=2026-10-12 |
Key 设了额度上限时，返回的是这把 Key 的额度
在 控制台 给某把 Key 设了「额度上限」或按 5 小时 / 1 天 / 7 天的限额后，用这把 Key 查询，mode 会变成 quota_limited，返回的是这把 Key 自己的额度情况，不包含账户余额 balance：
| 字段 | 意思 |
|---|---|
quota.limit / quota.used / quota.remaining | 这把 Key 的总额度、已用、剩余 |
remaining | 同 quota.remaining |
rate_limits | 按时间窗口的限额，每项有 window（5h / 1d / 7d）、limit、used、remaining、reset_at（何时重置） |
expires_at / days_until_expiry | 这把 Key 设了过期时间时才有：到期时间、还剩几天 |
status | 这把 Key 的状态，例如额度用完、已过期 |
所以想查账户余额，请用一把没有设额度上限的 Key 查询。给不同项目、不同同事分配 Key 时，可以用设了额度上限的 Key 让对方自己查还剩多少，又看不到你的账户余额。
CC Switch 里直接显示余额
用 CC Switch 的话不用自己写代码：在控制台密钥列表点「导入到 CCS」，会同时导入余额查询，CC Switch 的卡片上会显示剩余额度，每 30 分钟刷新一次。详细步骤看 CC Switch 配置教程。
做余额提醒的小建议
- 定时查询（例如每 10–30 分钟一次）就够了，没必要每次请求前都查。
- 余额低于你设的阈值（比如 20）时发提醒；读
balance时如果字段不存在，说明这把 Key 设了额度上限，改用remaining，或换一把没有额度上限的 Key。 - 余额较低时同时发出很多请求，系统会为进行中的请求预留额度，可能还没花完就提示余额不足（403 insufficient balance）。留一些余量再充值更稳。
- 查询用的 Key 和调模型的 Key 权限一样，请当密码保管，不要写进前端网页或公开仓库。
常见问题
返回 401 INVALID_API_KEY
Key 不对：常见原因是没把示例里的 sk-你的密钥 换成真实的 Key、复制时多了空格或换行、Key 已经被删除。到 控制台 重新复制一次。详见 401 报错排查。
返回 401 API_KEY_REQUIRED
请求里没带 Key。检查请求头是否写成 Authorization: Bearer sk-...（Bearer 后面有一个空格）。
返回的是一个网页，不是 JSON
地址少了 /v1。要写完整的 https://apikl.ai/v1/usage，不能写成 https://apikl.ai/usage。
返回 401 API_KEY_DISABLED 或 403 ACCESS_DENIED
前者是 Key 在控制台被停用了；后者是这把 Key 设了 IP 白名单，而你当前的 IP 不在名单里。启用 Key 或调整白名单后再查。
余额不足、Key 过期了还能查吗？
能。这个接口不检查余额、额度和有效期，欠费、额度用完或已过期的 Key 也能查，方便你确认原因。
查询会扣费吗？有次数限制吗？
不扣费，也不会出现在使用记录里。正常的定时查询不会受影响，但不要高频轮询（例如每秒一次）。
为什么 usage 里的金额和控制台总消费对不上？
usage 只统计当前查询用的这把 Key，控制台显示的是整个账户（所有 Key）的消费。要对账请到控制台「使用记录」按 Key 筛选。
能用一把 Key 查别的 Key 的用量吗？
不能。每把 Key 只能查到它自己的用量和额度；账户余额则用任何一把没设额度上限的 Key 都能查到。