FAQ

Integration

How much of the path should the base URL include?

The API domain itself does not include /v1. For the OpenAI SDK and most OpenAI-compatible clients, use https://<API domain>/v1; for the Anthropic SDK and Claude Code, use https://<API domain>; for the Gemini SDK, use https://<API domain>. A 404 usually means /v1 is missing or duplicated.


Why do I get a 401?
  • You didn't provide an API key...: No key was sent, or the key is not a 51-character string starting with sk-Xvs.
  • Unauthorized: The key does not exist or has been rotated.
  • Insufficient balance...: The balance is below the freeze threshold and the account has just been frozen. It recovers after you top up.

If the error body is in an upstream provider's JSON format, the request was probably sent straight to the official endpoint. Check your base_url.


Why am I told I can't use a model, or why is a different model called than the one I requested?
  • 403 Access denied: You are not authorized to use the '<model>' model: The account has a model allowlist.
  • XSI rewrites models according to MODEL_MAPPER, and model names not in the price list are fuzzy-matched to the closest-versioned priced model in the same family. Use the exact names from GET /v1/models or the price catalog.

Streaming output stalls or arrives all at once?

The reverse proxy is usually buffering the response. In Nginx, turn off proxy_buffering and set proxy_read_timeout long enough; if you go through a CDN, check its response timeout. See Reverse Proxy.


What if an open-source project doesn't let me configure base_url?

Most SDKs accept the endpoint from an environment variable (such as OPENAI_BASE_URL or ANTHROPIC_BASE_URL). If it truly cannot be configured, the only option is to change the API address in the project's source code.


Billing and credit

How is usage billed?

Charges are deducted in real time based on the actual usage reported by the upstream, in CNY:

Charge = list price Γ— usage Γ— model Rates Γ— account Rates Γ— account Factor

The price list records list prices in the provider's original currency; for models priced in USD, Rates defaults to 7. An account's final unit prices are shown in the final field of GET /x-pricing (sent with the key). See Billing and Pricing.


Are failed requests billed?

Regular HTTP requests for which the upstream returns an error directly and that produce no usage are not billed. A POST rejected by an allowlist or a model-level limit, an unparseable request body, or a call to an unpriced model incurs a one-time XAPI_FEE (default Β₯0.012), shown as XAPI in the bill. Interrupted or failed requests are settled according to the protocol and the usage obtained: reliable upstream usage takes precedence, and any missing part is estimated from the observed content and session history; input already accepted by the upstream may also be billed.


Does credit expire?

Yes. Each credit grant has its own expiry: top-ups default to 1 year, signup bonuses to 1 month, and credit transferred to a sub-account keeps the expiry of the source credit. See credit_balance in GET /dashboard/info.


My account still has a balance, so why does it say the balance is insufficient or the account is suspended?

When the balance is at or below the freeze threshold (USER_MIN_BALANCE βˆ’ 0.01, Β₯1.99 in the deployment template), the account is suspended: a request that first finds the balance insufficient returns 401, and once the account has been frozen by background settlement, requests return 429. It recovers automatically once a top-up brings the balance above the threshold.


Limits and rate limits

Why don't my RPM / DailyLimit settings take effect?

Credit limits and rate limits apply only to Role 2 (strict) and Role 3 (subscription) accounts. The root account created by INIT_USERS is Role 0; single-tenant self-signup accounts inherit root's Role (usually 0), multi-tenant signups default to Role 1, and sub-accounts inherit their parent's Role. Have the tenant owner set the accounts you want to limit to Role 2.


How long until a 429 clears?
Limit hitRecovery
RPM, TPMAbout 1 minute
RPH, TPHAbout 1 hour
RPD, TPD, DailyLimitMidnight the next day (server time zone)
HardLimitNext month

RPD/TPD are calendar-day limits, not rolling 24-hour windows. Requests are counted when they pass admission: admitted requests that fail upstream count too, while requests rejected during the cooldown do not consume quota again; tokens are added after a request completes, so overages usually start returning 429 from the next request. Clients should use exponential backoff instead of retrying continuously.


Why does calling /x-users return 403?

Managing sub-accounts requires all of the following: TPD > 800000000, sub-account capability (UserLimit > 0 or existing sub-accounts), and a balance above USER_API_BALANCE (default Β₯100). The error body states which requirement is missing. Check the manage field of GET /dashboard/status in advance.


Why can't a sub-account create its own sub-accounts?

When a parent account (other than root) has a UserLimit below 64, the sub-accounts it creates have UserLimit fixed at 0: they can use the service but cannot distribute it further.


Deployment

I can't sign in to the console, and the browser reports a CORS error?

XSI does not send CORS response headers. For the consoles to call the API cross-origin, the reverse proxy must add CORS headers for the API domain and answer OPTIONS preflight requests directly. Follow the Nginx example in Reverse Proxy.


Requests return 500 No available key?

There is no usable key in the Level for the requested model. Check that LEVEL_MAPPER maps the model to the correct Level, and whether all keys in that Level are disabled or sleeping. Sleeping and disabled keys are listed under Model Providers in the Admin Console and in GET /x-conf.


I changed the root key in docker-compose.yml. Why does the old key still work?

INIT_USERS only creates accounts that don't exist; it never updates existing ones. To rotate the root key, call POST /x-self with the confirmation phrase <date>-ROTATE-ROOT.


How do I change the default model prices?

Use a tenant PRICING override: it takes effect immediately with no restart. Editing api/pricing.json requires rebuilding the image or mounting the file, then restarting. See Billing and Pricing.


How do I scale out to multiple servers?

Point all instances at the same PostgreSQL and Redis, set SINGLE_MODE=false, and run them behind a load balancer. See Operations.


Licensing

Is XSI free to use?

Personal, non-commercial use (learning, research, experimentation, and personal use) is free. Enterprise production use and any other commercial use (including paid APIs or paid services operated by individuals) requires a commercial license; the standard fee is CNY 2,400 per licensed entity per year. See the commercial licensing terms.


Can I remove the XSI attribution from the consoles?

No. All users, including commercial licensees, must retain the XSI by XABC Labs attribution and the link to the original project; for applications with a sign-in page, showing it on the sign-in page is sufficient. You may customize the brand name, layout, and styling. See NOTICE.


Can I turn off the broadcast bar and the promotional card in the consoles?

The top broadcast bar and promotional card that the consoles show by default carry content provided by XABC Labs. They help fund XSI's continued development and operation and are what allows XSI to be offered free to individuals. When using XSI for free, please keep them as they are and do not remove, hide, replace or modify them; this condition is what lets us keep providing and maintaining XSI for free. Businesses that need to adjust or disable them can agree on it in a commercial license.


Is there a hosted service if I don't want to deploy it myself?
  • xsirouter.com: The AI API service operated by the XSI team; sign up and start calling models.
  • xsicontrol.com: The multi-tenant XSI cloud service; use your own upstream keys with no deployment.