# API Reference (中文 (简体))

🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇧🇦 [bs](../../../bs/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)

---

🌐 **语言：** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇧🇦 [Bosanski](../i18n/bs/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md)

OmniRoute API 的核心参考文档。本文涵盖公开的 `/v1` 接口以及最常用的管理端点；机器可读的 [`docs/openapi.yaml`](../openapi.yaml) 和 `src/app/api/` 下的路由树是详尽的权威来源。

有关专门的 OpenAI 兼容协议和提供者能力矩阵，请参阅
[`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md)。

---

## 目录

- [聊天补全](#chat-completions)
- [独占式托管会话租约](#exclusive-managed-session-leases)
- [嵌入](#embeddings)
- [图像生成](#image-generation)
- [文档 OCR](#document-ocr)
- [列出模型](#list-models)
- [提供者插件清单](#provider-plugin-manifest)
- [兼容性端点](#compatibility-endpoints)
- [文件 API](#files-api)
- [批处理 API](#batches-api)
- [搜索 API](#search-api)
- [WebSocket 流式传输](#websocket-streaming)
- [配额与问题报告](#quotas--issues-reporting)
- [语义缓存](#semantic-cache)
- [仪表板与管理](#dashboard--management)
- [组合管理](#combo-management)
- [Webhook](#webhooks)
- [已注册密钥（自动管理）](#registered-keys-auto-management)
- [智能体协议](#agents-protocol)
- [管理代理](#management-proxies)
- [弹性机制（扩展）](#resilience-extended)
- [技能](#skills)
- [记忆](#memory)
- [MCP 服务器](#mcp-server)
- [A2A 服务器](#a2a-server)
- [云、评测与评估](#cloud-evals--assess)
- [请求处理](#request-processing)
- [身份验证](#authentication)

---

## Chat Completions

```bash
POST /v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "编写一个函数来..."}
  ],
  "stream": true
}
```

### 自定义请求头

| 请求头                   | 方向 | 描述                                                                                                                                           |
| ------------------------ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache`   | 请求 | 设置为 `true` 以绕过缓存                                                                                                                       |
| `x-omniroute-no-memory`  | 请求 | 设置为 `true` 以跳过此请求的记忆和技能注入（与 no-cache 行为一致；避免每次调用产生额外的 token/成本开销）                                      |
| `X-OmniRoute-Progress`   | 请求 | 设置为 `true` 以启用进度事件                                                                                                                   |
| `X-Session-Id`           | 请求 | 用于外部会话亲和性的粘性会话键                                                                                                                 |
| `x_session_id`           | 请求 | 也接受下划线变体（直接 HTTP 请求）                                                                                                             |
| `X-OmniRoute-Session-Id` | 请求 | 调用方提供的会话/对话标签（也会用于记忆）。如果存在，则原样持久化到 `call_logs.session_tag`，以便按会话归因成本 (#8249) — 缺失时绝不会自动生成 |
| `Idempotency-Key`        | 请求 | 去重键（5 秒窗口）                                                                                                                             |
| `X-Request-Id`           | 请求 | 备用去重键                                                                                                                                     |
| `x-omniroute-connection` | 请求 | 通过连接 id 将单模型请求固定到一个提供者连接（账户）— 请参阅[按请求固定账户](#account-pinning-per-request)                                     |
| `X-OmniRoute-Cache`      | 响应 | `HIT` 或 `MISS`（非流式）                                                                                                                      |
| `X-OmniRoute-Idempotent` | 响应 | 如果已去重，则为 `true`                                                                                                                        |
| `X-OmniRoute-Progress`   | 响应 | 如果已启用进度跟踪，则为 `enabled`                                                                                                             |
| `X-OmniRoute-Session-Id` | 响应 | OmniRoute 使用的有效会话 ID                                                                                                                    |
| `X-OmniRoute-Request-Id` | 响应 | 请求关联 id（如果已知）                                                                                                                        |
| `X-OmniRoute-Version`    | 响应 | OmniRoute 构建版本（始终存在）                                                                                                                 |
| `X-OmniRoute-Cost-Saved` | 响应 | 缓存命中时节省的美元金额（仅限缓存命中）                                                                                                       |
| `X-OmniRoute-Decision`   | 响应 | 路由跟踪：`strategy=<name>; provider=<alias>; latency_ms=<n>`（`<name>` 是组合策略，对于非组合请求则为 `single`）— 在完成响应中始终存在        |

> Nginx 注意事项：如果依赖带下划线的请求头（例如 `x_session_id`），请启用 `underscores_in_headers on;`。

#### 按请求固定账户

当一个提供者具有多个连接（账户或密钥）时，OmniRoute 通常会通过其账户选择策略选取一个连接。请求也可以改为使用 `x-omniroute-connection` 请求头固定到某个特定连接：

```bash
curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer <您的 OmniRoute API 密钥>" \
  -H "Content-Type: application/json" \
  -H "x-omniroute-connection: <connection id>" \
  -d '{"model": "codex/gpt-5.5", "messages": [{"role": "user", "content": "你好"}]}'
```

- **在哪里查找 ID。** 在仪表板中打开提供者页面
  （**仪表板 → 提供者 → <provider>**），然后点击连接行上的 `xxxxxxxx…` ID 标签
  ——这会复制完整的连接 ID。
- **哪些请求会遵循此设置。** `/v1/chat/completions`、`/v1/messages` 和
  `/v1/responses` 上的单模型请求（`provider/model`）。组合请求会忽略该标头：如需为组合中的每个步骤固定账户，
  请改用该步骤自身的连接。
- **固定是严格约束，而非偏好。** 固定的连接将被独占使用。请求中发生故障时，
  会记录该账户的冷却状态，但**不会**轮换到同一提供者的其他账户。
- **冷却和配额限制会解除固定。** 当固定连接处于冷却期、
  配额已耗尽或被配额策略阻止时，后续请求会回退到该提供者的
  其他连接，其行为与未固定的流量完全相同。
- **未知或已禁用的 ID 会导致失败。** 如果某个 ID 不在提供者的活动池中（已删除、
  已停用或属于其他提供者），则不存在符合条件的账户，因此请求会失败，
  而不是静默路由到其他位置。

Claude Code 通过 `ANTHROPIC_CUSTOM_HEADERS` 发送自定义标头。请将其放入
`~/.claude/settings.json` 的 `env` 块中，或放入项目级 `.claude/settings.json`，以便为每个项目固定不同的
账户：

```jsonc
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>",
  },
}
```

来源：`src/sse/handlers/chat.ts`（读取标头）、`src/sse/services/auth.ts` 和
`src/sse/services/sessionAffinityPin.ts`（解除固定以及检查连接是否不在池中）。

> **成本遥测标头：** 非流式成功响应还会携带 `X-OmniRoute-*` 成本遥测标头集——`X-OmniRoute-Response-Cost`（美元，固定 10 位小数；免费或未定价时为 `0.0000000000`）、`X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`、`X-OmniRoute-Model`、`X-OmniRoute-Provider`、`X-OmniRoute-Latency-Ms`、`X-OmniRoute-Cache-Hit` 和 `X-OmniRoute-Fallback-Attempts`（仅当 > 0 时），以及 `X-OmniRoute-Request-Id` 和 `X-OmniRoute-Version`。这些标头由聊天补全、`/v1/responses`、`/v1/messages` **以及媒体端点**发出——`/v1/embeddings`、`/v1/images/generations`、`/v1/audio/speech`、`/v1/audio/transcriptions`、`/v1/rerank`、`/v1/videos/generations`、`/v1/music/generations` 和 `/v1/moderations`（成本始终为 `0`）。如果有可用定价，媒体成本将按模态计算（按图像、按秒、按字符、按搜索单元）；否则为 `0`（故障开放）。

> **缓存命中成本语义：** 语义缓存命中时（`X-OmniRoute-Cache-Hit: true`），不会进行上游调用，因此 `X-OmniRoute-Response-Cost` 为 `0.0000000000`（为该命中提供服务的**增量**成本）。原始成本或原本会产生的成本会在 `X-OmniRoute-Cost-Saved` 中单独报告。计费使用方应对 `X-OmniRoute-Response-Cost` 求和（命中不产生费用）；缓存分析可汇总 `X-OmniRoute-Cost-Saved`。

## 独占式托管会话租约

独占式托管会话租约是一种选择性加入、客户端中立的路由契约：一个活跃的所有者持有一个符合条件的 OmniRoute 连接。它不租用模型、不要求 OAuth、不识别特定客户端，也不要求特定提供者。

用于身份验证的 API 密钥必须具有 `lease:exclusive` 范围和一个明确的非空 `allowedConnections` 列表。数据库变动边界在密钥创建和部分更新时强制同时检查这两个字段。

```http
POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>

{"action":"acquire","model":"glm/glm-4.6"}
```

成功的获取、续订和释放响应会公开时间戳、`state` 和精确的正 `generation`，但绝不会公开所选的连接或凭据。续订和释放会在 JSON 正文中提供 generation：

```json
{ "action": "renew", "generation": 1 }
```

```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```

活跃的租约所有者可以明确请求其当前绑定的隐私安全显示元数据：

```json
{ "action": "status", "generation": 1 }
```

```json
{
  "state": "ACTIVE",
  "generation": 1,
  "acquiredAt": "2026-08-28T12:00:00.000Z",
  "renewedAt": "2026-08-28T12:00:30.000Z",
  "expiresAt": "2026-08-28T12:02:30.000Z",
  "connection": {
    "displayName": "Primary Codex",
    "provider": "codex"
  }
}
```

此选择性加入的状态操作由不透明的所有者、经过身份验证的托管 API 密钥以及数据库事务中的精确活跃 generation 进行隔离。`displayName` 仅是修剪后的配置连接名称；当不存在安全的配置名称时，它为 `null`。OmniRoute 绝不会替换电子邮件或生成的账户身份。提供者值是一个非敏感的显示标签，绝不是生成的兼容提供者标识符。凭据、令牌、cookie、原始连接或 API 密钥 ID、所有者哈希、隔离密钥和内部路由数据均被排除在外。

错误的密钥、错误的所有者、过时的 generation、缺失、过期、已释放和已失效的查找都会返回相同的 `409 LEASE_FENCE_STALE` 错误，且不带连接元数据。收到容量等待响应的客户端没有可检查的活跃绑定。当路由转换活跃租约时，相同的 generation 仍然有效，并且状态会原子性地返回新的绑定，而不是旧的绑定。现有客户端保持不变，因为获取、续订、释放和等待响应保留了其先前的形式。

此服务器契约不会改变标准 OpenAI Codex `/status`。标准 Codex 目前报告其模型提供者和内置的身份验证/账户状态，但不会渲染任意自定义提供者账户元数据；后续的客户端集成必须调用此操作并决定如何显示 `connection.displayName`。

每个托管推理请求随后都会提供这两个控制头：

```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```

精确的所有者、generation、活跃连接和经过身份验证的 API 密钥会在每次支持的上游尝试之前立即进行隔离。即使另一个密钥允许相同的连接，使用该密钥重放所有者和 generation 也会失败。原始所有者不会被持久化、记录、保留在请求快照中或转发到上游。

临时争用会返回带有 `Retry-After` 的 HTTP `429` 响应，并附带：

```json
{
  "state": "WAITING_FOR_CAPACITY",
  "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
  "reason": "NO_FREE_ELIGIBLE_CONNECTION",
  "retryAfter": 30
}
```

此响应仅表示普通的符合条件集合非空，并且每个空闲候选者都被外部活跃租约占用。不支持的模型/提供者、策略不匹配、冷却、配额、健康状况以及其他普通的资格失败会保留其现有的 OmniRoute 响应。

### `x-omniroute-compression`

每个请求的压缩计划覆盖。优先级最高——优于路由组合覆盖、活跃配置文件、自动触发和面板默认设置。值如下：

| 值            | 效果                                                              |
| ------------- | ----------------------------------------------------------------- |
| `off`         | 此请求不进行压缩。                                                |
| `default`     | 面板派生的默认配置文件（忽略活跃配置文件）。有损引擎保持关闭。    |
| `safe`        | 仅进行去重和空白折叠。                                            |
| `allow-lossy` | 保留此请求的操作员计划，包括摘要和样式重写。                      |
| `engine:<id>` | 启用时为单个引擎，例如 `engine:rtk`。此引擎的每个请求选择性加入。 |
| `<combo>`     | 命名组合，首先按名称（不区分大小写）匹配，然后按 ID 匹配。        |

注意：

- 未知值将被忽略（请求永远不会被拒绝）；解析将回退到正常的运算符优先级。
- 如果多个组合共享一个名称，请传递组合的 **ID** 以进行确定性匹配。
- 名称为 `off` 或 `default` 的组合不能通过名称选择（这些关键字会首先被解释）；请通过其 ID 引用此类组合。
- 主压缩开关是一个硬性门槛：当全局禁用压缩时，此标头无法启用它。

应用的计划会在响应头中回显：

```
X-OmniRoute-Compression: <mode>; source=<source>
```

其中 `<source>` 是 `request-header`、`routing-override`、`active-profile`、`auto-trigger`、`default` 或 `off` 之一。

---

## 嵌入

```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "nebius/Qwen/Qwen3-Embedding-8B",
  "input": "The food was delicious"
}
```

可用提供者：Nebius、OpenAI、Mistral、Together AI、Fireworks、NVIDIA、**OpenRouter**、Jina AI。

目录 ID 的格式为 `provider/model`（示例：`jina-ai/jina-embeddings-v5-omni-small`）。注册表中出现的无提供者前缀 Jina 模型 ID（例如 `jina-embeddings-v5-text-small`、`jina-reranker-v3.5`）也可以解析。Jina 的嵌入/重排序/分类/分段功能会优先使用控制面板中的 `jina-ai` 凭据；仅当不存在控制面板密钥时，才会使用 `JINA_AI_API_KEY` 作为后备。`jina-reader` 卡片仅用于 Reader / `r.jina.ai`（`POST /v1/web/fetch`），绝不提供嵌入或重排序服务。

注册表中声明支持多模态的模型还接受最多 32 个提供者无关的结构化
项目。媒体项目类型包括 `text`、`image`、`audio`、`video` 和 `document`。它们的媒体 `source`
可以是 `{"type":"url","url":"https://..."}`，也可以是
`{"type":"base64","data":"...","media_type":"..."}`。

Jina v5 Omni（`jina-ai/jina-embeddings-v5-omni-small`、`jina-ai/jina-embeddings-v5-omni-nano`
以及系列别名 `jina-ai/jina-embeddings-v5-omni` → omni-small）也接受 Jina 原生的
EmbeddingsV5Request 文档，并将其**原样转发**至 `https://api.jina.ai/v1/embeddings`：

```json
{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "task": "retrieval.query",
  "normalized": true,
  "input": [
    { "text": "a red bicycle" },
    { "image": "https://example.com/bike.png" },
    {
      "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }]
    }
  ]
}
```

原生 `{ image | audio | video | pdf }` 值可以是公共 HTTPS URL、`data:` URI 或原始
base64。OmniRoute 不会将这些对象字符串化，也不会获取原生图像 URL——Jina 会自行获取
公共媒体。额外的 Jina 字段（`task`、`normalized`、`truncate`、`embedding_type`）会被
转发。仅文本的 Jina SKU 仍会拒绝非文本文档。

安全与传输限制：

- 远程媒体 URL 必须是公共 HTTPS。规范的 `{type,source:url}` 项目会在服务器端获取
  （重定向重新验证、超时、大小限制、公共 DNS、连接固定），并在调用提供者之前以内联
  方式嵌入。Jina 原生 `{image:"https://..."}` 项目在通过相同的公共 HTTPS 检查后会按原样
  转发；URL 由 Jina 获取。
- 内联 base64 媒体的限制为每个项目解码后 8 MiB，整个请求解码后总计 16 MiB。

提供者转换（规范项目绝不会原样转发）：

- Jina 多模态模型：每个顶层项目都会成为一个以模态为键的对象
  （`text` / `image` / `audio` / `video` / `pdf`），内联媒体使用数据 URI；每个
  顶层项目对应一个向量。
- Gemini Embedding 2 系列：一个顶层数组会转换为单个原生
  `models/{model}:embedContent` 请求，其中包含 `content.parts`（`text` 或 `inline_data`）。
- llama.cpp（`llama-cpp/<model>`，本地服务器加载的任何模型）：规范 `text` 项目
  会转换为纯字符串，而 `image` / `audio` / `video` 各自转换为一个
  `{"content": [part]}` 对象，并以内联数据形式使用 llama-server 的聊天内容部分（`image_url`、
  `input_audio`，格式为 `wav` / `mp3` / `flac`，以及 `input_video`）；每个顶层项目对应
  一个向量。服务器必须使用 `--embedding --mmproj …` 运行；如果没有投影器，服务器会自行
  拒绝媒体。`document` 不受支持。
- 未提供明确模态元数据的未知/动态模型会拒绝结构化输入，并返回 HTTP 400。

```json
{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}
```

不受支持的模型/模态组合会返回 HTTP 400，而不会强制转换该项目。对于旧版字符串/令牌请求，
非输入扩展字段仍会保持不变地透传。

```bash
# 列出所有嵌入模型
GET /v1/embeddings
```

---

## 图像生成

```bash
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "openai/gpt-image-2",
  "prompt": "群山之上的美丽日落",
  "size": "1024x1024"
}
```

可用提供者包括 OpenAI（GPT Image 2）、xAI（Grok Image）、Together AI（FLUX）、Fireworks AI、Nebius（FLUX）、Hyperbolic、NanoBanana、**OpenRouter**、**ZenMux**、SD WebUI（本地）、ComfyUI（本地）。

`n` 会在 `data[]` 中返回 `n` 张图像。对于上游 API 每次调用仅返回一张图像的提供者（Black Forest Labs、Stability AI、Leonardo、Ideogram、Haiper、Hyperbolic、Magnific/Freepik、NVIDIA NIM、Cloudflare Workers AI），系统会发起 `n` 次独立的上游调用，最多同时执行 4 次。固定的 `seed` 会根据调用索引递增（`seed`、`seed + 1`、……），因此图像会有所不同，但仍可复现。`n` 的上限为 10。如果任何一次调用失败，则整个请求都会失败。扇出格式列表为
`open-sse/handlers/imageGeneration/fanOut.ts` 中的 `SINGLE_IMAGE_FANOUT_FORMATS`。

ZenMux 会复用现有的 API 密钥连接，并接受 `zenmux/` 或 `zm/` 前缀：

- `zenmux/openai/gpt-image-2` 使用 ZenMux 的 OpenAI Images API。选项包括 `size`、`quality`、`n`、`output_format`、`output_compression`、`background` 和 `response_format`。
- 其他发布商（例如 `zm/meta/muse-image-1.0`）使用 ZenMux 的 Vertex AI `:predict` 端点。`n` 映射到 `sampleCount`，`aspect_ratio` 映射到 `aspectRatio`，`image_size`（`1K`、`2K`、`4K`）映射到 `sampleImageSize`。以像素表示的 `size` 仅用于提供宽高比，不保证具体的像素尺寸。支持的宽高比、分辨率和数量因模型而异。
- `zm/inclusionai/ming-image-0.1-design` 会自行选择尺寸。请省略 `size`、`aspect_ratio` 和 `image_size`；显式指定这些值会返回 HTTP 400。可通过 `output_format` 请求 PNG、JPEG 和 WebP 格式。

此集成支持文生图，不支持参考图像编辑。Vertex 输出会被规范化为 `data[].b64_json`；当 `response_format: "url"` 时，将返回上游 HTTPS URL；如果仅有图像字节可用，则返回 base64 数据 URL。对于空输出或被过滤的输出，系统会返回错误，而不是返回内容为空的成功响应。模型访问权限取决于 ZenMux 账户。请参阅 [ZenMux 的 Vertex API](https://docs.zenmux.ai/api/vertexai/generate-images) 和 [OpenAI Images API](https://docs.zenmux.ai/api/openai/generate-an-image)。

```bash
# 列出所有图像模型
GET /v1/images/generations
```

---

## 文档 OCR

```bash
POST /v1/ocr
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "mistral/mistral-ocr-latest",
  "document": {
    "type": "document_url",
    "document_url": "https://example.com/invoice.pdf"
  }
}
```

`model` 通过 `provider/model` 前缀选择 OCR 提供者；不带前缀的模型 ID（例如
`mistral-ocr-latest`）会解析到其已注册的提供者，而省略 `model` 时则默认使用
Mistral (`mistral-ocr-latest`)。已注册的提供者（`open-sse/config/ocrRegistry.ts`）：

| 提供者 ID                     | 模型 ID              | `model` 值                                                        | 说明                                                                                            |
| ----------------------------- | -------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `mistral`                     | `mistral-ocr-latest` | `mistral/mistral-ocr-latest`（或不带前缀的 `mistral-ocr-latest`） | 同步——响应直接从单次上游调用返回。                                                              |
| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`                       | 异步上游（`analyze` + 轮询）——见下文。                                                          |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                           | 同步，通过 Vertex AI 的 `openapi/chat/completions` 合作伙伴端点——有关身份验证/URL，请参见下文。 |

所有三个提供者都以相同的 Mistral 格式响应：

```json
{
  "pages": [{ "index": 0, "markdown": "# Extracted text..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}
```

### Azure Document Intelligence 轮询流程

Azure Document Intelligence 的 `analyze` API 是异步的：初始请求会返回
`Operation-Location` 标头而不是响应正文，必须通过轮询来获取结果。处理程序
（`open-sse/handlers/ocr.ts`）每秒轮询一次该 URL，最多尝试 30 次；如果轮询响应不是
`ok` 或状态为 `"failed"`，则会快速失败（不会继续轮询）；如果在耗尽尝试次数后操作
仍在运行，则返回 `504`。最终的 Azure 响应在返回给调用方之前，会被规范化为与
Mistral 相同的 `pages`/`markdown` 格式，因此客户端代码无需对该提供者进行特殊处理。

### Vertex AI DeepSeek OCR 身份验证和端点解析

`vertex-deepseek-ocr` 复用 OmniRoute 已为聊天/图像流量提供支持的相同 Vertex AI
身份验证机制（`open-sse/executors/vertex.ts`）：连接的 API 密钥可以是 Service Account
JSON 凭据（通过 JWT bearer 流程交换为短期 OAuth 访问令牌），也可以是直接使用的、
已签发的 OAuth 访问令牌。上游端点 URL 是 Vertex 的通用
`openapi/chat/completions` 合作伙伴端点，根据连接的项目和区域构建——显式设置的
`providerSpecificData.project`/`providerSpecificData.region` 始终优先；否则，项目将从
Service Account JSON 的 `project_id` 派生，区域则默认为 `us-central1`。这两项解析均在
`open-sse/handlers/ocr.ts` 中进行（`resolveVertexOcrAccessToken`、
`resolveVertexOcrBaseUrl`），并由 `src/app/api/v1/ocr/route.ts` 在分派给 `handleOcr`
之前使用。

---

## 列出模型

```bash
GET /v1/models
Authorization: Bearer your-api-key

→ 以 OpenAI 格式返回所有聊天、嵌入和图像模型及组合
```

### 模型 ID 前缀（`?prefix=`）

大多数模型都使用**提供者前缀**进行公布。具体使用哪种前缀由
`MODELS_CATALOG_PREFIX_MODE` 功能标志控制，并且可以通过查询参数**按请求**覆盖——这对于希望在不更改面向所有用户的服务器全局设置的情况下获取简洁列表的客户端很有用：

```bash
GET /v1/models?prefix=alias        # 每个模型一个 ID——短别名前缀
GET /v1/models?prefix=dual         # 两种形式（服务器默认值）
GET /v1/models?prefix=canonical    # 仅完整的提供者 ID 前缀
```

| 模式        | 输出                                                     | 说明                                                                                                                                           |
| ----------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual`      | `cc/claude-sonnet-4-6` **和** `claude/claude-sonnet-4-6` | **默认值。** 两个 ID 都路由到同一个模型；保留此模式，以便硬编码任一形式的客户端配置继续正常工作。目录大小大约会翻倍。                          |
| `alias`     | `cc/claude-sonnet-4-6`                                   | 每个模型一个条目。没有独立别名的提供者仍会输出其条目，因此不会遗漏任何内容。                                                                   |
| `canonical` | `claude/claude-sonnet-4-6`                               | 每个模型以完整的提供者 ID 前缀输出一个条目。没有独立别名的提供者（例如 `antigravity/…`、`agy/…`）也会在此输出其唯一 ID，因此不会遗漏任何内容。 |

即使不使用查询参数，也可以识别出 `dual` 模式的镜像：它带有一个指向主 ID 的 `parent`
字段。

呈现模型选择器的客户端应请求 `?prefix=alias`——
[OmniCopilot VS Code 扩展](../guides/VSCODE-COPILOT.md)就是这样做的。

### 发现筛选器（`?capability=`、`?min_context=`、`?kind=`、`?q=`）

`GET /v1/models` 接受可选的发现筛选器。如果未提供任何筛选器，响应将保持不变。
这些筛选器会缩小调用方原本可见的目录范围（首先应用 API 密钥权限），
并在 OpenAI 风格的 `limit` / `after` 分页之前运行：

```bash
GET /v1/models?capability=vision&capability=tool_calling   # 列出的每项能力都必须为 true
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding                              # 目录 `type`；没有该字段的行为 `chat`
GET /v1/models?q=sonnet&limit=10                           # 对 ID 或名称进行不区分大小写的匹配
```

| 参数          | 值                                                                                                  |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `capability`  | `attachment`、`reasoning`、`structured_output`、`temperature`、`thinking`、`tool_calling`、`vision` |
| `min_context` | 非负整数，与 `context_length` 进行比较                                                              |
| `kind`        | `chat`、`audio`、`embedding`、`image`、`moderation`、`music`、`rerank`、`video`                     |
| `q`           | 1–200 个字符                                                                                        |

未知值或不是非负整数的 `min_context`（例如 `1.5`）
会返回 HTTP `400`，并在消息中列出有效值。实现位置：
`src/app/api/v1/models/catalogFilters.ts`。

### 模型候选列表（`POST /v1/models/query`）

`POST /v1/models/query` 从同一目录返回一个简短且确定性的列表，其身份验证和按密钥可见性规则与
`GET /v1/models` 相同：

```bash
POST /v1/models/query
Authorization: Bearer your-api-key
Content-Type: application/json

{ "capabilities": ["vision", "tool_calling"], "min_context": 128000, "max_output": 16000,
  "kind": "chat", "q": "gpt", "owned_by": "openai", "exclude": ["openai/gpt-4o"], "limit": 5 }

→ { "object": "list", "data": [ ...models ] }
```

所有字段均为可选。`capabilities` 和 `exclude` 接受数组或逗号分隔的字符串；
`max_output` 与 `max_output_tokens` 进行比较。结果先按 `owned_by` 排序，再按 `id` 排序。
`limit` 默认为 `20`，高于 `100` 的值会被限制为 `100`。无效 JSON、未知字段或无效值会返回 HTTP `400`。

### 单独隐藏的聊天模型

在其提供者页面上标记为 **Hidden** 的模型会从目录中排除，并且在显式请求时
返回 HTTP `404` / `model_not_found`。该检查使用解析后的
提供者和模型，包括提供者别名、兼容提供者的节点前缀以及
连接默认值。组合会跳过隐藏目标，并可使用可见的同级目标；当没有
可执行目标剩余时，它会返回相同的错误代码。取消隐藏会在下一次
请求时生效。仅限图像的可见性覆盖不会隐藏具有相同 ID 的聊天模型。

此单独模型设置与
[模型公开允许/拒绝列表](../routing/MODEL_EXPOSURE_LIST.md)相互独立；后者会筛选目录中公布的模型
和自动路由候选项，同时保留显式分派。API 密钥的模型
权限仍会独立应用。默认目录前缀模式仍为 `dual`。

### 无思考模型变体

对于支持思考的 Claude 模型，`/v1/models` 还会公布一个 ID 以 `claude-3-omniroute-no-thinking/` 为前缀的**无思考**变体：

```
claude-3-omniroute-no-thinking/<provider>/<model>
```

选择此 ID（例如，在始终附加 `thinking` 块的 Claude Code 配置中）会解析回真实的 `<provider>/<model>`，同时禁用推理——在 `/v1/messages` 路径上使用 `thinking:{type:"disabled"}`，或在 `/v1/chat/completions` 路径上丢弃 `reasoning`/`reasoning_effort` 字段。仅为支持思考功能**且**遵循 `disabled` 的 Claude 系列模型列出此变体（因此，例如，仅支持自适应思考且拒绝 `disabled` 的模型会被排除）。运维人员可以通过 `ModelSpec.noThinkingAlias` 为每个模型强制启用或禁用该变体。

---

## 提供者插件清单

```bash
GET /api/v1/provider-plugin-manifest
```

返回 Bifrost、CLIProxyAPI 和未来的 sidecar 路由器所使用的 JSON 安全提供者插件清单。该响应从 TypeScript 提供者注册表生成，并有意排除了 OAuth 客户端密钥、运行时环境解析、执行器函数、请求标头和账户数据。

当 sidecar 在进程外运行且无法直接导入 `open-sse/config/providerPluginManifestRegistry.ts` 时，请使用此端点。

---

## 兼容性端点

| 方法 | 路径                                      | 格式                             |
| ---- | ----------------------------------------- | -------------------------------- |
| POST | `/v1/chat/completions`                    | OpenAI                           |
| POST | `/v1/messages`                            | Anthropic                        |
| POST | `/v1/responses`                           | OpenAI Responses                 |
| POST | `/v1/embeddings`                          | OpenAI                           |
| POST | `/v1/images/generations`                  | OpenAI Images                    |
| POST | `/v1/images/edits`                        | OpenAI Images（编辑/局部重绘）   |
| POST | `/v1/videos/generations`                  | OpenAI 风格的视频生成            |
| POST | `/v1/music/generations`                   | OpenAI 风格的音乐生成            |
| POST | `/v1/audio/transcriptions`                | OpenAI Audio（语音转文本）       |
| POST | `/v1/audio/speech`                        | OpenAI TTS（返回音频正文）       |
| POST | `/v1/rerank`                              | Cohere/Voyage 风格的重新排序     |
| POST | `/v1/classify`                            | Jina 分类（`api.jina.ai`）       |
| POST | `/v1/segment`                             | Jina 分段器（`segment.jina.ai`） |
| POST | `/v1/moderations`                         | OpenAI Moderations               |
| GET  | `/v1/models`                              | OpenAI                           |
| POST | `/v1/models/query`                        | 筛选后的模型候选列表             |
| POST | `/v1/messages/count_tokens`               | Anthropic                        |
| GET  | `/v1beta/models`                          | Gemini                           |
| POST | `/v1beta/models/{...path}`                | Gemini generateContent           |
| POST | `/v1/api/chat`                            | Ollama                           |
| GET  | `/api/v1/vscode/{token}/`                 | OpenAI 模型目录别名              |
| GET  | `/api/v1/vscode/{token}/models`           | OpenAI 模型别名                  |
| POST | `/api/v1/vscode/{token}/chat/completions` | OpenAI 令牌化别名                |
| POST | `/api/v1/vscode/{token}/responses`        | OpenAI Responses 令牌化别名      |
| POST | `/api/v1/vscode/{token}/api/chat`         | Ollama 令牌化别名                |
| GET  | `/api/v1/vscode/{token}/api/tags`         | Ollama 标签令牌化别名            |

所有 POST 路由都遵循相同的形式：`Bearer your-api-key` + 经过 Zod 验证的 JSON 正文（`v1RerankSchema`、`v1ModerationSchema`、`v1AudioSpeechSchema` 等，参见 `src/shared/validation/schemas.ts`）。架构验证失败时返回 4xx。

对于无法附加 `Authorization: Bearer ...` 的客户端，OmniRoute 也支持通过 URL 传入 API 密钥，可使用查询字符串兼容方式（`?token=...`、`?apiKey=...`、`?api_key=...`、`?key=...`），或使用下面记录的专用 `/api/v1/vscode/{token}/...` 端点。

```bash
# 重新排序（云注册表提供者，或指定为 "<prefix>/<model>" 的 OpenAI 兼容提供者节点）
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina 分类（Foundation API 凭据）
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina 分段器
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina 搜索（s.jina.ai；提供者别名：jina-search、jina-ai、jina）
POST /v1/search      { "query": "...", "provider": "jina-search" }

# 内容审核
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — 返回 audio/mpeg（或请求的格式）正文
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Soniox TTS 需要语言和语音：`language` 默认为 "en"；缺少语音或使用
# OpenAI 预置语音名称（alloy、nova、……）时，将改用 "Adrian"
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }

# 图像编辑（multipart）
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# 视频/音乐生成（带提供者前缀的模型 ID）
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }
```

> **重排序提供者节点：**`POST /v1/rerank` 也会路由到兼容 OpenAI 的提供者节点
> （oMLX、vLLM、Infinity、网关后的 TEI 等），这些节点以 `<node-prefix>/<model>` 的形式寻址。环回
> 节点（`localhost`、`127.0.0.1`、`172.16.0.0/12`）始终符合条件，运营方在
> `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` 中列出的主机名也同样符合条件（例如 Docker/Compose 服务名称，
> 如 `http://reranker:8080/v1`；这些节点会被直接调用，绝不经过 `HTTP(S)_PROXY` 或
> 为连接固定的代理）。位于任何其他
> 主机上的节点（例如局域网设备或 Tailscale 对等节点）仅在运营方启用
> `RERANK_REMOTE_PROVIDER_NODES` 功能标志，**并且**节点的基础 URL 通过提供者
> 出站 URL 策略（`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`）时才符合条件。
> 内存引擎的重排序步骤会通过
> 环回地址调用此路由，因此相同的规则也适用于内存设置中的 `rerankProviderModel`。
>
> **本地服务器形式：**节点首先通过 `<base>/v1/rerank` 调用；如果返回 404，则通过 `<base>/rerank`
> 调用（Infinity、TEI）。上游请求正文同时包含 Cohere/OpenAI 拼写（`documents`、
> `return_documents`）和 TEI 拼写（`texts`、`return_text`），上游响应则会
> 规范化为 Cohere 信封格式：TEI 的裸 `[{index, score, text}]`、轻量网关返回的
> `{results: [{index, score}]}` 以及 Voyage 风格的 `{data: [...]}`，都会以
> `{results: [{index, relevance_score, document?}]}` 的形式返回给客户端，并按分数排序且最多保留 `top_n` 条。

> **提供者节点发现：**兼容 OpenAI 的提供者节点上的模型会以节点前缀显示在 `GET /v1/models`
> 中。不包含端点元数据的行（本地 `/v1/models` 列表通常如此）
> 会继承节点的 `apiType`，因此 `embeddings` 节点的模型为 `type: "embedding"`，
> `rerank` 节点的模型为 `type: "rerank"`，而不是默认归类为聊天模型；同步或手动添加的行中显式指定的
> `supportedEndpoints` 仍然具有更高优先级。

### 专用提供者路由

```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```

如果缺少提供者前缀，系统会自动添加。模型不匹配时返回 `400`。

---

## Files API

兼容 OpenAI 的文件端点，用于批量输入/输出及按文件用途上传。

| 方法   | 路径                     | 描述                                                                                                      |
| ------ | ------------------------ | --------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/files`              | 上传文件（multipart：`file`、`purpose`、`expires_after[anchor]`、`expires_after[seconds]`）— 最大 512 MiB |
| GET    | `/v1/files`              | 列出经身份验证的 API 密钥所拥有的文件                                                                     |
| GET    | `/v1/files/[id]`         | 获取文件的元数据                                                                                          |
| DELETE | `/v1/files/[id]`         | 删除文件                                                                                                  |
| GET    | `/v1/files/[id]/content` | 以流式方式返回原始文件内容                                                                                |

**身份验证：** Bearer API 密钥——文件通过 `getApiKeyRequestScope` 按 API 密钥隔离。一个密钥
只能查看、下载和删除自己的文件；不使用密钥的仪表板会话可以读取整个
实例；没有所有者的文件（匿名上传或通过仪表板会话上传）对所有
非会话调用方均拒绝访问。`GET /v1/files` 会对匿名调用方以及提供了
但无法解析的密钥返回 `401`，即使 `REQUIRE_API_KEY=false` 也是如此，而不会列出所有租户的
文件（GHSA-m3hp-hq9g-fpmv、GHSA-2jm2-mpx8-6523）。

---

## Batches API

兼容 OpenAI 的批处理。

| 方法   | 路径                      | 描述                                                                                                  |
| ------ | ------------------------- | ----------------------------------------------------------------------------------------------------- |
| POST   | `/v1/batches`             | 创建批处理——请求正文由 `v1BatchCreateSchema` 验证（`input_file_id`、`endpoint`、`completion_window`） |
| GET    | `/v1/batches`             | 列出批处理                                                                                            |
| GET    | `/v1/batches/[id]`        | 获取批处理状态及 `request_counts`                                                                     |
| DELETE | `/v1/batches/[id]`        | 删除已完成/失败的批处理                                                                               |
| POST   | `/v1/batches/[id]/cancel` | 取消正在进行的批处理                                                                                  |

**身份验证：** Bearer API 密钥。批处理按 API 密钥隔离，遵循与
文件相同的三方规则：仅限自身密钥、仪表板会话可访问整个实例、无所有者的记录对所有
非会话调用方均拒绝访问（包括获取、删除、取消，以及创建时的 `input_file_id` 检查）。
`GET /v1/batches` 会对匿名调用方返回 `401`，即使 `REQUIRE_API_KEY=false` 也是如此。

---

## 搜索 API

Web/搜索提供者抽象层（Tavily、Brave、Exa、Serper 等）。

| 方法 | 路径                   | 描述                                                            |
| ---- | ---------------------- | --------------------------------------------------------------- |
| GET  | `/v1/search`           | 列出已配置的搜索提供者及其能力                                  |
| POST | `/v1/search`           | 执行搜索查询——请求体由 `v1SearchSchema` 验证，支持缓存/请求合并 |
| GET  | `/v1/search/analytics` | 各提供者的命中率/延迟/缓存统计                                  |

**身份验证：** Bearer API 密钥（`extractApiKey` + `isValidApiKey`）。搜索策略通过 `enforceApiKeyPolicy` 强制执行。

### Exa 和 Tavily 的 `provider_options`

Exa 和 Tavily 从带命名空间的属性包中读取提供者特定字段：
`provider_options.exa`（或 `provider_options["exa-search"]`）和 `provider_options.tavily`
（或 `provider_options["tavily-search"]`）。仅转发下列键。每个键都会根据
`open-sse/handlers/search/providerOptionsPassthrough.ts` 中各自的 Zod 模式进行检查，
类型错误的键将被丢弃。任何其他键都会被忽略，包括身份验证信息、基础 URL、
`stream` 和 `outputSchema`。其他提供者使用的扁平键（`cx`、`depth` 等）仍会
像以前一样工作。

| 提供者 | 顶层字段                                                                                                                                                                                                                                                                                                                                                                  | 嵌套字段                                                                                                                                                   |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Exa    | `type`、`category`、`userLocation`、`moderation`、`additionalQueries`、`objective`、`systemPrompt`、`compliance`（扁平原始值）、`startPublishedDate`、`endPublishedDate`                                                                                                                                                                                                  | `contents.{text, highlights, summary, extras, subpages, subpageTarget, livecrawlTimeout, maxAgeHours}` 合并并覆盖默认值 `{ text: true, highlights: true }` |
| Tavily | `search_depth`、`chunks_per_source`、`time_range`、`start_date`、`end_date`、`include_published_date`、`filter_by_published_date`、`include_answer`、`include_raw_content`、`include_images`、`include_image_descriptions`、`include_favicon`、`include_domains_mode`、`language`、`filter_by_language`、`auto_parameters`、`exact_match`、`include_usage`、`safe_search` | —                                                                                                                                                          |

通用字段始终具有最高优先级：`query`、`max_results`、`filters`（域名）、`country`，以及从
`search_type` 派生的主题。在 Exa 上，`search_type: "news"` 会保留 `category: "news"`。
Tavily 还接受 `search_type: "finance"`（`topic: "finance"`）。

通用的 `time_range` 现在会传递给两个提供者：Exa 接收 `startPublishedDate`（ISO
时间戳），Tavily 接收 `start_date`（`YYYY-MM-DD`）。`provider_options` 中显式指定的日期
会覆盖映射后的日期。

Exa 结果会在 `provider_raw` 中保留 `id`、`highlight_scores`、`summary`、`subpages`、`entities`
和 `extras`。Tavily 结果会保留 `images` 和 `favicon`。

成本核算仍使用扁平注册表 `costPerQuery`。Tavily 对
`search_depth: "advanced"` 的每次调用收取更多点数，但这一差异不会反映在
`usage.search_cost_usd` 中。

---

## Web Fetch API

通过已配置的网页抓取提供者（Firecrawl、Jina Reader、Tavily Extract、TinyFish Fetch、Nimble Extract、Parallel Extract）从 URL 提取内容。

Parallel Extract（`parallel-search`，与 Parallel Search 使用相同的 API 密钥）仅返回 Markdown——任何其他 `format` 都会导致 `400`——并且内容上限为 100,000 个字符。当目标页面本身无法提取时，上游会在 HTTP 200 响应中报告该情况；OmniRoute 会将其转换为带有固定消息的 `422`。

| 方法 | 路径            | 描述                                              |
| ---- | --------------- | ------------------------------------------------- |
| POST | `/v1/web/fetch` | 获取/抓取 URL——请求正文由 `v1WebFetchSchema` 验证 |

**身份验证：** Bearer API 密钥（`extractApiKey` + `isValidApiKey`）。通过 `enforceApiKeyPolicy` 强制执行策略。

**配额感知回退（#8297）：** 当未明确指定 `provider` 时，提供者池
（`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search` →
`parallel-search`）会按固定
优先级顺序（优先填充）依次尝试——已配置但受速率限制的提供者会被跳过，
而不是直接终止请求；此外，在请求时，如果上游发生可重试/配额相关的失败
（HTTP 429 始终适用；对于 Firecrawl/Tavily/TinyFish 免费层中配额类的 402/403 也适用——
但不适用于 Jina Reader，也绝不适用于普通的 400 错误请求），则会继续尝试
下一个尚未尝试且已配置凭据的提供者。当池中的所有提供者均已耗尽时，
端点会返回单个 `429`（带有 `Retry-After`
标头），而不是之前通用的 `400`。当明确请求某个 `provider` 时，
**不会**进行静默回退——受速率限制或发生故障的指定提供者会直接返回其自身错误
（如果受速率限制则为 `429`，否则为上游
状态码）。

---

## WebSocket 流式传输

```bash
GET /v1/ws?handshake=1
```

验证 WebSocket 升级握手，并返回线路协议示例消息（`request`、`cancel`）。实际的 WS 帧由 Next.js 路由表之外的捆绑 WS 服务器处理。

**身份验证：** 握手期间使用 Bearer API 密钥。

### 通过 WebSocket 使用 Responses API（仅限 codex）

```bash
# 与 HTTP API 使用相同的主机和端口（默认 20128）；升级连接：
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# （或者：-H "Authorization: Bearer <OMNIROUTE_API_KEY>"）

# 第一帧必须是 response.create：
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```

Responses-API-over-WebSocket 代理**仅连接到 `codex`**（ChatGPT
后端）。它在与 API/仪表板相同的端口上侦听路径 `/v1/responses`、
`/responses` 和 `/api/v1/responses`。收到第一个 `response.create` 帧时，
它会通过内部 `codex-responses-ws` 桥接器进行身份验证和准备，选择一个
codex OAuth 连接，并通过 `wreq-js` 传输层将流量隧道转发至 `wss://chatgpt.com/backend-api/codex/responses`。
**非 codex 模型会被拒绝**（`codex_ws_provider_required`）。
如需使用配额共享路由，请使用 `model: "qtSd/<group>/codex/<model>"`。实现在
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts` 中。

**身份验证：** 握手期间使用 Bearer API 密钥。捆绑的 HTTP 服务器（`server-ws.mjs`）
必须是当前活动的入口点（当 `app/server-ws.mjs` 存在时，默认如此）。

#### 模型 ID：使用不带 `codex/` 前缀的 ChatGPT 原始 ID

当 `supports_websockets = true` 时，OpenAI **Codex CLI** 会在客户端验证模型名称，并且
**拒绝带提供者前缀的 ID**，例如
`codex/gpt-5.5`（`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`）。请发送**原始** ID（例如 `gpt-5.5`）。OmniRoute 的桥接器
仅支持 codex，因此在隧道转发至上游之前，它会将原始 ID 重新解析为 codex 模型
（`resolveCodexWsModelInfo`）——即使原始的
`gpt-5.5` 在通过 HTTP 请求时原本会被路由到其他提供者。

#### 配置 OpenAI Codex CLI

通过向 `~/.codex/config.toml` 添加支持 WebSocket 的自定义提供者，
将 Codex CLI 指向 OmniRoute（使用单独的 `CODEX_HOME`，以免修改
现有配置）：

```toml
model = "gpt-5.5"                 # 原始 ID——不是 "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # 不要添加尾部斜杠；WS URL 会自动派生（生产环境中使用 https/wss）
wire_api = "responses"                    # 自 2026 年 2 月起唯一支持的值
supports_websockets = true                # 启用 Responses-over-WS 传输
env_key = "OMNIROUTE_API_KEY"             # 保存 OmniRoute API 密钥（Bearer）
```

```bash
export OMNIROUTE_API_KEY=sk-...           # OmniRoute API 密钥（若 REQUIRE_API_KEY=false，则任意密钥均可）
codex exec "Responda apenas: PONG"
```

CLI 会将 `base_url + /responses` 升级为 WebSocket，OmniRoute 随后会将其
隧道转发至选定的 codex OAuth 连接。已针对本地服务器完成端到端验证：
ChatGPT 返回 `codex.rate_limits` + `response.created`，并以流式方式传输
补全结果。

---

## 配额与问题报告

| 方法 | 路径                | 描述                                                                |
| ---- | ------------------- | ------------------------------------------------------------------- |
| GET  | `/v1/quotas/check`  | 在签发已注册密钥之前，预先验证 `provider` + `accountId` 的配额      |
| POST | `/v1/issues/report` | 向 GitHub 报告配额/密钥签发失败（需要 `GITHUB_ISSUES_REPO` + 令牌） |

**身份验证：** Bearer API 密钥（`isAuthenticated`）。

---

## 自助用量查询（`/api/usage/om-usage`）

任何 API 密钥都可以读取**自身的**用量和配额——无需管理身份验证。客户端（CLI、OmniCopilot 面板）使用此端点向密钥持有者显示其支出。

```bash
# 文本形式（历史约定——用于终端的纯文本）
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# 结构化形式——供 UI 使用
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"
```

密钥必须启用 **`allowUsageCommand`**（默认关闭——仪表板的 API 密钥管理器可针对每个密钥切换此设置）。如果未启用，该端点将返回 `403`。

`?format=json` 返回一种可辨识的结构，因此调用者绝不会在请求被拒绝时读取数据字段。成功时：

```jsonc
{
  "allowed": true,
  // 仅当该密钥启用了按密钥设置的用量限制（每日/每周美元限额）时存在：
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // 所选提供者的配额快照；尚未缓存任何内容时为 null：
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // 每个连接的快照，以便 UI 并排呈现多个提供者：
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

请求被拒绝时（`401`：密钥无效；`403`：不允许访问），同一路由将返回
`{ "allowed": false, "error": { "message": "…" } }`——存在但为空的 `personal`/`provider`（密钥获准访问，但尚未获取任何数据）与拒绝状态不同，并且只有 JSON 形式能够区分这些状态。

**身份验证：**调用者自身的 Bearer API 密钥，通过 `isValidApiKey` 验证——这_不是_管理接口（`/api/keys/…`），后者仍受 `requireManagementAuth` 保护。

### 原始配额百分比与截止阈值调整后的配额百分比

使用 `/api/usage/om-usage` 时，调用者应注意**纯文本输出**与结构化 **JSON 输出**所呈现百分比之间的区别：

| 方面             | 纯文本格式（`/api/usage/om-usage` / `@@om-usage`）                          | JSON 格式（`?format=json`）                                   |
| :--------------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------ |
| **输出字段**     | `NN% left`（例如 `20% left`）                                               | `provider.quotas` / `providers[].quotas`                      |
| **衡量方式**     | **经截止阈值调整的可用额度**：高于截止阈值的剩余容量                        | **原始上游配额**：未经调整的提供者度量值                      |
| **截止阈值缩放** | 通过 `effectiveRemainingPercent()` 缩放，使受保护的预留额度显示为 `0% left` | 无（由提供者报告的原始快照值）                                |
| **阈值数据**     | 已纳入显示的百分比中                                                        | 按连接存储在 `quotaWindowThresholds` 中（或使用服务器默认值） |
| **主要使用者**   | 交互式 CLI、终端提示、人类操作员                                            | 程序化集成、仪表板、分析工具、计费跟踪器                      |

#### 截止阈值调整公式

OmniRoute 支持主动配额截止，以防止上游配额耗尽（通过连接的 `quotaWindowThresholds`、提供者默认值或全局弹性设置进行配置）。当某个配额窗口启用了截止阈值（例如 `cutoff = 25%`）时，文本渲染器按以下方式计算剩余额度：

- 如果 `remaining <= cutoff`：返回 `0%`。
- 如果 `remaining > cutoff`：返回 `((remaining - cutoff) / (100 - cutoff)) * 100`。

格式化的文本输出会将结果四舍五入到最接近的整数（`Math.round(...)`）。

#### 示例

假设某个提供者窗口的**原始用量为 60%**（因此**原始剩余配额为 40%**），并且配置了 **25% 的剩余配额截止阈值**：

| 表示形式                        | 计算                                               | 剩余量  |               隐含已用量               |
| :------------------------------ | :------------------------------------------------- | :-----: | :------------------------------------: |
| **原始 JSON（`?format=json`）** | 上游快照（`quotas[window]`）                       | **40%** |                **60%**                 |
| **文本格式（`NN% left`）**      | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **20%** | **80%**（若按 `100 - remaining` 计算） |

- **为什么文本显示剩余 20%：**账户实际剩余的 40% 配额中，有 25% 被截止策略预留。在路由器停止将流量路由到此连接之前，调用者在 75% 的可用余量中只剩下 15%。缩放可确保连接恰好在路由停止时发出配额耗尽信号（`0% left`）。
- **为什么 JSON 保留原始值：**JSON 载荷返回精确的提供者快照（`UsageSnapshot`），因此外部工具可以访问真实的上游利用率和连接级别的 `quotaWindowThresholds`，而不会受到服务器端有损缩放的影响。

#### 使用者迁移指南

如果某个外部集成（例如编辑器插件或代理扩展）之前抓取文本端点（`NN% left`），并通过 `100 - NN` 计算已用百分比，那么迁移到 `?format=json` 意味着：

- 读取原始 JSON 值将反映**实际的上游消耗量**（在上述示例中为已用 60%）。
- 如果集成希望保留文本端点的可用额度语义，可以在客户端使用 `quotaWindowThresholds` 中的连接级别覆盖设置计算有效剩余量公式。

---

## 语义缓存

```bash
# 获取缓存统计信息
GET /api/cache/stats

# 清除所有缓存
DELETE /api/cache/stats
```

响应示例：

```json
{
  "semanticCache": {
    "memorySize": 42,
    "memoryMaxSize": 500,
    "dbSize": 128,
    "hitRate": 0.65
  },
  "idempotency": {
    "activeKeys": 3,
    "windowMs": 5000
  }
}
```

### 延迟影响

语义缓存命中时，响应将直接从缓存提供，**不会发起上游调用**，因此报告的 `X-OmniRoute-Response-Latency` 接近于零（无论原始上游延迟是多少）。对延迟敏感的客户端（基准测试、p50/p99 监控）应检查 `X-OmniRoute-Cache-Latency` 响应标头：

| 值           | 含义                                   |
| ------------ | -------------------------------------- |
| `synthetic`  | 响应由缓存提供；延迟并非真实的上游耗时 |
| _（不存在）_ | 响应来自真实的上游调用                 |

### 按密钥绕过缓存

API 密钥可以通过 `cacheDefaultMode` 选择不读取语义缓存：

| 值       | 行为                           |
| -------- | ------------------------------ |
| `legacy` | 正常的缓存行为（默认）         |
| `bypass` | 完全跳过缓存查找；始终调用上游 |

在创建密钥（`POST /api/keys`）或更新密钥（`PATCH /api/keys/[id]`）时设置：

```json
{ "cacheDefaultMode": "bypass" }
```

### 按请求绕过缓存

无论密钥设置如何，任何请求都可以绕过缓存：

```
X-OmniRoute-No-Cache: true
```

---

## 仪表盘与管理

管理路由（`/api/*`，公开的 auth/login 除外）**无法**通过普通推理 API 密钥授权。凭证类别、作用域及 curl 示例：[管理认证](../guides/MANAGEMENT-AUTH.md)。

### 认证

| 端点                          | 方法     | 描述                                                                                                                                                                                                           |
| ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/auth/login`             | POST     | 登录                                                                                                                                                                                                           |
| `/api/auth/logout`            | POST     | 登出                                                                                                                                                                                                           |
| `/api/settings/require-login` | GET/POST | 登录状态（GET，公开）。POST 用于设置密码/切换登录开关：一旦密码已存在，仅操作者可执行（仪表盘会话、本地 CLI，或已禁用登录——API 密钥和 `oma_` 令牌会收到 `403`）；仪表盘会话会发送 `currentPassword` 以替换密码 |

### 提供者管理

| 端点                                    | 方法                      | 描述                                                                                                      |
| --------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------- |
| `/api/providers`                        | GET/POST                  | 列出/创建提供者                                                                                           |
| `/api/providers/[id]`                   | GET/PUT/DELETE            | 管理单个提供者                                                                                            |
| `/api/providers/[id]/test`              | POST                      | 测试提供者连接                                                                                            |
| `/api/providers/[id]/models`            | GET                       | 列出提供者模型                                                                                            |
| `/api/providers/validate`               | POST                      | 验证提供者配置                                                                                            |
| `/api/providers/bulk`                   | POST                      | 为单个提供者批量添加 API 密钥                                                                             |
| `/api/providers/import`                 | POST                      | 从解析后的 CSV/JSON 文件导入异构提供者列表（#6836）；返回逐行的部分失败结果                               |
| `/api/provider-nodes*`                  | 多种                      | 提供者节点管理                                                                                            |
| `/api/provider-models`                  | GET/POST/PUT/PATCH/DELETE | 自定义模型及按模型覆盖（添加、更新、隐藏/显示、删除）                                                     |
| `/api/provider-models/validate-and-add` | POST                      | 经管理认证的、可选启用的严格连接验证与原子化自定义模型注册；参见[模型验证](../guides/MODEL-VALIDATION.md) |

对于已同步/导入的模型，`PUT /api/provider-models` 接受 `provider`、`modelId` 和
`maxOutputTokenOverride`：正整数用于设置手动输出令牌上限，`null`
则清除该设置以恢复默认值。`GET /api/provider-models?provider=<provider>` 会在
`modelOutputOverrides` 中返回这些值，包括没有自定义模型行的模型。该覆盖
使用运行时的 `max_output_tokens` 能力，并在模型重新同步后仍然保留。OpenAI 兼容
提供者页面提供相同的编辑/清除控件，并会标记具有显式视觉支持的模型。

自定义 Chat Completions 节点会将显式的推理禁用适配到上游后端。连接测试成功
后，会为每个精确模型 ID 自动选择聊天模板控件——前提是其 `/models` 条目
包含可识别的 `owned_by` 值：`vllm`、`sglang` 或 `llamacpp`。
透明的 OpenAI 兼容封装层可能会将原始模型条目保留在嵌套的
`openai` 对象中；检测最多会追踪三层此类封装。所有权缺失、未知或
冲突的模型将保持普通的 OpenAI 行为。检测复用现有的目录请求，
不生成任何补全令牌，并在连接端点更改时失效。

对于不暴露该元数据的后端，如需固定此行为，请使用现有的部分
提供者更新 API：

```json
{
  "providerSpecificData": {
    "reasoningControl": "chat-template"
  }
}
```

将该请求体通过 `PUT /api/providers/<connection-id>` 发送。在该连接上，显式的推理力度 `none` 会以 `chat_template_kwargs.thinking=false` 和 `chat_template_kwargs.enable_thinking=false` 的形式发送。除非服务端推理规则强制指定推理力度，否则显式的原生模板值保持权威。该设置仅在自定义 OpenAI 兼容连接分发 Chat Completions 请求体时生效；Responses 请求和普通提供者保持其原生请求结构。将 `reasoningControl` 设为 `openai` 可强制普通 OpenAI 的 `reasoning_effort` 透传；省略它或将其设为 `null` 则使用自动检测。

当 Claude Code 自动模式分类器请求不包含显式推理控制时，原生思考功能默认禁用。检测基于 Claude 格式请求中分类器的系统标记，而非模型名称或补全上限。显式请求体控制、受支持的 effort/thinking 请求头、路由规则以及解析后的模型推理力度保持其现有优先级。分类器的两个阶段均保留其提示词、补全上限、停止序列以及真实的上游权限判定；第二阶段仍可以普通文本形式产出其请求的可见推理内容。

### OAuth 流程

| 端点                             | 方法    | 描述               |
| -------------------------------- | ------- | ------------------ |
| `/api/oauth/[provider]/[action]` | Various | 提供者特定的 OAuth |

### 路由与配置

| 端点                  | 方法     | 描述                       |
| --------------------- | -------- | -------------------------- |
| `/api/models/alias`   | GET/POST | 模型别名                   |
| `/api/models/catalog` | GET      | 按提供者和类型列出所有模型 |
| `/api/combos*`        | Various  | 组合管理                   |
| `/api/keys*`          | Various  | API 密钥管理               |
| `/api/pricing`        | GET      | 模型定价                   |

### 用量与分析

| 端点                             | 方法            | 描述                                                                                                                                                                                                                                               |
| -------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history`             | GET             | 用量历史                                                                                                                                                                                                                                           |
| `/api/usage/logs`                | GET             | 用量日志                                                                                                                                                                                                                                           |
| `/api/usage/request-logs`        | GET             | 请求级日志                                                                                                                                                                                                                                         |
| `/api/usage/[connectionId]`      | GET             | 按连接统计的用量                                                                                                                                                                                                                                   |
| `/api/usage/token-limits`        | GET/POST/DELETE | 按 API 密钥设置的 token 限额预算                                                                                                                                                                                                                   |
| `/api/usage/model-latency-stats` | GET             | 按提供者/模型滚动的延迟聚合（avg/p50/p95/p99、成功率）；筛选参数：`windowHours`/`minSamples`/`maxRows`/`provider`/`model`（#6873）                                                                                                                 |
| `/api/usage/cache-health`        | GET             | 基于 `call_logs` 的提示词缓存健康摘要 —— 写/读比率、p50/p90/p99 写入大小分布、重度写入集中度、按模型拆分，以及 `healthy`/`degraded`/`thrash`/`no-data` 判定结果；查询参数 `range`（`1h`\|`24h`\|`7d`\|`30d`，默认 `24h`）和可选的 `model`（#8827） |

### API 密钥权限

`PATCH /api/keys/{id}` 用于更新现有密钥的权限。与所有 `/api/keys*` 路由一样，它需要管理授权（参见[管理认证](../guides/MANAGEMENT-AUTH.md)），而非推理密钥。仅发送你想要修改的字段；不包含任何这些字段的请求会被拒绝并返回 `No valid fields to update`。可接受的字段由 `src/shared/validation/schemas/keys.ts` 中的 `updateKeyPermissionsSchema` 定义。

| 字段                                        | 类型                                                    | 备注                                                                                             |
| ------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `name`                                      | 字符串，1-200 个字符                                    |                                                                                                  |
| `isActive`                                  | 布尔值                                                  |                                                                                                  |
| `isBanned`                                  | 布尔值                                                  |                                                                                                  |
| `expiresAt`                                 | ISO 8601 日期时间或 `null`                              | `null` 表示清除过期时间                                                                          |
| `modelAccessMode`                           | `all` \| `restricted`                                   | 当模式为 `all` 时，`allowedModels` 必须为空                                                      |
| `allowedModels`、`blockedModels`            | 字符串数组，最多 1000 个                                |                                                                                                  |
| `allowedCombos`                             | 字符串数组，最多 500 个                                 | 控制该密钥可调用哪些组合；直接模型由 `modelAccessMode` / `allowedModels` 控制                    |
| `connectionAccessMode`                      | `all` \| `restricted`                                   | 当为 `restricted` 时 `allowedConnections` 必须非空，当为 `all` 时必须为空                        |
| `allowedConnections`                        | UUID 数组，最多 100 个                                  |                                                                                                  |
| `allowAutoCombos`                           | 布尔值                                                  | `false` 会拒绝此密钥对 `auto/*` 模型的请求；从未设置过该字段的密钥则允许请求                     |
| `catalogScope`                              | `all` \| `combos` \| `models`                           | 决定 `GET /v1/models` 为该密钥列出哪些内容（仅组合、仅模型或两者）；它不会改变该密钥可调用的内容 |
| `forcedModel`                               | 最长 300 个字符的字符串，或 `null`                      | 将聊天请求路由到此模型/组合，优先级高于 `X-Route-Model` 和 `body.model`；该密钥的限制仍然生效    |
| `noLog`、`autoResolve`                      | 布尔值                                                  |                                                                                                  |
| `throttleDelayMs`                           | 整数，0-300000                                          |                                                                                                  |
| `maxSessions`                               | 整数，0-10000                                           |                                                                                                  |
| `rateLimits`                                | `{ limit, window }` 数组（正整数，最多 50 个）或 `null` | `null` 表示清除限制                                                                              |
| `accessSchedule`                            | 计划对象或 `null`                                       | `null` 表示清除计划                                                                              |
| `scopes`                                    | 字符串数组，最多 32 个                                  |                                                                                                  |
| `allowedEndpoints`                          | 字符串数组，最多 20 个                                  |                                                                                                  |
| `streamDefaultMode`                         | `legacy` \| `json`                                      |                                                                                                  |
| `cacheDefaultMode`                          | `legacy` \| `bypass`                                    | 参见 [按密钥绕过缓存](#per-key-cache-bypass)                                                     |
| `compressionEnabled`                        | 布尔值                                                  |                                                                                                  |
| `codexServiceMode`                          | Codex 服务模式之一                                      |                                                                                                  |
| `disableNonPublicModels`                    | boolean                                                 |                                                                                                  |
| `allowUsageCommand`                         | boolean                                                 |                                                                                                  |
| `usageLimitEnabled`                         | boolean                                                 |                                                                                                  |
| `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | number >= 0 or `null`                                   |                                                                                                  |
| `chaosModeEnabled`                          | boolean                                                 |                                                                                                  |

```bash
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
  -H "Authorization: Bearer <management-credential>" \
  -H "Content-Type: application/json" \
  -d '{ "allowAutoCombos": false, "catalogScope": "combos" }'
```

### 设置

| 端点                                  | 方法          | 描述                                                                                                                                                                                                                          |
| ------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings`                       | GET/PUT/PATCH | 通用设置。安全策略相关的键（`requireLogin`、`newPassword`、`oidc*`、`corsOrigins`、`bruteForceProtection`）需要 `currentPassword` 以及操作员凭据 —— API 密钥和 `oma_` 令牌会收到 `403`；每次变更都需要 `admin` 访问令牌作用域 |
| `/api/settings/proxy`                 | GET/PUT       | 网络代理配置                                                                                                                                                                                                                  |
| `/api/settings/proxy/test`            | POST          | 测试代理连接                                                                                                                                                                                                                  |
| `/api/settings/ip-filter`             | GET/PUT       | IP 白名单/黑名单                                                                                                                                                                                                              |
| `/api/settings/thinking-budget`       | GET/PUT       | 思考/推理**请求**重写模式（passthrough / auto-strip / custom / adaptive）。独立于压缩功能。参见 [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md)。                                                                          |
| `/api/settings/system-prompt`         | GET/PUT       | 全局系统提示词                                                                                                                                                                                                                |
| `/api/settings/compression`           | GET/PUT       | 全局压缩配置                                                                                                                                                                                                                  |
| `/api/settings/purge-request-history` | POST          | 清除请求日志记录和本地调用日志文件                                                                                                                                                                                            |

### 上下文与压缩

| 端点                                   | 方法           | 描述                                                     |
| -------------------------------------- | -------------- | -------------------------------------------------------- |
| `/api/compression/preview`             | POST           | 预览 off/lite/standard/aggressive/ultra/RTK/stacked 压缩 |
| `/api/compression/language-packs`      | GET            | 列出可用的 Caveman 语言包                                |
| `/api/compression/rules`               | GET            | 列出 Caveman 规则元数据                                  |
| `/api/context/caveman/config`          | GET/PUT        | Caveman 专用设置别名                                     |
| `/api/context/rtk/config`              | GET/PUT        | RTK 专用设置，包括自定义过滤器和原始输出保留             |
| `/api/context/rtk/filters`             | GET            | RTK 过滤器目录和自定义过滤器诊断                         |
| `/api/context/rtk/test`                | POST           | 对文本负载运行 RTK 预览/测试                             |
| `/api/context/rtk/raw-output/[id]`     | GET            | 按指针 id 读取已保留的脱敏原始输出                       |
| `/api/context/combos`                  | GET/POST       | 压缩组合列表/创建                                        |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | 压缩组合详情/更新/删除                                   |
| `/api/context/combos/[id]/assignments` | GET/PUT        | 将压缩组合分配给路由组合                                 |
| `/api/context/analytics`               | GET            | 压缩分析别名                                             |

### 监控

| 端点                                 | 方法       | 描述                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/sessions`                      | GET        | 活动会话跟踪                                                                                                                                                                                                                                                                                                                                                             |
| `/api/rate-limits`                   | GET        | 每账户速率限制                                                                                                                                                                                                                                                                                                                                                           |
| `/api/monitoring/health`             | GET        | 健康检查 + 提供者摘要（`catalogCount`、`configuredCount`、`activeCount`、`monitoredCount`）。管理视图包含 `credentialHealth`：探测缓存标量、当 `failed>0` 时的 `failedConnections`，以及 `staleDbNonOkCount`（SQLite 粘性 `test_status`，而非仪表盘指标）。请参阅 [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status)。 |
| `/api/cache/stats`                   | GET/DELETE | 缓存统计 / 清除                                                                                                                                                                                                                                                                                                                                                          |
| `/api/modality-bridge/stats`         | GET        | 内存中的 `attempts`、成功数/`bridged`、失败数、缓存命中数、`totalLatencyMs`、`latencySamples`、以样本数为分母的 `averageLatencyMs`，以及最后使用时间（重启时重置；需要管理认证）                                                                                                                                                                                         |
| `/api/modality-bridge/video/runtime` | GET        | 在管理认证/探测之前进行严格的可信回环检查；经过脱敏处理的 FFmpeg/ffprobe 可用性与版本信息（no-store）                                                                                                                                                                                                                                                                    |
| `/api/modality-bridge/video/extract` | POST       | 内部认证的可信回环字节代理；50 MiB 输入、有界队列/32 MiB 输出、`503` 容量限制、`499` 断开连接、`504` 超时；非公开上传 API                                                                                                                                                                                                                                                |

### 备份与导出/导入

| 端点                        | 方法   | 描述                                                   |
| --------------------------- | ------ | ------------------------------------------------------ |
| `/api/db-backups`           | GET    | 列出可用的备份                                         |
| `/api/db-backups`           | PUT    | 创建手动备份                                           |
| `/api/db-backups`           | POST   | 从指定的备份恢复                                       |
| `/api/db-backups`           | PATCH  | 保存备份保留设置（仅限操作员）                         |
| `/api/db-backups`           | DELETE | 按保留设置清理已存储的备份（仅限操作员）               |
| `/api/db-backups/export`    | GET    | 下载数据库为 .sqlite 文件                              |
| `/api/db-backups/import`    | POST   | 上传 .sqlite 文件以替换数据库（`?dryRun=true` 仅验证） |
| `/api/db-backups/exportAll` | GET    | 下载完整备份为 .tar.gz 压缩包                          |

`/api/db-backups/export`、`/api/db-backups/exportAll` 和 `/api/settings/export-json` 会暴露所有已存储的凭据，因此它们要求仪表盘会话或本地 CLI（或禁用登录）。任何作用域的 API 密钥以及 `oma_` 访问令牌都会收到 `403`。恢复操作遵循相同的边界：`POST /api/db-backups/import`（包括 `dryRun=true`）、`POST /api/db-backups`（按 id 恢复）以及 `POST /api/settings/import-json` 会替换在线数据库或设置，因此机器凭据在这些端点同样会收到 `403`；`omniroute sync import` 会发送本地 CLI 凭据。`DELETE /api/db-backups`（清理已存储的备份）和 `PATCH /api/db-backups`（保留设置：持久化的值会在每次备份后驱动自动清理）也是如此。列出（`GET`）和创建手动备份（`PUT`）则保留常规的管理认证。

### 云同步

| 端点                   | 方法 | 描述       |
| ---------------------- | ---- | ---------- |
| `/api/sync/cloud`      | 多种 | 云同步操作 |
| `/api/sync/initialize` | POST | 初始化同步 |
| `/api/cloud/*`         | 多种 | 云管理     |

### 隧道

| 端点                       | 方法 | 描述                                                          |
| -------------------------- | ---- | ------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET  | 为仪表盘读取 Cloudflare Quick Tunnel 的安装/运行状态          |
| `/api/tunnels/cloudflared` | POST | 启用或禁用 Cloudflare Quick Tunnel（`action=enable/disable`） |
| `/api/tunnels/ngrok`       | GET  | 为仪表盘读取 ngrok Tunnel 的运行状态                          |
| `/api/tunnels/ngrok`       | POST | 启用或禁用 ngrok Tunnel（`action=enable/disable`）            |

### CLI 工具

| 端点                               | 方法 | 描述              |
| ---------------------------------- | ---- | ----------------- |
| `/api/cli-tools/claude-settings`   | GET  | Claude CLI 状态   |
| `/api/cli-tools/codex-settings`    | GET  | Codex CLI 状态    |
| `/api/cli-tools/droid-settings`    | GET  | Droid CLI 状态    |
| `/api/cli-tools/openclaw-settings` | GET  | OpenClaw CLI 状态 |
| `/api/cli-tools/runtime/[toolId]`  | GET  | 通用 CLI 运行时   |

CLI 响应包含：`installed`、`runnable`、`command`、`commandPath`、`runtimeMode`、`reason`。

### ACP 代理

| 端点              | 方法   | 描述                                          |
| ----------------- | ------ | --------------------------------------------- |
| `/api/acp/agents` | GET    | 列出所有检测到的代理（内置 + 自定义）及其状态 |
| `/api/acp/agents` | POST   | 添加自定义代理或刷新检测缓存                  |
| `/api/acp/agents` | DELETE | 通过 `id` 查询参数删除自定义代理              |

GET 响应包含 `agents[]`（id, name, binary, version, installed, protocol, isCustom）和 `summary`（total, installed, notFound, builtIn, custom）。

### 弹性与速率限制

| 端点                              | 方法      | 描述                                                                                                                                                                                                                                                                                                                              |
| --------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/resilience`                 | GET/PATCH | 获取/更新请求队列、连接冷却、提供方熔断器及等待设置                                                                                                                                                                                                                                                                               |
| `/api/resilience/reset`           | POST      | 重置提供方熔断器                                                                                                                                                                                                                                                                                                                  |
| `/api/resilience/model-cooldowns` | GET       | 列出当前生效的按（提供方、连接、模型）维度的锁定，按剩余时间排序                                                                                                                                                                                                                                                                  |
| `/api/resilience/model-cooldowns` | DELETE    | 清除某个模型锁定——请求体为 `{provider, model}`，或使用 `{all: true}` 清除全部                                                                                                                                                                                                                                                     |
| `/api/rate-limits`                | GET/POST  | 查看每个账号的速率限制状态（GET），或为某个连接开启/关闭速率限制保护（POST `{connectionId, enabled}`）。这是 `rateLimitProtection` 支持的写入路径（绝不能通过 `PUT /api/providers/[id]` 修改）。注意：`enabled: false` 会关闭显式保护，但不会让处于激活状态的 API 密钥连接脱离全局自动启用安全网（`autoEnableApiKeyProviders`）。 |
| `/api/rate-limit`                 | GET       | 全局速率限制配置（已弃用；为 `/api/rate-limits` 的别名）                                                                                                                                                                                                                                                                          |

> 所有四个 `/api/resilience/*` 路由都需要**管理认证**（`requireManagementAuth`）。有关提供方熔断器、连接冷却与模型锁定三者的完整区别说明，请参阅[弹性（扩展）](#resilience-extended)。

### 评估（Evals）

| 端点         | 方法     | 描述                    |
| ------------ | -------- | ----------------------- |
| `/api/evals` | GET/POST | 列出评估套件 / 运行评估 |

### 策略（Policies）

| 端点            | 方法            | 描述         |
| --------------- | --------------- | ------------ |
| `/api/policies` | GET/POST/DELETE | 管理路由策略 |

### 合规（Compliance）

| 端点                        | 方法 | 描述                      |
| --------------------------- | ---- | ------------------------- |
| `/api/compliance/audit-log` | GET  | 合规审计日志（最近 N 条） |

### v1beta（兼容 Gemini）

| 端点                       | 方法 | 描述                          |
| -------------------------- | ---- | ----------------------------- |
| `/v1beta/models`           | GET  | 以 Gemini 格式列出模型        |
| `/v1beta/models/{...path}` | POST | Gemini `generateContent` 端点 |

这些端点镜像了 Gemini 的 API 格式，面向需要原生 Gemini SDK 兼容性的客户端。

### 内部 / 系统 API

| 端点                     | 方法 | 描述                                           |
| ------------------------ | ---- | ---------------------------------------------- |
| `/api/init`              | GET  | 应用初始化检查（首次运行时使用）               |
| `/api/tags`              | GET  | 兼容 Ollama 的模型标签（供 Ollama 客户端使用） |
| `/api/restart`           | POST | 触发服务器优雅重启                             |
| `/api/shutdown`          | POST | 触发服务器优雅关闭                             |
| `/api/system/env/repair` | POST | 修复 OAuth 提供方的环境变量                    |
| `/api/system/version`    | GET  | 当前/最新版本、更新状态、发布渠道              |
| `/api/system/version`    | POST | 启动一次可感知部署方式的更新，升级到最新版本   |

> **注意：**这些端点由系统内部使用，或用于兼容 Ollama 客户端，最终用户通常不会调用它们。

### OAuth 环境修复 _(v3.6.1+)_

```bash
POST /api/system/env/repair
Content-Type: application/json

{
  "provider": "claude-code"
}
```

修复特定提供者缺失或损坏的 OAuth 环境变量。返回：

```json
{
  "success": true,
  "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
  "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}
```

### 版本与发布渠道

```bash
GET /api/system/version
```

仅限回环地址访问的管理路由（管理员认证）。返回当前运行的版本、最新发布的版本以及自动更新状态。`releaseChannel` 和 `channels` 为新增字段（rail 3.8.54）；`channel` 保持其原有含义——仪表板更新器所使用的部署模式（`npm`、`source` 或 `docker-compose`）。

```json
{
  "current": "3.8.52",
  "latest": "3.8.52",
  "updateAvailable": false,
  "channel": "npm",
  "autoUpdateSupported": true,
  "autoUpdateError": null,
  "news": null,
  "releaseChannel": "latest",
  "channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" }
}
```

- `releaseChannel` — 当前运行构建所属的 npm 渠道：`-nightly.*` 版本为 `nightly`，其他预发布版本（`-rc.*`、`-beta.*`、`-alpha.*`）为 `next`，低于 `channels.latest` 的旧主版本的稳定版为 `lts`，其余情况为 `latest`。规则与 `scripts/release/dist-tag.mjs` 相同，该脚本在发布时选择 npm dist-tag。
- `channels` — 各 dist-tag 已发布的最新版本，来自 `npm view omniroute dist-tags`（registry HTTP 回退），与 `latest` 使用相同的 10 分钟 TTL 缓存。`latest` 始终存在（先回退到 `latest` 字段，再回退到 `"unavailable"`）；`next`、`nightly` 和 `lts` 仅在对应 dist-tag 存在时出现。携带 `Cache-Control: no-cache` 的请求会同时刷新这两项查询。

渠道模型（`latest` = 4.0 GA 之前的 v3，`next` = rc，`nightly` = `develop` 构建，`lts` = 4.0 GA 之后的 v3 补丁）在 `docs/ops/RELEASE_STRATEGY.md` 中有详细说明。

---

## 音频转录

```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```

使用任意已配置的 STT 提供者转录音频文件。第一个路径段用于选择原生提供者（`openai/…`、`deepgram/…`）。重新导出其他供应商模型的网关使用限定 ID（`openrouter/deepgram/nova-3`）。

**请求：**

```bash
curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@recording.mp3" \
  -F "model=openai/whisper-1"
```

**响应：**

```json
{
  "text": "Hello, this is the transcribed audio content.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}
```

**模型 ID 示例：** `openai/whisper-1`（需要 OpenAI 密钥）、
`openrouter/deepgram/nova-3`（需要 OpenRouter 密钥）、
`deepgram/nova-3`（需要原生 Deepgram 密钥）。仅使用
`deepgram/nova-3` 的请求**不会**使用 OpenRouter。

**支持的格式：** `mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。

---

## Ollama 兼容性

对于使用 Ollama API 格式的客户端：

```bash
# 聊天端点（Ollama 格式）
POST /v1/api/chat

# 模型列表（Ollama 格式）
GET /api/tags
```

请求会在 Ollama 格式与内部格式之间自动转换。

## 包含令牌的 VS Code / 无请求头别名

当集成无法注入 `Authorization` 请求头，并且需要将 API 密钥嵌入基础 URL 时，请使用这些别名。

```bash
# OpenAI 风格的目录别名
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# OpenAI 风格的聊天别名
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Ollama 风格的别名
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```

示例：

```bash
curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'
```

注意：

- 包含令牌的别名复用与 `/v1/*` 和 `/api/tags` 相同的处理程序；响应结构保持不变。
- 只要客户端支持自定义请求头，就应优先使用 `Authorization: Bearer ...`。
- 基于 URL 的令牌可能会出现在反向代理日志、浏览器历史记录以及 OmniRoute 外部的遥测数据中。应将其视为一种兼容性选项，而不是默认身份验证方式。

---

## 遥测

```bash
# 获取延迟遥测摘要（每个提供者的 p50/p95/p99）
GET /api/telemetry/summary
```

**响应：**

```json
{
  "providers": {
    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
  }
}
```

---

## 预算

```bash
# 获取所有 API 密钥的预算状态
GET /api/usage/budget

# 设置或更新预算
POST /api/usage/budget
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "dailyLimitUsd": 5.00,
  "weeklyLimitUsd": 30.00,
  "monthlyLimitUsd": 100.00,
  "warningThreshold": 0.8,
  "resetInterval": "monthly"
}
```

> **Schema 说明**（`setBudgetSchema`）：`apiKeyId` 为必填；`dailyLimitUsd`、`weeklyLimitUsd` 或 `monthlyLimitUsd` 中至少有一个必须大于零。可选字段：`warningThreshold`（0–1）、`resetInterval`（`daily` | `weekly` | `monthly`）、`resetTime`（`HH:MM`）。旧版 `{keyId, limit, period}` 格式将返回 `400 Bad Request`。

## Token 限制

每个 API 密钥的 **token** 预算（不同于上面的美元预算）。在请求路径中直接执行：当密钥在当前窗口内的使用量达到限制时，请求将被拒绝并返回 `429 Too Many Requests`。限制可限定于特定 `model`、`provider`，也可在整个密钥范围内以 `global` 方式应用；当一个请求匹配多个限制时，以最严格的限制为准。

```bash
# 列出密钥的 token 限制（包括当前窗口的实时使用量）
GET /api/usage/token-limits?apiKeyId=key-123

# 创建或更新 token 限制
POST /api/usage/token-limits
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "scopeType": "model",
  "scopeValue": "openai/gpt-4o",
  "tokenLimit": 1000000,
  "resetInterval": "monthly",
  "enabled": true
}

# 按 id 删除 token 限制
DELETE /api/usage/token-limits?id=tl-abc
```

> **Schema 说明**（`setTokenLimitSchema`）：`apiKeyId` 和 `scopeType`（`model` | `provider` | `global`）为必填项。除非 `scopeType` 为 `global`，否则必须提供 `scopeValue`（例如，`model` 作用域使用模型 id，`provider` 作用域使用提供者 id）。`tokenLimit` 必须为正整数（可从字符串强制转换）。可选项：`id`（创建时省略，更新时提供）、`resetInterval`（`daily` | `weekly` | `monthly`，默认为 `monthly`）、`resetTime`（`HH:MM`）、`enabled`（默认为 `true`）。`GET` 响应会为每项限制补充 `tokensUsed`、`remaining`、`windowStart`、`periodStartAt` 和 `nextResetAt`。这是一个管理类端点（由 authz 流水线集中实施身份验证）。

## 请求处理

1. 客户端向 `/v1/*` 发送请求
2. 路由处理程序调用 `handleChat`、`handleEmbedding`、`handleAudioTranscription` 或 `handleImageGeneration`
3. 解析模型（直接指定提供者/模型，或使用别名/组合）
4. 从本地数据库中选择凭据，并根据账户可用性进行筛选
5. 对于聊天：`handleChatCore` 检查语义/签名缓存，并解析组合压缩设置
6. 启用后，在转换为提供者格式之前运行主动压缩（`lite`、Caveman、RTK 或堆叠模式）
7. 提供者执行器发送上游请求
8. 将响应转换回客户端格式（聊天），或按原样返回（嵌入/图像/音频）
9. 记录使用量、压缩分析数据和请求日志
10. 发生错误时，根据组合规则应用回退机制

完整架构参考：[`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## 组合管理

更高级别的路由组合（已在 `/api/combos*` 下进行概述）也可以从模型 id 模式进行 1:1 映射，从而将 OpenAI 风格的模型 id 透明地重定向到组合。

| 方法   | 路径                             | 说明                                                                       |
| ------ | -------------------------------- | -------------------------------------------------------------------------- |
| GET    | `/api/model-combo-mappings`      | 列出所有模型→组合映射                                                      |
| POST   | `/api/model-combo-mappings`      | 创建映射 — 请求体：`{pattern, comboId, priority?, enabled?, description?}` |
| GET    | `/api/model-combo-mappings/[id]` | 获取单个映射                                                               |
| PUT    | `/api/model-combo-mappings/[id]` | 更新现有映射的字段                                                         |
| DELETE | `/api/model-combo-mappings/[id]` | 删除映射                                                                   |

**身份验证：** 管理会话/API 密钥（`requireManagementAuth`）。

---

## Webhook

用于订阅 OmniRoute 事件（请求完成、配额耗尽、密钥轮换等）的出站 Webhook。

| 方法   | 路径                      | 描述                                                                  |
| ------ | ------------------------- | --------------------------------------------------------------------- |
| GET    | `/api/webhooks`           | 列出 Webhook（密钥将被掩码为 `<prefix>...`）                          |
| POST   | `/api/webhooks`           | 创建 Webhook — 请求体：`{url, events?: ["*"], secret?, description?}` |
| GET    | `/api/webhooks/[id]`      | 获取 Webhook                                                          |
| PUT    | `/api/webhooks/[id]`      | 更新 url/events/secret/description                                    |
| DELETE | `/api/webhooks/[id]`      | 删除 Webhook                                                          |
| POST   | `/api/webhooks/[id]/test` | 向 Webhook URL 发送测试负载并返回投递状态                             |

**身份验证：** 管理会话/API 密钥（`requireManagementAuth`）。

---

## 注册密钥（自动管理）

由自动密钥管理子系统使用，通过后端提供者/账户签发和轮换 API 密钥，并设置每日/每小时配额。

| 方法   | 路径                                  | 描述                                                                                                                                                                       |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/registered-keys`             | 列出已注册的密钥（仅显示经过掩码处理的前缀）                                                                                                                               |
| POST   | `/api/v1/registered-keys`             | 签发新的注册密钥 — 请求体：`{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`。原始密钥**仅返回一次**。因配额而被拒绝时返回 `429`。 |
| GET    | `/api/v1/registered-keys/[id]`        | 获取注册密钥的元数据（不包含原始密钥内容）                                                                                                                                 |
| DELETE | `/api/v1/registered-keys/[id]`        | 撤销注册密钥                                                                                                                                                               |
| POST   | `/api/v1/registered-keys/[id]/revoke` | 显式撤销端点（效果与 DELETE 相同）                                                                                                                                         |

**身份验证：**管理会话/API 密钥（`requireManagementAuth`）— 使用与 `/api/keys` 相同的守卫：仪表板会话、本地 CLI 令牌，或具有 `manage`/`admin` 作用域的 API 密钥；仅限推理的 API 密钥会收到 `403`。另请参阅 `/v1/quotas/check` 和 `/v1/issues/report`。

---

## 代理任务协议

代表 OmniRoute 用户远程执行的云端代理任务（Claude Code、Codex Cloud、OpenHands 等）。

| 方法   | 路径                          | 说明                                                                                                                             |
| ------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/agents/tasks`        | 列出任务 — 可选参数 `?provider=`、`?status=`、`?limit=`（1–500，默认值为 50）                                                    |
| POST   | `/api/v1/agents/tasks`        | 创建任务 — 请求体由 `CreateCloudAgentTaskSchema` 验证（`providerId`、`prompt`、`source`、`options?`）。返回 `201` 及任务封装对象 |
| DELETE | `/api/v1/agents/tasks?id=...` | 删除任务                                                                                                                         |
| GET    | `/api/v1/agents/tasks/[id]`   | 读取任务 — 设置 `external_id` 后，将同步从上游云端代理刷新状态                                                                   |
| POST   | `/api/v1/agents/tasks/[id]`   | 可区分的操作：`{action: "approve"}`、`{action: "message", message}` 或 `{action: "cancel"}`                                      |
| DELETE | `/api/v1/agents/tasks/[id]`   | 按 id 删除特定任务                                                                                                               |

> **身份验证：** 每种方法都需要管理身份验证（`requireCloudAgentManagementAuth`）。在 v3.8.0 之前，这些方法无需身份验证 — 有关这项破坏性变更，请参阅提交 `588a0333`。

```bash
# 创建 Claude Code 云端任务
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'
```

---

## 管理代理服务器

可分配给提供者、账户或全局使用的出站 HTTP(S)/SOCKS 代理服务器。

| 方法   | 路径                                         | 说明                                                                                                                   |
| ------ | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/management/proxies`                 | 列出代理服务器（使用 `?id=` 返回一个；使用 `?id=&where_used=1` 返回分配关系图）                                        |
| POST   | `/api/v1/management/proxies`                 | 创建代理服务器 — 请求体由 `createProxyRegistrySchema` 验证                                                             |
| PATCH  | `/api/v1/management/proxies`                 | 更新代理服务器 — 请求体由 `updateProxyRegistrySchema` 验证（需要 `id`）                                                |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | 删除代理服务器（使用 `force=1` 解除分配）                                                                              |
| GET    | `/api/v1/management/proxies/assignments`     | 列出分配 — 可按 `proxy_id`、`scope`、`scope_id` 筛选；传入 `resolve_connection_id=<id>` 可解析某个连接的活动代理服务器 |
| PUT    | `/api/v1/management/proxies/assignments`     | 分配 — 请求体由 `proxyAssignmentSchema` 验证（`{scope, scopeId?, proxyId?}`）。清除调度器缓存                          |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | 批量分配 — 请求体由 `bulkProxyAssignmentSchema` 验证（`{scope, scopeIds[], proxyId?}`）                                |
| GET    | `/api/v1/management/proxies/health?hours=24` | 汇总一个时间窗口内的代理服务器健康状况（成功/失败次数、延迟）                                                          |

**身份验证：** 每个路由都需要管理会话/API 密钥（`requireManagementAuth`）。

> 任务描述中的 `POST /api/v1/management/proxies/[id]/assignments` 和 `POST /api/v1/management/proxies/[id]/health` 由上面所示的扁平 `/assignments` 和 `/health` 路由提供服务 — 代码库中不存在按 id 划分的子路由。

---

## 弹性（扩展）

OmniRoute 提供三种相互独立的临时故障处理机制；以下管理端点允许运维人员读取和覆盖它们：

| 范围         | 状态存储                          | 读取                                      | 重置 / 清除                              |
| ------------ | --------------------------------- | ----------------------------------------- | ---------------------------------------- |
| 提供方熔断器 | `domain_circuit_breakers` + 内存  | `/api/monitoring/health`                  | `POST /api/resilience/reset`             |
| 连接冷却     | 提供方连接上的 `rateLimitedUntil` | `/api/rate-limits`、`/api/providers/[id]` | （惰性重新启用；通过提供方 PUT 清除）    |
| 模型锁定     | 内存中的模型可用性注册表          | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns` |

`PATCH /api/resilience` 接受位于 `providerBreaker.oauth` 和 `providerBreaker.apikey` 下的提供方熔断器覆盖配置。每个配置档都支持 `degradationThreshold`、`failureThreshold` 和 `resetTimeoutMs`；同样的字段也在 Dashboard → Settings → Resilience 中开放。

```bash
# 清除单个模型锁定
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o-mini"}'

# 清除所有锁定
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'
```

完整的概念参考和熔断器默认值：参见 [`CLAUDE.md`](../../CLAUDE.md) 中的 "Resilience Runtime State" 以及 [`docs/architecture/RESILIENCE_GUIDE.md`](../architecture/RESILIENCE_GUIDE.md)。

### 速率限制队列与自动启用安全网

- **受支持的写入路径**：`POST /api/rate-limits`，请求体为 `{"connectionId": "<id>", "enabled": true|false}`，这是用于切换连接速率限制保护的受支持管理端点。`PUT /api/providers/[id]` 特意不修改或翻转 `rateLimitProtection`（#11278）。
- **`enabled: false` 的语义**：设置 `enabled: false` 会移除该连接的显式保护，但**不会**使处于活动状态的 API 密钥连接脱离全局自动启用安全网（`autoEnableApiKeyProviders = true`）。在 `reconcileEnabledConnections`（`open-sse/services/rateLimitManager.ts`）中，`false` 和 `undefined` 是等效的；没有显式保护的活动 API 密钥连接仍会处于自动启用安全网的保护之下。
- **全局禁用**：若要让 API 密钥连接在不使用速率限制队列的情况下运行，请通过 `RATE_LIMIT_AUTO_ENABLE=false`（环境变量）或 `resilienceSettings.requestQueue.autoEnableApiKeyProviders = false`（Settings → Resilience / `PATCH /api/resilience`）全局禁用该安全网。

---

## 技能

用于通过自定义可执行处理程序扩展 OmniRoute 的技能框架，以及市场集成。

| 方法   | 路径                              | 描述                                                                                                        |
| ------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`                     | 列出已安装的技能 — 可按 `?q=`、`?mode=on\|off\|auto`、`?source=skillsmp\|skillssh\|local` 筛选，并支持分页  |
| GET    | `/api/skills/[id]`                | 获取单个技能                                                                                                |
| PUT    | `/api/skills/[id]`                | 更新技能（名称、描述、模式、schema、处理程序、标签）                                                        |
| DELETE | `/api/skills/[id]`                | 卸载技能                                                                                                    |
| POST   | `/api/skills/install`             | 从原始清单安装技能 — 请求体：`{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET    | `/api/skills/executions`          | 列出最近的技能执行记录（包含输入/输出/持续时间的审计追踪）                                                  |
| GET    | `/api/skills/marketplace?q=...`   | 从 SkillsMP 市场获取搜索结果/热门列表（需要 `skillsmpApiKey` 设置）                                         |
| POST   | `/api/skills/marketplace/install` | 按 id 从 SkillsMP 安装技能                                                                                  |
| GET    | `/api/skills/skillssh?q=&limit=`  | 搜索 skills.sh 注册表                                                                                       |
| POST   | `/api/skills/skillssh/install`    | 按 id 从 skills.sh 安装技能                                                                                 |

**身份验证：** 管理会话/API 密钥。市场搜索路由接受管理身份验证或 Bearer API 密钥（`isAuthenticated`）。

---

## 记忆

持久化的对话/事实记忆存储，作用域限定为每个 API 密钥/会话。

| 方法   | 路径                 | 描述                                                                                                     |
| ------ | -------------------- | -------------------------------------------------------------------------------------------------------- |
| GET    | `/api/memory`        | 列出记忆 — 支持 `?apiKeyId=`、`?type=`、`?sessionId=`、`?q=`，并使用 `offset/limit` 或 `page/limit` 分页 |
| POST   | `/api/memory`        | 创建记忆 — 请求体由 Zod 验证：`{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}`      |
| GET    | `/api/memory/[id]`   | 获取单条记忆                                                                                             |
| DELETE | `/api/memory/[id]`   | 删除记忆                                                                                                 |
| GET    | `/api/memory/health` | 记忆子系统健康状态（数据库连接、嵌入后端、向量索引状态）                                                 |

**身份验证：**管理会话/API 密钥（`requireManagementAuth`）。`type` 枚举：`FACTUAL`、`EPISODIC`、`SEMANTIC`、`PROCEDURAL`（请参阅 `src/lib/memory/types.ts` 中的 `MemoryType`）。

---

## MCP 服务器

OmniRoute 内置了一个模型上下文协议服务器，支持 3 种传输方式（stdio、SSE、streamable-http）和限定作用域的工具。以下仪表板端点用于读取状态/审计数据，并代理 HTTP 传输。

| 方法 | 路径 | 描述 |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | 心跳、传输方式、在线状态、最近调用、热门工具、24 小时成功率 |
| GET | `/api/mcp/tools` | MCP 工具列表，包含 `name`、`description`、`scopes`、`phase`、`auditLevel`、`sourceEndpoints` |
| GET | `/api/mcp/sse` | 为 SSE 传输打开 SSE 流（如果 MCP 已禁用或传输方式不匹配，则返回 `503`） |
| POST | `/api/mcp/sse` | 通过 SSE 传输发送 JSON-RPC 帧 |
| GET | `/api/mcp/stream` | 打开 Streamable HTTP 传输的 SSE 端（服务器发起的消息） |
| POST | `/api/mcp/stream` | 通过 Streamable HTTP 传输发送 JSON-RPC 帧 |
| DELETE | `/api/mcp/stream` | 结束 Streamable HTTP 会话 |
| GET | `/api/mcp/audit` | 查询审计日志 — `?limit=`、`?offset=`、`?tool=`、`?success=true                                | false`、`?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | 汇总审计统计信息（总数、成功率、平均持续时间、热门工具） |

**身份验证：**`sse`/`stream` 传输遵循 MCP 专用身份验证机制（具有 `mcp` 作用域的 Bearer API 密钥）；`status`/`tools`/`audit*` 路由可从仪表板读取（除了能够访问仪表板主机外，无需额外身份验证）。

> 两种 HTTP 传输均受 `settings.mcpEnabled` 和 `settings.mcpTransport` 控制 — 传输方式不匹配时返回 `400`，MCP 禁用时返回 `503`。

---

## A2A 服务器

OmniRoute 提供一个 A2A（代理到代理）JSON-RPC 2.0 端点，以及一个用于检查和仪表板的 REST 封装。

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # 可选，除非设置了 OMNIROUTE_API_KEY
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Route this coding task"}]
  }
}
```

支持的方法（均受 `settings.a2aEnabled` 控制）：

| 方法             | 描述                                             |
| ---------------- | ------------------------------------------------ |
| `message/send`   | 同步执行技能；返回 `{task, artifacts, metadata}` |
| `message/stream` | 通过 SSE 流式执行同一组技能                      |
| `tasks/get`      | 通过 `taskId` 获取任务                           |
| `tasks/cancel`   | 通过 `taskId` 取消任务                           |

内置技能：`smart-routing`、`quota-management`、`provider-discovery`、`cost-analysis`、`health-report`。

### 代理卡片

```bash
GET /.well-known/agent.json
```

返回公开的 A2A 代理卡片（名称、描述、能力、技能目录、身份验证方案）— 公开缓存 1 小时。无需身份验证。

### REST 辅助接口

| 方法 | 路径                         | 描述                                                                                                           |
| ---- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
| GET  | `/api/a2a/status`            | A2A 启用状态 + 任务统计信息 + 已缓存的代理卡片摘要                                                             |
| GET  | `/api/a2a/tasks`             | 列出任务 — `?state=submitted\|working\|completed\|failed\|cancelled`、`?skill=`、`?limit=`（≤200）、`?offset=` |
| POST | `/api/a2a/tasks`             | （未实现为 REST 辅助接口 — 请通过 JSON-RPC `message/send` 创建）                                               |
| GET  | `/api/a2a/tasks/[id]`        | 获取单个任务                                                                                                   |
| POST | `/api/a2a/tasks/[id]/cancel` | 取消任务                                                                                                       |

**身份验证：**REST 辅助接口无需管理身份验证即可运行（仪表板可读取）；如果已配置 Bearer `OMNIROUTE_API_KEY`，JSON-RPC `/a2a` 路由将使用它进行身份验证。

---

## 云端、评测与评估

| 方法 | 路径 | 描述 |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | 验证 Bearer 密钥，并返回供云同步客户端使用的已脱敏提供者连接和模型别名 |
| POST | `/api/cloud/credentials/update` | 更新云同步提供者的加密凭据 |
| POST | `/api/cloud/model/resolve` | 使用本地路由表将逻辑模型 ID 解析为具体的提供者/模型 |
| GET | `/api/cloud/models/alias` | 列出向云同步公开的模型别名 |
| GET | `/api/assess` | 读取最新的评估分类结果（按提供者/模型） |
| POST | `/api/assess` | 运行评估 — 请求体：`{scope: {type:"all"}                                                   | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | 列出内置评测套件及其最近一次运行 |
| POST | `/api/evals` | 触发评测运行 |
| POST | `/api/evals/suites` | 创建自定义评测套件 — 请求体由 `evalSuiteSaveSchema` 验证 |
| GET | `/api/evals/suites/[id]` | 获取自定义评测套件 |

**认证：** `/api/cloud/auth` 直接验证 Bearer 密钥；仅当密钥具有 `manage` / `admin` 作用域时，才返回每个连接的已脱敏密钥和 `projectId`；其他 `/api/cloud/*`、`/api/evals/*` 和 `/api/assess` 路由需要管理会话/API 密钥。`/api/assess` 的 POST 请求使用 `validateBody` 和带判别字段的联合作用域模式。

---

## ACP（Agent Client Protocol）管理

作为子进程运行。这些端点用于管理 ACP 智能体检测和自定义智能体注册。

| 方法   | 路径              | 描述                                                                                                                                       |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/acp/agents` | 列出所有已知的 CLI 智能体（内置 + 自定义），包括安装状态、版本和二进制文件                                                                 |
| POST   | `/api/acp/agents` | 注册自定义 ACP 智能体或刷新缓存——请求体：`{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` 或 `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | 移除自定义 ACP 智能体——查询参数：`?id=<agentId>`                                                                                           |

**响应示例**（`GET /api/acp/agents`）：

```json
{
  "agents": [
    {
      "id": "claude",
      "name": "Claude Code CLI",
      "binary": "claude",
      "version": "1.0.45",
      "installed": true,
      "protocol": "stdio",
      "providerAlias": "claude",
      "isCustom": false
    },
    {
      "id": "my-custom-cli",
      "name": "My Custom CLI",
      "installed": false,
      "protocol": "stdio",
      "providerAlias": "my-provider",
      "isCustom": true
    }
  ],
  "cacheTtlMs": 60000,
  "cacheAge": 1234
}
```

**身份验证：** 需要管理会话（仪表板 `auth_token` Cookie）或具有管理作用域的 API 密钥。

完整详情请参阅 [ACP 框架](../frameworks/ACP.md)。

---

## 分析与可观测性

用于监控路由、压缩和提供者多样性的实时分析端点。这些端点为 `/dashboard/analytics/*` 页面提供支持。

### 自动路由分析

| 方法 | 路径                                 | 描述                                                           |
| ---- | ------------------------------------ | -------------------------------------------------------------- |
| GET  | `/api/analytics/auto-routing`        | 汇总自动路由统计信息：调用总数、策略分布、层级分布、热门提供者 |
| GET  | `/api/analytics/auto-routing?days=7` | 指定时间窗口的统计信息（默认 24 小时）                         |

**响应示例**：

```json
{
  "window": "24h",
  "totalCalls": 1234,
  "strategyBreakdown": {
    "rules": 800,
    "cost": 200,
    "latency": 150,
    "sla-aware": 50,
    "lkgp": 34
  },
  "tierBreakdown": {
    "ultra": 100,
    "pro": 500,
    "standard": 400,
    "free": 234
  },
  "topProviders": [
    { "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
    { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
  ]
}
```

### 压缩分析

| 方法 | 路径                         | 描述                                                               |
| ---- | ---------------------------- | ------------------------------------------------------------------ |
| GET  | `/api/analytics/compression` | 汇总压缩统计信息：节省的令牌数、节省百分比、模式分布、引擎使用情况 |

**响应示例**：

```json
{
  "window": "24h",
  "totalOriginalTokens": 5000000,
  "totalCompressedTokens": 3500000,
  "totalSavings": 1500000,
  "savingsPct": 30.0,
  "modeBreakdown": {
    "lite": 400,
    "standard": 600,
    "aggressive": 100,
    "ultra": 50,
    "rtk": 84
  },
  "engineBreakdown": {
    "caveman": 800,
    "rtk": 434
  }
}
```

### 提供者多样性跟踪

| 方法 | 路径                       | 描述                                                         |
| ---- | -------------------------- | ------------------------------------------------------------ |
| GET  | `/api/analytics/diversity` | 基于香农熵的多样性跟踪：通过衡量提供者分布情况来避免单点故障 |

**响应示例**：

```json
{
  "window": "24h",
  "shannonEntropy": 2.45,
  "maxEntropy": 3.17,
  "diversityRatio": 0.77,
  "providerUsage": {
    "openai": 0.4,
    "anthropic": 0.25,
    "google": 0.2,
    "kiro": 0.15
  },
  "warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"]
}
```

**身份验证：** 需要管理会话或具有管理作用域的 API 密钥。

---

## 管理员操作

仅限管理员使用的运维管理端点。

| 方法 | 路径                     | 描述                                                                             |
| ---- | ------------------------ | -------------------------------------------------------------------------------- |
| GET  | `/api/admin/concurrency` | 读取当前并发限制（全局及各提供者）                                               |
| POST | `/api/admin/concurrency` | 更新并发限制 — 请求体：`{global?: number, perProvider?: Record<string, number>}` |

**身份验证：** 需要具有管理员权限范围的管理会话。

---

## CLI 工具管理

管理与 OmniRoute 集成的 CLI 工具（antigravity、commandCode、
devin-cli 等）。完整列表请参阅[提供者参考](./PROVIDER_REFERENCE.md)。

| 方法 | 路径                                    | 描述                                                                                                                        |
| ---- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| GET  | `/api/cli-tools/all-statuses`           | 所有 CLI 工具的状态（是否已安装、版本、最后一次出现时间）                                                                   |
| GET  | `/api/cli-tools/status`                 | 单个 CLI 工具的详细状态（使用 `?tool=` 查询参数）                                                                           |
| POST | `/api/cli-tools/apply`                  | 写入工具生成的配置（`dryRun` 用于预览；容器化时返回 `422` + `containerEphemeralTarget`；`migration` 会注明旧版 Codex YAML） |
| GET  | `/api/cli-tools/backups`                | 列出 CLI 工具配置备份                                                                                                       |
| POST | `/api/cli-tools/backups`                | 创建所有 CLI 工具配置的备份                                                                                                 |
| POST | `/api/cli-tools/backups`                | 恢复：在请求体中包含 `{tool, backupId}`，通过同一端点恢复该备份                                                             |
| GET  | `/api/cli-tools/antigravity-mitm`       | Antigravity MITM 代理状态（“antigravity-mitm” CLI 工具）                                                                    |
| POST | `/api/cli-tools/antigravity-mitm/alias` | 配置 antigravity-mitm 别名                                                                                                  |

**身份验证：** 需要管理会话。

---

## Agent 技能

管理 AI Agent 技能（类似于 OpenAI 的自定义 GPT，但面向 Agent）。

| 方法   | 路径                         | 描述                                                                                |
| ------ | ---------------------------- | ----------------------------------------------------------------------------------- |
| GET    | `/api/agent-skills`          | 列出所有 Agent 技能（内置及自定义）                                                 |
| GET    | `/api/agent-skills/[id]`     | 获取特定 Agent 技能                                                                 |
| POST   | `/api/agent-skills`          | 创建自定义 Agent 技能 — 请求体：`{name, description, prompt, model?, temperature?}` |
| PUT    | `/api/agent-skills/[id]`     | 更新自定义 Agent 技能                                                               |
| DELETE | `/api/agent-skills/[id]`     | 删除自定义 Agent 技能                                                               |
| GET    | `/api/agent-skills/[id]/raw` | 获取原始提示词及元数据（不执行）                                                    |
| POST   | `/api/agent-skills/generate` | 根据自然语言描述使用 AI 生成新技能                                                  |

**身份验证：** 需要管理会话或具有管理权限范围的 API 密钥。

---

## 缓存管理

管理语义缓存和推理缓存。

| 方法   | 路径                   | 描述                                                                                     |
| ------ | ---------------------- | ---------------------------------------------------------------------------------------- |
| GET    | `/api/cache`           | 缓存概览：条目总数、命中率、磁盘占用空间                                                 |
| GET    | `/api/cache/entries`   | 列出缓存条目（支持分页）                                                                 |
| DELETE | `/api/cache/entries`   | 删除缓存条目（按查询参数筛选）                                                           |
| GET    | `/api/cache/stats`     | 详细的缓存统计信息（按提供者、按模型）                                                   |
| GET    | `/api/cache/reasoning` | 推理缓存状态（用于推理重放）                                                             |
| DELETE | `/api/cache/reasoning` | 清除推理缓存 — 查询参数：`?toolCallId=<id>`（单个）、`?provider=<p>`，或不带参数（全部） |

**身份验证：** 需要管理会话。

---

## 记忆系统

管理持久化记忆（FTS5 + 向量嵌入）。

| 方法   | 路径               | 描述                                                           |
| ------ | ------------------ | -------------------------------------------------------------- |
| GET    | `/api/memory`      | 列出记忆条目（按作用域、类型、搜索查询筛选）                   |
| POST   | `/api/memory`      | 创建新的记忆条目 — 请求体：`{scope, type, content, metadata?}` |
| GET    | `/api/memory/[id]` | 获取特定的记忆条目                                             |
| PUT    | `/api/memory/[id]` | 更新记忆条目                                                   |
| DELETE | `/api/memory/[id]` | 删除记忆条目                                                   |
| GET    | `/api/memory?q=`   | 搜索记忆（FTS5 + 向量）— 同一响应中包含统计信息                |

**身份验证：** 需要管理会话或管理作用域的 API 密钥。

---

## Webhook

管理事件的 Webhook 订阅。

| 方法   | 路径                            | 描述                                                            |
| ------ | ------------------------------- | --------------------------------------------------------------- |
| GET    | `/api/webhooks`                 | 列出所有 Webhook 订阅                                           |
| POST   | `/api/webhooks`                 | 创建 Webhook 订阅 — 请求体：`{url, events[], secret?, active?}` |
| GET    | `/api/webhooks/[id]`            | 获取特定的 Webhook 订阅                                         |
| PUT    | `/api/webhooks/[id]`            | 更新 Webhook 订阅                                               |
| DELETE | `/api/webhooks/[id]`            | 删除 Webhook 订阅                                               |
| GET    | `/api/webhooks/[id]/deliveries` | 列出 Webhook 的投递历史记录（成功/失败日志）                    |
| POST   | `/api/webhooks/[id]/test`       | 向 Webhook 发送测试事件                                         |

**身份验证：** 需要管理会话。

有关完整的事件类型，请参阅 [Webhook 框架](../frameworks/WEBHOOKS.md)。

---

## Skills 框架

管理 Skills（智能体扩展框架）。

| 方法   | 路径                     | 描述                                                                             |
| ------ | ------------------------ | -------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | 列出所有已安装的 Skills（内置 + 自定义）                                         |
| POST   | `/api/skills/install`    | 从本地路径或 URL 安装 Skill                                                      |
| DELETE | `/api/skills/[id]`       | 卸载 Skill                                                                       |
| PUT    | `/api/skills/[id]`       | 启用或禁用 Skill — 请求体：`{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST   | `/api/skills/executions` | 执行 Skill — 请求体：`{skillName, apiKeyId, input?, sessionId?}`                 |
| GET    | `/api/skills/executions` | 列出所有 Skills 的执行历史记录（使用 `?apiKeyId=` 进行筛选）                     |

**身份验证：** 需要管理会话或具有管理作用域的 API 密钥。

完整详情请参阅 [Skills 框架](../frameworks/SKILLS.md)。

---

## 插件

管理 OmniRoute 插件（第三方扩展）。

| 方法   | 路径                               | 描述               |
| ------ | ---------------------------------- | ------------------ |
| GET    | `/api/plugins`                     | 列出已安装的插件   |
| POST   | `/api/plugins/marketplace/install` | 从插件市场安装插件 |
| DELETE | `/api/plugins/[name]`              | 卸载插件           |
| POST   | `/api/plugins/[name]/activate`     | 激活插件           |
| POST   | `/api/plugins/[name]/deactivate`   | 停用插件           |
| GET    | `/api/plugins/[name]/config`       | 获取插件配置       |
| PUT    | `/api/plugins/[name]/config`       | 更新插件配置       |

**身份验证：** 需要管理会话。

完整详情请参阅 [插件框架](../frameworks/PLUGIN_SDK.md)。

---

## 影子路由

提供者的影子 / A-B 对比**并非独立的 REST 接口** — 它通过组合路由进行配置（请参阅 [自动组合](../routing/AUTO-COMBO.md)）。每个组合的对比指标由 `GET /api/combos/metrics` 提供。

---

## 防护机制

检查运行时防护机制（PII 检测、提示词注入检测、视觉桥接）。防护机制会针对每个请求运行；可通过 `x-omniroute-disabled-guardrails` 请求标头针对单次调用选择退出 — 不提供持久化的启用/禁用接口。

| 方法 | 路径                   | 描述                                                                  |
| ---- | ---------------------- | --------------------------------------------------------------------- |
| GET  | `/api/guardrails`      | 列出已注册的防护机制及其状态（名称 / 是否启用 / 优先级）              |
| POST | `/api/guardrails/test` | 使用示例输入试运行调用前管道 — 请求体：`{input, disabledGuardrails?}` |

**身份验证：** 需要管理会话。

完整详情请参阅 [安全性 > 防护机制](../security/GUARDRAILS.md)。

---

---

## 身份验证

有关四类凭据（仪表板会话、本地 CLI 令牌、`oma_live_…` 访问令牌、管理范围 API 密钥）及其与推理密钥的区别，请参阅[管理身份验证](../guides/MANAGEMENT-AUTH.md)。

- 仪表板路由（`/dashboard/*`）使用 `auth_token` Cookie
- 登录使用已保存的密码哈希；若无则回退使用 `INITIAL_PASSWORD`
- `requireLogin` 可通过 `/api/settings/require-login` 切换
- 当 `REQUIRE_API_KEY=true` 时，`/v1/*` 路由可要求提供 Bearer API 密钥
- 本参考文档中的“管理令牌”/“管理范围 API 密钥”是指该指南中所述的某一类凭据，而不是未定义的其他密钥类型

> **破坏性变更（v3.8.0）** — `/api/v1/agents/tasks/*` 和冷却时间管理端点现在需要**管理身份验证**（仪表板 `auth_token` Cookie 或管理范围 API 密钥）。此前未进行身份验证就调用这些路由的客户端将收到 `401 Unauthorized`。请参阅提交 `588a0333`（`fix(auth): require management auth for agent and cooldown APIs`）。