API Reference
XSI serves two kinds of APIs from a single HTTP endpoint:
- Data plane (Router API): model calls. XSI preserves the native semantics of upstream protocols such as OpenAI, Anthropic and Gemini; to connect, just replace the
base_urland the API key. - Control plane (Management API): accounts, credit, upstream keys, tenant configuration and the pricing catalog. All paths start with
/x-or/dashboard/.
Every field, default value and error string in this reference is taken from the source code (the api/ directory).
Base URL
export XSI_BASE_URL="https://api.xsicontrol.com" # XSI Control; replace with your own API domain when self-hosting
export XSI_API_KEY="sk-Xvs..."XSI_BASE_URL does not include /v1. Model endpoints are usually written as $XSI_BASE_URL/v1/...; in SDKs, set base_url to $XSI_BASE_URL/v1 (for the Anthropic SDK, use $XSI_BASE_URL).
Authentication
All APIs authenticate with an XSI account API key. Keys start with sk-Xvs and are exactly 51 characters long; malformed keys are rejected before any database lookup.
| API type | Accepted credential locations |
|---|---|
Model calls and /dashboard/* | Authorization: Bearer <key>, x-api-key: <key>, x-goog-api-key: <key> (the first non-empty value, in this order) |
| DeepSeek text-to-speech WebSocket | Also accepts the subprotocol Sec-WebSocket-Protocol: tts, bearer.<key> |
Management APIs /x-* | Authorization header only (Bearer <key> recommended; a bare key is also accepted) |
| Public APIs | GET /x-pricing, /x-sign/* and GET /healthz require no authentication |
- Passing the key in a query parameter (such as Gemini-style
?key=) is not supported. - Before forwarding, XSI strips all caller credential headers (
Authorization,x-api-key,x-goog-api-key,api-key,Cookie, etc.) and client-IP forwarding headers, then writes the upstream key according to the upstream type. The caller's XSI key is never sent to a model provider. - Brute-force protection: an IP with 12 failed authentications within 1 minute is blocked for 2 minutes; 48 failures within 10 minutes block it for 15 minutes. Blocked requests receive
429. The same invalid key is rejected outright for 90 seconds.
Permission levels
| Level | Condition | Typical APIs |
|---|---|---|
| Any account | Valid key and enabled account | Model calls, /dashboard/*, POST /x-self |
| Manager | root; or all of: TPD > 800000000, sub-account capability (UserLimit > 0 or existing sub-accounts), and a balance above USER_API_BALANCE (default 100) | /x-users, /x-dna, /x-bill, /x-news, /dashboard/logs |
| Tenant owner | ID == OID; root is also an owner | /x-keys, /x-config, /x-conf, /x-info |
| root | DNA == "." | System announcements, signup domain policy |
The manage field returned by GET /dashboard/status is the result of the manager check, and the owner field is the result of the tenant owner check.
Common conventions
- Encoding: requests and responses are UTF-8. Set
Content-Type: application/jsonormultipart/form-datacorrectly on model endpoints; otherwise XSI cannot readmodelfrom the request body, and model mapping and model permissions will not apply. - Compressed request bodies:
Content-Encoding: gzip,deflate,brandzstdare supported; XSI decompresses before forwarding. - Request body limit: 200 MiB by default, configurable via
REQUEST_BODY_LIMIT_BYTES. XSI checks the declaredContent-Lengthbefore authentication, then checks the decompressed size while reading; larger bodies receive413. Realtime calls and Live session creation have a separate 4 MiB limit. - Dates: query parameters use
YYYY-MM-DDand are interpreted in the server time zone (the deployment template defaults toAsia/Shanghai); timestamps in responses are RFC 3339. - Currency: balances, charges and prices are all in Chinese yuan (CNY).
- Management API field names: requests and responses for
/x-users,/x-keysand/x-confuse Go field names (PascalCase, e.g.CreditGranted);/dashboard/*,/x-infoand/x-pricinguse snake_case. Write field names with exactly the casing shown in this reference. - Pagination: account and key lists accept
pageandsize, return at most 8192 items per page, and returnX-Total-Count; paginated responses also includeX-Page,X-Per-PageandX-Total-Pages. For/dashboard/logs,sizeis 1β100 and the total is returned in the JSON body. - Management call fee: some management queries are charged
XAPI_FEE(default Β₯0.012) and appear in the bill under the model nameXAPI. See each endpoint for details.
Error format
- Errors generated by XSI itself are single-line
text/plainmessages (e.g.Unauthorized); the HTTP status code indicates the error class. - Errors returned by an upstream are passed through unchanged, preserving the upstream status code and JSON structure.
- The signup API
/x-signand the configuration API/x-configreturn JSON results.
For the full list of status codes and error strings, see Errors.
Endpoint index
Data plane
| Endpoint | Docs |
|---|---|
POST /v1/chat/completions, /v1/responses, /v1/messages, /v1/embeddings, /v1/images/*, /v1/audio/*, /v1/videos/*, Gemini /v1beta/models/*, etc. | Router API |
| Responses WebSocket, Realtime, Live, DeepSeek TTS | WebSocket and Realtime APIs |
GET /v1/models, GET /user/balance | Router API |
Control plane
| Endpoint | Description | Docs |
|---|---|---|
GET /dashboard/status, /info, /live, /bill, /logs, /news | Current account status and usage | Account and Usage API |
GET /x-bill | Descendant usage and rankings | Account and Usage API |
/x-users, /x-dna, /x-users/batch-credit, /x-self, /x-news | Sub-accounts, credit and announcements | Account Management API |
/x-keys | Upstream Provider Keys | Provider Key API |
/x-config, /x-conf, /x-info | Tenant configuration and runtime control | Tenant Configuration API |
GET /x-pricing | Pricing catalog | Pricing Catalog API |
/x-sign | Self-service signup | Signup API |
/x-notify/* | Payment gateway notifications | Payment Notification API |
GET /healthz | Health check; returns OK | β |