余额查询
用 API Key 查询个人空间或组织的当前可用余额，可用于余额告警和充值提醒。
端点为 GET /v1/balance。用调用模型时的同一把 API Key 鉴权，返回这把 Key 的扣费方当前的可用余额。调用本身不收费。
基本调用
curl https://api.goodputai.cn/v1/balance \
-H "Authorization: Bearer $GOODPUT_API_KEY"也可以直接复用 OpenAI SDK 的客户端：
import httpx
from openai import OpenAI
client = OpenAI(
base_url="https://api.goodputai.cn/v1",
api_key="你的 GoodPut API Key",
)
balance = client.get("/balance", cast_to=httpx.Response).json()
print(balance["balance"], balance["is_available"])响应
{
"object": "balance",
"owner_type": "personal",
"currency": "CNY",
"balance": "86.12",
"is_available": true,
"as_of": "2026-09-17T08:00:00Z"
}| 字段 | 说明 |
|---|---|
owner_type | 扣费方：personal 为个人空间，organization 为组织 |
currency | 币种，固定为 CNY |
balance | 可用余额（元），字符串，保留到分，向下截断（如 9.699999 元返回 "9.69"）；账户不限额时为 null |
is_available | 网关是否还会按余额放行请求，与网关的实际判断一致；账户不限额时恒为 true。因为按截断前的余额判断，余额不足 1 分钱时（部分早期组织在余额恰好用完时也是）可能出现 balance 为 "0.00"、is_available 仍为 true |
as_of | 查询时刻（UTC） |
balance 以字符串返回，避免浮点误差。需要数值计算时，请用 Decimal 等十进制类型解析。
查的是谁的余额
| Key 类型 | 返回 |
|---|---|
| 个人 Key | 个人空间余额 |
| 团队 Key、成员在团队内的 Key | 所属组织的余额 |
| 订阅 Key | Key 所属个人空间或组织的按量余额；套餐额度不在此返回，请到控制台「财务 → 套餐管理」查看 |
Key 的层级说明见组织与团队。
持有团队 Key 的任何人都能查到组织余额。分发团队 Key 时请考虑这一点。
与控制台余额的差异
- 更新时机不同：本接口按网关的实时扣费计算，控制台余额要等结算后才更新（通常在几分钟内）。因此两边可能短暂不一致，对账以控制台为准。
- 不显示欠费金额：余额用完或欠费时，本接口只返回
"balance": "0.00"和"is_available": false。具体欠费金额请到控制台「财务」查看。 - 不反映额度上限：Key 额度、团队额度等上限只限制花费，不会改变本接口的返回值。
错误
错误结构与其他接口相同，见错误码与限流。
| 状态码 | 原因 | 处理建议 |
|---|---|---|
| 401 | Key 无效、已删除或已被停用 | 检查 Key |
| 429 | 账户欠费冻结（code: credit_balance_exhausted） | 登录控制台查看余额并充值，充值后自动恢复 |
| 503 | 暂时无法获取余额 | 稍后重试 |
做余额告警时，建议每分钟查询一次或更低频率，并在 is_available 变为 false 之前设定提醒阈值。