Skip to content
中

Account API overview

Issue a read-only key in the console and connect XiuAI account data to your monitoring, reconciliation, and reporting systems.

Updated Reviewed
View Markdown

Use the Account API to monitor your account balance, sync request records, and summarize costs by model and API key for reconciliation and internal reporting.

Each key can read data only for its assigned XiuAI account. This API uses a separate, read-only key that cannot call models, add funds, or change the account. Continue using your XiuAI API key for model requests.

Task Request Required scope
Read the balance and cumulative spending GET /open/v1/balance balance:read
Sync individual request records GET /open/v1/requests usage:read
Summarize usage and costs for a period GET /open/v1/requests/summary usage:read

The base URL is https://api.xiu.ai. All requests use HTTPS and responses are UTF-8 JSON.

Get a key

Issue keys yourself in the console. You do not need to contact support:

  1. Sign in to the XiuAI console and open the Account API page.
  2. Select Issue key, enter a name, select the scopes you need, and choose an expiration if needed. Reading the balance requires balance:read; reading request records and cost summaries requires usage:read. Select both if you need both.
  3. Copy the complete key, which begins with xiu_sk_, into your server’s secret manager or environment variables. It is shown only once; after you close it, only its last four characters are available.

Each account can hold up to 10 active keys at a time. To add scopes to an existing key, edit it in the console; replacement is unnecessary. If a key is lost or may have been exposed, revoke it in the console and issue a new one. Revocation takes effect immediately. The assigned account and expiration cannot be changed after issuance.

An administrator can also issue a key for your account. Such keys appear in your console list as well, and you can edit or revoke them.

The usage:read scope allows access to all request records for the assigned account. The keyName parameter filters results; it does not restrict which records the read-only key can access or provide permission boundaries between projects or team members.

Authenticate and make your first query

Send an Authorization: Bearer header with every request. Do not pass the key in URL parameters or cookies.

After injecting the key into the server environment variable XIU_OPEN_API_KEY, run:

curl --fail-with-body --silent --show-error \
  --connect-timeout 5 --max-time 15 \
  https://api.xiu.ai/open/v1/balance \
  -H "Authorization: Bearer $XIU_OPEN_API_KEY"

A successful response returns HTTP 200 and balance JSON. For 401, confirm you are using a read-only key beginning with xiu_sk_, then check its status in the console. For 403, add balance:read to the key in the console.

Keep the key on your server. Do not include it in browser or mobile app code, repositories, logs, or support tickets. The API does not return CORS headers and cannot be called directly from a browser. To show data in your own application, retrieve it on your server and serve the results to your page.

A successful query returns the fields described in Read the account balance. For request synchronization, see request records and the Python example.

Navigation

Enter keywords to search

↑↓ Move↵ OpenEsc Close