概念

设计原则

多源聚合、协议透明、透明计费、自动故障转移 —— xAPI 的核心架构选择。

多源上游池

xAPI 同时接入官方 API、经过验证的第三方中转服务,以及逆向访问通道, 对外暴露统一的访问入口。同一个模型可以在多个上游下以不同价格提供, 例如 claude-opus-4-7:

上游输入(USD / 1M)输出(USD / 1M)
SkyAPI$1.00$5.00
SuperToken Max(官方源)$2.00$10.00
SuperToken 逆向通道$0.65$3.30

在 cost 策略下,网关会自动选择当前最便宜的健康上游执行请求, 跨源差价的复杂度由网关吸收,调用方仅感知最终的结算金额。

协议透明

xAPI 不发明新协议,完全兼容业界两套主流规范:

  • Anthropic Messages API(POST /v1/messages)—— 聚合路由使用此协议, Claude Code 及其他 Anthropic SDK 仅需修改 base_url 即可接入
  • OpenAI Chat Completions(POST /v1/chat/completions)—— 每个上游通过独立子域暴露, 使用上游原生 OpenAI 协议

请求字段全量透传(stream、tools、tool_choice、所有 anthropic-* 协议头等), 新增的供应商参数无需等待网关适配。响应体不注入任何 xAPI 特有字段, 所有平台层信息通过 response headers 返回。

透明计费

每次调用按预扣 → 结算两步走,确保高并发场景下不会重复扣费或漏扣:

1

请求到达

按该模型的单价预留一笔预估金额。

2

上游响应

按实际 token 用量结算,多扣的退还、少扣的补上。

异常处理:

  • 上游 4xx / 5xx / 超时 → 预扣金额全额释放
  • 客户端中断非流式请求 → 预扣金额全额释放
  • 客户端中断流式请求 → 按累计输出长度估算扣费

非流式成功响应在 X-AI-Cost 头中返回精确到 8 位小数的 USD 金额, 连同 X-AI-Tokens-Input / Output / Total 一并提供 —— 每一次调用都能即时对账。

自动故障转移

聚合路由检测到上游 5xx、429 或超时时,毫秒级切换至候选池中下一个健康上游, 继续完成当前请求。重试过程对调用方透明,可通过 X-Routing-Attempts 与 X-Routing-Fallback 响应头获取本次请求的实际路由轨迹。

底层加固措施:

  • 上游请求默认 2 分钟连接超时
  • 不跟随 3xx 重定向,状态码直接透传给调用方
  • 转发前完成 DNS 解析与 IP 校验,防御 SSRF 与 DNS rebinding 攻击

路由策略

聚合路由 https://ai.xapi.to 通过路径前缀指定路由偏好:

路径前缀策略名上游选择逻辑
/quality(默认)质量优先官方源与高 SLA 上游优先
/speed速度优先当前实测延迟最低的上游
/cost成本优先当前价格最低的健康上游
/default显式默认等价于 /quality

策略仅影响网关的上游选择逻辑,不修改请求体或响应体内容。

范围声明

为了保持网关层的简洁与可预期性,xAPI 明确不提供以下能力:

  • 请求或响应内容的缓存(网关层完全透传)
  • 在响应体内注入 xAPI 自有字段(平台元数据仅通过 headers 暴露)
  • 锁定模型命名(各上游使用各自的命名约定,网关执行不区分大小写的模糊匹配)
  • 自定义协议层(完全遵循 Anthropic Messages / OpenAI Chat Completions 规范)
  • API Key 明文存储(经哈希后缓存,上游凭据加密落库)