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:

  1. Authentication: parse the caller's key and check the account status and authentication failure rate.
  2. Account admission: IP allowlist β†’ account status, suspension, daily/monthly credit limits, balance, account-level RPM/TPM β†’ resource (path) allowlist.
  3. Model resolution: read the model name from the request body (or URL) and map it to an upstream model using MODEL_MAPPER and related rules.
  4. Model admission: model allowlist (AllowModels) and model-level limits (MODEL_LIMITS).
  5. 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.
  6. 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.
  7. 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:

CapabilityMethod and pathNotes
Chat CompletionsPOST /v1/chat/completionsSupports sticky sessions
ResponsesPOST /v1/responsesSupports sticky sessions; also available over WebSocket, see WebSocket and Realtime APIs
Responses compactionPOST /v1/responses/compactXSI forces Accept: application/json
Responses sub-resourcesGET /v1/responses/{id}, POST /v1/responses/{id}/cancel, GET /v1/responses/{id}/input_itemsFollow the same sticky path as the create request; GET requests are not billed
EmbeddingsPOST /v1/embeddingsBilled by usage.prompt_tokens
Image generation and editingPOST /v1/images/generations, POST /v1/images/edits, POST /v1/images/variationsBilled per image or per token, see below
Video generationPOST /v1/videos/generations, GET /v1/videos/{request_id}Asynchronous jobs, see below
AudioPOST /v1/audio/transcriptions, /v1/audio/translations, /v1/audio/speechTranscriptions and translations without a model are routed as whisper-1
ModerationsPOST /v1/moderationsRouted 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
RealtimeGET /v1/realtime (WebSocket), POST /v1/realtime/calls, POST /v1/realtime/client_secretsSee WebSocket and Realtime APIs
LivePOST /v1/live/sessions, WebSocket /v1/live/sessionsSee WebSocket and Realtime APIs
Model listGET /v1/modelsHandled 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 /v1 depends on the upstream's path mapping. For api.openai.com, XSI expands /chat/completions, /responses, /embeddings, /models, /images/*, /audio/*, /files, /batches, /fine_tuning, /realtime and /moderations to /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-2 and gpt-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 is 1024x1024; the grok-imagine* series is priced by resolution (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:

  1. POST /v1/videos/generations creates a job. XSI replaces the upstream request_id in the response with a signed token (of the form vjob_...) bound to the XSI account that created it and to the upstream key.
  2. 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 returns 400 invalid video request_id; if the upstream key that created the job is no longer available, it returns 503 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 (default 480p) + 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

CapabilityMethod and path
MessagesPOST /v1/messages
Token countingPOST /v1/messages/count_tokens
Files/v1/files (with the anthropic-beta: files-api-... header)
  • Authenticate with x-api-key or Authorization; when forwarding to Anthropic, XSI keeps a single x-api-key (the upstream key).
  • /v1/messages supports sticky sessions, which improves prompt cache hit rates.
  • count_tokens responses 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}:embedContent

The /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; model in the request body is ignored, and model mapping rewrites the URL directly.
  • Authenticate with x-goog-api-key or Authorization; ?key= is not supported.
  • A request is treated as streaming when the path contains streamGenerateContent, or it carries ?alt=sse or Accept: 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.

APIPathBilling model
ChatPOST /v1/chat/completions, /v1/responses, /v1/messagesdeepseek-flash, etc.
Web search / fetchPOST /v1/tools/search, /v1/tools/fetchdeepseek-search, deepseek-fetch
OCRPOST /v1/tools/ocrdeepseek-ocr
Text-to-speech / speech recognitionPOST /v1/tools/tts (also over WebSocket), POST /v1/tools/asrdeepseek-tts, deepseek-asr
FilesPOST/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": true in the JSON, Accept: text/event-stream, a path containing streamGenerateContent, or a stream=true or alt=sse query parameter.
  • SSE is passed through unchanged; XSI only parses usage out of band. Streaming requests are sent upstream with Accept-Encoding: identity to 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:

  1. Request header session_id
  2. Request header conversation_id
  3. prompt_cache_key in the JSON request body
  4. Request header session-id
  5. 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 < 600 and is not in NO_RETRY_STATUS. By default 400, 403, 404, 405, 413, 421, 422, 499, 500 are not retried, so 401, 402, 408, 409, 429, 502–504, 524 and 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 400 with an error containing not 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, 503 and 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) or service_tier in 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; flex is billed at the standard price.

Query endpoints

Method and pathDescriptionAuthentication
GET /v1/models (also /models, /dashboard/models)Model catalogAPI key
GET /user/balance (also /v1/user/balance)Current account balance in DeepSeek formatAPI key
GET /x-pricingPricing catalog, see Pricing Catalog APIOptional
GET /dashboard/*Account status and usage, see Account and Usage APIAPI 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:

  1. Operator's temporary failover replacement (MODEL_FAILOVER)
  2. Account-level ModelMapper (exact, then wildcard)
  3. Tenant-level MODEL_MAPPER (exact, then wildcard)
  4. 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
  5. Use as is
Because of fuzzy matching, a misspelled or retired model name may be mapped to another priced model in the same family. Use the names listed in the pricing catalog or /v1/models.

Limits

ItemDefault
Request body (after decompression)200 MiB (REQUEST_BODY_LIMIT_BYTES)
Realtime calls / Live HTTP request body4 MiB
WebSocket frame16 MiB
WebSocket connection duration60 minutes (WS_MAX_CONN_DURATION)
Upstream response header wait1800 seconds (RESPONSE_HEADER_TIMEOUT_SECS)