Balance query
Query the available balance of a personal space or organization for balance alerts and recharge reminders.
Use GET /v1/balance with the same API Key you use for model calls. It returns the available balance of the party charged for that key. The query itself is free.
Basic request
curl https://api.goodputai.cn/v1/balance \
-H "Authorization: Bearer $GOODPUT_API_KEY"You can also reuse your OpenAI SDK client:
import httpx
from openai import OpenAI
client = OpenAI(
base_url="https://api.goodputai.cn/v1",
api_key="YOUR_GOODPUT_API_KEY",
)
balance = client.get("/balance", cast_to=httpx.Response).json()
print(balance["balance"], balance["is_available"])Response
{
"object": "balance",
"owner_type": "personal",
"currency": "CNY",
"balance": "86.12",
"is_available": true,
"as_of": "2026-09-17T08:00:00Z"
}| Field | Description |
|---|---|
owner_type | Charged party: personal for a personal space, organization for an organization |
currency | Always CNY |
balance | Available balance in yuan, as a string truncated downward to two decimal places (for example, 9.699999 returns "9.69"); null for an uncapped account |
is_available | Whether the gateway still admits requests based on the balance, matching its actual decision; always true for uncapped accounts. The decision uses the balance before truncation, so a balance below 1 cent can return "0.00" while this field remains true. Some early organizations may also show this at exactly zero |
as_of | Query time in UTC |
balance is a string to avoid floating-point errors. Use a decimal type such as Decimal for calculations.
Whose balance is returned?
| Key type | Balance returned |
|---|---|
| Personal key | Personal space balance |
| Team key, or a member’s key within a team | The organization’s balance |
| Subscription key | Pay-as-you-go balance of the key’s personal space or organization. Package quotas are not included; view them under Finance → Plan Management in the console |
See organizations and teams for key levels.
Anyone holding a team key can query the organization’s balance. Consider this when distributing keys.
Differences from the console
- Update timing: this API uses the gateway’s live deductions. The console updates after settlement, usually within a few minutes. Temporary differences are possible; use the console for reconciliation.
- Arrears are not shown: when funds are exhausted or the account is in arrears, this API returns only
"balance": "0.00"and"is_available": false. View the arrears amount under Finance in the console. - Budget caps are not reflected: key and team caps limit spending but do not change this response.
Errors
The error structure matches other endpoints; see errors and rate limits.
| Status | Cause | Action |
|---|---|---|
| 401 | Invalid, deleted, or disabled key | Check the key |
| 429 | Account frozen for insufficient funds (code: credit_balance_exhausted) | Check the console balance and add funds; service resumes automatically |
| 503 | Balance temporarily unavailable | Retry later |
For balance alerts, query once per minute or less often, and set a threshold that alerts before is_available becomes false.