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_url and 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 typeAccepted 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 WebSocketAlso 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 APIsGET /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

LevelConditionTypical APIs
Any accountValid key and enabled accountModel calls, /dashboard/*, POST /x-self
Managerroot; 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 ownerID == OID; root is also an owner/x-keys, /x-config, /x-conf, /x-info
rootDNA == "."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/json or multipart/form-data correctly on model endpoints; otherwise XSI cannot read model from the request body, and model mapping and model permissions will not apply.
  • Compressed request bodies: Content-Encoding: gzip, deflate, br and zstd are supported; XSI decompresses before forwarding.
  • Request body limit: 200 MiB by default, configurable via REQUEST_BODY_LIMIT_BYTES. XSI checks the declared Content-Length before authentication, then checks the decompressed size while reading; larger bodies receive 413. Realtime calls and Live session creation have a separate 4 MiB limit.
  • Dates: query parameters use YYYY-MM-DD and are interpreted in the server time zone (the deployment template defaults to Asia/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-keys and /x-conf use Go field names (PascalCase, e.g. CreditGranted); /dashboard/*, /x-info and /x-pricing use snake_case. Write field names with exactly the casing shown in this reference.
  • Pagination: account and key lists accept page and size, return at most 8192 items per page, and return X-Total-Count; paginated responses also include X-Page, X-Per-Page and X-Total-Pages. For /dashboard/logs, size is 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 name XAPI. See each endpoint for details.

Error format

  • Errors generated by XSI itself are single-line text/plain messages (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-sign and the configuration API /x-config return JSON results.

For the full list of status codes and error strings, see Errors.

Endpoint index

Data plane

EndpointDocs
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 TTSWebSocket and Realtime APIs
GET /v1/models, GET /user/balanceRouter API

Control plane

EndpointDescriptionDocs
GET /dashboard/status, /info, /live, /bill, /logs, /newsCurrent account status and usageAccount and Usage API
GET /x-billDescendant usage and rankingsAccount and Usage API
/x-users, /x-dna, /x-users/batch-credit, /x-self, /x-newsSub-accounts, credit and announcementsAccount Management API
/x-keysUpstream Provider KeysProvider Key API
/x-config, /x-conf, /x-infoTenant configuration and runtime controlTenant Configuration API
GET /x-pricingPricing catalogPricing Catalog API
/x-signSelf-service signupSignup API
/x-notify/*Payment gateway notificationsPayment Notification API
GET /healthzHealth check; returns OKβ€”