Skip to navigation
AI Gateway

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。

鉴权

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

x-api-key: sk-xapi-...
Authorization: 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

响应头

X-XAPI-Request-Id
string

平台生成的 UUID,所有响应必返回。排障时附在工单中。

X-XAPI-Source
string

provider(上游响应)或 platform(网关层错误)。

X-AI-Cost
string

本次扣款金额(USD,8 位小数)。仅在非流式 + 上游 2xx 时返回。

X-AI-Tokens-Input
integer

输入 token 数。仅非流式 + 上游 2xx。

X-AI-Tokens-Output
integer

输出 token 数。仅非流式 + 上游 2xx。

X-AI-Tokens-Total
integer

总 token 数。仅非流式 + 上游 2xx。

X-Routing-Provider
string

聚合路由实际命中的上游标识(如 skyapi)。

X-Routing-Attempts
integer

尝试次数。> 1 表示发生过自动故障转移。

X-Routing-Fallback
boolean

是否使用了 fallback 上游。

流式响应不会在 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 扩展字段:

{
  "x-billing": {
    "type": "PER_TOKEN",
    "pricingMode": "PER_MODEL",
    "allowedModels": ["gpt-5.5", "claude-opus-4-7"],
    "strictModelValidation": true,
    "modelPricing": {
      "claude-opus-4-7": {
        "inputPricePerToken": 0.0000010,
        "outputPricePerToken": 0.0000050,
        "cacheCreationPricePerToken": 0.00000125,
        "cacheReadPricePerToken": 0.0000005
      }
    },
    "streaming": { "supported": true, "format": "sse" },
    "estimatedMaxTokens": 4096
  }
}

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

平台限制

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