查询额度使用情况

用途#

查询当前 API Key 对应的令牌额度，以及该令牌所属用户的账户额度。接口同时返回令牌与用户两个维度的剩余 credits 和累计已用 credits，适合余额展示、调用前检查和低余额告警。

原 /api/usage/token/ 已移除，请统一使用本接口。

请求示例#

cURL

curl --request GET \
  --url https://api.apimax.ai/v1/usage \
  --header 'Authorization: Bearer sk-xxxx'

鉴权与参数#

本接口使用与模型调用相同的 API Key 鉴权，不需要后台登录态 access token。

参数	位置	类型	必填	说明
`Authorization`	header	string	是	`Bearer <API Key>`，即后台创建令牌时生成的 `sk-` 开头字符串

接口没有 query 或 body 参数。API Key 必须处于启用状态且未过期，并满足令牌 IP 与分组限制。

成功响应#

200

{
  "success": true,
  "message": "",
  "data": {
    "token": {
      "remaining_credits": 7.6,
      "used_credits": 2.4,
      "unlimited_credits": false
    },
    "user": {
      "remaining_credits": 12.5,
      "used_credits": 3.5
    }
  }
}

响应字段#

字段	类型	说明
`success`	bool	请求是否成功
`message`	string	成功时为空字符串
`data.token.remaining_credits`	number	当前 API 令牌的剩余 credits
`data.token.used_credits`	number	当前 API 令牌的累计已用 credits
`data.token.unlimited_credits`	bool	当前令牌是否为无限额度令牌
`data.user.remaining_credits`	number	令牌所属用户的账户剩余 credits
`data.user.used_credits`	number	令牌所属用户的账户累计已用 credits

Credits 换算#

响应中的 credits 由内部 quota 除以系统 QuotaPerUnit 得到。当前默认配置为 500000 quota = 1 credit：

3800000 quota 返回为 7.6 credits
实际扣费仍按模型价格、输入输出 token、分组倍率及其他计费规则结算

unlimited_credits=true 表示令牌不受令牌剩余额度限制；remaining_credits 仍作为统计参考。用户账户额度仍按系统计费规则管理。

错误响应#

HTTP	说明
401	API Key 缺失、无效、已禁用、已过期或额度已耗尽
403	用户被禁用、来源 IP 不在令牌白名单内，或令牌分组不可用
429	请求频率超过限制
500	服务内部查询失败

401

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: ...)",
    "type": "new_api_error"
  }
}