API Key 用量与余额查询

1. 接口说明

通过当前 API Key 查询允许公开的余额及累计消耗数据。

接口使用 API Key 认证。返回的余额范围由该 API Key 的「用量查询」设置决定，金额或额度单位跟随平台系统配置。

本接口为只读接口，不修改余额、令牌限额或用量查询设置。

主要规则

每个 API Key 独立配置用量查询权限，默认关闭。

选择「令牌限额」时，仅公开当前令牌的额度信息。

选择「用户总额度」时，公开令牌所属账户的当前剩余余额。

所有成功响应中的累计消耗，均为当前 API Key 的累计消耗。

返回的剩余额度已经由服务端计算完成，客户端不要再次扣减累计消耗。

单位以响应中的 unit 为准，不固定为 USD。

2. 开启 API Key 用量查询

2.1 设置入口

登录平台控制台。

进入「令牌管理」。

找到需要查询用量的 API Key，点击「更多 → 编辑令牌」。

在编辑窗口中找到「用量查询」。

根据需要选择「关闭」「令牌限额」或「用户总额度」。

点击「保存修改」。

创建新令牌时，也可以在同一区域设置用量查询方式。新建令牌及未主动开启该设置的令牌，默认均为「关闭」。

保存后，后续查询请求按照保存后的设置处理。查询接口本身不能开启或修改该权限。

2.2 设置选项

控制台选项	接口中的设置值	允许查询的信息
关闭	`off`	不允许通过此 API Key 查询余额或累计消耗
令牌限额	`token`	当前 API Key 的剩余额度及累计消耗
用户总额度	`user`	所属账户当前剩余余额，以及当前 API Key 的累计消耗

这里的 off、token、user 是返回字段的取值，不是调用 /v1/usage 时需要传入的参数。

2.3 关闭

关闭时，请求返回 HTTP 403。

{
  "success": false,
  "message": "该令牌未开启用量查询",
  "error": {
    "type": "usage_query_disabled",
    "message": "该令牌未开启用量查询"
  }
}

关闭只影响通过 API Key 查询用量数据的权限，不会因此禁用该令牌的模型调用能力。

2.4 令牌限额

仅公开当前 API Key 的额度和消耗，不返回账户钱包余额。

有限额令牌

当前令牌剩余额度；

当前令牌累计消耗；

当前额度汇总对象 quota。

例如，当前令牌累计消耗 20，剩余额度 80，接口返回的额度汇总为：

{
  "limit": 100,
  "used": 20,
  "remaining": 80,
  "unit": "CNY"
}

其中 limit 按“当前剩余额度 + 当前令牌累计消耗”计算。如果令牌额度曾经调整，不应把这个字段理解为首次创建令牌时填写的原始限额。

不限额令牌

当前令牌累计消耗；

remaining: 0；

不返回 quota 对象。

不限额时的 remaining: 0 是该查询模式的固定表示方式，不代表账户余额为零，也不代表令牌额度已经耗尽。

客户端应将这种情况显示为“已用”，不显示剩余余额。

2.5 用户总额度

公开当前 API Key 所属账户的当前剩余余额：

账户当前剩余余额 = 当前充值余额 + 当前赠送余额

接口在服务端完成合并，只返回合计余额，不分别公开充值余额和赠送余额。

请注意：

返回的是当前剩余余额，不是累计充值金额。

返回的余额已经扣除了实际消费，不需要再次减去已用金额。

此模式下的累计消耗仍属于当前 API Key，不是整个账户所有 API Key 的累计消耗。

允许查询账户余额不会改变当前令牌实际调用时受到的额度限制。

选择该选项后，持有此 API Key 的人可以查询账户合计余额，请根据实际需要开启。

3. 请求方式

3.1 基本信息

项目	内容
请求方法	`GET`
请求路径	`/v1/usage`
完整地址示例	`https://api.example.com/v1/usage`
认证方式	Bearer API Key
路径参数	无
Query 参数	无
请求体	无
成功响应类型	`application/json`

本接口不支持按日期、模型或时间范围筛选，也不提供逐条消费明细。

3.2 请求头

请求头	是否必填	示例	说明
`Authorization`	是	`Bearer sk-your-api-key`	使用需要查询的 API Key 完整值
`Accept`	否	`application/json`	声明期望返回 JSON

请求示例：

认证时请注意：

使用完整 API Key，不能使用列表中显示的掩码值。

不需要提供用户 ID。

不需要提供控制台登录 Cookie。

不需要使用系统访问凭证或管理接口凭证。

不支持通过 URL 查询参数代替 Authorization 请求头传递 API Key。

3.3 地址拼接

如果客户端配置的 API 基础地址已经以 /v1 结尾：

https://api.example.com/v1

则在其后追加 /usage：

https://api.example.com/v1/usage

不要拼接成：

https://api.example.com/v1/v1/usage

如果平台部署在包含路径前缀的地址下，应保留实际部署路径前缀，再拼接接口路径。

4. 成功响应字段

成功时返回 HTTP 200，JSON 对象直接位于响应根节点，没有统一的 data 包装层。

4.1 公共字段

字段	类型	说明
`isValid`	boolean	成功时为 `true`，表示当前请求通过了用量查询校验
`status`	integer	令牌当前保存的状态值
`planName`	string	令牌限额模式下为令牌名称；用户总额度模式下为固定值「钱包余额」
`mode`	string	兼容字段，取值见下方说明
`usage_query_mode`	string	当前查询设置：`token` 或 `user`
`remaining`	number	按当前设置返回的剩余额度或账户剩余余额；不限额令牌在令牌限额模式下固定为 `0`
`unit`	string	平台当前配置的货币或额度单位
`expires_at`	integer	令牌过期时间，Unix 时间戳，单位为秒；`0` 表示没有设置过期时间
`usage`	object	当前 API Key 的累计消耗数据
`usage.total`	object	累计消耗汇总
`usage.total.actual_cost`	number	当前 API Key 的累计消耗，单位与根节点 `unit` 一致

4.2 条件字段

字段	类型	出现条件	说明
`quota`	object	`token` 模式且令牌有限额	当前令牌额度汇总
`quota.limit`	number	存在 `quota` 时	当前剩余额度与当前令牌累计消耗之和
`quota.used`	number	存在 `quota` 时	当前 API Key 的累计消耗
`quota.remaining`	number	存在 `quota` 时	当前令牌剩余额度，与根节点 `remaining` 一致
`quota.unit`	string	存在 `quota` 时	与根节点 `unit` 一致
`balance`	number	`user` 模式	账户当前合计剩余余额，与根节点 `remaining` 一致

quota 和 balance 都不是必然存在的字段。未出现时，不应自行补成 0 再据此判断余额状态。

4.3 `mode` 与 `usage_query_mode`

`usage_query_mode`	`mode`	实际含义
`token`	`quota_limited`	使用令牌额度查询规则，可能是有限额令牌，也可能是不限额令牌
`user`	`unrestricted`	使用账户钱包余额查询规则

不能只根据 mode 判断令牌是否不限额。

mode 是兼容字段：

quota_limited 不保证一定返回 quota。

unrestricted 不表示当前 API Key 的模型调用没有额度限制。

判断令牌限额模式中的“不限额”情况，应同时满足：

usage_query_mode 为 token，并且响应中不存在 quota 对象

4.4 令牌状态

`status`	含义	是否允许用量查询
`1`	已启用	开启用量查询且通过其他校验时允许
`2`	已禁用	不允许，返回 HTTP `401`
`3`	已过期	开启用量查询且通过其他校验时允许只读查询
`4`	额度耗尽	开启用量查询且通过其他校验时允许只读查询

正常成功响应不会返回禁用状态的令牌。

status 是令牌保存的状态字段，本接口不会根据当前时间重新计算并更新该状态。需要判断到期时间时，可以同时读取 expires_at。

isValid: true 只表示本次用量查询成功，不保证当前令牌仍能调用模型。过期、额度耗尽等情况仍可能允许查询。

5. 成功响应示例

以下示例统一使用 CNY。实际接入请始终读取返回的 unit。

5.1 令牌限额：有限额

当前令牌累计消耗 20 CNY，剩余 80 CNY：

{
  "isValid": true,
  "status": 1,
  "planName": "生产环境调用令牌",
  "mode": "quota_limited",
  "usage_query_mode": "token",
  "remaining": 80,
  "unit": "CNY",
  "expires_at": 0,
  "usage": {
    "total": {
      "actual_cost": 20
    }
  },
  "quota": {
    "limit": 100,
    "used": 20,
    "remaining": 80,
    "unit": "CNY"
  }
}

客户端展示：

已用：20 CNY
剩余：80 CNY

5.2 令牌限额：不限额

当前令牌未设置额度限制，累计消耗 20 CNY：

{
  "isValid": true,
  "status": 1,
  "planName": "开发测试令牌",
  "mode": "quota_limited",
  "usage_query_mode": "token",
  "remaining": 0,
  "unit": "CNY",
  "expires_at": 0,
  "usage": {
    "total": {
      "actual_cost": 20
    }
  }
}

客户端展示：

已用：20 CNY

此响应没有 quota，客户端不应将其显示为“余额耗尽”。

5.3 用户总额度

账户当前充值余额为 80 CNY，赠送余额为 20 CNY，当前 API Key 累计消耗为 12 CNY：

{
  "isValid": true,
  "status": 1,
  "planName": "钱包余额",
  "mode": "unrestricted",
  "usage_query_mode": "user",
  "remaining": 100,
  "balance": 100,
  "unit": "CNY",
  "expires_at": 0,
  "usage": {
    "total": {
      "actual_cost": 12
    }
  }
}

客户端展示：

当前 API Key 已用：12 CNY
账户剩余：100 CNY

不能计算为 100 - 12 = 88。 100 已经是账户当前剩余余额。

此模式下，remaining + actual_cost 也不能作为账户历史总额度，因为两者的统计范围不同。

5.4 有限额令牌额度耗尽

{
  "isValid": true,
  "status": 4,
  "planName": "临时体验令牌",
  "mode": "quota_limited",
  "usage_query_mode": "token",
  "remaining": 0,
  "unit": "CNY",
  "expires_at": 0,
  "usage": {
    "total": {
      "actual_cost": 10
    }
  },
  "quota": {
    "limit": 10,
    "used": 10,
    "remaining": 0,
    "unit": "CNY"
  }
}

这里存在 quota，因此可以与不限额令牌区分。

客户端展示：

已用：10 CNY
剩余：0 CNY

6. 单位与数值规则

6.1 单位跟随系统配置

系统额度显示设置	`unit` 示例	数值含义
美元	`USD`	已换算为美元
人民币	`CNY`	已按系统配置换算为人民币
自定义货币或额度单位	如 `积分`、`点`	已按系统配置换算为相应单位
TOKENS	`TOKENS`	平台内部额度计量值，不等同于模型输入、输出 Token 数量

客户端应直接使用接口返回的数值和 unit，不要再应用平台内部额度比例或汇率进行换算。

6.2 精度与展示

数值以 JSON number 返回。

不保证固定保留两位小数。

小额消耗可能出现多位小数。

展示时可以按业务需要格式化，但不要先将金额取整再参与余额判断。

同一次响应中的余额和消耗使用相同单位。

系统单位或换算配置发生变化后，不应把不同单位下的历史查询结果直接相加。

6.3 剩余额度边界

令牌限额模式下：

有限额令牌返回当前剩余额度。

有限额令牌的剩余额度小于零时，对外按 0 返回。

不限额令牌固定返回 remaining: 0，且不返回 quota。

不使用负余额表示“累计已用”。

需要展示消耗时，请读取：

usage.total.actual_cost

7. cURL 调用示例

7.1 直接请求

7.2 同时查看 HTTP 状态码和响应头

排查问题时，应同时检查 HTTP 状态码和响应体，不能只判断是否收到了 JSON。

8. Apifox 接入配置

8.1 环境变量

在项目环境中配置：

变量	示例值	说明
`baseUrl`	`https://api.example.com`	平台根地址，不包含末尾 `/v1`
`apiKey`	`sk-your-api-key`	完整 API Key

本文以下示例约定 baseUrl 不包含末尾 /v1。

8.2 创建接口

配置接口：

请求方法：GET
请求地址：{{baseUrl}}/v1/usage

使用 Bearer Token 认证，Token 值填写：

{{apiKey}}

也可以直接配置请求头：

Authorization: Bearer {{apiKey}}
Accept: application/json

两种认证配置方式选择一种即可，避免重复发送 Authorization。

Query 参数和请求体均留空。

8.3 配置成功响应结构

公共字段设置为必填：

isValid
status
planName
mode
usage_query_mode
remaining
unit
expires_at
usage
usage.total
usage.total.actual_cost

以下字段设置为可选：

quota
quota.limit
quota.used
quota.remaining
quota.unit
balance

如果使用多种响应示例，建议分别保存：

令牌限额：有限额；

令牌限额：不限额；

用户总额度；

用量查询关闭；

无效或已禁用 API Key。

不要将 quota 配置为所有成功响应都必填，否则不限额令牌和用户总额度模式会被错误地判定为响应校验失败。

8.4 调试顺序

在控制台为 API Key 开启用量查询。

将完整 API Key 配置到 Apifox 环境变量。

发送请求，确认 HTTP 状态码为 200。

检查 usage_query_mode 是否与控制台设置一致。

检查 unit 是否符合平台当前单位设置。

按所选模式核对余额及累计消耗。

9. JavaScript 接入示例

以下示例适用于支持 fetch 的服务端 JavaScript 环境。

示例中的 API Key 从服务端环境变量读取。

接入时的展示规则：

令牌限额 + 有限额：显示已用和剩余
令牌限额 + 不限额：只显示已用
用户总额度：显示当前 API Key 已用和账户剩余

10. 错误响应

错误响应结构可能来自认证层、业务层或限流层，因此不完全统一。

客户端应先检查 HTTP 状态码，再尝试读取：

error.message
message

不要要求所有错误响应都包含 error.type，也不要假设所有错误都会返回 isValid: false。

10.1 错误对照表

HTTP 状态码	场景	典型信息	处理方式
`401`	未提供认证请求头	未提供 Authorization 请求头	添加 Bearer API Key
`401`	API Key 无效、已删除或不正确	无效的令牌	检查完整密钥及目标平台地址
`401`	令牌被禁用	令牌已禁用	通过控制台启用令牌
`403`	未开启用量查询	该令牌未开启用量查询	编辑令牌，开启相应查询模式
`403`	来源 IP 不在允许范围内	您的 IP 不在令牌允许访问的列表中	核对查询服务的出口 IP 和令牌 IP 限制
`403`	所属用户已被封禁	用户已被封禁	联系平台管理员
`429`	请求触发平台限流	响应体可能为空	降低频率并延迟重试
`500`	获取用户或账户余额等服务异常	如：获取账户余额失败	稍后重试，持续失败时联系平台

10.2 缺少认证请求头

{
  "success": false,
  "message": "未提供 Authorization 请求头"
}

10.3 无效 API Key

{
  "success": false,
  "message": "无效的令牌"
}

10.4 令牌已禁用

{
  "success": false,
  "message": "令牌已禁用"
}

10.5 未开启用量查询

{
  "success": false,
  "message": "该令牌未开启用量查询",
  "error": {
    "type": "usage_query_disabled",
    "message": "该令牌未开启用量查询"
  }
}

10.6 来源 IP 不允许

{
  "success": false,
  "message": "您的 IP 不在令牌允许访问的列表中"
}

10.7 获取账户余额失败

{
  "error": {
    "type": "api_error",
    "message": "获取账户余额失败"
  }
}

多个条件同时不满足时，接口按实际校验顺序返回错误，单次请求不会一次列出所有问题。

11. 客户端展示与轮询建议

11.1 字段读取

展示内容	字段
当前 API Key 累计已用	`usage.total.actual_cost`
剩余额度或账户余额	`remaining`
单位	`unit`
余额范围	`usage_query_mode`
是否为令牌不限额场景	`usage_query_mode === "token"` 且没有 `quota`

不要通过以下方式判断不限额：

remaining === 0
mode === "unrestricted"

因为：

有限额令牌耗尽时也会返回 remaining: 0。

用户总额度模式的 mode 是 unrestricted，但其账户余额仍需要展示。

11.2 轮询

客户端可以按需定期刷新，通常无需高频轮询。

建议：

普通余额面板每 30～60 秒刷新一次；

避免同时为同一 API Key 发起大量重复请求；

401 或 403 时提示用户修正配置，不持续快速重试；

429 或暂时性 5xx 时延迟重试，可采用逐步延长间隔的方式；

失败时显示查询错误，不要把失败结果当作余额 0。

以上为客户端接入建议，不代表平台承诺固定限流阈值。

12. 常见问题

为什么模型可以调用，但用量查询返回 403？

模型调用权限与用量查询权限是两项独立设置。请在「令牌管理 → 编辑令牌 → 用量查询」中开启查询。

为什么不限额令牌查询到的剩余值是 0？

在「令牌限额」模式下，不限额令牌固定返回 remaining: 0，且不返回 quota。客户端应只显示已用，不将其解释为余额耗尽。

为什么选择用户总额度后，已用金额与账户消费总额不一致？

usage.total.actual_cost 始终是当前 API Key 的累计消耗，账户其他 API Key 产生的消耗不包含在其中。

用户总额度返回的是总充值还是剩余余额？

返回的是当前剩余充值余额与剩余赠送余额之和，不是历史累计充值，也不是账户历史总额度。

可以用 remaining 减去 actual_cost 得到剩余余额吗？

不可以。remaining 已经是服务端计算好的剩余值，再次相减会导致重复扣减。

能否分别查询充值余额和赠送余额？

本接口不分别返回这两个字段，只返回合计剩余余额。

可以查询本月、本日或某个模型的消耗吗？

本接口返回当前 API Key 的累计消耗，不支持时间范围或模型筛选。

过期或额度耗尽的 API Key 还能查询吗？

可以进行只读查询，但前提是已开启用量查询、令牌未禁用、所属用户未被封禁，并且请求来源符合令牌的 IP 限制。

HTTP 200 是否表示该令牌可以正常调用模型？

不表示。它仅说明本次用量查询成功。模型调用仍受令牌有效期、余额、状态、模型限制及其他调用规则约束。

用量查询受令牌 IP 限制影响吗？

受影响。若配置了 IP 或 CIDR 限制，查询请求也必须来自允许的地址范围。

用量查询单位是否固定为美元？

不固定。请读取 unit，服务端会按照平台系统配置返回相应单位和换算后的数值。

修改用量查询设置后，需要重新生成 API Key 吗？

不需要。保存设置后，可继续使用原 API Key 查询；关闭后，该 Key 的后续用量查询会被拒绝。

关闭用量查询后，能否通过旧余额接口继续查询？

现有 API Key 用量及兼容余额查询入口也遵守同一项用量查询设置。关闭后，不应通过旧接口绕过该设置。

1. 接口说明#

主要规则#

2. 开启 API Key 用量查询#

2.1 设置入口#

2.2 设置选项#

2.3 关闭#

2.4 令牌限额#

有限额令牌#

不限额令牌#

2.5 用户总额度#

3. 请求方式#

3.1 基本信息#

3.2 请求头#

3.3 地址拼接#

4. 成功响应字段#

4.1 公共字段#

4.2 条件字段#

4.3 mode 与 usage_query_mode#

4.4 令牌状态#

5. 成功响应示例#

5.1 令牌限额：有限额#

5.2 令牌限额：不限额#

5.3 用户总额度#

5.4 有限额令牌额度耗尽#

6. 单位与数值规则#

6.1 单位跟随系统配置#

6.2 精度与展示#

6.3 剩余额度边界#

7. cURL 调用示例#

7.1 直接请求#

7.2 同时查看 HTTP 状态码和响应头#

8. Apifox 接入配置#

8.1 环境变量#

8.2 创建接口#

8.3 配置成功响应结构#

8.4 调试顺序#

9. JavaScript 接入示例#

10. 错误响应#

10.1 错误对照表#

10.2 缺少认证请求头#

10.3 无效 API Key#

10.4 令牌已禁用#

10.5 未开启用量查询#

10.6 来源 IP 不允许#

10.7 获取账户余额失败#

11. 客户端展示与轮询建议#

11.1 字段读取#

11.2 轮询#

12. 常见问题#

为什么模型可以调用，但用量查询返回 403？#

为什么不限额令牌查询到的剩余值是 0？#

为什么选择用户总额度后，已用金额与账户消费总额不一致？#

用户总额度返回的是总充值还是剩余余额？#

可以用 remaining 减去 actual_cost 得到剩余余额吗？#

能否分别查询充值余额和赠送余额？#

可以查询本月、本日或某个模型的消耗吗？#

过期或额度耗尽的 API Key 还能查询吗？#

HTTP 200 是否表示该令牌可以正常调用模型？#

用量查询受令牌 IP 限制影响吗？#

用量查询单位是否固定为美元？#

修改用量查询设置后，需要重新生成 API Key 吗？#

关闭用量查询后，能否通过旧余额接口继续查询？#

1. 接口说明

主要规则

2. 开启 API Key 用量查询

2.1 设置入口

2.2 设置选项

2.3 关闭

2.4 令牌限额

有限额令牌

不限额令牌

2.5 用户总额度

3. 请求方式

3.1 基本信息

3.2 请求头

3.3 地址拼接

4. 成功响应字段

4.1 公共字段

4.2 条件字段

4.3 `mode` 与 `usage_query_mode`

4.4 令牌状态

5. 成功响应示例

5.1 令牌限额：有限额

5.2 令牌限额：不限额

5.3 用户总额度

5.4 有限额令牌额度耗尽

6. 单位与数值规则

6.1 单位跟随系统配置

6.2 精度与展示

6.3 剩余额度边界

7. cURL 调用示例

7.1 直接请求

7.2 同时查看 HTTP 状态码和响应头

8. Apifox 接入配置

8.1 环境变量

8.2 创建接口

8.3 配置成功响应结构

8.4 调试顺序

9. JavaScript 接入示例

10. 错误响应

10.1 错误对照表

10.2 缺少认证请求头

10.3 无效 API Key

10.4 令牌已禁用

10.5 未开启用量查询

10.6 来源 IP 不允许

10.7 获取账户余额失败

11. 客户端展示与轮询建议

11.1 字段读取

11.2 轮询

12. 常见问题

为什么模型可以调用，但用量查询返回 403？

为什么不限额令牌查询到的剩余值是 0？

为什么选择用户总额度后，已用金额与账户消费总额不一致？

用户总额度返回的是总充值还是剩余余额？

可以用 remaining 减去 actual_cost 得到剩余余额吗？

能否分别查询充值余额和赠送余额？

可以查询本月、本日或某个模型的消耗吗？

过期或额度耗尽的 API Key 还能查询吗？

HTTP 200 是否表示该令牌可以正常调用模型？

用量查询受令牌 IP 限制影响吗？

用量查询单位是否固定为美元？

修改用量查询设置后，需要重新生成 API Key 吗？

关闭用量查询后，能否通过旧余额接口继续查询？