> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.xapi.to/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.xapi.to/_mcp/server.

# 设计原则

## 多源上游池

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 返回。

## 透明计费

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

#### 请求到达

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

#### 上游响应

按实际 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` |

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

## 范围声明

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

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