# 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)

---

🌐 **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)

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

---

## 目录

- [聊天补全](#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)

---

## 聊天补全

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Write a function to..."}
  ],
  "stream": true
}
```

### 自定义标头

| 标头                     | 方向 | 说明                                                                                                                                             |
| ------------------------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-OmniRoute-No-Cache`   | 请求 | 设置为 `true` 以绕过缓存                                                                                                                         |
| `x-omniroute-no-memory`  | 请求 | 设置为 `true` 以跳过此请求的记忆和技能注入（与无缓存行为一致；可避免每次调用产生的令牌/成本开销）                                                |
| `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-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;`。

> **成本遥测标头：**非流式成功响应还会携带 `X-OmniRoute-*` 成本遥测标头集——`X-OmniRoute-Response-Cost`（USD，固定 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`）。
- 没有显式模态元数据的未知/动态模型会拒绝结构化输入，并返回 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**、SD WebUI（本地）、ComfyUI（本地）。

```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)就是这样做的。

### 无思考模型变体

对于支持思考的 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 响应                     |
| POST | `/v1/embeddings`                          | OpenAI                          |
| POST | `/v1/images/generations`                  | OpenAI 图像                     |
| POST | `/v1/images/edits`                        | OpenAI 图像 (编辑/修复)         |
| POST | `/v1/videos/generations`                  | OpenAI 风格的视频生成           |
| POST | `/v1/music/generations`                   | OpenAI 风格的音乐生成           |
| POST | `/v1/audio/transcriptions`                | OpenAI 音频 (语音转文本)        |
| 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 内容审核                 |
| GET  | `/v1/models`                              | OpenAI                          |
| 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 响应令牌化别名           |
| 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 也支持通过查询字符串兼容性（`?token=...`、`?apiKey=...`、`?api_key=...`、`?key=...`）或通过下方文档中列出的专用 `/api/v1/vscode/{token}/...` 端点在 URL 中接受 API 密钥。

```bash
# 重排序（云注册表提供者，或 OpenAI 兼容的提供者节点，格式为 "<prefix>/<model>"）
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" }

# 图像编辑 (多部分)
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`) 始终符合条件。任何其他主机上的节点（局域网设备或 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` 强制执行搜索策略。

---

## 网页抓取 API

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

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

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

**配额感知回退（#8297）：** 未明确指定 `provider` 时，将按固定
优先级顺序遍历提供者池
（`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-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,
  // 仅当密钥启用了按密钥计算的用量限制（每日/每周 USD）时才存在：
  "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` 保护。

---

## 语义缓存

```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/*`）**不能**使用普通推理 API 密钥进行授权。有关凭据类型、权限范围和 curl 示例，请参阅：
[管理身份验证](../guides/MANAGEMENT-AUTH.md)。

### 身份验证

| 端点                          | 方法    | 描述             |
| ----------------------------- | ------- | ---------------- |
| `/api/auth/login`             | POST    | 登录             |
| `/api/auth/logout`            | POST    | 退出登录         |
| `/api/settings/require-login` | GET/PUT | 切换是否要求登录 |

### 提供者管理

| 端点                         | 方法                  | 描述                                                                        |
| ---------------------------- | --------------------- | --------------------------------------------------------------------------- |
| `/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/PATCH/DELETE | 自定义模型（添加、更新、隐藏/显示、删除）                                   |

### OAuth 流程

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

### 路由与配置

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

### 使用情况与分析

| Endpoint                         | 方法            | 描述                                                                                                                                                                                                                                                       |
| -------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/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 密钥的令牌限额预算                                                                                                                                                                                                                                |
| `/api/usage/model-latency-stats` | GET             | 按提供者/模型滚动统计的延迟汇总（平均值/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) |

### 设置

| Endpoint                              | 方法          | 描述                                                                                                                                    |
| ------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings`                       | GET/PUT/PATCH | 常规设置                                                                                                                                |
| `/api/settings/proxy`                 | GET/PUT       | 网络代理配置                                                                                                                            |
| `/api/settings/proxy/test`            | POST          | 测试代理连接                                                                                                                            |
| `/api/settings/ip-filter`             | GET/PUT       | IP 允许列表/阻止列表                                                                                                                    |
| `/api/settings/thinking-budget`       | GET/PUT       | 思考/推理**请求**重写模式（透传 / 自动移除 / 自定义 / 自适应）。与压缩无关。请参阅 [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           | 预览关闭/轻量/标准/激进/超强/RTK/堆叠压缩    |
| `/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 可用性及版本信息（不存储）                                                                                                                                                                                                                                                      |
| `/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/export`    | GET  | 将数据库下载为 .sqlite 文件       |
| `/api/db-backups/import`    | POST | 上传 .sqlite 文件以替换数据库     |
| `/api/db-backups/exportAll` | GET  | 将完整备份下载为 .tar.gz 归档文件 |

### 云同步

| 端点                   | 方法 | 描述       |
| ---------------------- | ---- | ---------- |
| `/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       | 每个账户的速率限制状态                                                        |
| `/api/rate-limit`                 | GET       | 全局速率限制配置                                                              |

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

### 评估

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

### 策略

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

### 合规性

| 端点                        | 方法 | 描述                      |
| --------------------------- | ---- | ------------------------- |
| `/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 提供者的环境变量                      |

> **注意：** 这些端点由系统内部使用，或用于兼容 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
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 相同）                                                                                                                                     |

**身份验证：** Bearer API 密钥（`isAuthenticated`）。另请参阅 `/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`；相同字段也可在控制面板 → 设置 → 弹性机制中配置。

```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) →“弹性机制运行时状态”。

---

## 技能

用于通过自定义可执行处理程序扩展 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 密钥；其他 `/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`）。