Proxy Interface

This page is synchronized with the current proxy implementation and covers model proxy routes plus dashboard query routes.

Base Information

Runtime domains by mode:
- SaaS single-tenant: https://api.xairouter.com
- BYOK multi-tenant: https://api.xaicontrol.com
Examples below use $BASE_URL; set it first:

export BASE_URL="https://api.xairouter.com"      # SaaS
# export BASE_URL="https://api.xaicontrol.com"   # BYOK

Auth: Authorization: Bearer sk-Xvs...

curl ${BASE_URL}/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'

Compatible Proxy Endpoints

Common routes currently handled by code include:

OpenAI-compatible

/v1/chat/completions
/v2/chat/completions
/chat/completions
/v1/responses
/responses
/v1/embeddings
/embeddings
/v1/images/generations
/v1/images/edits
/v1/images/variations
/v1/audio/transcriptions
/v1/audio/translations
/v1/realtime/client_secrets
/v1/realtime (WebSocket)
/v1/moderations
/v1/threads
/v1/files
/v1/models, /models (model list)

Anthropic-compatible

/v1/messages
/messages

Dashboard Routes (same domain, GET)

These query routes are served by the same proxy domain:

/dashboard/status
/dashboard/info
/dashboard/live
/dashboard/bill
/dashboard/logs
/dashboard/news
/dashboard/models

Routing Behavior (code-level)

1) Model mapping

Requested model names are resolved through:

user-level ModelMapper
owner-level ModelMapper

Mapped model is then used for routing and billing.

2) Level routing

LevelMapper selects the key pool level; keys in that level are picked by round-robin.

3) Failover

Two failover layers are supported:

ModelFailover (model chain)
SwitchOver (level switch)

4) ACL & limits

Requests pass through:

IP allowlist (AllowIPs)
resource allowlist (Resources, prefix matching)
model allowlist (AllowModels)
user-level rate limits and model-level ModelLimits

Quick Examples

Chat Completions

curl ${BASE_URL}/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role":"user","content":"Say hello"}]
  }'

Anthropic Messages

curl ${BASE_URL}/v1/messages \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 256,
    "messages": [{"role":"user","content":"hello"}]
  }'

Model list

curl ${BASE_URL}/v1/models \
  -H "Authorization: Bearer $API_KEY"