Skip to main content

​
概述

平台提供专用的账号余额查询接口 GET /api/user/balance，返回当前剩余额度和累计已用额度。
此接口使用个人资料访问令牌认证，不是模型调用 API Key（sk-xxx）。两者用途不同，请勿混淆。
余额响应同时包含原始额度字段和展示金额字段。原始额度字段始终以 quota 为单位；展示金额只用于前端展示，不改变账号额度、扣费或计费口径。

​
认证方式

在个人资料页生成或重置个人资料访问令牌，通过 Authorization header 传递： 
curl -H "Authorization: Bearer <你的个人资料访问令牌>" \
  https://models.kapon.cloud/api/user/balance
模型调用 API Key（sk-xxx 开头）无法访问此接口。请确保使用个人资料访问令牌。

​
响应示例

​
金额展示启用时

{
  "success": true,
  "message": "",
  "data": {
    "quota": 1000000,
    "used_quota": 500000,
    "balance_quota": 1000000,
    "quota_unit": "quota",
    "display": {
      "enabled": true,
      "currency": "CNY",
      "balance": 14.0,
      "used": 7.0
    }
  }
}

​
金额展示禁用时

{
  "success": true,
  "message": "",
  "data": {
    "quota": 1000000,
    "used_quota": 500000,
    "balance_quota": 1000000,
    "quota_unit": "quota",
    "display": {
      "enabled": false
    }
  }
}

​
字段说明

字段类型说明
quotaint当前剩余额度（原始值）
used_quotaint累计已用额度（原始值）
balance_quotaint当前剩余余额，等于 quota
quota_unitstring固定值 "quota"，标识原始字段单位
display.enabledbool金额展示是否启用
display.currencystring货币标识，跟随个人设置，默认 "CNY"（启用时返回）
display.balancefloat剩余余额金额（启用时返回，6位小数）
display.usedfloat已用金额（启用时返回，6位小数）
推荐使用 data.display.balance 直接展示余额金额；如需原始额度值用于自定义计算，使用 data.balance_quota。展示币种可在「个人资料」页面的“额度展示币种”中调整，默认人民币 CNY。该设置只影响 display 展示字段，不影响原始 quota 数值和实际计费。

​
与其他接口的区别

接口认证方式用途
GET /api/user/balance个人资料访问令牌推荐 — 专用余额查询
GET /api/user/self个人资料访问令牌兼容 — 返回完整用户资料（含 quota/used_quota）
GET /v1/dashboard/billing/subscription模型 API Key (sk-xxx)OpenAI 兼容 — 返回令牌视角额度，非账号余额

​
常见问题

登录平台后，进入「个人资料」页面，点击「生成访问令牌」即可获取。
sk-xxx 是模型调用 API Key，只能用于 /v1/ 下的模型请求接口。账号余额查询需要使用个人资料访问令牌；用 sk-xxx 调用此接口返回认证失败是预期行为。
不会。展示币种只影响 display.currency、display.balance 和 display.used 等展示字段。quota、used_quota 和 balance_quota 仍是原始额度值，实际扣费和额度计算不受展示币种影响。
两者值相同。balance_quota 是为余额展示场景提供的语义更清晰的字段名。
display.enabled 为 false 时，平台未对外提供可直接展示的金额字段。此时请保留原始 quota 值用于额度判断，不要假设站点的金额换算配置。