账号余额查询 API

概述

平台提供专用的账号余额查询接口 GET /api/user/balance，返回当前剩余额度和累计已用额度。

此接口使用个人资料访问令牌认证，不是模型调用 API Key（sk-xxx）。两者用途不同，请勿混淆。

余额响应同时包含原始额度字段和展示金额字段。原始额度字段始终以 quota 为单位；展示金额只用于前端展示，不改变账号额度、扣费或计费口径。

认证方式

在个人资料页生成或重置个人资料访问令牌，通过 Authorization header 传递：

curl -H "Authorization: Bearer <你的个人资料访问令牌>" \
  https://models.phanedge.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
    }
  }
}

字段说明

字段	类型	说明
`quota`	int	当前剩余额度（原始值）
`used_quota`	int	累计已用额度（原始值）
`balance_quota`	int	当前剩余余额，等于 `quota`
`quota_unit`	string	固定值 `"quota"`，标识原始字段单位
`display.enabled`	bool	金额展示是否启用
`display.currency`	string	货币标识，跟随个人设置，默认 `"CNY"`（启用时返回）
`display.balance`	float	剩余余额金额（启用时返回，6位小数）
`display.used`	float	已用金额（启用时返回，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 调用返回认证失败？

sk-xxx 是模型调用 API Key，只能用于 /v1/ 下的模型请求接口。账号余额查询需要使用个人资料访问令牌；用 sk-xxx 调用此接口返回认证失败是预期行为。

展示币种会影响扣费吗？

不会。展示币种只影响 display.currency、display.balance 和 display.used 等展示字段。quota、used_quota 和 balance_quota 仍是原始额度值，实际扣费和额度计算不受展示币种影响。

balance_quota 和 quota 有什么区别？

两者值相同。balance_quota 是为余额展示场景提供的语义更清晰的字段名。

display 禁用时如何计算金额？

display.enabled 为 false 时，平台未对外提供可直接展示的金额字段。此时请保留原始 quota 值用于额度判断，不要假设站点的金额换算配置。

入门

帮助

概述

认证方式

响应示例

金额展示启用时

金额展示禁用时

字段说明

与其他接口的区别

常见问题

​概述

​认证方式

​响应示例

​金额展示启用时

​金额展示禁用时

​字段说明

​与其他接口的区别

​常见问题

概述

认证方式

响应示例

金额展示启用时

金额展示禁用时

字段说明

与其他接口的区别

常见问题