Appearance
账号余额查询 API
通过 API 查询账号余额,用于在自有系统中展示可用余额和历史消费
概述
平台提供专用的账号余额查询接口 GET /api/user/balance,返回当前剩余额度和累计已用额度。
INFO
此接口使用个人资料访问令牌认证,不是模型调用 API Key(sk-xxx)。两者用途不同,请勿混淆。
余额响应同时包含原始额度字段和展示金额字段。原始额度字段始终以 quota 为单位;展示金额只用于前端展示,不改变账号额度、扣费或计费口径。
认证方式
在个人资料页生成或重置个人资料访问令牌,通过 Authorization header 传递:
bash
curl -H "Authorization: Bearer <你的个人资料访问令牌>" \
https://aiapi.fhddos.com/api/user/balanceWARNING
模型调用 API Key(sk-xxx 开头)无法访问此接口。请确保使用个人资料访问令牌。
响应示例
金额展示启用时
json
{
"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
}
}
}金额展示禁用时
json
{
"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位小数) |
TIP
推荐使用 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 值用于额度判断,不要假设站点的金额换算配置。