查询余额

1. 接口说明

该接口用于通过普通 API Key 查询：

• 当前 API Key 所属的用户 ID
• 用户账户余额
• 用户余额按站点配置换算后的展示金额
• 当前这把 API Key 的额度信息

该接口使用普通 sk-... API Key 调用，不需要用户登录态。

---

2. 请求信息

项目	内容
请求方法	GET
请求路径	/api/usage/balance
鉴权方式	Authorization: Bearer sk-xxx
Content-Type	无请求体，可不传

---

3. 请求示例

curl -X GET "https://api.aijisu.cn/api/usage/balance" \
  -H "Authorization: Bearer sk-your-api-key"

---

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

HTTP 状态码：401

{
  "success": false,
  "message": "Token not provided"
}

6.2 API Key 不存在或无效

HTTP 状态码：401

{
  "success": false,
  "message": "Invalid token"
}

6.3 API Key 已禁用

HTTP 状态码：403

{
  "success": false,
  "message": "Token invalid"
}

---

7. 调用注意事项

• 必须使用 Authorization: Bearer sk-xxx 传入 API Key。
• 返回的是 API Key 所属用户的账户余额，不是上游渠道余额。
• 接口不会返回原始 API Key 字符串。
• 已禁用的 API Key 不能查询余额。
• API Key 已过期或额度耗尽时，仍可查询余额，只要 Key 未禁用且用户未被封禁。
• amount 和 display_amount 会根据站点当前余额展示配置动态变化。