Skip to main content
GET
获取用户余额

接口说明

用户余额查询接口提供账户的完整财务信息,帮助您实时了解账户状态。

主要特性

  • 实时余额: 查询当前可用余额
  • 累计统计: 显示累计充值和消费金额
  • 快速响应: 无需复杂计算,直接返回结果
  • 安全认证: 支持API Key和JWT双重认证

认证方式

string
required
Bearer Token认证,支持API Key或JWT Token

请求参数

此接口无需请求参数,直接GET请求即可。

响应参数

integer
required
用户ID
string
required
当前账户余额(元)使用字符串格式保证精度,避免浮点数精度问题
string
required
累计充值金额(元)用户注册以来的所有充值总和
string
required
累计消费金额(元)用户注册以来的所有消费总和
string
required
账户创建时间(北京时间)格式:ISO 8601
string
required
账户最后更新时间(北京时间)每次充值或消费后更新

请求示例

响应示例

错误码说明

使用场景

在调用 AIGC 改写等付费接口前,建议先查询余额:
定期查询余额,实现余额预警功能:
为用户提供清晰的余额显示:
根据余额计算还能调用多少次服务:

数据精度说明

重要: 余额字段使用字符串格式而非数字,以保证精度。
在进行金额计算时,建议使用高精度数值类型:
  • Python: 使用 decimal.Decimal
  • JavaScript: 使用 Big.jsdecimal.js
  • Java: 使用 BigDecimal

时区说明

所有时间字段均已转换为 北京时间(UTC+8),无需客户端再次转换。
示例时间格式:
解析示例:

最佳实践

1. 缓存余额信息

避免频繁查询,合理使用缓存:

2. 错误处理

完善的错误处理机制:

3. 余额变化监听

监听余额变化,及时更新UI:

常见问题

使用字符串格式可以避免浮点数精度问题。金融数据对精度要求极高,使用字符串+高精度库(如Decimal)是业界最佳实践。
余额更新是实时的。当您充值或消费后,立即调用此接口即可获得最新余额。
系统支持欠费保护机制。当余额不足但服务已完成时,会创建欠费订单,余额可能变为负数。充值回正后,可以查看欠费期间的处理结果。

技术支持

遇到问题?我们随时为您提供帮助:

Authorizations

Authorization
string
header
required

使用API Key进行认证,格式:Bearer ak_xxxxxxxxxxxxxxxx

Response

查询成功

user_id
integer
required

用户ID

Example:

123

current_balance
string
required

当前余额(元)

Example:

"158.50"

total_recharged
string
required

累计充值金额(元)

Example:

"500.00"

total_consumed
string
required

累计消费金额(元)

Example:

"341.50"

created_at
string<date-time>
required

账户创建时间(北京时间)

Example:

"2025-01-15T10:30:00+08:00"

updated_at
string<date-time>
required

最后更新时间(北京时间)

Example:

"2025-09-30T14:20:00+08:00"