# 素问中转 · LLM 文档索引

> 一个 OpenAI 兼容 + Anthropic 兼容的 API 中转：官方直连上游（不经第三方池），CNY 计价，倍率固定 **1.25×**，缓存读当前不计费（比价目表更便宜）。给人和 AI 读的最小索引。

## 0. 免鉴权端点（不填 key 就能自举）

| 端点 | 用途 |
|---|---|
| `GET /llms.txt` | 本文件 |
| `GET /public/models` | **模型清单（免 key）**，含 `unit`/`note` 口径 |
| `GET /v1/pricing` | 倍率表：`official → final`，CNY/百万 token，含 promo |
| `GET /status` | 服务与上游健康（含上游状态依据 URL） |
| `GET /healthz` | 存活与钥匙池概览 |
| `GET /changelog` `/docs` | 变更记录、完整文档 |

> 已知差别：有的中转站 `/v1/models` 需鉴权（302.AI、硅基），有的公开（AIHubMix）——我们**两者都给**：免鉴权走 `/public/models`，带 key 走 `/v1/models`。

## 1. 基本信息

- 协议：**OpenAI 兼容**（`/v1/chat/completions`、`/v1/models`）与 **Anthropic 兼容**（`/v1/messages`、`/v1/messages/count_tokens`（**估算**，字符数/4，非上游精确计数））。
- 鉴权：`Authorization: Bearer <key>` 或 `x-api-key: <key>`。
- 计价：`final = official × markup`（CNY/百万 token）；实时倍率见 `/v1/pricing`。

## 2. 三行接入

```bash
# Claude Code
export ANTHROPIC_BASE_URL=https://api.<域名>
export ANTHROPIC_AUTH_TOKEN=sk-你的key
claude
```

```toml
# Codex CLI（~/.codex/config.toml）
model_provider = "relay"
[model_providers.relay]
name = "Relay"
base_url = "https://api.<域名>/v1"
env_key = "RELAY_API_KEY"
wire_api = "chat"
requires_openai_auth = false
```

（Cursor：Settings → Models → 填 OpenAI API Key 与 Override Base URL；注意自定义 key 只对 chat 模型生效，Tab 补全仍走 Cursor 自带。）

## 3. 自助端点

| 端点 | 用途 |
|---|---|
| `GET /v1/key` | 余额、额度到期、限速余量、当前倍率 |
| `GET /v1/quota` | 同上（旧名，保留） |
| `GET /v1/plans` | 套餐表 |
| `POST /v1/checkin` | 每日签到送额度 |
| `POST /v1/redeem` | 兑换邀请码 |
| `GET /v1/pricing` | 倍率表（机器可读） |
| `GET /status` | 服务与上游健康（含钥匙池概览） |
| `POST /pay/notify` | 支付回调（验签 + 幂等） |

## 3b. 第三方工具兼容（New-API 形状，照 T66 生态盘点）

本站**按 new-api 形状**暴露最小账号面，第三方工具（`all-api-hub`、`metapi`、各类签到扩展等）可直接认站：

| 端点 | 鉴权 | 说明 |
|---|---|---|
| `GET /api/status` | 免 | 站点信息（`checkin_enabled` 等） |
| `GET /api/user/self` | key | 账号/额度（`quota`=剩余 token、`group`=套餐） |
| `GET`/`POST /api/user/checkin` | key | 每日签到 |
| `GET /v1/pricing` | 免 | 倍率表（我们自有格式，更详细） |

> 说明：扩展类工具多用**浏览器会话/OAuth** 认站；当前我们提供 **key 形式**（`Authorization: Bearer`）。会话/linux.do OAuth 登录页为后续项。

## 4. 错误码（照 OpenRouter 语义）

`400` 参数错｜`401` key 无效｜**`402` 额度不足**（`X-Relay-Remaining` 给剩余额度）｜`403` 权限/拦截｜`408` 超时｜**`429` 限速**（带 `Retry-After`、`X-RateLimit-Limit/Remaining/Reset`）｜`502` 上游模型故障｜**`503` 无可用上游**（带 `error.metadata.provider_code`）。

## 5. 行为承诺

- 倍率固定；改价**提前 3 天**公告。
- **不改你的请求**：`User-Agent` / `anthropic-beta` / `x-app` / `x-stainless-*` 原样透传。
- 余额与用量可查；到期未用完额度结转 1 个月；未使用全退、已用按剩余比例退。

## 五维横评榜单

- 页面 `/bench`：模型 × 五维（autonomy/env/goal/learn/temporal），只读判定层（按标准答案硬项），每格带可判格数、复现中位与真 P10~P90。
- 数据 `/site/bench.json`；构建 `python scripts/relay/bench_build.py`（读 `LLM五维横评/runs`，复用 `runner/judge_gold.py` 口径）。
- 上屏门槛：任一模型在任一维上 ≥50% 不达标才入表。

## 错误码（与 /docs#errors 同源）

| 码 | 含义 | 响应里可获得 |
|---|---|---|
| 400 | 参数非法或缺失 | `error.message` |
| 401 | key 无效或未携带 | — |
| 402 | 额度不足或已过期 | `error.code`、响应头 `X-Relay-Remaining` |
| 403 | 权限或拦截 | — |
| 408 | 请求超时 | — |
| 429 | 速率超限 | `Retry-After`、`X-RateLimit-Limit/Remaining/Reset` |
| 502 | 上游模型故障 | — |
| 503 | 无可用上游 | `error.metadata.provider_code` |

错误体形如 `{"error":{"type":…,"code":…,"message":…}}`（对齐 OpenRouter 公开规范）。

## 限速与计费

- 速率：默认 60 次/分钟，按 key 计，超限 429（带 `Retry-After`）；并发超限排队不报错。
- 免费额度：无需付费，按日限额，当前值见 `/status` 的 `free_daily_requests`。
- 计费：按 token；缓存读（cache read）当前不计费（上游口径），暂未按缓存价单列；对外价＝上游官方价 × 1.25× × 汇率（人民币报价的模型不乘）。
- 自助查询：`GET /v1/key` 返回余额、到期、限速余量与当前倍率。