参考

API 参考

端点、鉴权、请求字段、响应头、错误码完整参考。

端点总览

xAPI 的主接入点是 https://ai.xapi.to,同时支持 Anthropic Messages 与 OpenAI Chat Completions 两套协议:

端点协议
POST https://ai.xapi.to/v1/messagesAnthropic Messages
POST https://ai.xapi.to/{strategy}/v1/messagesAnthropic,显式选策略
POST https://ai.xapi.to/v1/chat/completionsOpenAI Chat Completions
POST https://ai.xapi.to/{strategy}/v1/chat/completionsOpenAI,显式选策略
POST https://ai.xapi.to/v1/messages/count_tokens暂未实现,返回 404
GET https://ai.xapi.to/openapi.json实时 OpenAPI 3.0 规范(无需鉴权)

其中 {strategy} 取值为 default | quality | speed | cost。

需要锁定特定上游(跳过自动路由)时,可使用直连子域 https://{host}.p.xapi.to/{path} 作为高级用法 —— 但聚合路由已经能满足绝大多数场景,优先使用 ai.xapi.to。

鉴权

所有端点统一接受两种鉴权头,任选其一:

1x-api-key: sk-xapi-...
2Authorization: Bearer sk-xapi-...
客户端类型默认头是否需要额外配置
Anthropic SDK / Claude Codex-api-key否
OpenAI SDK / Codex / CursorAuthorization: Bearer否
手写 curl / fetch任选—

Anthropic Messages 请求

model
stringRequired

模型 ID。例如 claude-opus-4-7。完整清单参见 模型与价格。

max_tokens
integerRequired

生成的最大 token 数。

messages
arrayRequired

对话消息数组,每项含 role(user | assistant)和 content。

system
string

可选 system prompt。

stream
booleanDefaults to false

是否流式返回。流式响应通过 SSE 传输,事件结构与 Anthropic 官方一致。

temperature
numberDefaults to 1.0

采样温度,范围 0–1。

tools
array

Tool / function 定义,透传至上游。

tool_choice
object

Tool 选择策略,透传至上游。

请求体除 stream 与 priority 字段外,其余内容全量透传至上游。 所有以 anthropic- 开头的协议头(anthropic-version、anthropic-beta 等) 亦原样透传。

OpenAI Chat Completions 请求

model
stringRequired

模型 ID,按 模型与价格 中的命名传入。例如 gpt-5.5、claude-opus-4-7。

messages
arrayRequired

对话消息数组。

stream
booleanDefaults to false

是否流式返回。

temperature
numberDefaults to 1.0
tools
array

路由策略

聚合路由通过 URL 路径前缀指定策略,不影响请求体或响应体:

路径策略
ai.xapi.to/v1/...默认(等价于 quality)
ai.xapi.to/quality/v1/...显式 quality
ai.xapi.to/speed/v1/...speed
ai.xapi.to/cost/v1/...cost

响应头

Something went wrong!
Something went wrong!
Something went wrong!
Something went wrong!
Something went wrong!
Something went wrong!
Something went wrong!
Something went wrong!
Something went wrong!

流式响应不会在 response headers 中返回 X-AI-Cost —— 响应头在 stream 开始时已发送至客户端。 如需获取流式调用的实际费用,请查询控制台 → Usage Records。

错误码

平台错误(X-XAPI-Source: platform)

HTTPtype含义
400invalid_request_error字段校验失败 / 模型未在 tokenPricing 中配置
401authentication_errorAPI Key 无效或缺失
402Payment Required账户余额不足 / API Key 限额超出
429rate_limit_error上游限频
502server_error · ALL_PROVIDERS_FAILED候选池内所有上游均失败
504server_error上游请求超时

上游错误(X-XAPI-Source: provider)

HTTP 状态码与响应体由上游决定,xAPI 原样透传,不进行任何重写。

OpenAPI 自动生成

每个上游均提供实时生成的 OpenAPI 3.0 规范:

$curl https://ai.xapi.to/openapi.json

每个 endpoint 在 spec 中包含 x-billing 扩展字段:

1{
2  "x-billing": {
3    "type": "PER_TOKEN",
4    "pricingMode": "PER_MODEL",
5    "allowedModels": ["gpt-5.5", "claude-opus-4-7"],
6    "strictModelValidation": true,
7    "modelPricing": {
8      "claude-opus-4-7": {
9        "inputPricePerToken": 0.0000010,
10        "outputPricePerToken": 0.0000050,
11        "cacheCreationPricePerToken": 0.00000125,
12        "cacheReadPricePerToken": 0.0000005
13      }
14    },
15    "streaming": { "supported": true, "format": "sse" },
16    "estimatedMaxTokens": 4096
17  }
18}

可直接导入 Swagger UI、Stoplight、Postman 等工具查阅与调试。

平台限制

  • 请求体大小:≤ 20 MB(Traefik body-limit middleware)
  • 连接超时:2 分钟(UPSTREAM_TIMEOUT_MS,流式传输阶段不受此限制)
  • 重定向:不跟随(maxRedirects: 0,3xx 状态码直接透传给调用方)
  • SSRF 防护:转发前完成 DNS 解析与 IP pin,纵深防御 DNS rebinding