查询余额

GET /v1/account/balance 返回账号级余额：剩余可用额度和累计已用金额（单位 USD）。可以把它接入自己的监控系统、充值提醒或内部运维面板，在请求开始报错之前及时发现余额不足。

账号级，不是 key 级

本接口返回的是 API key 所属账号的余额，不受这把 key 自身额度限额的约束。如果要查某一把 key 还剩多少额度，请用 key 级 billing 端点。

请求

账号下任意一把有效 API key 都可以。key 在这里只作为凭证，额度耗尽的 key 同样可以查余额，余额见底后仍能查到正是本接口的用途。

curl https://api.hiapi.ai/v1/account/balance \
  -H "Authorization: Bearer $HIAPI_API_KEY"

无请求体，无查询参数。

响应

{"object":"account_balance","balance_usd":9.98,"used_usd":194.56,"currency":"USD"}

字段	类型	说明
object	string	固定为 account_balance。
balance_usd	number	账号剩余余额，单位 USD。
used_usd	number	账号注册以来的累计已用金额，单位 USD。
currency	string	固定为 USD。单位固定，不随站点展示设置变化。

余额由平台内部额度单位换算而来，存在轻微的浮点舍入属正常现象。

错误

HTTP	含义
401	API key 缺失、无效、已禁用或已过期。
403	请求来源 IP 不在该 key 的允许 IP 列表内。
429	触发限流：每账号每分钟 60 次。退避后重试。
500	内部错误，如数据库故障或计费配置异常。

余额查询免费：不消耗任何额度，限流额度独立于生成请求。

与 billing 端点的区别

HiAPI 也保留了 OpenAI 兼容的端点：

• GET /v1/dashboard/billing/subscription 返回的是调用者这把 key 自己的额度上限
• GET /v1/dashboard/billing/usage 是这把 key 的用量

这两个端点跟 key 自身额度走，且字段名沿用 OpenAI 的旧命名，用来做账号余额监控容易误读。新集成请优先使用 /v1/account/balance。