查询用户余额接口
API Key 查询用户余额接口
1. 接口说明
sk-... API Key 调用，不需要用户登录态。2. 请求信息
| 项目 | 内容 |
|---|---|
| 请求方法 | GET |
| 请求路径 | /api/usage/balance |
| 鉴权方式 | Authorization: Bearer sk-xxx |
| Content-Type | 无请求体， 可不传 |
3. 请求示例
4. 成功响应示例
{
"success": true,
"message": "",
"data": {
"object": "api_key_balance",
"user_id": 1,
"balance": {
"quota": 1000000,
"amount": 14.6,
"display_amount": "¥14.60",
"quota_per_unit": 500000,
"quota_display_type": "CNY",
"currency_symbol": "¥",
"exchange_rate": 7.3
},
"token": {
"id": 12,
"name": "my-key",
"remain_quota": 100000,
"used_quota": 5000,
"total_quota": 105000,
"unlimited_quota": false,
"expired_time": -1,
"status": 1,
"model_limits_enabled": false,
"model_limits": {}
}
}
}5. 响应参数说明
5.1 顶层参数
| 参数 | 类型 | 说明 |
|---|---|---|
success | boolean | 请求是否成功 |
message | string | 响应消息，成功时通常为空字符串 |
data | object | 响应数据 |
5.2 data 参数
| 参数 | 类型 | 说明 |
|---|---|---|
data.object | string | 对象类型，固定为 api_key_balance |
data.user_id | number | 当前 API Key 所属的用户 ID |
data.balance | object | 用户账户余额信息 |
data.token | object | 当前 API Key 的额度信息 |
5.3 data.balance 参数
| 参数 | 类型 | 说明 |
|---|---|---|
data.balance.quota | number | 用户账户原始额度，系统内部额度单位 |
data.balance.amount | number | 按站点展示配置换算后的余额金额 |
data.balance.display_amount | string | 格式化后的展示金额，通常包含货币符号 |
data.balance.quota_per_unit | number | 额度换算单位，例如 500000 表示 500000 quota = 1 USD |
data.balance.quota_display_type | string | 余额展示类型，可能值：USD、CNY、CUSTOM、TOKENS |
data.balance.currency_symbol | string | 当前展示货币符号，例如 $、¥；当展示类型为 TOKENS 时为空字符串 |
data.balance.exchange_rate | number | 当前展示币种使用的汇率；USD 通常为 1，CNY 为人民币汇率，CUSTOM 为自定义汇率 |
5.4 data.token 参数
| 参数 | 类型 | 说明 |
|---|---|---|
data.token.id | number | 当前 API Key 的 ID |
data.token.name | string | 当前 API Key 的名称 |
data.token.remain_quota | number | 当前 API Key 剩余额度 |
data.token.used_quota | number | 当前 API Key 已使用额度 |
data.token.total_quota | number | 当前 API Key 总额度，计算方式为 remain_quota + used_quota |
data.token.unlimited_quota | boolean | 当前 API Key 是否为无限额度 |
data.token.expired_time | number | 当前 API Key 过期时间戳；-1 表示不过期 |
data.token.status | number | 当前 API Key 状态；1 表示启用 |
data.token.model_limits_enabled | boolean | 当前 API Key 是否启用模型限制 |
data.token.model_limits | object | 当前 API Key 的模型限制配置；未限制时通常为空对象 {} |
6. 错误响应
6.1 未传 API Key
401{
"success": false,
"message": "Token not provided"
}6.2 API Key 不存在或无效
401{
"success": false,
"message": "Invalid token"
}6.3 API Key 已禁用
403{
"success": false,
"message": "Token invalid"
}7. 调用注意事项
Authorization: Bearer sk-xxx 传入 API Key。amount 和 display_amount 会根据站点当前余额展示配置动态变化。修改于 2026-05-21 04:43:40