API Reference (中文 (繁體))

聊天補全
獨佔式受管工作階段租約
嵌入
圖片生成
文件 OCR
列出模型
提供者外掛程式資訊清單
相容性端點
Files API
Batches API
Search 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 金鑰以及資料庫交易中確切的活躍世代進行圍欄。displayName 僅是修剪過的配置連線名稱；當沒有安全的配置名稱時，它為 null。OmniRoute 絕不會替換電子郵件或生成的帳戶身份。提供者值是一個非敏感的顯示標籤，絕不是生成的相容提供者識別碼。憑證、令牌、cookie、原始連線或 API 金鑰 ID、所有者雜湊、圍欄密鑰和內部路由資料均被排除。

錯誤金鑰、錯誤所有者、過時世代、遺失、過期、已釋放和已失效的查詢都會返回相同的 409 LEASE_FENCE_STALE 錯誤，且不帶連線元資料。收到容量等待回應的客戶端沒有可檢查的活躍綁定。當路由轉換活躍租賃時，相同的世代仍然有效，並且狀態會原子性地返回新的綁定，而不是舊的。現有客戶端保持不變，因為取得、續約、釋放和等待回應保留了其先前的形狀。

此伺服器合約不會改變標準 OpenAI Codex /status。標準 Codex 目前報告其模型提供者和內建的身份驗證/帳戶狀態，但不會呈現任意自訂提供者帳戶元資料；後續的客戶端整合必須呼叫此操作並決定如何顯示 connection.displayName。

每個託管推斷請求隨後都會提供兩個控制標頭：

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

確切的所有者、世代、活躍連線和經過身份驗證的 API 金鑰在每次支援的上游嘗試之前都會立即進行圍欄。即使另一個金鑰允許相同的連線，使用該金鑰重播所有者和世代也會失敗。原始所有者不會被持久化、記錄、保留在請求快照中或轉發到上游。

暫時性爭用會返回帶有 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 金鑰。

# 重新排序 (雲端註冊服務提供者，或作為 "&lt;prefix&gt;/&lt;model&gt;" 的 OpenAI 相容提供者節點)
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina 分類 (基礎 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 強制執行。

Web 擷取 API

透過已設定的 Web 擷取提供者（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 一律適用；402/403 則適用於 Firecrawl／Tavily／TinyFish 的配額型免費方案 — 不適用於 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 Proxy 僅連接至 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：使用純 ChatGPT ID（不加 `codex/` 前綴）

當 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 CLI 指向 OmniRoute，請在 ~/.codex/config.toml 中新增一個支援 WebSocket 的自訂提供者（請使用個別的 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	模型定價

使用情況與分析

端點	方法	說明
`/api/usage/history`	GET	使用量歷史記錄
`/api/usage/logs`	GET	使用量日誌
`/api/usage/request-logs`	GET	請求層級日誌
`/api/usage/[connectionId]`	GET	各連線的使用量
`/api/usage/token-limits`	GET/POST/DELETE	各 API 金鑰的 token 限額預算
`/api/usage/model-latency-stats`	GET	各提供者／模型的滾動延遲彙總（avg/p50/p95/p99、成功率）；篩選條件：`windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)
`/api/usage/cache-health`	GET	`call_logs` 的提示詞快取健康狀態摘要——寫入／讀取比率、p50/p90/p99 寫入大小分布、大量寫入集中度、各模型拆分，以及 `healthy`/`degraded`/`thrash`/`no-data` 判定；查詢參數為 `range`（`1h`\|`24h`\|`7d`\|`30d`，預設為 `24h`）及選用的 `model` (#8827)

設定

端點	方法	說明
`/api/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 預算（不同於上方以 USD 為基礎的預算）。在請求路徑中即時強制執行：當金鑰在目前時間窗口內的使用量達到限制時，請求會以 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

結構描述備註（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]`	更新技能（名稱、說明、模式、結構描述、處理常式、標籤）
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 隨附內嵌的 Model Context Protocol 伺服器，提供 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（代理程式用戶端協定）管理

作為子程序。這些端點用於管理 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 別名

驗證： 需要管理工作階段。

代理技能

管理 AI 代理技能（類似 OpenAI 的自訂 GPT，但用於代理）。

方法	路徑	說明
GET	`/api/agent-skills`	列出所有代理技能（內建及自訂）
GET	`/api/agent-skills/[id]`	取得特定代理技能
POST	`/api/agent-skills`	建立自訂代理技能 — 請求主體：`{name, description, prompt, model?, temperature?}`
PUT	`/api/agent-skills/[id]`	更新自訂代理技能
DELETE	`/api/agent-skills/[id]`	刪除自訂代理技能
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 框架。

技能框架

管理技能（代理式擴充功能框架）。

方法	路徑	說明
GET	`/api/skills`	列出所有已安裝的技能（內建 + 自訂）
POST	`/api/skills/install`	從本機路徑或 URL 安裝技能
DELETE	`/api/skills/[id]`	解除安裝技能
PUT	`/api/skills/[id]`	啟用或停用技能 — 主體：`{enabled?: boolean, mode?: "on" \| "off" \| "auto"}`
POST	`/api/skills/executions`	執行技能 — 主體：`{skillName, apiKeyId, input?, sessionId?}`
GET	`/api/skills/executions`	列出所有技能的執行記錄（可依 `?apiKeyId=` 篩選）

驗證： 需要管理工作階段或具管理範圍的 API 金鑰。

完整詳細資訊請參閱技能框架。

外掛程式

管理 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 是智慧代理程式開發工作台，結合結構化工作流程、多代理程式執行與 Hero Dungeon 介面，將想法化為交付成果。

以更聰明、更快速且更有趣的智慧代理程式工作流程，打造實用的軟體。

Smart結構化流程將意圖轉化為從構想到交付的可執行步驟。
Efficient多代理程式工作流程讓研究、實作與審查並行進行。
FunHero Dungeon 讓長時間的程式協作更直覺、更有參與感。

造訪 HagiCode

API Reference (中文 (繁體))

目錄

聊天補全

自訂標頭

獨佔式託管會話租賃

x-omniroute-compression

嵌入

圖像生成

文件 OCR

Azure Document Intelligence 輪詢流程

Vertex AI DeepSeek OCR 驗證與端點解析

列出模型

模型 ID 前綴（?prefix=）

無思考模型變體

提供者外掛資訊清單

相容性端點

專用提供者路由

Files API

Batches API

搜尋 API

Web 擷取 API

WebSocket 串流

透過 WebSocket 使用 Responses API（僅限 codex）

模型 ID：使用純 ChatGPT ID（不加 codex/ 前綴）

設定 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（代理程式用戶端協定）管理

分析與可觀測性

自動路由分析

壓縮分析

提供者多樣性追蹤

管理員操作

CLI 工具管理

`x-omniroute-compression`

模型 ID 前綴（`?prefix=`）

模型 ID：使用純 ChatGPT ID（不加 `codex/` 前綴）

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