API Reference (中文 (简体))

聊天补全
独占式托管会话租约
嵌入
图像生成
文档 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 &lt;managed-api-key&gt;
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 绝不会替换电子邮件或生成的账户身份。提供者值是一个非敏感的显示标签，绝不是生成的兼容提供者标识符。凭据、令牌、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`	面板派生的默认配置文件（忽略活跃配置文件）。有损引擎保持关闭。
`safe`	仅进行去重和空白折叠。
`allow-lossy`	保留此请求的操作员计划，包括摘要和样式重写。
`engine:<id>`	启用时为单个引擎，例如 `engine:rtk`。此引擎的每个请求选择性加入。
`<combo>`	命名组合，首先按名称（不区分大小写）匹配，然后按 ID 匹配。

注意：

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

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

X-OmniRoute-Compression: &lt;mode&gt;; 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/&lt;provider&gt;/&lt;model&gt;

选择此 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 响应
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 密钥。

# 重排序（云注册表提供者，或 OpenAI 兼容的提供者节点，格式为 "&lt;prefix&gt;/&lt;model&gt;"）
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 仍然具有优先权。

专用提供者路由

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 &lt;your-api-key&gt;" \
  http://localhost:20128/api/usage/om-usage

# 结构化形式——供 UI 使用
curl -H "Authorization: Bearer &lt;your-api-key&gt;" \
  "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"
}

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

# 列出密钥的 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 流水线集中实施身份验证）。

请求处理

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

完整架构参考：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 传输。

身份验证：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）。

OmniRoute 源码 (a58000c7685f)

HagiCode

HagiCode 是一套智能体编码工作台：结构化工作流、多 Agent 并行执行与 Hero Dungeon 视图，把想法变成真正交付的软件。

让想法更快变成好用的软件，让智能编码更聪明、更高效，也更有趣。

Smart结构化工作流将意图转化为从想法到交付的可执行路径。
Efficient多 Agent 工作流让调研、实现与审阅并行推进。
FunHero Dungeon 让长时间编码协作更直观、更有参与感。

访问 HagiCode

API Reference (中文 (简体))

目录

聊天补全

自定义标头

独占式托管会话租约

x-omniroute-compression

嵌入

图像生成

文档 OCR

Azure Document Intelligence 轮询流程

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

列出模型

模型 id 前缀（?prefix=）

无思考模型变体

提供者插件清单

兼容性端点

专用提供者路由

Files API

Batches API

搜索 API

网页抓取 API

WebSocket 流式传输

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

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

配置 OpenAI Codex CLI

配额与问题报告

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

语义缓存

延迟影响

按密钥绕过缓存

按请求绕过缓存

仪表盘与管理

身份验证

提供者管理

OAuth 流程

路由与配置

使用情况与分析

设置

上下文与压缩

监控

备份与导出/导入

云同步

隧道

CLI 工具

ACP 代理

弹性与速率限制

评估

策略

合规性

v1beta（兼容 Gemini）

内部/系统 API

OAuth 环境修复 (v3.6.1+)

音频转录

Ollama 兼容性

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

遥测

预算

Token 限制

请求处理

组合管理

Webhook

已注册的密钥（自动管理）

代理任务协议

管理代理服务器

弹性机制（扩展）

技能

记忆

MCP 服务器

A2A 服务器

JSON-RPC

代理卡片

REST 辅助接口

云、评估与测评

ACP（Agent Client Protocol）管理

分析与可观测性

自动路由分析

压缩分析

提供者多样性跟踪

管理员操作

CLI 工具管理

`x-omniroute-compression`

模型 id 前缀（`?prefix=`）

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

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