Router API
Router API
XSI is a protocol-native router: it does not translate requests into a "unified format". Instead, it preserves the request and response semantics of each upstream protocol and rewrites only the model name, path and upstream credentials where necessary. Official SDKs and clients such as Codex and Claude Code only need a new base_url and API key.
export XSI_BASE_URL="https://api.xsicontrol.com" # Or your own API domain
export XSI_API_KEY="sk-Xvs..."How a request is processed
Every model request goes through these steps in order:
- Authentication: parse the caller's key and check the account status and authentication failure rate.
- Account admission: IP allowlist β account status, suspension, daily/monthly credit limits, balance, account-level RPM/TPM β resource (path) allowlist.
- Model resolution: read the model name from the request body (or URL) and map it to an upstream model using
MODEL_MAPPERand related rules. - Model admission: model allowlist (
AllowModels) and model-level limits (MODEL_LIMITS). - Upstream selection: determine the Level (group) from the model, then pick a key from that group's key pool by sticky session or round robin.
- Forwarding: rewrite the path and upstream auth headers, then forward. If the upstream returns a retryable error, XSI automatically retries with another key before writing any byte to the client.
- Metering and settlement: read usage from the response (including SSE streams) out of band and settle it against the price table.
For routing details, see Routing and Failover; for billing details, see Billing and Pricing.
OpenAI-compatible APIs
Except for the paths marked "handled locally" below, XSI forwards any path and method to the upstream of the selected key, so any API the upstream supports (such as /v1/batches, /v1/fine_tuning/*, /v1/vector_stores and /v1/completions) works directly. The table below lists the APIs XSI handles specifically:
| Capability | Method and path | Notes |
|---|---|---|
| Chat Completions | POST /v1/chat/completions | Supports sticky sessions |
| Responses | POST /v1/responses | Supports sticky sessions; also available over WebSocket, see WebSocket and Realtime APIs |
| Responses compaction | POST /v1/responses/compact | XSI forces Accept: application/json |
| Responses sub-resources | GET /v1/responses/{id}, POST /v1/responses/{id}/cancel, GET /v1/responses/{id}/input_items | Follow the same sticky path as the create request; GET requests are not billed |
| Embeddings | POST /v1/embeddings | Billed by usage.prompt_tokens |
| Image generation and editing | POST /v1/images/generations, POST /v1/images/edits, POST /v1/images/variations | Billed per image or per token, see below |
| Video generation | POST /v1/videos/generations, GET /v1/videos/{request_id} | Asynchronous jobs, see below |
| Audio | POST /v1/audio/transcriptions, /v1/audio/translations, /v1/audio/speech | Transcriptions and translations without a model are routed as whisper-1 |
| Moderations | POST /v1/moderations | Routed as omni-moderation-latest when no model is given |
| Files | /v1/files, /v1/files/{id} | List requests carry no model and use the pseudo model name files for group mapping |
| Threads | /v1/threads, /v1/threads/{id}/... | Collection paths use the pseudo model name thread; sub-paths use the thread ID as the path model value |
| Realtime | GET /v1/realtime (WebSocket), POST /v1/realtime/calls, POST /v1/realtime/client_secrets | See WebSocket and Realtime APIs |
| Live | POST /v1/live/sessions, WebSocket /v1/live/sessions | See WebSocket and Realtime APIs |
| Model list | GET /v1/models | Handled locally, see Query endpoints |
About the /v1 prefix
- Locally handled routes (model list, balance, Realtime, Live, video, DeepSeek tools and files) accept paths both with and without
/v1. - Whether a forwarded route can omit
/v1depends on the upstream's path mapping. Forapi.openai.com, XSI expands/chat/completions,/responses,/embeddings,/models,/images/*,/audio/*,/files,/batches,/fine_tuning,/realtimeand/moderationsto/v1/.... - Always use
/v1/...for new integrations.
Example: Chat Completions
curl "$XSI_BASE_URL/v1/chat/completions" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6.2-sol",
"messages": [{"role": "user", "content": "Introduce XSI in one sentence"}],
"stream": true,
"stream_options": {"include_usage": true}
}'For streaming Chat Completions requests, set stream_options.include_usage. If the upstream stream contains no usage, XSI estimates usage from the actual output and the conversation content.
Example: Responses
curl "$XSI_BASE_URL/v1/responses" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-6.2-sol", "input": "Reply with OK only"}'from openai import OpenAI
client = OpenAI(base_url="https://api.xsicontrol.com/v1", api_key="sk-Xvs...")
resp = client.responses.create(model="gpt-6.2-sol", input="Reply with OK only")
print(resp.output_text)Images
- Image models that also have token prices in the price table (such as
gpt-image-2andgpt-image-2.6-*) are billed per token. - Other image models are billed by
ImgPricing:size price Γ n + input image price Γ number of input images. The default size is1024x1024; thegrok-imagine*series is priced byresolution(e.g.1k,2k).
curl "$XSI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-image-2.6-flare", "prompt": "a lighthouse at dawn", "size": "1024x1024"}'Video
Video generation is asynchronous:
POST /v1/videos/generationscreates a job. XSI replaces the upstreamrequest_idin the response with a signed token (of the formvjob_...) bound to the XSI account that created it and to the upstream key.- Poll
GET /v1/videos/{request_id}with a key from the same XSI account, passing the token unchanged. If the token does not belong to the current account or has been tampered with, XSI returns400 invalid video request_id; if the upstream key that created the job is no longer available, it returns503 video generation account unavailable.
- Video creation requests are never retried automatically, to avoid duplicate generations; any 2xx response counts as a successful creation and is billed.
- Billing:
duration(1β15 seconds, default 6) Γ resolution price (default480p) + number of input images (image,reference_images) Γ input image price.
curl "$XSI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "grok-imagine-video", "prompt": "waves on a quiet beach", "duration": 6, "resolution": "720p"}'Anthropic-compatible APIs
| Capability | Method and path |
|---|---|
| Messages | POST /v1/messages |
| Token counting | POST /v1/messages/count_tokens |
| Files | /v1/files (with the anthropic-beta: files-api-... header) |
- Authenticate with
x-api-keyorAuthorization; when forwarding to Anthropic, XSI keeps a singlex-api-key(the upstream key). /v1/messagessupports sticky sessions, which improves prompt cache hit rates.count_tokensresponses contain no usage and incur no token charges.
curl "$XSI_BASE_URL/v1/messages" \
-H "x-api-key: $XSI_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello"}]
}'import anthropic
client = anthropic.Anthropic(base_url="https://api.xsicontrol.com", api_key="sk-Xvs...")
msg = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}])
print(msg.content[0].text)Gemini native APIs
Paths that carry the model in the URL are handled as the native Gemini protocol:
/v1beta/models/{model}:generateContent
/v1beta/models/{model}:streamGenerateContent?alt=sse
/v1beta/models/{model}:countTokens
/v1beta/models/{model}:embedContentThe /v1beta1/models/, /v1alpha/models/ and /v1/models/{model}:... prefixes are also supported, as are Vertex-style paths containing /publishers/google/models/{model}.
- The model in the URL takes precedence;
modelin the request body is ignored, and model mapping rewrites the URL directly. - Authenticate with
x-goog-api-keyorAuthorization;?key=is not supported. - A request is treated as streaming when the path contains
streamGenerateContent, or it carries?alt=sseorAccept: text/event-stream. - Usage is read from
usageMetadata.
curl "$XSI_BASE_URL/v1beta/models/$GEMINI_MODEL:generateContent" \
-H "x-goog-api-key: $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents": [{"parts": [{"text": "Hello"}]}]}'$GEMINI_MODEL must be a Gemini model that the operator has configured in the price table and that your account is allowed to use.
DeepSeek APIs
With a DeepSeek upstream, XSI passes through all DeepSeek APIs, including the Anthropic format (/anthropic/v1/messages), web search and fetch, OCR, text-to-speech and speech recognition, files and balance queries. All paths work with or without /v1.
| API | Path | Billing model |
|---|---|---|
| Chat | POST /v1/chat/completions, /v1/responses, /v1/messages | deepseek-flash, etc. |
| Web search / fetch | POST /v1/tools/search, /v1/tools/fetch | deepseek-search, deepseek-fetch |
| OCR | POST /v1/tools/ocr | deepseek-ocr |
| Text-to-speech / speech recognition | POST /v1/tools/tts (also over WebSocket), POST /v1/tools/asr | deepseek-tts, deepseek-asr |
| Files | POST/GET /v1/files, GET/DELETE /v1/files/{id} | Document parsing is billed as deepseek-files |
For per-user file isolation, tool billing units and other details, see DeepSeek Full-Suite Integration.
xAI (Grok) APIs
api.x.ai upstreams are forwarded using the OpenAI-compatible protocol (Bearer auth, no path mapping). x_search_call items in Responses output are billed per search (the Query price); see above for image and video rules.
Streaming responses
- A request is treated as streaming if any of the following holds:
"stream": truein the JSON,Accept: text/event-stream, a path containingstreamGenerateContent, or astream=trueoralt=ssequery parameter. - SSE is passed through unchanged; XSI only parses usage out of band. Streaming requests are sent upstream with
Accept-Encoding: identityto avoid compression buffering. - If the client disconnects mid-stream, the portion already generated is still billed at actual usage.
- The maximum wait for upstream response headers is controlled by
RESPONSE_HEADER_TIMEOUT_SECS(default 1800 seconds).
Sticky sessions
For /v1/responses (including sub-resources), */chat/completions and */messages, XSI pins a conversation to the same upstream key to improve prompt cache hit rates. When reading /v1/responses/{id}, send the same session headers as the create request and route to the same Level to reach the upstream account that created it (the binding is stored per session, not per response ID). The session identifier is read in this order of precedence:
- Request header
session_id - Request header
conversation_id prompt_cache_keyin the JSON request body- Request header
session-id - Request header
thread-id
When no identifier is provided, an account is pinned to the same key per Level by default. Whether sticky sessions are enabled is configured by the operator (STICKY_SCHEDULER, STICKY_LEVELS).
Automatic retries and failover
XSI performs retries on the server side. If all retries fail, the client receives the upstream response from the first failure (status code and body passed through unchanged):
- Retry conditions: POST requests only; the upstream status satisfies
400 < status < 600and is not inNO_RETRY_STATUS. By default400, 403, 404, 405, 413, 421, 422, 499, 500are not retried, so401, 402, 408, 409, 429,502β504,524and similar statuses are retried automatically with another key. - Attempts: up to 7 within the current Level; after that, up to 3 more per group on other Levels the account is allowed to use (depending on the account's routing mode).
- Not retried: video creation; requests bound to an upstream account, such as DeepSeek file reads and deletes, are not switched to another key.
- If a Responses create request returns
400with an error containingnot supported(for example, when an upstream account does not support the capability), XSI retries only with other keys in the same group, at most once per key.
Client-side retry recommendations:
- Retry only
429,502,503and network errors, a limited number of times, with exponential backoff and random jitter. - Do not automatically resubmit non-idempotent generation requests such as images and video.
- Log status codes and response bodies, but never log full API keys.
Speed tiers and service tiers
speed (standard/fast/ultrafast) or service_tier in the request (priority/fast count as fast, ultrafast as ultrafast, and default/standard/flex as standard) affects the token price:
- The
speed(for Anthropic,usage.speed) orservice_tierin the upstream response takes precedence; if the response does not include it, the request value is billed. - fast: token cost Γ the model's
FastTokenMultiplier. - ultrafast: token cost Γ 6.
- The multipliers apply only to token costs, not to per-call or per-unit charges;
flexis billed at the standard price.
Query endpoints
| Method and path | Description | Authentication |
|---|---|---|
GET /v1/models (also /models, /dashboard/models) | Model catalog | API key |
GET /user/balance (also /v1/user/balance) | Current account balance in DeepSeek format | API key |
GET /x-pricing | Pricing catalog, see Pricing Catalog API | Optional |
GET /dashboard/* | Account status and usage, see Account and Usage API | API key |
GET /v1/models
{"object": "list", "data": [{"id": "gpt-6.2-sol", "object": "model", "owned_by": "xai"}]}Returns every model in the operator's price table (chat, image, video, audio, rerank, etc.), sorted by name. The list is not filtered by the account's model allowlist; whether an account can call a model is determined by the admission result of the actual request.
GET /user/balance
Works with any upstream, not just DeepSeek:
{
"is_available": true,
"balance_infos": [
{"currency": "CNY", "total_balance": "110.00", "granted_balance": "0.00", "topped_up_balance": "110.00"}
]
}is_available is true when the balance is greater than 0 and the account is not suspended.
Model name resolution
The model name in a request is resolved in the following order; the first match wins:
- Operator's temporary failover replacement (
MODEL_FAILOVER) - Account-level
ModelMapper(exact, then wildcard) - Tenant-level
MODEL_MAPPER(exact, then wildcard) - Fuzzy matching: if the model is in the price table, use it as is; otherwise, choose the priced model in the same family and modality with the closest version
- Use as is
/v1/models.Limits
| Item | Default |
|---|---|
| Request body (after decompression) | 200 MiB (REQUEST_BODY_LIMIT_BYTES) |
| Realtime calls / Live HTTP request body | 4 MiB |
| WebSocket frame | 16 MiB |
| WebSocket connection duration | 60 minutes (WS_MAX_CONN_DURATION) |
| Upstream response header wait | 1800 seconds (RESPONSE_HEADER_TIMEOUT_SECS) |