Query User Balance

Get the remaining and used balance of the current user account. This endpoint returns user-level balance information, independent of specific tokens, for viewing the overall account balance.

curl --request GET \
  --url 'https://gccai.heqingsong.uk/v1/user/balance' \
  --header 'Authorization: Bearer <token>'

{
  "success": true,
  "remain_balance": 100.0,
  "used_balance": 25.5,
  "unlimited_quota": false
}

Authorization

string

required

All API endpoints require Bearer Token authenticationGet your API Key:Visit the API Key Management Page to get your API KeyAdd it to the request header:

Authorization: Bearer YOUR_API_KEY

Endpoints

GET /v1/user/balance
GET /user/balance

Both endpoints have the same functionality, you can use either one.

Response

success

boolean

Whether the request was successful

message

string

Error message (only returned on failure)

remain_balance

float

User remaining balance (returned on success). Returns -1 when unlimited_quota is true

used_balance

float

User used balance (returned on success)

unlimited_quota

boolean

Whether the user has unlimited quota. true means unlimited, false means limited

Token Balance vs User Balance

Comparison	Token Balance (`/v1/balance`)	User Balance (`/v1/user/balance`)
Scope	Single token	Entire user account
Data Source	Token’s RemainQuota and UsedQuota	User’s quota and used_quota
Use Case	Monitor single API Key usage	View overall account balance
Limited By	Token-level quota limits	User-level quota limits

Use Cases

View overall user account balance
Set up recharge reminders and balance alerts
Display account balance in user dashboard

Balance Unit InformationThe unit of the balance value depends on system configuration:

USD - US Dollars
CNY - Chinese Yuan
Tokens - Token count

Unlimited Quota UserWhen a user is set to unlimited quota:

unlimited_quota field returns true
remain_balance field returns -1
The user has no quota restrictions and can use the API without limits

Common Errors

Error Message	Cause	Solution
No Authorization header	Authorization header not provided	Add `Authorization: Bearer sk-xxxxx` header
Failed to get user quota	User doesn’t exist	Check if the user associated with the token exists
Failed to get used quota	Database query error	Contact admin to check system status

Security NoteYour API Key is like a password. Keep it secure and don’t share it with others. Always use HTTPS in production.

Documentation Index

​Authorization

​Endpoints

​Response

​Token Balance vs User Balance

​Use Cases