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

API Reference (中文 (繁體))

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

---

🌐 語言： 🇺🇸 English | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

OmniRoute API 的核心參考文件。涵蓋公開的 /v1 介面及最常用的管理端點；機器可讀的 docs/openapi.yaml 與 src/app/api/ 下的路由樹則是完整的參考來源。

---

目錄

• 聊天補全
• 獨佔式受管工作階段租約
• 嵌入
• 圖片生成
• 文件 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 <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>

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

成功的取得、續約和釋放回應會公開時間戳記、state 和確切的正整數 generation，但絕不會公開所選連線或憑證。續約和釋放會在 JSON 主體中提供 generation：

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

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

作用中的租約擁有者可以明確要求其目前繫結的隱私安全顯示中繼資料：

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

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

這項選擇加入的狀態動作，會在單一資料庫交易中受到不透明的擁有者、已驗證的受管理 API 金鑰，以及確切作用中 generation 的防護。displayName 僅為經修整的已設定連線名稱；若不存在安全的已設定名稱，則為 null。OmniRoute 絕不會以電子郵件或產生的帳戶身分取代它。提供者值是非敏感的顯示標籤，絕不會是產生的相容提供者識別碼。憑證、權杖、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 仍會失敗。原始擁有者資訊不會被持久儲存、記錄、保留於請求快照中，或轉送至上游。

暫時性競用會傳回 HTTP 429、Retry-After，以及：

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

此回應僅表示一般的符合資格集合不是空的，而且每個可用候選項目都由其他擁有者的作用中租約持有。不受支援的模型／提供者、原則不符、冷卻期、配額、健康狀態，以及其他一般資格判定失敗，會保留其現有的 OmniRoute 回應。

x-omniroute-compression

逐一請求覆寫壓縮計畫。優先順序最高——高於路由組合覆寫、作用中設定檔、自動觸發條件，以及面板的「預設」設定。值：

值	效果
off	此請求不進行壓縮。
default	面板衍生的「預設」設定檔（忽略作用中設定檔）。
engine:<id>	啟用時使用單一引擎，例如 engine:rtk。
<combo>	具名組合，先依名稱比對（不區分大小寫），再依 ID 比對。

注意：

• 未知值會被忽略（絕不會拒絕請求）；解析會回退至正常的運算子優先順序。
• 如果多個組合共用同一名稱，請傳遞組合的 id 以確保比對結果可預測。
• 名稱為 off 或 default 的組合無法依名稱選取（系統會先解譯這些關鍵字）；請透過其 ID 參照此類組合。
• 壓縮總開關是硬性閘門：全域停用壓縮時，此標頭無法啟用壓縮。

套用的計畫會在回應標頭中回傳：

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

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

---

嵌入

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

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

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

目錄 ID 採用 provider/model 格式（例如：jina-ai/jina-embeddings-v5-omni-small）。登錄檔中出現的純 Jina 模型 ID（例如 jina-embeddings-v5-text-small、jina-reranker-v3.5）也可以解析。Jina 的嵌入／重新排序／分類／分段功能會優先使用儀表板中的 jina-ai 憑證；只有在不存在儀表板金鑰時，才會使用 JINA_AI_API_KEY 作為備援。jina-reader 卡片僅供 Reader／r.jina.ai 使用（POST /v1/web/fetch），絕不提供嵌入或重新排序服務。

登錄模型若標示支援多模態，也可接受最多 32 個提供者中立的結構化 項目。媒體項目類型為 text、image、audio、video 與 document。其媒體 source 可以是 {"type":"url","url":"https://..."}，也可以是 {"type":"base64","data":"...","media_type":"..."}。

Jina v5 Omni（jina-ai/jina-embeddings-v5-omni-small、jina-ai/jina-embeddings-v5-omni-nano 以及系列別名 jina-ai/jina-embeddings-v5-omni → omni-small）也接受 Jina 原生的 EmbeddingsV5Request 文件，並將其完整轉送至 https://api.jina.ai/v1/embeddings：

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

原生 { image | audio | video | pdf } 值可以是公開的 HTTPS URL、data: URI 或原始 base64。OmniRoute 不會將這些物件字串化，也不會擷取原生圖片 URL——Jina 會自行擷取 公開媒體。額外的 Jina 欄位（task、normalized、truncate、embedding_type）會被 轉送。僅文字的 Jina SKU 仍會拒絕非文字文件。

安全性與傳輸限制：

• 遠端媒體 URL 必須是公開的 HTTPS。標準 {type,source:url} 項目會由伺服器端擷取 （重新驗證重新導向、逾時、大小限制、公開 DNS、連線固定），並在呼叫提供者前 內嵌。Jina 原生 {image:"https://..."} 項目在經過相同的公開 HTTPS 檢查後會原樣 轉送；URL 由 Jina 擷取。
• 內嵌 base64 媒體限制為每個項目解碼後 8 MiB，整個請求解碼後合計 16 MiB。

提供者轉譯（標準項目絕不會原樣轉送）：

• Jina 多模態模型：每個頂層項目都會成為一個以模態為鍵的物件 （text／image／audio／video／pdf），內嵌媒體使用資料 URI；每個 頂層項目產生一個向量。
• Gemini Embedding 2 系列：一個頂層陣列會成為單一原生 models/{model}:embedContent 請求，並包含 content.parts（text 或 inline_data）。
• 沒有明確模態中繼資料的未知／動態模型會以 HTTP 400 拒絕結構化輸入。

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

不支援的模型／模態組合會傳回 HTTP 400，而不是強制轉換該項目。舊版字串／權杖請求中的 非輸入擴充欄位仍會原樣傳遞。

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

---

圖像生成

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

{
  "model": "openai/gpt-image-2",
  "prompt": "A beautiful sunset over mountains",
  "size": "1024x1024"
}

可用的提供者：OpenAI (GPT Image 2)、xAI (Grok Image)、Together AI (FLUX)、Fireworks AI、Nebius (FLUX)、Hyperbolic、NanoBanana、OpenRouter、SD WebUI（本機）、ComfyUI（本機）。

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

---

文件 OCR

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

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

model 透過 provider/model 前綴選取 OCR 提供者；僅提供模型 ID（例如 mistral-ocr-latest）時，會解析至其已註冊的提供者；若省略 model，則預設為 Mistral（mistral-ocr-latest）。已註冊的提供者（open-sse/config/ocrRegistry.ts）：

提供者 ID	模型 ID	model 值	備註
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest（或僅使用 mistral-ocr-latest）	同步——回應會直接從單次上游呼叫傳回。
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	非同步上游（analyze + 輪詢）——詳見下文。
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	同步，透過 Vertex AI 的 openapi/chat/completions 合作夥伴端點——驗證／URL 詳見下文。

三個提供者都會以相同的 Mistral 格式主體回應：

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

Azure Document Intelligence 輪詢流程

Azure Document Intelligence 的 analyze API 是非同步的：初始請求會傳回 Operation-Location 標頭而非主體，且必須透過輪詢取得結果。處理常式 （open-sse/handlers/ocr.ts）會每秒輪詢該 URL，最多嘗試 30 次；遇到非 ok 的輪詢回應或 "failed" 狀態時會立即失敗（不會繼續輪詢）；若用盡嘗試次數後作業仍在執行，則傳回 504。最終的 Azure 回應在傳回給呼叫端之前，會正規化為與 Mistral 相同的 pages/markdown 格式，因此用戶端程式碼不需要針對提供者進行特殊處理。

Vertex AI DeepSeek OCR 驗證與端點解析

vertex-deepseek-ocr 會重複使用 OmniRoute 已支援、用於聊天／圖像流量的相同 Vertex AI 驗證機制（open-sse/executors/vertex.ts）：連線的 API 金鑰可以是 Service Account JSON 憑證（透過 JWT-bearer 流程交換為短效 OAuth 存取權杖），也可以是直接使用的既有 OAuth 存取權杖。上游端點 URL 是 Vertex 通用的 openapi/chat/completions 合作夥伴端點，根據連線的專案與區域建構——明確指定的 providerSpecificData.project/providerSpecificData.region 一律優先；否則，專案會從 Service Account JSON 的 project_id 衍生，而區域則預設為 us-central1。這兩項解析都會在 open-sse/handlers/ocr.ts 中進行（resolveVertexOcrAccessToken、resolveVertexOcrBaseUrl），並由 src/app/api/v1/ocr/route.ts 在分派至 handleOcr 前使用。

---

列出模型

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

→ 以 OpenAI 格式傳回所有聊天、嵌入與圖片模型及其組合

模型 ID 前綴（?prefix=）

大多數模型會以提供者前綴呈現。所使用的前綴由 MODELS_CATALOG_PREFIX_MODE 功能旗標控制，也可透過查詢參數針對每個請求覆寫——這對於希望取得簡潔清單、但不想變更整個伺服器設定而影響其他所有使用者的用戶端很有用：

GET /v1/models?prefix=alias        # 每個模型一個 ID——簡短的別名前綴
GET /v1/models?prefix=dual         # 兩種形式（伺服器預設值）
GET /v1/models?prefix=canonical    # 僅使用完整的提供者 ID 前綴

模式	輸出	備註
dual	cc/claude-sonnet-4-6 與 claude/claude-sonnet-4-6	預設值。 兩個 ID 都會路由至相同模型；保留此模式是為了讓硬編碼任一形式的用戶端設定能繼續運作。模型目錄大小約會加倍。
alias	cc/claude-sonnet-4-6	每個模型一個項目。沒有獨立別名的提供者仍會輸出其項目，因此不會遺漏任何內容。
canonical	claude/claude-sonnet-4-6	每個模型在完整的提供者 ID 前綴下各有一個項目。沒有獨立別名的提供者（例如 antigravity/…、agy/…）也會在此輸出其唯一的 ID，因此不會遺漏任何內容。

即使沒有查詢參數，也能識別 dual 模式的鏡像：它會帶有指向主要 ID 的 parent 欄位。

呈現模型選擇器的用戶端應請求 ?prefix=alias—— OmniCopilot VS Code 擴充功能就是採用此方式。

無思考模型變體

對於支援思考的 Claude 模型，/v1/models 也會提供一個 ID 以 claude-3-omniroute-no-thinking/ 為前綴的無思考變體：

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

選取此 ID（例如在一律附加 thinking 區塊的 Claude Code 設定中）後，會解析回實際的 <provider>/<model>，但停用推理——在 /v1/messages 路徑上使用 thinking:{type:"disabled"}，或在 /v1/chat/completions 路徑上移除 reasoning/reasoning_effort 欄位。此變體只會針對支援思考且接受 disabled 的 Claude 系列模型列出（因此，例如會拒絕 disabled、僅支援自適應模式的模型將被排除）。運算子可透過 ModelSpec.noThinkingAlias，針對每個模型強制啟用或停用此變體。

---

提供者外掛資訊清單

GET /api/v1/provider-plugin-manifest

傳回 Bifrost、CLIProxyAPI 及未來的 sidecar 路由器所使用、可安全序列化為 JSON 的提供者外掛資訊清單。此回應由 TypeScript 提供者登錄檔產生，並刻意排除 OAuth 用戶端密鑰、執行階段環境解析、執行器函式、請求標頭及帳戶資料。

當 sidecar 於行程外執行，且無法直接匯入 open-sse/config/providerPluginManifestRegistry.ts 時，請使用此端點。

---

相容性端點

方法	路徑	格式
POST	/v1/chat/completions	OpenAI
POST	/v1/messages	Anthropic
POST	/v1/responses	OpenAI Responses
POST	/v1/embeddings	OpenAI
POST	/v1/images/generations	OpenAI Images
POST	/v1/images/edits	OpenAI Images（編輯／局部重繪）
POST	/v1/videos/generations	OpenAI 風格的影片生成
POST	/v1/music/generations	OpenAI 風格的音樂生成
POST	/v1/audio/transcriptions	OpenAI Audio（語音轉文字）
POST	/v1/audio/speech	OpenAI TTS（傳回音訊主體）
POST	/v1/rerank	Cohere/Voyage 風格的重新排序
POST	/v1/classify	Jina 分類（api.jina.ai）
POST	/v1/segment	Jina 分段器（segment.jina.ai）
POST	/v1/moderations	OpenAI Moderations
GET	/v1/models	OpenAI
POST	/v1/messages/count_tokens	Anthropic
GET	/v1beta/models	Gemini
POST	/v1beta/models/{...path}	Gemini generateContent
POST	/v1/api/chat	Ollama
GET	/api/v1/vscode/{token}/	OpenAI 目錄別名
GET	/api/v1/vscode/{token}/models	OpenAI 模型別名
POST	/api/v1/vscode/{token}/chat/completions	OpenAI 權杖化別名
POST	/api/v1/vscode/{token}/responses	OpenAI Responses 權杖化別名
POST	/api/v1/vscode/{token}/api/chat	Ollama 權杖化別名
GET	/api/v1/vscode/{token}/api/tags	Ollama 標籤權杖化別名

所有 POST 路由都遵循相同格式：Bearer your-api-key + 經 Zod 驗證的 JSON 主體（v1RerankSchema、v1ModerationSchema、v1AudioSpeechSchema 等；請參閱 src/shared/validation/schemas.ts）。結構描述驗證失敗時會傳回 4xx。

對於無法附加 Authorization: Bearer ... 的用戶端，OmniRoute 也接受透過 URL 傳入的 API 金鑰；可使用查詢字串相容方式（?token=...、?apiKey=...、?api_key=...、?key=...），或使用下方記載的專用 /api/v1/vscode/{token}/... 端點。

# 重新排序
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

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

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

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

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

# TTS — 傳回 audio/mpeg（或所要求的格式）主體
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# 影像編輯（multipart）
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# 影片／音樂生成（帶有提供者前綴的模型 ID）
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

專用提供者路由

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

若缺少提供者前綴，系統會自動加上。模型不相符時會傳回 400。

---

Files API

與 OpenAI 相容的檔案端點，用於批次輸入／輸出及依檔案用途上傳。

方法	路徑	說明
POST	/v1/files	上傳檔案（multipart：file、purpose、expires_after[anchor]、expires_after[seconds]）— 上限 512 MiB
GET	/v1/files	列出已驗證 API 金鑰的檔案
GET	/v1/files/[id]	取得檔案的中繼資料
DELETE	/v1/files/[id]	刪除檔案
GET	/v1/files/[id]/content	以串流方式傳回原始檔案內容

驗證： Bearer API 金鑰 — 檔案會透過 getApiKeyRequestScope 依 API 金鑰劃分範圍。金鑰 只能查看、下載及刪除其自己的檔案；沒有金鑰的儀表板工作階段可讀取 整個執行個體；沒有擁有者的檔案（匿名或透過儀表板工作階段上傳）會拒絕所有 非工作階段呼叫者存取。GET /v1/files 會對匿名呼叫者及無法解析的已提供金鑰 傳回 401，即使 REQUIRE_API_KEY=false 亦然，而不會列出所有租戶的 檔案（GHSA-m3hp-hq9g-fpmv、GHSA-2jm2-mpx8-6523）。

---

Batches API

與 OpenAI 相容的批次處理。

方法	路徑	說明
POST	/v1/batches	建立批次 — 請求本文由 v1BatchCreateSchema 驗證（input_file_id、endpoint、completion_window）
GET	/v1/batches	列出批次
GET	/v1/batches/[id]	取得批次狀態及 request_counts
DELETE	/v1/batches/[id]	刪除已完成／失敗的批次
POST	/v1/batches/[id]/cancel	取消處理中的批次

驗證： Bearer API 金鑰。批次會依 API 金鑰劃分範圍，並採用與 檔案相同的三方規則：僅限自己的金鑰、儀表板工作階段可存取整個執行個體、無擁有者的記錄會拒絕所有 非工作階段呼叫者存取（取得、刪除、取消，以及建立時的 input_file_id 檢查）。 GET /v1/batches 會對匿名呼叫者傳回 401，即使 REQUIRE_API_KEY=false 亦然。

---

搜尋 API

Web／搜尋提供者抽象層（Tavily、Brave、Exa、Serper 等）。

方法	路徑	說明
GET	/v1/search	列出已設定的搜尋提供者與功能
POST	/v1/search	執行搜尋查詢 — 請求主體由 v1SearchSchema 驗證，支援快取／合併
GET	/v1/search/analytics	各提供者的命中率／延遲／快取統計資料

驗證： Bearer API 金鑰（extractApiKey + isValidApiKey）。搜尋政策透過 enforceApiKeyPolicy 強制執行。

---

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

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

金鑰必須啟用 allowUsageCommand（預設停用——儀表板的 API 金鑰管理器可針對每把金鑰切換此設定）。若未啟用，端點會回傳 403。

?format=json 會回傳可辨識聯集的資料結構，確保呼叫端不會從拒絕回應中讀取資料欄位。成功時：

{
  "allowed": true,
  // 僅當金鑰選擇啟用個別金鑰用量限制（每日／每週 USD）時才會出現：
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // 所選提供者的配額快照；若尚未快取任何資料，則為 null：
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // 每個連線的快照，讓 UI 能並列呈現多個提供者：
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

拒絕時（401 金鑰無效／403 不允許），同一路由會回傳 { "allowed": false, "error": { "message": "…" } }——存在但為空的 personal／provider（金鑰已獲允許，但尚未取得任何資料）與拒絕是不同的狀態，而且只有 JSON 格式能區分兩者。

驗證： 呼叫端自己的 Bearer API 金鑰，使用 isValidApiKey 驗證——這_不是_管理介面（/api/keys/…）；後者仍受 requireManagementAuth 保護。

---

語意快取

# 取得快取統計資料
GET /api/cache/stats

# 清除所有快取
DELETE /api/cache/stats

回應範例：

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

延遲影響

語意快取命中時，會直接從快取提供回應，不會呼叫上游，因此回報的 X-OmniRoute-Response-Latency 接近零（不受原始上游延遲影響）。對延遲敏感的用戶端（效能基準測試、p50/p99 監控）應檢查 X-OmniRoute-Cache-Latency 回應標頭：

值	意義
synthetic	回應來自快取；此延遲並非真實的上游耗時
（不存在）	回應來自真實的上游呼叫

各金鑰的快取略過設定

API 金鑰可透過 cacheDefaultMode 選擇不讀取語意快取：

值	行為
legacy	一般快取行為（預設）
bypass	完全略過快取查找；一律呼叫上游

可在建立金鑰時（POST /api/keys）設定，或透過更新（PATCH /api/keys/[id]）設定：

{ "cacheDefaultMode": "bypass" }

各請求的略過設定

無論金鑰設定為何，任何請求都能略過快取：

X-OmniRoute-No-Cache: true

---

儀表板與管理

管理路由（/api/*，公開驗證／登入除外）不接受一般推論 API 金鑰的授權。關於憑證類型、權限範圍與 curl 範例，請參閱： 管理驗證。

驗證

端點	方法	說明
/api/auth/login	POST	登入
/api/auth/logout	POST	登出
/api/settings/require-login	GET/PUT	切換是否要求登入

提供者管理

端點	方法	說明
/api/providers	GET/POST	列出／建立提供者
/api/providers/[id]	GET/PUT/DELETE	管理提供者
/api/providers/[id]/test	POST	測試提供者連線
/api/providers/[id]/models	GET	列出提供者模型
/api/providers/validate	POST	驗證提供者設定
/api/providers/bulk	POST	為單一提供者批次新增 API 金鑰
/api/providers/import	POST	從已剖析的 CSV/JSON 檔案匯入異質提供者清單（#6836）；提供每列的部分失敗結果
/api/provider-nodes*	各種	提供者節點管理
/api/provider-models	GET/POST/PATCH/DELETE	自訂模型（新增、更新、隱藏／顯示、刪除）

OAuth 流程

端點	方法	說明
/api/oauth/[provider]/[action]	各種	提供者特定的 OAuth

路由與設定

端點	方法	說明
/api/models/alias	GET/POST	模型別名
/api/models/catalog	GET	依提供者與類型列出所有模型
/api/combos*	各種	組合管理
/api/keys*	各種	API 金鑰管理
/api/pricing	GET	模型定價

使用情況與分析

端點	方法	說明
/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 管線集中強制執行）。

請求處理

1. 用戶端將請求傳送至 /v1/*
2. 路由處理常式呼叫 handleChat、handleEmbedding、handleAudioTranscription 或 handleImageGeneration
3. 解析模型（直接指定提供者/模型，或使用別名/組合）
4. 從本機資料庫選取憑證，並依帳戶可用性進行篩選
5. 對於聊天：handleChatCore 會檢查語意/簽章快取，並解析組合壓縮設定
6. 啟用時，會在提供者轉譯之前執行主動壓縮（lite、Caveman、RTK 或堆疊模式）
7. 提供者執行器向上游傳送請求
8. 將回應轉譯回用戶端格式（聊天），或依原樣傳回（嵌入/圖片/音訊）
9. 記錄使用量、壓縮分析資料和請求日誌
10. 發生錯誤時，依照組合規則套用後援機制

完整架構參考：ARCHITECTURE.md

---

組合管理

較高階的路由組合（已在 /api/combos* 下摘要說明）也可以從模型 id 模式進行 1:1 對應，讓 OpenAI 風格的模型 id 能夠透明地重新導向至某個組合。

方法	路徑	說明
GET	/api/model-combo-mappings	列出所有模型→組合對應
POST	/api/model-combo-mappings	建立對應 — 請求主體：{pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	擷取單一對應
PUT	/api/model-combo-mappings/[id]	更新現有對應的欄位
DELETE	/api/model-combo-mappings/[id]	移除對應

驗證： 管理工作階段/API 金鑰（requireManagementAuth）。

---

Webhook

OmniRoute 事件（請求完成、配額耗盡、金鑰輪替等）的對外 Webhook 訂閱。

方法	路徑	說明
GET	/api/webhooks	列出 Webhook（密鑰會遮蔽為 <prefix>...）
POST	/api/webhooks	建立 Webhook — 主體：{url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	擷取 Webhook
PUT	/api/webhooks/[id]	更新 url/events/secret/description
DELETE	/api/webhooks/[id]	移除 Webhook
POST	/api/webhooks/[id]/test	將測試承載資料傳送至 Webhook URL，並傳回遞送狀態

驗證： 管理工作階段/API 金鑰（requireManagementAuth）。

---

已註冊的金鑰（自動管理）

由自動金鑰管理子系統使用，以透過後端提供者/帳戶發行及輪替 API 金鑰，並設有每日/每小時配額。

方法	路徑	說明
GET	/api/v1/registered-keys	列出已註冊的金鑰（僅顯示遮蔽後的前綴）
POST	/api/v1/registered-keys	發行新的已註冊金鑰 — 主體：{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}。原始金鑰只會傳回一次。因配額而拒絕時傳回 429。
GET	/api/v1/registered-keys/[id]	擷取已註冊金鑰的中繼資料（不包含原始金鑰內容）
DELETE	/api/v1/registered-keys/[id]	撤銷已註冊的金鑰
POST	/api/v1/registered-keys/[id]/revoke	明確的撤銷端點（效果與 DELETE 相同）

驗證： Bearer API 金鑰（isAuthenticated）。另請參閱 /v1/quotas/check 和 /v1/issues/report。

---

代理程式協定

代表 OmniRoute 使用者在遠端執行的雲端代理程式任務（Claude Code、Codex Cloud、OpenHands 等）。

方法	路徑	說明
GET	/api/v1/agents/tasks	列出任務 — 可選用 ?provider=、?status=、?limit=（1–500，預設為 50）
POST	/api/v1/agents/tasks	建立任務 — 請求主體由 CreateCloudAgentTaskSchema 驗證（providerId、prompt、source、options?）。傳回含任務封裝的 201
DELETE	/api/v1/agents/tasks?id=...	刪除任務
GET	/api/v1/agents/tasks/[id]	讀取任務 — 設定 external_id 時，會同步從上游雲端代理程式重新整理狀態
POST	/api/v1/agents/tasks/[id]	可辨識聯集動作：{action: "approve"}、{action: "message", message} 或 {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	依 id 刪除特定任務

驗證： 每個方法都需要管理驗證（requireCloudAgentManagementAuth）。在 v3.8.0 之前，這些方法不需要驗證 — 請參閱提交 588a0333，瞭解這項破壞性變更。

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

---

管理代理伺服器

可指派給提供者、帳戶或全域使用的對外 HTTP(S)/SOCKS 代理伺服器。

方法	路徑	說明
GET	/api/v1/management/proxies	列出代理伺服器（使用 ?id= 傳回一個；使用 ?id=&where_used=1 傳回指派關聯圖）
POST	/api/v1/management/proxies	建立代理伺服器 — 請求主體由 createProxyRegistrySchema 驗證
PATCH	/api/v1/management/proxies	更新代理伺服器 — 請求主體由 updateProxyRegistrySchema 驗證（需要 id）
DELETE	/api/v1/management/proxies?id=...&force=1	刪除代理伺服器（使用 force=1 解除指派）
GET	/api/v1/management/proxies/assignments	列出指派 — 可依 proxy_id、scope、scope_id 篩選；傳入 resolve_connection_id=<id> 可解析連線目前使用的代理伺服器
PUT	/api/v1/management/proxies/assignments	指派 — 請求主體由 proxyAssignmentSchema 驗證（{scope, scopeId?, proxyId?}）。清除分派器快取
PUT	/api/v1/management/proxies/bulk-assign	批次指派 — 請求主體由 bulkProxyAssignmentSchema 驗證（{scope, scopeIds[], proxyId?}）
GET	/api/v1/management/proxies/health?hours=24	彙總指定時間範圍內的代理伺服器健康狀態（成功／失敗次數、延遲）

驗證： 每個路由都需要管理工作階段/API 金鑰（requireManagementAuth）。

任務說明中的 POST /api/v1/management/proxies/[id]/assignments 和 POST /api/v1/management/proxies/[id]/health，實際由上方所示的扁平 /assignments 和 /health 路由提供 — 程式碼庫中沒有依 id 區分的子路由。

---

韌性（延伸）

OmniRoute 提供三種彼此獨立的暫時性故障處理機制；下列管理端點可讓維運人員讀取及覆寫這些機制：

範圍	狀態儲存位置	讀取	重設／清除
提供者斷路器	domain_circuit_breakers + 記憶體內	/api/monitoring/health	POST /api/resilience/reset
連線冷卻	提供者連線上的 rateLimitedUntil	/api/rate-limits, /api/providers/[id]	（延遲至使用時重新啟用；可透過提供者 PUT 清除）
模型鎖定	記憶體內的模型可用性登錄檔	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience 接受位於 providerBreaker.oauth 和 providerBreaker.apikey 下的提供者斷路器覆寫設定。每個設定檔皆支援 degradationThreshold、failureThreshold 和 resetTimeoutMs；也可在「儀表板 → 設定 → 韌性」中設定相同欄位。

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

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

完整概念參考與斷路器預設值：請參閱 CLAUDE.md →「韌性執行階段狀態」。

---

技能

用於透過自訂可執行處理常式擴充 OmniRoute 的技能框架，以及市集整合功能。

方法	路徑	說明
GET	/api/skills	列出已安裝的技能 — 可依 ?q=、?mode=on|off|auto、?source=skillsmp|skillssh|local 篩選，並支援分頁
GET	/api/skills/[id]	擷取單一技能
PUT	/api/skills/[id]	更新技能（名稱、說明、模式、結構描述、處理常式、標籤）
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 傳輸。

方法	路徑	說明
GET	/api/mcp/status	心跳、傳輸方式、線上狀態、最後呼叫、熱門工具、24 小時成功率
GET	/api/mcp/tools	列出 MCP 工具及其 name、description、scopes、phase、auditLevel、sourceEndpoints
GET	/api/mcp/sse	開啟 SSE 傳輸的 SSE 串流（若 MCP 已停用或傳輸方式不符，則回傳 503）
POST	/api/mcp/sse	在 SSE 傳輸上傳送 JSON-RPC 訊框
GET	/api/mcp/stream	開啟 Streamable HTTP 傳輸的 SSE 端（伺服器主動發送的訊息）
POST	/api/mcp/stream	在 Streamable HTTP 傳輸上傳送 JSON-RPC 訊框
DELETE	/api/mcp/stream	結束 Streamable HTTP 工作階段
GET	/api/mcp/audit	查詢稽核記錄 — ?limit=、?offset=、?tool=、`?success=true	false、?apiKeyId=`
GET	/api/mcp/audit/stats	彙總稽核統計資料（總數、成功率、平均持續時間、熱門工具）

驗證： sse／stream 傳輸遵循 MCP 專用的驗證介面（具有 mcp 範圍的 Bearer API 金鑰）；status／tools／audit* 路由可從儀表板讀取（除了能夠存取儀表板主機外，不需要額外驗證）。

兩種 HTTP 傳輸均受 settings.mcpEnabled 和 settings.mcpTransport 控制 — 傳輸方式不符時回傳 400，MCP 停用時回傳 503。

---

A2A 伺服器

OmniRoute 提供一個 A2A（代理程式對代理程式）JSON-RPC 2.0 端點，以及一個供檢查／儀表板使用的 REST 包裝層。

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # 選用，除非已設定 OMNIROUTE_API_KEY
Content-Type: application/json

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

支援的方法（全部由 settings.a2aEnabled 控制）：

方法	說明
message/send	同步執行技能；傳回 {task, artifacts, metadata}
message/stream	以串流 SSE 執行相同的技能集
tasks/get	依 taskId 擷取任務
tasks/cancel	依 taskId 取消任務

內建技能：smart-routing、quota-management、provider-discovery、cost-analysis、health-report。

代理程式卡片

GET /.well-known/agent.json

傳回公開的 A2A 代理程式卡片（名稱、說明、功能、技能目錄、驗證配置）— 公開快取 1 小時。無需驗證。

REST 輔助端點

方法	路徑	說明
GET	/api/a2a/status	A2A 啟用狀態 + 任務統計資料 + 已快取的代理程式卡片摘要
GET	/api/a2a/tasks	列出任務 — ?state=submitted|working|completed|failed|cancelled、?skill=、?limit=（≤200）、?offset=
POST	/api/a2a/tasks	（未實作為 REST 輔助端點 — 請透過 JSON-RPC message/send 建立）
GET	/api/a2a/tasks/[id]	擷取單一任務
POST	/api/a2a/tasks/[id]/cancel	取消任務

**驗證：**REST 輔助端點不需要管理驗證即可執行（儀表板可讀取）；若已設定 Bearer OMNIROUTE_API_KEY，JSON-RPC /a2a 路由將使用該金鑰。

---

雲端、評測與評估

方法	路徑	說明
POST	/api/cloud/auth	驗證 Bearer 金鑰，並傳回經遮罩處理的提供者連線與供雲端同步用戶端使用的模型別名
POST	/api/cloud/credentials/update	更新雲端同步提供者的加密認證資料
POST	/api/cloud/model/resolve	使用本機路由表，將邏輯模型 ID 解析為具體的提供者／模型
GET	/api/cloud/models/alias	列出公開給雲端同步使用的模型別名
GET	/api/assess	讀取最新的評估分類（按提供者／模型）
POST	/api/assess	執行評估 — 本文：`{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	列出內建評測套件與最近的執行記錄
POST	/api/evals	觸發評測執行
POST	/api/evals/suites	建立自訂評測套件 — 本文由 evalSuiteSaveSchema 驗證
GET	/api/evals/suites/[id]	擷取自訂評測套件

驗證：/api/cloud/auth 會直接驗證 Bearer 金鑰；其他 /api/cloud/*、/api/evals/* 與 /api/assess 路由需要管理工作階段／API 金鑰。/api/assess POST 使用 validateBody 搭配可辨識聯集範圍結構描述。

---

ACP（代理程式用戶端協定）管理

作為子程序。這些端點用於管理 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、chipotle、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 Proxy 狀態（「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）。