OmniRoute/docs/i18n/zh-CN/docs/reference/API_REFERENCE.md

API Reference (中文 (简体))

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

---

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

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

---

目录

• 聊天补全
• 独占式托管会话租约
• 嵌入
• 图像生成
• 文档 OCR
• 列出模型
• 提供者插件清单
• 兼容性端点
• 文件 API
• 批处理 API
• 搜索 API
• WebSocket 流式传输
• 配额与问题报告
• 语义缓存
• 仪表板与管理
• 组合管理
• Webhook
• 已注册密钥（自动管理）
• 智能体协议
• 管理代理
• 弹性机制（扩展）
• 技能
• 记忆
• MCP 服务器
• A2A 服务器
• 云、评测与评估
• 请求处理
• 身份验证

---

聊天补全

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 列表。在创建密钥和进行部分更新时，数据库变更边界会同时强制要求这两个字段。

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：

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

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

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

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

{
  "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 绝不会用电子邮件地址或生成的账户身份替代它。provider 值是非敏感的显示标签，绝不会是生成的兼容提供者标识符。凭据、令牌、Cookie、原始连接或 API 密钥 ID、所有者哈希、隔离密钥以及内部路由数据均被排除。

使用错误密钥、错误所有者、过期 generation，以及查询缺失、已过期、已释放或已失效的租约时，均返回相同的 409 LEASE_FENCE_STALE 错误，且不包含连接元数据。收到容量等待响应的客户端没有可供检查的活动绑定。当路由切换活动租约时，同一 generation 仍然有效，并且状态操作会以原子方式返回新绑定，而绝不会返回旧绑定。现有客户端保持不变，因为获取、续租、释放和等待响应仍保留之前的结构。

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

之后，每个托管推理请求都需要提供以下两个控制标头：

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

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

临时争用会返回带有 Retry-After 的 HTTP 429，以及：

{
  "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	使用由面板派生的默认配置文件（忽略活动配置文件）。
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 之一。

---

嵌入

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：

{
  "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。

{
  "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，而不是强制转换项目。对于旧版字符串/令牌请求，非输入扩展字段仍会按原样传递。

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

---

图像生成

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（本地）。

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

---

文档 OCR

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 格式响应：

{
  "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 之前使用。

---

列出模型

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

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

模型 id 前缀（?prefix=）

大多数模型都使用提供者前缀发布。具体使用哪个前缀由 MODELS_CATALOG_PREFIX_MODE 功能标志控制，并且可以通过查询参数按请求覆盖——这对于希望获得简洁列表，同时又不更改面向其他所有用户的服务器全局设置的客户端很有用：

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 扩展就是这样做的。

无思考模型变体

对于支持思考的 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 为每个模型强制启用或禁用该变体。

---

提供者插件清单

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（STT）
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/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}/... 端点。

# 重排序
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" }

# 图像编辑（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": "suno/v3.5",   "prompt": "..." }

专用提供者路由

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 流式传输

GET /v1/ws?handshake=1

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

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

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

# 与 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，以免修改 现有配置）：

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）

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 面板）用来向密钥持有者显示其支出的端点。

# 文本形式（历史约定——用于终端的纯文本）
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 返回可辨识的结构，确保调用方不会从拒绝响应中读取数据字段。成功时：

{
  "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 保护。

---

语义缓存

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

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

响应示例：

{
  "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]）时设置：

{ "cacheDefaultMode": "bypass" }

按请求绕过缓存

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

X-OmniRoute-No-Cache: true

---

仪表盘与管理

管理路由（除公共身份验证/登录之外的 /api/*）不能使用普通推理 API 密钥进行授权。有关凭据类型、权限范围和 curl 示例，请参阅： 管理身份验证。

身份验证

端点	方法	描述
/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。
/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。
/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）。有关提供者断路器、连接冷却与模型锁定的完整说明，请参阅弹性（扩展）。

评估

端点	方法	描述
/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+)

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

{
  "provider": "claude-code"
}

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

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

---

音频转录

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

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

请求：

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

响应：

{
  "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 格式的客户端：

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

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

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

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

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

# 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

示例：

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 外部的遥测数据中。应将其视为一种兼容性选项，而不是默认身份验证方式。

---

遥测

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

响应：

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

---

预算

# 获取所有 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"
}

架构说明（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 方式应用；当一个请求匹配多个限制时，以最严格的限制为准。

# 列出密钥的 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

---

组合管理

更高级别的路由组合（已在 /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。

# 创建 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；相同字段也可在控制面板 → 设置 → 弹性机制中配置。

# 清除单个模型锁定
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 →“弹性机制运行时状态”。

---

技能

用于通过自定义可执行处理程序扩展 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

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。

代理卡片

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）：

{
  "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 框架。

---

分析与可观测性

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

自动路由分析

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

响应示例：

{
  "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	汇总压缩统计信息：节省的令牌数、节省百分比、模式分布、引擎使用情况

响应示例：

{
  "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	基于香农熵的多样性跟踪：通过衡量提供者分布情况来避免单点故障

响应示例：

{
  "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 等）。完整列表请参阅提供者参考。

方法	路径	描述
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 框架。

---

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 框架。

---

插件

管理 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	更新插件配置

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

完整详情请参阅 插件框架。

---

影子路由

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

---

防护机制

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

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

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

完整详情请参阅 安全性 > 防护机制。

---

---

身份验证

有关四类凭据（仪表板会话、本地 CLI 令牌、oma_live_… 访问令牌、管理范围 API 密钥）及其与推理密钥的区别，请参阅管理身份验证。

• 仪表板路由（/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）。