Router API

Router API

XSI 是协议原生的路由器:它不把请求翻译成某种“统一格式”,而是保持每个上游协议的请求与响应语义,只在必要处改写模型名、路径与上游凭证。因此官方 SDK、Codex、Claude Code 等客户端只需替换 base_url 与 API Key。

export XSI_BASE_URL="https://api.xsicontrol.com"   # 或你自己的 API 域名
export XSI_API_KEY="sk-Xvs..."

请求如何被处理

每个模型请求依次经过以下步骤:

  1. 认证:解析调用方 Key,检查账号状态与认证失败频率。
  2. 账号准入:IP 白名单 → 账号状态、冻结、日/月额度、余额、账号级 RPM/TPM → 资源(路径)白名单。
  3. 模型解析:从请求体(或 URL)读取模型名,按 MODEL_MAPPER 等规则映射为上游模型。
  4. 模型准入:模型白名单(AllowModels)与模型级限额(MODEL_LIMITS)。
  5. 选择上游:按模型确定 Level(分组),在该组的 Key 池中按粘性会话或轮询选择一个 Key。
  6. 转发:改写路径与上游鉴权头后转发;上游返回可重试错误时,在向客户端写出任何字节之前自动换 Key 重试。
  7. 计量与结算:从响应(含 SSE 流)中旁路读取用量,按价格表结算。

路由细节见《路由与故障转移》,计费细节见《计费与价格》。

OpenAI 兼容接口

除下文标注“本地处理”的路径外,XSI 会把任何路径与方法转发给选中 Key 的上游,因此上游支持的接口(如 /v1/batches、/v1/fine_tuning/*、/v1/vector_stores、/v1/completions)都可以直接使用。下表列出 XSI 有专门处理的接口:

能力方法与路径说明
Chat CompletionsPOST /v1/chat/completions支持粘性会话
ResponsesPOST /v1/responses支持粘性会话;也可通过 WebSocket 连接,见《WebSocket 与实时接口》
Responses 压缩POST /v1/responses/compactXSI 强制 Accept: application/json
Responses 子资源GET /v1/responses/{id}、POST /v1/responses/{id}/cancel、GET /v1/responses/{id}/input_items与创建请求走同一粘性路径;GET 不计费
EmbeddingsPOST /v1/embeddings按 usage.prompt_tokens 计费
图片生成与编辑POST /v1/images/generations、POST /v1/images/edits、POST /v1/images/variations按张或按 Token 计费,见下文
视频生成POST /v1/videos/generations、GET /v1/videos/{request_id}异步任务,见下文
音频POST /v1/audio/transcriptions、/v1/audio/translations、/v1/audio/speech转录与翻译未指定模型时按 whisper-1 路由
ModerationsPOST /v1/moderations未指定模型时按 omni-moderation-latest 路由
Files/v1/files、/v1/files/{id}列表请求无模型,使用伪模型名 files 做分组映射
Threads/v1/threads、/v1/threads/{id}/...集合路径使用伪模型名 thread,子路径以线程 ID 作为路径模型值
RealtimeGET /v1/realtime(WebSocket)、POST /v1/realtime/calls、POST /v1/realtime/client_secrets见《WebSocket 与实时接口》
LivePOST /v1/live/sessions、WebSocket /v1/live/sessions见《WebSocket 与实时接口》
模型列表GET /v1/models本地处理,见查询接口

关于 /v1 前缀

  • 本地处理的路由(模型列表、余额、Realtime、Live、视频、DeepSeek 工具与文件)同时接受带与不带 /v1 的写法。
  • 转发路由能否省略 /v1 取决于上游的路径映射。对 api.openai.com,XSI 会把 /chat/completions、/responses、/embeddings、/models、/images/*、/audio/*、/files、/batches、/fine_tuning、/realtime、/moderations 补全为 /v1/...。
  • 新接入请始终使用 /v1/...。

示例: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": "用一句话介绍 XSI"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Chat Completions 流式请求建议设置 stream_options.include_usage。上游流中没有 usage 时,XSI 会按实际输出与会话内容估算用量。

示例: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": "只回复 OK"}'
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="只回复 OK")
print(resp.output_text)

图片

  • 定价表中同时以 Token 计价的图片模型(如 gpt-image-2、gpt-image-2.6-*)按 Token 计费。
  • 其他图片模型按 ImgPricing 计费:尺寸单价 × n + 输入图单价 × 输入图数。默认尺寸为 1024x1024;grok-imagine* 系列按 resolution(如 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"}'

视频

视频生成是异步流程:

  1. POST /v1/videos/generations 创建任务。XSI 会把响应中的上游 request_id 替换为一个签名令牌(形如 vjob_...),令牌绑定创建它的 XSI 账号与上游 Key。
  2. 使用同一个 XSI 账号的 Key 原样轮询 GET /v1/videos/{request_id}。令牌不属于当前账号或已被篡改时返回 400 invalid video request_id;创建任务的上游 Key 已不可用时返回 503 video generation account unavailable。
  • 视频创建请求不会自动重试,以免重复生成;任何 2xx 响应都视为创建成功并计费。
  • 计费:duration(1–15 秒,默认 6)× 分辨率单价(默认 480p)+ 输入图片数(image、reference_images)× 输入图单价。
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 兼容接口

能力方法与路径
MessagesPOST /v1/messages
Token 计数POST /v1/messages/count_tokens
Files/v1/files(带 anthropic-beta: files-api-... 请求头)
  • 鉴权可使用 x-api-key 或 Authorization;XSI 转发给 Anthropic 时只保留一个 x-api-key(上游 Key)。
  • /v1/messages 支持粘性会话,有利于提示缓存命中。
  • count_tokens 的响应不含 usage,不产生 Token 费用。
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": "你好"}]
  }'
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": "你好"}])
print(msg.content[0].text)

Gemini 原生接口

模型写在 URL 中的路径都按 Gemini 原生协议处理:

/v1beta/models/{model}:generateContent
/v1beta/models/{model}:streamGenerateContent?alt=sse
/v1beta/models/{model}:countTokens
/v1beta/models/{model}:embedContent

同样支持 /v1beta1/models/、/v1alpha/models/、/v1/models/{model}:... 前缀,以及包含 /publishers/google/models/{model} 的 Vertex 风格路径。

  • 以 URL 中的模型为准,请求体中的 model 被忽略;模型映射会直接改写 URL。
  • 鉴权使用 x-goog-api-key 或 Authorization,不支持 ?key=。
  • 路径含 streamGenerateContent、带 ?alt=sse 或 Accept: text/event-stream 时按流式处理。
  • 用量从 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": "你好"}]}]}'

$GEMINI_MODEL 应为运营方已在定价表中配置、且你的账号有权使用的 Gemini 模型。

DeepSeek 接口

使用 DeepSeek 上游时,XSI 透传 DeepSeek 的全部接口,包括 Anthropic 格式(/anthropic/v1/messages)、联网搜索与抓取、OCR、语音合成与识别、文件以及余额查询。所有路径带不带 /v1 均可。

接口路径计费模型
对话POST /v1/chat/completions、/v1/responses、/v1/messagesdeepseek-flash 等
网页搜索 / 抓取POST /v1/tools/search、/v1/tools/fetchdeepseek-search、deepseek-fetch
OCRPOST /v1/tools/ocrdeepseek-ocr
语音合成 / 识别POST /v1/tools/tts(亦可 WebSocket)、POST /v1/tools/asrdeepseek-tts、deepseek-asr
文件POST/GET /v1/files、GET/DELETE /v1/files/{id}文档解析为 deepseek-files

文件按用户隔离、工具接口的计费单位等细节见《DeepSeek 全家桶接入》。

xAI(Grok)接口

api.x.ai 上游按 OpenAI 兼容协议转发(Bearer 鉴权,不做路径映射)。Responses 输出中的 x_search_call 按搜索次数(Query 单价)计费;图片与视频规则见上文。

流式响应

  • 以下任一条件成立即按流式处理:JSON 中 "stream": true、Accept: text/event-stream、路径含 streamGenerateContent、查询参数 stream=true 或 alt=sse。
  • SSE 原样透传,XSI 仅在旁路解析用量;流式请求会以 Accept-Encoding: identity 发往上游,避免压缩缓冲。
  • 客户端中途断开时,已生成部分仍按实际用量结算。
  • 上游响应头等待上限由 RESPONSE_HEADER_TIMEOUT_SECS 控制,默认 1800 秒。

粘性会话

对 /v1/responses(含子资源)、*/chat/completions、*/messages,XSI 会把同一会话固定到同一个上游 Key,以提高提示缓存命中率。读取 /v1/responses/{id} 时,请携带与创建时相同的会话请求头并路由到同一 Level,才能回到创建它的上游账号(绑定按会话而非 response ID 保存)。会话标识按以下优先级读取:

  1. 请求头 session_id
  2. 请求头 conversation_id
  3. JSON 请求体的 prompt_cache_key
  4. 请求头 session-id
  5. 请求头 thread-id

未提供任何标识时,同一账号在同一 Level 上默认固定到同一个 Key。是否启用由运营方配置(STICKY_SCHEDULER、STICKY_LEVELS)。

自动重试与故障转移

XSI 在服务端完成重试;所有重试都失败时,客户端收到的是首次失败的上游响应(状态码与正文原样透传):

  • 重试条件:仅 POST 请求;上游状态码满足 400 < status < 600 且不在 NO_RETRY_STATUS 中。默认不重试 400、403、404、405、413、421、422、499、500,因此 401、402、408、409、429、502–504、524 等会自动换 Key 重试。
  • 次数:当前 Level 内最多 7 次;之后可在账号允许的其他 Level 上每组最多再试 3 次(视账号的路由模式而定)。
  • 不重试:视频创建;DeepSeek 文件读取与删除等绑定上游账号的请求不会切换到其他 Key。
  • Responses 创建返回 400 且错误含 not supported 时(例如某个上游账号不支持该能力),XSI 只在同组内换 Key 重试,每个 Key 最多一次。

客户端的重试建议:

  • 仅对 429、502、503 与网络错误做有限次重试,使用指数退避加随机抖动。
  • 不要自动重复提交图片、视频等非幂等生成请求。
  • 记录状态码与响应正文,但不要记录完整的 API Key。

快速档位与服务等级

请求中的 speed(standard/fast/ultrafast)或 service_tier(priority/fast 视为 fast,ultrafast 视为 ultrafast,default/standard/flex 视为标准)会影响 Token 单价:

  • 以上游响应中的 speed(Anthropic 为 usage.speed)或 service_tier 为准;响应未给出时按请求值计费。
  • fast:Token 费 × 模型的 FastTokenMultiplier。
  • ultrafast:Token 费 × 6。
  • 倍率只作用于 Token 费用,不作用于按次或按单位计价的部分;flex 按标准价计费。

查询接口

方法与路径说明认证
GET /v1/models(亦可 /models、/dashboard/models)模型目录API Key
GET /user/balance(亦可 /v1/user/balance)以 DeepSeek 格式返回当前账号余额API Key
GET /x-pricing价格目录,见《价格目录 API》可选
GET /dashboard/*账号状态与用量,见《账号与用量 API》API Key

GET /v1/models

{"object": "list", "data": [{"id": "gpt-6.2-sol", "object": "model", "owned_by": "xai"}]}

返回运营方价格表中的全部模型(对话、图片、视频、音频、Rerank 等),按名称排序。列表不按账号的模型白名单过滤;账号能否调用某个模型以实际请求的准入结果为准。

GET /user/balance

适用于任何上游,不限于 DeepSeek:

{
  "is_available": true,
  "balance_infos": [
    {"currency": "CNY", "total_balance": "110.00", "granted_balance": "0.00", "topped_up_balance": "110.00"}
  ]
}

is_available 为 true 表示余额大于 0 且账号未被冻结。

模型名解析

请求中的模型名按以下顺序解析,取第一个命中项:

  1. 运营方临时故障替换(MODEL_FAILOVER)
  2. 账号级 ModelMapper(精确,再通配)
  3. 租户级 MODEL_MAPPER(精确,再通配)
  4. 模糊匹配:模型已在价格表中则原样使用;否则在同家族、同模态中选择版本最接近的已定价模型
  5. 原样使用
因为存在模糊匹配,拼错或已下线的模型名可能被映射到同家族的另一个已定价模型。请以价格目录或 /v1/models 中的名称为准。

限制

项目默认值
请求体(解压后)200 MiB(REQUEST_BODY_LIMIT_BYTES)
Realtime calls / Live HTTP 请求体4 MiB
WebSocket 单帧16 MiB
WebSocket 单连接时长60 分钟(WS_MAX_CONN_DURATION)
上游响应头等待1800 秒(RESPONSE_HEADER_TIMEOUT_SECS)

相关文档