用 API Key 查询余额

用 sk- API Key 查询当前密钥的剩余额度：GET /v1/user/balance 返回 is_active / balance / unit，GET /v1/credits 返回 OpenRouter 风格的 total_credits / total_usage，兼容 cc-switch 等第三方客户端轮询。

用 sk- 开头的 API Key 直接查询当前这把 Key 的剩余额度与可用状态，适合第三方客户端在界面上显示余额，或用脚本做余额监控。

这是只读接口：不计费、不消耗额度。鉴权只校验 Key 本身，所以即使在额度已用尽、业务请求会被拒绝的状态下，也能查到剩余额度（此时返回 is_active: false）。

1. 接口总览

端点适配的客户端格式返回
GET /v1/user/balancecc-switch 通用余额模板is_active / balance / unit，Key 设了总额度时另带 used / total
GET /user/balance同上，Base URL 不带 /v1 时的写法与上一行完全相同
GET /v1/creditsOpenRouter 风格data.total_credits / data.total_usage
项值
Base URLhttps://api.lmuai.com
鉴权方式Authorization: Bearer <sk-...>
返回格式JSON
是否需要登录不需要，API Key 即可

/user/balance 是 /v1/user/balance 的别名（客户端把 Base URL 填成不带 /v1 的形式时会用到）。/v1/credits 没有根路径别名，必须带 /v1。

2. 余额口径

接口返回的 balance 不一定是账户钱包余额，而是当前 Key 实际可用的剩余额度，按以下顺序取第一项：

顺序Key 的情况balance 表示
1Key 单独设了总额度该 Key 的剩余额度（total - used）
2Key 属于订阅分组订阅的剩余额度（unit 为 requests 时表示剩余次数）
3以上都不是账户钱包余额

另外，is_active 表示这把 Key 当前是否可用于业务调用：Key 状态为启用、未过期、总额度未用尽时为 true；订阅分组下没有生效中的订阅时也会是 false。

3. GET /v1/user/balance

GET /v1/user/balance HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx

响应 —— 钱包余额模式（Key 没限额、也不是订阅分组）：

{
  "is_active": true,
  "balance": 1575.13,
  "unit": "USD"
}

响应 —— Key 设了总额度（此时额外返回 used 与 total）：

{
  "is_active": true,
  "balance": 6,
  "unit": "USD",
  "used": 4,
  "total": 10
}

响应 —— 订阅分组（按次数计）：

{
  "is_active": true,
  "balance": 842,
  "unit": "requests"
}

响应字段

字段类型说明
is_activeboolKey 当前是否可用于业务调用
balancenumber剩余额度，单位见 unit
unitstringUSD（默认），或 requests（按次数计费的订阅分组）
usednumber仅在 Key 设了总额度时出现，该 Key 的已用额度
totalnumber仅在 Key 设了总额度时出现，该 Key 的总额度

used / total 只在 Key 总额度模式下有确切值。钱包余额与订阅模式下没有这两个字段，请以 balance 为准，不要用 total - used 反推。

4. GET /v1/credits

OpenRouter 风格的余额格式，客户端按 total_credits - total_usage 显示剩余额度。

GET /v1/credits HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx

响应：

{
  "data": {
    "total_credits": 20,
    "total_usage": 4
  }
}
字段类型说明
data.total_creditsnumber已用 + 剩余，保证 total_credits - total_usage 恰好等于剩余额度
data.total_usagenumber已用额度

total_credits 是「已用 + 剩余」的合成值，不是额度上限的字面值。钱包余额模式下 total_usage 为 0、total_credits 就等于余额；额度已用尽时剩余额度被钳到 0，此时 total_credits 等于已用量。

5. 在第三方客户端里填写

客户端 / 场景填法
cc-switch 通用余额模板Base URL 填 https://api.lmuai.com（不带 /v1）或 https://api.lmuai.com/v1（带 /v1）都可以，两种都能命中
OpenRouter 兼容客户端（Kelivo、RikkaHub 等）Base URL 填 https://api.lmuai.com/v1，客户端会请求 /v1/credits
自写脚本建议直接调 /v1/user/balance，字段更直观
curl -s https://api.lmuai.com/v1/user/balance \
  -H "Authorization: Bearer sk-xxxxxxxx"

6. 错误响应

查询余额走网关统一的 API Key 鉴权，出错时返回与业务接口相同的错误格式。请求没带 Key 时：

{
  "code": "API_KEY_REQUIRED",
  "message": "API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header"
}
状态码code场景
200—正常返回；额度用尽、Key 已过期、订阅缺失也走 200，用 is_active: false 表示不可用
401API_KEY_REQUIRED请求没带 API Key
401INVALID_API_KEYKey 不存在或格式不对
401API_KEY_DISABLEDKey 已被停用
403ACCESS_DENIED这把 Key 设了 IP 白名单 / 黑名单，当前 IP 不允许

更多通用错误见错误码速查。

7. 与「导出 Usage 使用明细」的区别

本文的余额接口导出 Usage 使用明细
鉴权sk- API Key账号密码换 JWT
粒度当前 Key 的剩余额度账号级逐条请求明细
用途客户端显示余额、余额监控账单导出、对账、入 BI

GET /v1/usage 是介于两者之间的接口：同样用 sk- Key，返回当前 Key 的今日 / 累计用量统计与额度信息，字段更详细。

最后更新：

京ICP备2020034311号-7

本页目录

1. 接口总览2. 余额口径3. GET /v1/user/balance响应字段4. GET /v1/credits5. 在第三方客户端里填写6. 错误响应7. 与「导出 Usage 使用明细」的区别