OmniRoute/docs/i18n/vi/docs/reference/API_REFERENCE.md

API Reference (Tiếng Việt)

🌐 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 · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 Ngôn ngữ: 🇺🇸 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á | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

Tài liệu tham khảo cốt lõi cho API OmniRoute. Tài liệu này đề cập đến bề mặt /v1 công khai và các endpoint quản lý được sử dụng nhiều nhất; tệp mà máy có thể đọc được docs/openapi.yaml và cây route trong src/app/api/ là các nguồn đầy đủ.

---

Mục lục

• Hoàn thành hội thoại
• Quyền thuê phiên được quản lý độc quyền
• Embedding
• Tạo hình ảnh
• OCR tài liệu
• Liệt kê mô hình
• Tệp kê khai plugin nhà cung cấp
• Endpoint tương thích
• API tệp
• API lô
• API tìm kiếm
• Truyền phát WebSocket
• Báo cáo hạn ngạch & sự cố
• Bộ nhớ đệm ngữ nghĩa
• Bảng điều khiển & quản lý
• Quản lý combo
• Webhook
• Khóa đã đăng ký (Tự động quản lý)
• Giao thức tác tử
• Proxy quản lý
• Khả năng phục hồi (mở rộng)
• Kỹ năng
• Bộ nhớ
• Máy chủ MCP
• Máy chủ A2A
• Đám mây, đánh giá & thẩm định
• Xử lý yêu cầu
• Xác thực

---

Hoàn thành hội thoại

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Viết một hàm để..."}
  ],
  "stream": true
}

Header tùy chỉnh

Header	Hướng	Mô tả
X-OmniRoute-No-Cache	Yêu cầu	Đặt thành true để bỏ qua bộ nhớ đệm
x-omniroute-no-memory	Yêu cầu	Đặt thành true để bỏ qua việc chèn bộ nhớ + kỹ năng cho yêu cầu này (tương tự no-cache; tránh chi phí token/chi phí trên mỗi lần gọi)
X-OmniRoute-Progress	Yêu cầu	Đặt thành true để nhận các sự kiện tiến trình
X-Session-Id	Yêu cầu	Khóa phiên cố định dành cho cơ chế liên kết phiên bên ngoài
x_session_id	Yêu cầu	Biến thể có dấu gạch dưới cũng được chấp nhận (HTTP trực tiếp)
X-OmniRoute-Session-Id	Yêu cầu	Thẻ phiên/cuộc hội thoại do bên gọi cung cấp (cũng được đưa vào bộ nhớ). Khi có mặt, giá trị được lưu nguyên văn vào call_logs.session_tag để phân bổ chi phí theo từng phiên (#8249) — không bao giờ được tự tạo khi vắng mặt
Idempotency-Key	Yêu cầu	Khóa khử trùng lặp (cửa sổ 5 giây)
X-Request-Id	Yêu cầu	Khóa khử trùng lặp thay thế
X-OmniRoute-Cache	Phản hồi	HIT hoặc MISS (không truyền phát)
X-OmniRoute-Idempotent	Phản hồi	true nếu đã được khử trùng lặp
X-OmniRoute-Progress	Phản hồi	enabled nếu tính năng theo dõi tiến trình đang bật
X-OmniRoute-Session-Id	Phản hồi	ID phiên thực tế được OmniRoute sử dụng
X-OmniRoute-Request-Id	Phản hồi	ID tương quan của yêu cầu (khi xác định được)
X-OmniRoute-Version	Phản hồi	Phiên bản bản dựng OmniRoute (luôn hiện diện)
X-OmniRoute-Cost-Saved	Phản hồi	Số USD mà bộ nhớ đệm giúp tiết kiệm khi HIT (chỉ áp dụng cho lượt truy cập bộ nhớ đệm)
X-OmniRoute-Decision	Phản hồi	Dấu vết định tuyến: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> là chiến lược combo hoặc single đối với yêu cầu không phải combo) — luôn hiện diện trong các phản hồi hoàn tất

Lưu ý về Nginx: nếu bạn sử dụng các header có dấu gạch dưới (ví dụ: x_session_id), hãy bật underscores_in_headers on;.

Các header đo lường chi phí: các phản hồi thành công không phát trực tuyến cũng chứa bộ thông tin đo lường chi phí X-OmniRoute-* — X-OmniRoute-Response-Cost (USD, cố định 10 chữ số thập phân; 0.0000000000 nếu miễn phí/chưa định giá), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit và X-OmniRoute-Fallback-Attempts (chỉ khi > 0), cùng với X-OmniRoute-Request-Id và X-OmniRoute-Version. Các header này được trả về bởi các API hoàn thành trò chuyện, /v1/responses, /v1/messages, cũng như các endpoint đa phương tiện — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations và /v1/moderations (chi phí luôn là 0). Chi phí đa phương tiện được tính theo từng phương thức (theo hình ảnh, theo giây, theo ký tự, theo đơn vị tìm kiếm) khi có thông tin định giá; nếu không, chi phí là 0 (fail-open).

Ngữ nghĩa chi phí khi truy cập bộ nhớ đệm: khi HIT bộ nhớ đệm ngữ nghĩa (X-OmniRoute-Cache-Hit: true), không có lệnh gọi nào được gửi đến dịch vụ thượng nguồn, vì vậy X-OmniRoute-Response-Cost là 0.0000000000 (chi phí gia tăng để phục vụ lần truy cập này). Chi phí ban đầu/lẽ ra đã phát sinh được báo cáo riêng trong X-OmniRoute-Cost-Saved. Các hệ thống xử lý thanh toán nên cộng tổng X-OmniRoute-Response-Cost (các lần truy cập bộ nhớ đệm không phát sinh chi phí); hệ thống phân tích bộ nhớ đệm có thể tổng hợp X-OmniRoute-Cost-Saved.

Lease phiên được quản lý độc quyền

Lease phiên được quản lý độc quyền là một hợp đồng định tuyến tùy chọn, trung lập với client: một chủ sở hữu đang hoạt động nắm giữ một kết nối OmniRoute đủ điều kiện. Cơ chế này không lease một mô hình, không yêu cầu OAuth, không xác định một client cụ thể và cũng không yêu cầu một nhà cung cấp cụ thể.

Khóa API dùng để xác thực phải có phạm vi lease:exclusive và danh sách allowedConnections tường minh, không rỗng. Ranh giới đột biến cơ sở dữ liệu thực thi đồng thời cả hai trường khi tạo khóa và cập nhật một phần.

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"}

Các phản hồi acquire, renew và release thành công cung cấp dấu thời gian, state và giá trị generation dương chính xác, nhưng không bao giờ cung cấp kết nối đã chọn hoặc thông tin xác thực. Renew và release cung cấp generation trong phần thân JSON:

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

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

Chủ sở hữu lease đang hoạt động có thể yêu cầu rõ ràng metadata hiển thị an toàn về quyền riêng tư cho liên kết hiện tại của mình:

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

Hành động status tùy chọn này được rào chắn bằng chủ sở hữu không trong suốt, khóa API được quản lý đã xác thực và generation đang hoạt động chính xác trong một giao dịch cơ sở dữ liệu duy nhất. displayName chỉ là tên kết nối đã cấu hình được cắt bỏ khoảng trắng; giá trị này là null khi không tồn tại tên cấu hình an toàn. OmniRoute không bao giờ thay thế bằng email hoặc danh tính tài khoản được tạo. Giá trị nhà cung cấp là một nhãn hiển thị không nhạy cảm và không bao giờ là mã định danh nhà cung cấp tương thích được tạo. Thông tin xác thực, token, cookie, id kết nối hoặc khóa API thô, hàm băm chủ sở hữu, bí mật rào chắn và dữ liệu định tuyến nội bộ đều bị loại trừ.

Các truy vấn sử dụng sai khóa, sai chủ sở hữu, generation cũ, bị thiếu, hết hạn, đã phát hành hoặc bị vô hiệu hóa đều trả về cùng một lỗi 409 LEASE_FENCE_STALE mà không có metadata kết nối. Client đã nhận phản hồi chờ dung lượng không có liên kết đang hoạt động để kiểm tra. Khi định tuyến chuyển đổi một lease đang hoạt động, cùng một generation vẫn hợp lệ và status trả về liên kết mới một cách nguyên tử, không bao giờ trả về liên kết cũ. Các client hiện có không thay đổi vì phản hồi acquire, renew, release và chờ vẫn giữ nguyên cấu trúc trước đó.

Hợp đồng máy chủ này không thay đổi /status của OpenAI Codex nguyên bản. Codex nguyên bản hiện báo cáo nhà cung cấp mô hình và trạng thái xác thực/tài khoản tích hợp sẵn, nhưng không hiển thị metadata tài khoản tùy ý của nhà cung cấp tùy chỉnh; một tích hợp client sau này phải gọi hành động này và quyết định cách hiển thị connection.displayName.

Sau đó, mỗi yêu cầu suy luận được quản lý đều cung cấp cả hai header điều khiển:

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

Chủ sở hữu chính xác, generation, kết nối đang hoạt động và khóa API đã xác thực được rào chắn ngay trước mỗi lần thử upstream được hỗ trợ. Việc phát lại chủ sở hữu và generation bằng một khóa khác sẽ thất bại ngay cả khi khóa đó cho phép cùng một kết nối. Chủ sở hữu thô không được lưu trữ lâu dài, ghi nhật ký, giữ lại trong snapshot yêu cầu hoặc chuyển tiếp upstream.

Tranh chấp tạm thời trả về HTTP 429 cùng với Retry-After và:

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

Phản hồi này chỉ có nghĩa là tập hợp đủ điều kiện thông thường không rỗng và mọi ứng viên đang rảnh đều do một lease ngoại lai đang hoạt động nắm giữ. Các mô hình/nhà cung cấp không được hỗ trợ, chính sách không khớp, thời gian chờ, hạn ngạch, tình trạng hoạt động và các lỗi đủ điều kiện thông thường khác vẫn giữ nguyên phản hồi OmniRoute hiện có.

x-omniroute-compression

Ghi đè kế hoạch nén theo từng yêu cầu. Có mức ưu tiên cao nhất — cao hơn ghi đè tổ hợp định tuyến, hồ sơ đang hoạt động, trình kích hoạt tự động và giá trị Mặc định của bảng điều khiển. Các giá trị:

Giá trị	Hiệu ứng
off	Không nén yêu cầu này.
default	Hồ sơ Mặc định lấy từ bảng điều khiển (bỏ qua hồ sơ đang hoạt động).
engine:<id>	Một engine duy nhất khi được bật, ví dụ: engine:rtk.
<combo>	Một combo có tên, trước tiên được khớp theo tên (không phân biệt chữ hoa chữ thường), sau đó theo id.

Lưu ý:

• Các giá trị không xác định sẽ bị bỏ qua (yêu cầu không bao giờ bị từ chối); quá trình phân giải sẽ chuyển sang thứ tự ưu tiên toán tử thông thường.
• Nếu nhiều combo có cùng tên, hãy truyền id của combo để có kết quả khớp xác định.
• Không thể chọn theo tên một combo có tên là off hoặc default (các từ khóa này được diễn giải trước); hãy tham chiếu combo đó bằng id.
• Công tắc nén chính là một cổng cứng: khi tính năng nén bị vô hiệu hóa trên toàn hệ thống, header này không thể bật tính năng đó.

Kế hoạch được áp dụng sẽ được phản hồi lại trong header phản hồi:

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

trong đó <source> là một trong các giá trị request-header, routing-override, active-profile, auto-trigger, default hoặc off.

---

Embedding

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

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

Các nhà cung cấp khả dụng: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

ID danh mục có dạng provider/model (ví dụ: jina-ai/jina-embeddings-v5-omni-small). Các ID mô hình Jina không kèm tên nhà cung cấp xuất hiện trong registry (ví dụ: jina-embeddings-v5-text-small, jina-reranker-v3.5) cũng được phân giải. Các thao tác embed/rerank/classify/segment của Jina ưu tiên sử dụng thông tin xác thực jina-ai trên dashboard; JINA_AI_API_KEY chỉ được dùng làm phương án dự phòng khi không có khóa trên dashboard. Thẻ jina-reader chỉ dành cho Reader / r.jina.ai (POST /v1/web/fetch) và không bao giờ phục vụ embedding hoặc rerank.

Các mô hình trong registry công bố hỗ trợ đa phương thức cũng chấp nhận tối đa 32 mục có cấu trúc, trung lập với nhà cung cấp. Các loại mục phương tiện gồm text, image, audio, video và document. source của phương tiện có thể là {"type":"url","url":"https://..."} hoặc {"type":"base64","data":"...","media_type":"..."}.

Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano và bí danh họ mô hình jina-ai/jina-embeddings-v5-omni → omni-small) cũng chấp nhận các tài liệu EmbeddingsV5Request gốc của Jina và chuyển tiếp nguyên vẹn chúng đến 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,..." }]
    }
  ]
}

Các giá trị { image | audio | video | pdf } gốc có thể là URL HTTPS công khai, URI data: hoặc dữ liệu base64 thô. OmniRoute không chuyển các đối tượng đó thành chuỗi hoặc tải các URL hình ảnh gốc — Jina tự truy xuất phương tiện công khai. Các trường Jina bổ sung (task, normalized, truncate, embedding_type) được chuyển tiếp. Các SKU Jina chỉ hỗ trợ văn bản vẫn từ chối tài liệu không phải văn bản.

Giới hạn bảo mật và truyền tải:

• URL phương tiện từ xa phải là HTTPS công khai. Các mục chuẩn hóa {type,source:url} được tải ở phía máy chủ (xác thực lại chuyển hướng, thời gian chờ, giới hạn kích thước, DNS công khai, ghim kết nối) và được nhúng trực tiếp trước khi gọi nhà cung cấp. Các mục gốc của Jina {image:"https://..."} được chuyển tiếp nguyên trạng sau cùng bước kiểm tra HTTPS công khai; Jina sẽ tải URL.
• Phương tiện base64 nội tuyến được giới hạn ở 8 MiB dữ liệu đã giải mã cho mỗi mục và 16 MiB dữ liệu đã giải mã cho toàn bộ yêu cầu.

Chuyển đổi theo nhà cung cấp (các mục chuẩn hóa không bao giờ được chuyển tiếp nguyên trạng):

• Các mô hình đa phương thức của Jina: mỗi mục cấp cao nhất trở thành một đối tượng có khóa theo phương thức (text / image / audio / video / pdf), sử dụng URI dữ liệu cho phương tiện nội tuyến; mỗi mục cấp cao nhất tương ứng với một vector.
• Họ Gemini Embedding 2: một mảng cấp cao nhất trở thành một yêu cầu gốc duy nhất models/{model}:embedContent với content.parts (text hoặc inline_data).
• Các mô hình không xác định/động không có siêu dữ liệu phương thức rõ ràng sẽ từ chối đầu vào có cấu trúc với 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"
}

Các tổ hợp mô hình/phương thức không được hỗ trợ sẽ trả về HTTP 400 thay vì ép kiểu mục đó. Các trường mở rộng không thuộc đầu vào trên những yêu cầu chuỗi/token cũ tiếp tục được truyền nguyên trạng.

# Liệt kê tất cả các mô hình embedding
GET /v1/embeddings

---

Tạo hình ảnh

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

{
  "model": "openai/gpt-image-2",
  "prompt": "Một cảnh hoàng hôn tuyệt đẹp trên núi",
  "size": "1024x1024"
}

Các nhà cung cấp khả dụng: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (cục bộ), ComfyUI (cục bộ).

# Liệt kê tất cả mô hình tạo hình ảnh
GET /v1/images/generations

---

OCR tài liệu

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 chọn nhà cung cấp OCR thông qua tiền tố provider/model; một id mô hình đơn lẻ (ví dụ: mistral-ocr-latest) được phân giải thành nhà cung cấp đã đăng ký tương ứng, còn nếu bỏ qua model thì mặc định là Mistral (mistral-ocr-latest). Các nhà cung cấp đã đăng ký (open-sse/config/ocrRegistry.ts):

Id nhà cung cấp	Id mô hình	Giá trị model	Ghi chú
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (hoặc dạng đơn lẻ mistral-ocr-latest)	Đồng bộ — phản hồi được trả về trực tiếp từ một lệnh gọi upstream duy nhất.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Upstream bất đồng bộ (analyze + thăm dò) — xem bên dưới.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Đồng bộ, qua endpoint đối tác openapi/chat/completions của Vertex AI — xem bên dưới về xác thực/URL.

Cả ba nhà cung cấp đều phản hồi bằng phần thân có cùng định dạng như Mistral:

{
  "pages": [{ "index": 0, "markdown": "# Văn bản đã trích xuất..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}

Luồng thăm dò của Azure Document Intelligence

API analyze của Azure Document Intelligence hoạt động bất đồng bộ: yêu cầu ban đầu trả về header Operation-Location thay vì phần thân, và kết quả phải được thăm dò. Trình xử lý (open-sse/handlers/ocr.ts) thăm dò URL đó mỗi giây, tối đa 30 lần; dừng và báo lỗi ngay (không tiếp tục thăm dò) khi phản hồi thăm dò không phải ok hoặc có trạng thái "failed", đồng thời trả về 504 nếu thao tác vẫn đang chạy sau khi đã sử dụng hết số lần thử. Phản hồi cuối cùng của Azure được chuẩn hóa thành cùng cấu trúc pages/markdown mà Mistral sử dụng trước khi được trả về cho bên gọi, vì vậy mã phía máy khách không cần xử lý riêng theo từng nhà cung cấp.

Xác thực và phân giải endpoint OCR DeepSeek của Vertex AI

vertex-deepseek-ocr tái sử dụng cùng cơ chế xác thực Vertex AI mà OmniRoute đã hỗ trợ cho lưu lượng trò chuyện/hình ảnh (open-sse/executors/vertex.ts): khóa API của kết nối là thông tin xác thực Service Account JSON (được trao đổi lấy token truy cập OAuth ngắn hạn thông qua luồng JWT-bearer) hoặc một token truy cập OAuth đã được cấp sẵn và được sử dụng nguyên trạng. URL endpoint upstream là endpoint đối tác openapi/chat/completions dùng chung của Vertex, được tạo từ dự án và khu vực của kết nối — providerSpecificData.project/providerSpecificData.region được chỉ định rõ ràng luôn được ưu tiên; nếu không, dự án được lấy từ project_id trong Service Account JSON và khu vực mặc định là us-central1. Cả hai quá trình phân giải đều diễn ra trong open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), được src/app/api/v1/ocr/route.ts sử dụng trước khi chuyển tiếp đến handleOcr.

---

Liệt kê mô hình

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

→ Trả về tất cả mô hình trò chuyện, embedding và hình ảnh cùng các tổ hợp theo định dạng OpenAI

Tiền tố id mô hình (?prefix=)

Hầu hết các mô hình được công bố dưới một tiền tố nhà cung cấp. Tiền tố bạn nhận được chịu sự kiểm soát của cờ tính năng MODELS_CATALOG_PREFIX_MODE và có thể được ghi đè cho từng yêu cầu bằng một tham số truy vấn — hữu ích cho ứng dụng khách muốn có một danh sách gọn gàng mà không thay đổi thiết lập trên toàn máy chủ cho những người khác:

GET /v1/models?prefix=alias        # một id cho mỗi mô hình — tiền tố bí danh ngắn
GET /v1/models?prefix=dual         # cả hai dạng (mặc định của máy chủ)
GET /v1/models?prefix=canonical    # chỉ tiền tố id đầy đủ của nhà cung cấp

Chế độ	Xuất ra	Ghi chú
dual	cc/claude-sonnet-4-6 và claude/claude-sonnet-4-6	Mặc định. Cả hai id đều định tuyến đến cùng một mô hình; được duy trì để các cấu hình ứng dụng khách đã mã hóa cứng một trong hai dạng tiếp tục hoạt động. Kích thước danh mục gần như tăng gấp đôi.
alias	cc/claude-sonnet-4-6	Một mục cho mỗi mô hình. Các nhà cung cấp không có bí danh riêng vẫn xuất mục của họ, nên không có gì bị mất.
canonical	claude/claude-sonnet-4-6	Một mục cho mỗi mô hình dưới tiền tố id đầy đủ của nhà cung cấp. Các nhà cung cấp không có bí danh riêng (ví dụ: antigravity/…, agy/…) cũng xuất id duy nhất của họ ở đây, nên không có gì bị mất.

Một bản sao ở chế độ dual cũng có thể được nhận diện mà không cần tham số truy vấn: nó chứa trường parent trỏ đến id chính.

Các ứng dụng khách hiển thị bộ chọn mô hình nên yêu cầu ?prefix=alias — đây là cách tiện ích mở rộng OmniCopilot cho VS Code hoạt động.

Các biến thể mô hình không suy luận

Đối với các mô hình Claude có khả năng suy luận, /v1/models cũng công bố một biến thể không suy luận có id được thêm tiền tố claude-3-omniroute-no-thinking/:

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

Việc chọn id này (ví dụ: trong cấu hình Claude Code luôn đính kèm khối thinking) sẽ phân giải trở lại <provider>/<model> thực với khả năng suy luận bị vô hiệu hóa — thinking:{type:"disabled"} trên đường dẫn /v1/messages, hoặc loại bỏ các trường reasoning/reasoning_effort trên đường dẫn /v1/chat/completions. Biến thể này chỉ được liệt kê cho các mô hình thuộc họ Claude có hỗ trợ suy luận và chấp nhận disabled (do đó, ví dụ: các mô hình chỉ thích ứng nhưng từ chối disabled sẽ bị loại trừ). Người vận hành có thể buộc bật hoặc tắt biến thể này cho từng mô hình thông qua ModelSpec.noThinkingAlias.

---

Manifest Plugin Nhà cung cấp

GET /api/v1/provider-plugin-manifest

Trả về manifest plugin nhà cung cấp an toàn cho JSON, được Bifrost, CLIProxyAPI và các bộ định tuyến sidecar trong tương lai sử dụng. Phản hồi được tạo từ registry nhà cung cấp TypeScript và chủ ý loại trừ các bí mật OAuth client, quá trình phân giải môi trường runtime, các hàm thực thi, header yêu cầu và dữ liệu tài khoản.

Sử dụng endpoint này khi một sidecar chạy ngoài tiến trình và không thể nhập trực tiếp open-sse/config/providerPluginManifestRegistry.ts.

---

Các Endpoint Tương thích

Phương thức	Đường dẫn	Định dạng
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 (chỉnh sửa/inpaint)
POST	/v1/videos/generations	Tạo video theo phong cách OpenAI
POST	/v1/music/generations	Tạo nhạc theo phong cách OpenAI
POST	/v1/audio/transcriptions	OpenAI Audio (STT)
POST	/v1/audio/speech	OpenAI TTS (trả về nội dung âm thanh)
POST	/v1/rerank	Xếp hạng lại theo phong cách Cohere/Voyage
POST	/v1/classify	Phân loại Jina (api.jina.ai)
POST	/v1/segment	Trình phân đoạn 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}/	Bí danh danh mục OpenAI
GET	/api/v1/vscode/{token}/models	Bí danh model OpenAI
POST	/api/v1/vscode/{token}/chat/completions	Bí danh OpenAI được token hóa
POST	/api/v1/vscode/{token}/responses	Bí danh OpenAI Responses được token hóa
POST	/api/v1/vscode/{token}/api/chat	Bí danh Ollama được token hóa
GET	/api/v1/vscode/{token}/api/tags	Bí danh tag Ollama được token hóa

Tất cả các route POST đều tuân theo cùng một cấu trúc: Bearer your-api-key + nội dung JSON được Zod xác thực (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema, v.v., xem src/shared/validation/schemas.ts). Mã 4xx được trả về khi xác thực schema thất bại.

Đối với các client không thể đính kèm Authorization: Bearer ..., OmniRoute cũng chấp nhận khóa API trong URL thông qua khả năng tương thích chuỗi truy vấn (?token=..., ?apiKey=..., ?api_key=..., ?key=...) hoặc các endpoint /api/v1/vscode/{token}/... chuyên dụng được ghi lại bên dưới.

# Xếp hạng lại
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Phân loại Jina (thông tin xác thực Foundation API)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Trình phân đoạn Jina
POST /v1/segment     { "content": "...", "return_chunks": true }

# Tìm kiếm Jina (s.jina.ai; bí danh nhà cung cấp: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Kiểm duyệt
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — trả về nội dung audio/mpeg (hoặc định dạng được yêu cầu)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Chỉnh sửa hình ảnh (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Tạo video / nhạc (ID model có tiền tố nhà cung cấp)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Các Route Chuyên biệt cho Nhà cung cấp

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

Tiền tố nhà cung cấp được tự động thêm nếu còn thiếu. Các model không khớp trả về 400.

---

Files API

Endpoint tệp tương thích với OpenAI dành cho đầu vào/đầu ra theo lô và tải lên tệp theo mục đích.

Phương thức	Đường dẫn	Mô tả
POST	/v1/files	Tải lên tệp (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — tối đa 512 MiB
GET	/v1/files	Liệt kê các tệp của API key đã xác thực
GET	/v1/files/[id]	Truy xuất siêu dữ liệu của tệp
DELETE	/v1/files/[id]	Xóa tệp
GET	/v1/files/[id]/content	Truyền phát nội dung thô của tệp trả về

Xác thực: API key dạng Bearer — các tệp được giới hạn phạm vi theo từng API key thông qua getApiKeyRequestScope. Một key chỉ có thể xem, tải xuống và xóa các tệp của chính nó; một phiên dashboard không có key có thể đọc toàn bộ instance; một tệp không có chủ sở hữu (được tải lên ẩn danh hoặc qua phiên dashboard) sẽ bị từ chối đối với mọi bên gọi không dùng phiên. GET /v1/files từ chối bên gọi ẩn danh — cũng như key được cung cấp nhưng không thể phân giải — với mã 401 ngay cả khi REQUIRE_API_KEY=false, thay vì liệt kê các tệp của mọi tenant (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

Batches API

Xử lý theo lô tương thích với OpenAI.

Phương thức	Đường dẫn	Mô tả
POST	/v1/batches	Tạo lô — nội dung được xác thực bởi v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET	/v1/batches	Liệt kê các lô
GET	/v1/batches/[id]	Truy xuất trạng thái lô + request_counts
DELETE	/v1/batches/[id]	Xóa lô đã hoàn tất/thất bại
POST	/v1/batches/[id]/cancel	Hủy lô đang được xử lý

Xác thực: API key dạng Bearer. Các lô được giới hạn phạm vi theo từng API key theo cùng quy tắc ba trường hợp như tệp: chỉ key sở hữu, phiên dashboard có phạm vi toàn instance, các bản ghi có chủ sở hữu null bị từ chối đối với mọi bên gọi không dùng phiên (truy xuất, xóa, hủy và kiểm tra input_file_id khi tạo). GET /v1/batches từ chối bên gọi ẩn danh với mã 401 ngay cả khi REQUIRE_API_KEY=false.

---

API Tìm kiếm

Lớp trừu tượng cho nhà cung cấp web/tìm kiếm (Tavily, Brave, Exa, Serper, v.v.).

Phương thức	Đường dẫn	Mô tả
GET	/v1/search	Liệt kê các nhà cung cấp tìm kiếm đã cấu hình + khả năng
POST	/v1/search	Chạy truy vấn tìm kiếm — phần thân được xác thực bởi v1SearchSchema, hỗ trợ bộ nhớ đệm/gộp
GET	/v1/search/analytics	Thống kê lượt truy cập/độ trễ/bộ nhớ đệm theo từng nhà cung cấp

Xác thực: Khóa API Bearer (extractApiKey + isValidApiKey). Chính sách tìm kiếm được thực thi qua enforceApiKeyPolicy.

---

API Tải nội dung Web

Trích xuất nội dung từ một URL thông qua nhà cung cấp tải nội dung web đã cấu hình (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Phương thức	Đường dẫn	Mô tả
POST	/v1/web/fetch	Tải/thu thập dữ liệu từ URL — phần thân được xác thực bởi v1WebFetchSchema

Xác thực: Khóa API Bearer (extractApiKey + isValidApiKey). Chính sách được thực thi qua enforceApiKeyPolicy.

Chuyển đổi dự phòng có xét hạn ngạch (#8297): khi không chỉ định provider rõ ràng, nhóm (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) được duyệt theo thứ tự ưu tiên cố định (ưu tiên lấp đầy) — một nhà cung cấp đã cấu hình nhưng bị giới hạn tốc độ sẽ được bỏ qua thay vì chấm dứt sớm yêu cầu, và một lỗi phía thượng nguồn có thể thử lại/liên quan đến hạn ngạch (HTTP 429 trong mọi trường hợp; 402/403 đối với các gói miễn phí kiểu hạn ngạch của Firecrawl/Tavily/TinyFish — không áp dụng cho Jina Reader và không bao giờ áp dụng cho yêu cầu không hợp lệ 400 thông thường) sẽ chuyển sang nhà cung cấp tiếp theo có thông tin xác thực và chưa được thử tại thời điểm xử lý yêu cầu. Khi mọi nhà cung cấp trong nhóm đều đã cạn, endpoint trả về một mã 429 duy nhất (kèm header Retry-After) thay cho mã 400 chung trước đây. Khi yêu cầu một provider rõ ràng, sẽ không có chuyển đổi dự phòng ngầm — nhà cung cấp được chỉ định rõ ràng nếu bị giới hạn tốc độ hoặc gặp lỗi sẽ trả về lỗi của chính nó (429 nếu bị giới hạn tốc độ, nếu không thì là trạng thái từ phía thượng nguồn).

---

Truyền trực tuyến qua WebSocket

GET /v1/ws?handshake=1

Xác thực quá trình bắt tay nâng cấp WebSocket và trả về các thông điệp mẫu của giao thức truyền (request, cancel). Các frame WS thực tế được xử lý bởi máy chủ WS đi kèm bên ngoài bảng định tuyến Next.js.

Xác thực: Khóa API Bearer trong quá trình bắt tay.

Responses API qua WebSocket (chỉ codex)

# Cùng host:port với API HTTP (mặc định là 20128); nâng cấp kết nối:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (hoặc: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Frame đầu tiên PHẢI là response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Một proxy Responses-API-over-WebSocket được kết nối độc quyền với codex (backend ChatGPT). Proxy này lắng nghe trên cùng cổng với API/bảng điều khiển tại các đường dẫn /v1/responses, /responses và /api/v1/responses. Khi nhận frame response.create đầu tiên, proxy xác thực + chuẩn bị thông qua cầu nối nội bộ codex-responses-ws, chọn một kết nối OAuth codex và tạo đường hầm tới wss://chatgpt.com/backend-api/codex/responses thông qua phương thức truyền tải wreq-js. Các mô hình không phải codex sẽ bị từ chối (codex_ws_provider_required). Để định tuyến theo tỷ lệ hạn ngạch, hãy dùng model: "qtSd/<group>/codex/<model>". Được triển khai trong app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Xác thực: Khóa API Bearer trong quá trình bắt tay. Máy chủ HTTP đi kèm (server-ws.mjs) phải là entrypoint đang hoạt động (mặc định là như vậy khi app/server-ws.mjs tồn tại).

ID mô hình: dùng ID ChatGPT thuần (không có tiền tố codex/)

Codex CLI của OpenAI xác thực tên mô hình ở phía máy khách khi supports_websockets = true và từ chối các ID có tiền tố nhà cung cấp như codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Hãy gửi ID thuần (ví dụ: gpt-5.5). Cầu nối của OmniRoute chỉ dành cho codex, vì vậy nó phân giải lại một ID thuần thành mô hình codex (resolveCodexWsModelInfo) trước khi tạo đường hầm đến phía thượng nguồn — mặc dù một ID thuần gpt-5.5 nếu không sẽ được định tuyến đến nhà cung cấp khác qua HTTP.

Cấu hình OpenAI Codex CLI

Trỏ Codex CLI đến OmniRoute bằng cách thêm một nhà cung cấp tùy chỉnh có hỗ trợ WebSocket vào ~/.codex/config.toml (dùng một CODEX_HOME riêng để tránh tác động đến cấu hình hiện có):

model = "gpt-5.5"                 # ID thuần — KHÔNG PHẢI "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # không có dấu gạch chéo ở cuối; URL WS được suy ra (dùng https/wss trong môi trường production)
wire_api = "responses"                    # giá trị duy nhất được hỗ trợ kể từ tháng 2 năm 2026
supports_websockets = true                # bật phương thức truyền Responses-over-WS
env_key = "OMNIROUTE_API_KEY"             # chứa khóa API OmniRoute (Bearer)

export OMNIROUTE_API_KEY=sk-...           # một khóa API OmniRoute (khóa bất kỳ nếu REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

CLI nâng cấp base_url + /responses thành WebSocket và OmniRoute tạo đường hầm kết nối đó tới kết nối OAuth codex đã chọn. Đã được xác thực đầu-cuối với máy chủ cục bộ: ChatGPT trả về codex.rate_limits + response.created và truyền trực tuyến phần hoàn thành.

---

Hạn mức & Báo cáo sự cố

Phương thức	Đường dẫn	Mô tả
GET	/v1/quotas/check	Xác thực trước hạn mức cho một provider + accountId trước khi cấp khóa đã đăng ký
POST	/v1/issues/report	Báo cáo lỗi cấp hạn mức/khóa lên GitHub (yêu cầu GITHUB_ISSUES_REPO + token)

Xác thực: Khóa API Bearer (isAuthenticated).

---

Sử dụng tự phục vụ (/api/usage/om-usage)

Bất kỳ khóa API nào cũng có thể đọc mức sử dụng và hạn mức của chính nó — không cần quyền xác thực quản lý. Đây là endpoint mà client (CLI, bảng điều khiển OmniCopilot) sử dụng để hiển thị mức chi tiêu cho chủ sở hữu khóa.

# Dạng văn bản (giao ước truyền thống — văn bản thuần túy dành cho terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Dạng có cấu trúc — dạng mà UI sử dụng
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Khóa phải được bật allowUsageCommand (mặc định là tắt — trình quản lý khóa API trên bảng điều khiển bật/tắt tùy chọn này cho từng khóa). Nếu không, endpoint sẽ trả về 403.

?format=json trả về một cấu trúc phân biệt để trình gọi không bao giờ đọc trường dữ liệu từ một phản hồi từ chối. Khi thành công:

{
  "allowed": true,
  // chỉ xuất hiện khi khóa chọn sử dụng giới hạn mức dùng theo từng khóa (USD hằng ngày/hằng tuần):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // ảnh chụp hạn mức của nhà cung cấp đã chọn, hoặc null khi chưa có gì được lưu vào bộ nhớ đệm:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // ảnh chụp của mọi kết nối để UI có thể hiển thị nhiều nhà cung cấp cạnh nhau:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

Khi bị từ chối (401 khóa không hợp lệ / 403 không được phép), cùng route đó trả về { "allowed": false, "error": { "message": "…" } } — personal/provider có mặt nhưng trống (khóa được cho phép, nhưng chưa thu thập được dữ liệu) là trạng thái khác với bị từ chối, và chỉ dạng JSON mới phân biệt được chúng.

Xác thực: Khóa API Bearer của chính trình gọi, được xác thực bằng isValidApiKey — đây không phải là bề mặt quản lý (/api/keys/…), vốn vẫn được bảo vệ bởi requireManagementAuth.

---

Bộ nhớ đệm ngữ nghĩa

# Lấy số liệu thống kê bộ nhớ đệm
GET /api/cache/stats

# Xóa toàn bộ bộ nhớ đệm
DELETE /api/cache/stats

Ví dụ phản hồi:

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

Ảnh hưởng đến độ trễ

Một HIT của bộ nhớ đệm ngữ nghĩa phục vụ phản hồi từ bộ nhớ đệm mà không thực hiện lệnh gọi ngược dòng, do đó X-OmniRoute-Response-Latency được báo cáo gần bằng không (bất kể độ trễ ngược dòng ban đầu). Các client nhạy cảm với độ trễ (đo điểm chuẩn, giám sát p50/p99) nên kiểm tra header phản hồi X-OmniRoute-Cache-Latency:

Giá trị	Ý nghĩa
synthetic	Phản hồi được phục vụ từ bộ nhớ đệm; độ trễ không phải thời gian ngược dòng thực tế
(không có)	Phản hồi từ lệnh gọi ngược dòng thực tế

Bỏ qua bộ nhớ đệm theo từng khóa

Các khóa API có thể không sử dụng thao tác đọc bộ nhớ đệm ngữ nghĩa thông qua cacheDefaultMode:

Giá trị	Hành vi
legacy	Hành vi bộ nhớ đệm thông thường (mặc định)
bypass	Bỏ qua hoàn toàn việc tra cứu bộ nhớ đệm; luôn gọi ngược dòng

Thiết lập khi tạo khóa (POST /api/keys) hoặc cập nhật (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Bỏ qua theo từng yêu cầu

Bất kỳ yêu cầu nào cũng có thể bỏ qua bộ nhớ đệm bất kể cài đặt của khóa:

X-OmniRoute-No-Cache: true

---

Bảng điều khiển & Quản lý

Các route quản lý (/api/* ngoại trừ xác thực/đăng nhập công khai) không được cấp quyền bằng các khóa API suy luận thông thường. Các nhóm thông tin xác thực, phạm vi và ví dụ curl: Xác thực quản lý.

Xác thực

Endpoint	Phương thức	Mô tả
/api/auth/login	POST	Đăng nhập
/api/auth/logout	POST	Đăng xuất
/api/settings/require-login	GET/PUT	Bật/tắt yêu cầu đăng nhập

Quản lý nhà cung cấp

Endpoint	Phương thức	Mô tả
/api/providers	GET/POST	Liệt kê / tạo nhà cung cấp
/api/providers/[id]	GET/PUT/DELETE	Quản lý một nhà cung cấp
/api/providers/[id]/test	POST	Kiểm tra kết nối với nhà cung cấp
/api/providers/[id]/models	GET	Liệt kê các mô hình của nhà cung cấp
/api/providers/validate	POST	Xác thực cấu hình nhà cung cấp
/api/providers/bulk	POST	Thêm hàng loạt khóa API cho MỘT nhà cung cấp
/api/providers/import	POST	Nhập một DANH SÁCH nhà cung cấp không đồng nhất từ tệp CSV/JSON đã phân tích cú pháp (#6836); kết quả lỗi một phần theo từng hàng
/api/provider-nodes*	Nhiều phương thức	Quản lý nút nhà cung cấp
/api/provider-models	GET/POST/PATCH/DELETE	Mô hình tùy chỉnh (thêm, cập nhật, ẩn/hiện, xóa)

Luồng OAuth

Endpoint	Phương thức	Mô tả
/api/oauth/[provider]/[action]	Nhiều phương thức	OAuth dành riêng cho nhà cung cấp

Định tuyến & Cấu hình

Endpoint	Phương thức	Mô tả
/api/models/alias	GET/POST	Bí danh mô hình
/api/models/catalog	GET	Tất cả mô hình theo nhà cung cấp + loại
/api/combos*	Nhiều phương thức	Quản lý tổ hợp
/api/keys*	Nhiều phương thức	Quản lý khóa API
/api/pricing	GET	Giá mô hình

Mức sử dụng & Phân tích

Điểm cuối	Phương thức	Mô tả
/api/usage/history	GET	Lịch sử sử dụng
/api/usage/logs	GET	Nhật ký sử dụng
/api/usage/request-logs	GET	Nhật ký cấp độ yêu cầu
/api/usage/[connectionId]	GET	Mức sử dụng theo từng kết nối
/api/usage/token-limits	GET/POST/DELETE	Ngân sách giới hạn token theo từng khóa API
/api/usage/model-latency-stats	GET	Số liệu tổng hợp luân phiên về độ trễ theo từng nhà cung cấp/mô hình (trung bình/p50/p95/p99, tỷ lệ thành công); bộ lọc: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	Bản tóm tắt tình trạng bộ nhớ đệm prompt dựa trên call_logs — tỷ lệ ghi/đọc, phân phối kích thước ghi p50/p90/p99, mức độ tập trung của các lượt ghi lớn, phân tách theo từng mô hình và kết luận healthy/degraded/thrash/no-data; tham số truy vấn range (1h|24h|7d|30d, mặc định 24h) và model tùy chọn (#8827)

Cài đặt

Điểm cuối	Phương thức	Mô tả
/api/settings	GET/PUT/PATCH	Cài đặt chung
/api/settings/proxy	GET/PUT	Cấu hình proxy mạng
/api/settings/proxy/test	POST	Kiểm tra kết nối proxy
/api/settings/ip-filter	GET/PUT	Danh sách cho phép/chặn IP
/api/settings/thinking-budget	GET/PUT	Chế độ ghi lại yêu cầu suy nghĩ/lập luận (truyền nguyên trạng / tự động loại bỏ / tùy chỉnh / thích ứng). Độc lập với tính năng nén. Xem THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Prompt hệ thống toàn cục
/api/settings/compression	GET/PUT	Cấu hình nén toàn cục
/api/settings/purge-request-history	POST	Xóa các hàng nhật ký yêu cầu và thành phần lạ nhật ký cuộc gọi cục bộ

Ngữ cảnh & Nén

Điểm cuối	Phương thức	Mô tả
/api/compression/preview	POST	Xem trước chế độ nén off/lite/standard/aggressive/ultra/RTK/stacked
/api/compression/language-packs	GET	Liệt kê các gói ngôn ngữ Caveman có sẵn
/api/compression/rules	GET	Liệt kê siêu dữ liệu quy tắc Caveman
/api/context/caveman/config	GET/PUT	Bí danh cho các cài đặt dành riêng cho Caveman
/api/context/rtk/config	GET/PUT	Cài đặt dành riêng cho RTK, bao gồm bộ lọc tùy chỉnh và lưu giữ đầu ra thô
/api/context/rtk/filters	GET	Danh mục bộ lọc RTK và thông tin chẩn đoán bộ lọc tùy chỉnh
/api/context/rtk/test	POST	Chạy bản xem trước/kiểm thử RTK với một tải trọng văn bản
/api/context/rtk/raw-output/[id]	GET	Đọc đầu ra thô đã biên tập và được lưu giữ theo id con trỏ
/api/context/combos	GET/POST	Liệt kê/tạo tổ hợp nén
/api/context/combos/[id]	GET/PUT/DELETE	Xem chi tiết/cập nhật/xóa tổ hợp nén
/api/context/combos/[id]/assignments	GET/PUT	Gán các tổ hợp nén cho các tổ hợp định tuyến
/api/context/analytics	GET	Bí danh phân tích nén

Giám sát

Điểm cuối	Phương thức	Mô tả
/api/sessions	GET	Theo dõi các phiên đang hoạt động
/api/rate-limits	GET	Giới hạn tốc độ theo từng tài khoản
/api/monitoring/health	GET	Kiểm tra tình trạng + tóm tắt nhà cung cấp (catalogCount, configuredCount, activeCount, monitoredCount). Chế độ xem quản lý bao gồm credentialHealth: các giá trị vô hướng của bộ nhớ đệm thăm dò, failedConnections khi failed>0 và staleDbNonOkCount (test_status cố định của SQLite, không phải chỉ số đo). Xem MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Thống kê/xóa bộ nhớ đệm
/api/modality-bridge/stats	GET	attempts trong bộ nhớ, số lần thành công/bridged, số lần thất bại, số lần trúng bộ nhớ đệm, totalLatencyMs, latencySamples, averageLatencyMs tính theo số mẫu và thời điểm sử dụng gần nhất (đặt lại khi khởi động lại; xác thực quản lý)
/api/modality-bridge/video/runtime	GET	Kiểm tra nghiêm ngặt vòng lặp cục bộ đáng tin cậy trước khi xác thực/thăm dò quản lý; trạng thái khả dụng và phiên bản FFmpeg/ffprobe đã được làm sạch (không lưu trữ)
/api/modality-bridge/video/extract	POST	Bộ môi giới byte nội bộ có xác thực trên vòng lặp cục bộ đáng tin cậy; đầu vào 50 MiB, hàng đợi có giới hạn/đầu ra 32 MiB, 503 khi hết dung lượng, 499 khi ngắt kết nối, 504 khi quá hạn; không phải API tải lên công khai

Sao lưu & Xuất/Nhập

Endpoint	Phương thức	Mô tả
/api/db-backups	GET	Liệt kê các bản sao lưu hiện có
/api/db-backups	PUT	Tạo bản sao lưu thủ công
/api/db-backups	POST	Khôi phục từ một bản sao lưu cụ thể
/api/db-backups/export	GET	Tải cơ sở dữ liệu xuống dưới dạng tệp .sqlite
/api/db-backups/import	POST	Tải tệp .sqlite lên để thay thế cơ sở dữ liệu
/api/db-backups/exportAll	GET	Tải bản sao lưu đầy đủ dưới dạng tệp lưu trữ .tar.gz

Đồng bộ đám mây

Endpoint	Phương thức	Mô tả
/api/sync/cloud	Nhiều loại	Các thao tác đồng bộ đám mây
/api/sync/initialize	POST	Khởi tạo đồng bộ
/api/cloud/*	Nhiều loại	Quản lý đám mây

Đường hầm

Endpoint	Phương thức	Mô tả
/api/tunnels/cloudflared	GET	Đọc trạng thái cài đặt/hoạt động của Cloudflare Quick Tunnel cho bảng điều khiển
/api/tunnels/cloudflared	POST	Bật hoặc tắt Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok	GET	Đọc trạng thái hoạt động của ngrok Tunnel cho bảng điều khiển
/api/tunnels/ngrok	POST	Bật hoặc tắt ngrok Tunnel (action=enable/disable)

Công cụ CLI

Endpoint	Phương thức	Mô tả
/api/cli-tools/claude-settings	GET	Trạng thái Claude CLI
/api/cli-tools/codex-settings	GET	Trạng thái Codex CLI
/api/cli-tools/droid-settings	GET	Trạng thái Droid CLI
/api/cli-tools/openclaw-settings	GET	Trạng thái OpenClaw CLI
/api/cli-tools/runtime/[toolId]	GET	Môi trường chạy CLI chung

Phản hồi CLI bao gồm: installed, runnable, command, commandPath, runtimeMode, reason.

Tác nhân ACP

Endpoint	Phương thức	Mô tả
/api/acp/agents	GET	Liệt kê tất cả tác nhân được phát hiện (tích hợp sẵn + tùy chỉnh) cùng trạng thái
/api/acp/agents	POST	Thêm tác nhân tùy chỉnh hoặc làm mới bộ nhớ đệm phát hiện
/api/acp/agents	DELETE	Xóa tác nhân tùy chỉnh theo tham số truy vấn id

Phản hồi GET bao gồm agents[] (id, tên, tệp nhị phân, phiên bản, đã cài đặt, giao thức, tùy chỉnh) và summary (tổng số, đã cài đặt, không tìm thấy, tích hợp sẵn, tùy chỉnh).

Khả năng phục hồi & Giới hạn tốc độ

Endpoint	Phương thức	Mô tả
/api/resilience	GET/PATCH	Lấy/cập nhật hàng đợi yêu cầu, thời gian chờ kết nối, bộ ngắt nhà cung cấp và các thiết lập chờ
/api/resilience/reset	POST	Đặt lại các bộ ngắt mạch của nhà cung cấp
/api/resilience/model-cooldowns	GET	Liệt kê các khóa đang hoạt động theo từng (nhà cung cấp, kết nối, mô hình), sắp xếp theo thời gian còn lại
/api/resilience/model-cooldowns	DELETE	Xóa khóa mô hình — phần thân {provider, model} hoặc {all: true} để xóa toàn bộ
/api/rate-limits	GET	Trạng thái giới hạn tốc độ theo từng tài khoản
/api/rate-limit	GET	Cấu hình giới hạn tốc độ toàn cục

Cả bốn tuyến /api/resilience/* đều yêu cầu xác thực quản lý (requireManagementAuth). Xem Khả năng phục hồi (mở rộng) để biết phân tích đầy đủ về bộ ngắt nhà cung cấp, thời gian chờ kết nối và khóa mô hình.

Đánh giá

Endpoint	Phương thức	Mô tả
/api/evals	GET/POST	Liệt kê các bộ đánh giá / chạy đánh giá

Chính sách

Endpoint	Phương thức	Mô tả
/api/policies	GET/POST/DELETE	Quản lý các chính sách định tuyến

Tuân thủ

Endpoint	Phương thức	Mô tả
/api/compliance/audit-log	GET	Nhật ký kiểm tra tuân thủ (N mục gần nhất)

v1beta (Tương thích với Gemini)

Endpoint	Phương thức	Mô tả
/v1beta/models	GET	Liệt kê các mô hình theo định dạng Gemini
/v1beta/models/{...path}	POST	Endpoint generateContent của Gemini

Các endpoint này mô phỏng định dạng API của Gemini dành cho các ứng dụng khách yêu cầu khả năng tương thích với SDK Gemini gốc.

API nội bộ / hệ thống

Điểm cuối	Phương thức	Mô tả
/api/init	GET	Kiểm tra khởi tạo ứng dụng (được dùng trong lần chạy đầu tiên)
/api/tags	GET	Các thẻ mô hình tương thích với Ollama (dành cho máy khách Ollama)
/api/restart	POST	Kích hoạt khởi động lại máy chủ một cách an toàn
/api/shutdown	POST	Kích hoạt tắt máy chủ một cách an toàn
/api/system/env/repair	POST	Sửa chữa các biến môi trường của nhà cung cấp OAuth

Lưu ý: Các điểm cuối này được hệ thống sử dụng nội bộ hoặc để đảm bảo khả năng tương thích với máy khách Ollama. Người dùng cuối thường không gọi các điểm cuối này.

Sửa chữa môi trường OAuth (v3.6.1+)

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

{
  "provider": "claude-code"
}

Sửa chữa các biến môi trường OAuth bị thiếu hoặc hỏng cho một nhà cung cấp cụ thể. Trả về:

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

---

Phiên âm thanh

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

Phiên âm các tệp âm thanh bằng bất kỳ nhà cung cấp STT nào đã được cấu hình. Phân đoạn đầu tiên của đường dẫn chọn nhà cung cấp gốc (openai/…, deepgram/…). Các cổng kết nối cung cấp lại mô hình của nhà cung cấp khác sử dụng id đầy đủ (openrouter/deepgram/nova-3).

Yêu cầu:

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

Phản hồi:

{
  "text": "Hello, this is the transcribed audio content.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}

Ví dụ về id mô hình: openai/whisper-1 (yêu cầu khóa OpenAI), openrouter/deepgram/nova-3 (yêu cầu khóa OpenRouter), deepgram/nova-3 (yêu cầu khóa Deepgram gốc). Yêu cầu deepgram/nova-3 thuần túy không sử dụng OpenRouter.

Các định dạng được hỗ trợ: mp3, wav, m4a, flac, ogg, webm.

---

Khả năng tương thích với Ollama

Dành cho các client sử dụng định dạng API của Ollama:

# Điểm cuối trò chuyện (định dạng Ollama)
POST /v1/api/chat

# Danh sách mô hình (định dạng Ollama)
GET /api/tags

Các yêu cầu được tự động chuyển đổi giữa định dạng Ollama và định dạng nội bộ.

Bí danh được mã hóa bằng token cho VS Code / Không cần header

Sử dụng các bí danh này khi một tích hợp không thể chèn header Authorization và cần nhúng khóa API vào URL cơ sở.

# Bí danh danh mục theo kiểu OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Bí danh trò chuyện theo kiểu OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Bí danh theo kiểu Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Ví dụ:

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"}]}'

Lưu ý:

• Các bí danh được mã hóa bằng token tái sử dụng cùng các trình xử lý như /v1/* và /api/tags; cấu trúc phản hồi vẫn giữ nguyên.
• Ưu tiên sử dụng Authorization: Bearer ... bất cứ khi nào client hỗ trợ header tùy chỉnh.
• Token dựa trên URL có thể xuất hiện trong nhật ký reverse proxy, lịch sử trình duyệt và dữ liệu đo từ xa bên ngoài OmniRoute. Hãy coi chúng là một tùy chọn tương thích, không phải chế độ xác thực mặc định.

---

Dữ liệu đo từ xa

# Lấy bản tóm tắt dữ liệu đo độ trễ (p50/p95/p99 cho mỗi nhà cung cấp)
GET /api/telemetry/summary

Phản hồi:

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

---

Ngân sách

# Lấy trạng thái ngân sách cho tất cả các khóa API
GET /api/usage/budget

# Đặt hoặc cập nhật ngân sách
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"
}

Ghi chú về schema (setBudgetSchema): apiKeyId là bắt buộc; ít nhất một trong các trường dailyLimitUsd, weeklyLimitUsd hoặc monthlyLimitUsd phải lớn hơn 0. Các trường tùy chọn: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Cấu trúc cũ {keyId, limit, period} trả về 400 Bad Request.

Giới hạn token

Ngân sách token theo từng khóa API (khác với Ngân sách dựa trên USD ở trên). Được thực thi trực tiếp trên luồng xử lý yêu cầu: khi mức sử dụng trong cửa sổ hiện tại của một khóa đạt đến giới hạn, các yêu cầu sẽ bị từ chối với 429 Too Many Requests. Các giới hạn có thể được áp dụng cho một model, một provider cụ thể hoặc áp dụng global trên toàn bộ khóa; khi có nhiều giới hạn khớp với một yêu cầu, giới hạn nghiêm ngặt nhất sẽ được áp dụng.

# Liệt kê các giới hạn token của một khóa (bao gồm mức sử dụng trực tiếp trong cửa sổ)
GET /api/usage/token-limits?apiKeyId=key-123

# Tạo hoặc cập nhật một giới hạn 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
}

# Xóa một giới hạn token theo id
DELETE /api/usage/token-limits?id=tl-abc

Ghi chú về schema (setTokenLimitSchema): apiKeyId và scopeType (model | provider | global) là bắt buộc. scopeValue là bắt buộc trừ khi scopeType là global (ví dụ: id mô hình cho phạm vi model, id nhà cung cấp cho phạm vi provider). tokenLimit phải là một số nguyên dương (được ép kiểu từ chuỗi). Tùy chọn: id (bỏ qua để tạo mới, cung cấp để cập nhật), resetInterval (daily | weekly | monthly, mặc định là monthly), resetTime (HH:MM), enabled (mặc định là true). Phản hồi GET bổ sung cho mỗi giới hạn các trường tokensUsed, remaining, windowStart, periodStartAt và nextResetAt. Đây là endpoint thuộc lớp quản lý (việc xác thực được thực thi tập trung bởi quy trình authz).

Xử lý yêu cầu

1. Máy khách gửi yêu cầu đến /v1/*
2. Trình xử lý tuyến gọi handleChat, handleEmbedding, handleAudioTranscription hoặc handleImageGeneration
3. Mô hình được phân giải (nhà cung cấp/mô hình trực tiếp hoặc bí danh/combo)
4. Thông tin xác thực được chọn từ cơ sở dữ liệu cục bộ, có lọc theo tính khả dụng của tài khoản
5. Đối với chat: handleChatCore kiểm tra bộ nhớ đệm ngữ nghĩa/chữ ký và phân giải các cài đặt nén của combo
6. Tính năng nén chủ động chạy trước bước chuyển đổi cho nhà cung cấp khi được bật (lite, Caveman, RTK hoặc kết hợp nhiều lớp)
7. Bộ thực thi của nhà cung cấp gửi yêu cầu ngược dòng
8. Phản hồi được chuyển đổi trở lại định dạng của máy khách (chat) hoặc được trả về nguyên trạng (embeddings/hình ảnh/âm thanh)
9. Mức sử dụng, dữ liệu phân tích về nén và nhật ký yêu cầu được ghi lại
10. Cơ chế dự phòng được áp dụng khi xảy ra lỗi theo các quy tắc của combo

Tài liệu tham khảo kiến trúc đầy đủ: ARCHITECTURE.md

---

Quản lý combo

Các combo định tuyến cấp cao hơn (đã được tóm tắt trong /api/combos*) cũng có thể được ánh xạ 1:1 từ một mẫu id mô hình, cho phép chuyển hướng minh bạch một id mô hình kiểu OpenAI đến một combo.

Phương thức	Đường dẫn	Mô tả
GET	/api/model-combo-mappings	Liệt kê tất cả ánh xạ mô hình→combo
POST	/api/model-combo-mappings	Tạo ánh xạ — phần thân: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	Truy xuất một ánh xạ
PUT	/api/model-combo-mappings/[id]	Cập nhật các trường của một ánh xạ hiện có
DELETE	/api/model-combo-mappings/[id]	Xóa một ánh xạ

Xác thực: phiên quản lý/khóa API (requireManagementAuth).

---

Webhook

Đăng ký webhook gửi đi cho các sự kiện OmniRoute (hoàn tất yêu cầu, cạn hạn ngạch, xoay vòng khóa, v.v.).

Phương thức	Đường dẫn	Mô tả
GET	/api/webhooks	Liệt kê các webhook (secret được che thành <prefix>...)
POST	/api/webhooks	Tạo webhook — phần thân: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Truy xuất một webhook
PUT	/api/webhooks/[id]	Cập nhật url/events/secret/description
DELETE	/api/webhooks/[id]	Xóa một webhook
POST	/api/webhooks/[id]/test	Gửi payload thử nghiệm đến URL webhook và trả về trạng thái phân phối

Xác thực: phiên quản lý/khóa API (requireManagementAuth).

---

Khóa đã đăng ký (Tự động quản lý)

Được hệ thống con quản lý khóa tự động sử dụng để cấp và xoay vòng khóa API với nhà cung cấp/tài khoản nền tảng, kèm hạn ngạch hằng ngày/hằng giờ.

Phương thức	Đường dẫn	Mô tả
GET	/api/v1/registered-keys	Liệt kê các khóa đã đăng ký (chỉ hiển thị tiền tố đã được che)
POST	/api/v1/registered-keys	Cấp khóa đã đăng ký mới — phần thân: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Trả về khóa thô một lần duy nhất. Trả về 429 khi bị từ chối do hạn ngạch.
GET	/api/v1/registered-keys/[id]	Truy xuất siêu dữ liệu của khóa đã đăng ký (không có dữ liệu khóa thô)
DELETE	/api/v1/registered-keys/[id]	Thu hồi một khóa đã đăng ký
POST	/api/v1/registered-keys/[id]/revoke	Điểm cuối thu hồi rõ ràng (có cùng hiệu lực như DELETE)

Xác thực: khóa API Bearer (isAuthenticated). Xem thêm /v1/quotas/check và /v1/issues/report.

---

Giao thức tác nhân

Các tác vụ tác nhân đám mây (Claude Code, Codex Cloud, OpenHands, v.v.) được thực thi từ xa thay mặt người dùng OmniRoute.

Phương thức	Đường dẫn	Mô tả
GET	/api/v1/agents/tasks	Liệt kê tác vụ — tùy chọn ?provider=, ?status=, ?limit= (1–500, mặc định 50)
POST	/api/v1/agents/tasks	Tạo tác vụ — phần thân được xác thực bằng CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Trả về 201 cùng với phong bì tác vụ
DELETE	/api/v1/agents/tasks?id=...	Xóa một tác vụ
GET	/api/v1/agents/tasks/[id]	Đọc tác vụ — làm mới đồng bộ trạng thái từ tác nhân đám mây thượng nguồn khi external_id được đặt
POST	/api/v1/agents/tasks/[id]	Hành động phân biệt: {action: "approve"}, {action: "message", message}, hoặc {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	Xóa một tác vụ cụ thể theo id

Xác thực: yêu cầu xác thực quản lý cho mọi phương thức (requireCloudAgentManagementAuth). Trước v3.8.0, các phương thức này không yêu cầu xác thực — xem commit 588a0333 để biết thay đổi gây mất tương thích.

# Tạo một tác vụ đám mây 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":"..."}}'

---

Proxy quản lý

Các proxy HTTP(S)/SOCKS đi ra có thể được gán cho nhà cung cấp, tài khoản hoặc trên toàn cục.

Phương thức	Đường dẫn	Mô tả
GET	/api/v1/management/proxies	Liệt kê proxy (với ?id= trả về một proxy; với ?id=&where_used=1 trả về biểu đồ phân công)
POST	/api/v1/management/proxies	Tạo proxy — phần thân được xác thực bằng createProxyRegistrySchema
PATCH	/api/v1/management/proxies	Cập nhật proxy — phần thân được xác thực bằng updateProxyRegistrySchema (yêu cầu id)
DELETE	/api/v1/management/proxies?id=...&force=1	Xóa proxy (dùng force=1 để gỡ các phân công)
GET	/api/v1/management/proxies/assignments	Liệt kê các phân công — có thể lọc theo proxy_id, scope, scope_id; truyền resolve_connection_id=<id> để phân giải proxy đang hoạt động cho một kết nối
PUT	/api/v1/management/proxies/assignments	Gán — phần thân được xác thực bằng proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Xóa bộ nhớ đệm của bộ điều phối
PUT	/api/v1/management/proxies/bulk-assign	Gán hàng loạt — phần thân được xác thực bằng bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Tổng hợp tình trạng proxy (số lần thành công/thất bại, độ trễ) trong một khoảng thời gian

Xác thực: phiên quản lý/khóa API trên mọi route (requireManagementAuth).

POST /api/v1/management/proxies/[id]/assignments và POST /api/v1/management/proxies/[id]/health trong phần mô tả tác vụ được phục vụ bởi các route phẳng /assignments và /health nêu trên — không có route con theo từng id trong cơ sở mã.

---

Khả năng phục hồi (mở rộng)

OmniRoute cung cấp ba cơ chế xử lý lỗi tạm thời độc lập; các endpoint quản lý bên dưới cho phép người vận hành xem và ghi đè chúng:

Phạm vi	Nơi lưu trữ trạng thái	Xem	Đặt lại / xóa
Bộ ngắt mạch nhà cung cấp	domain_circuit_breakers + trong bộ nhớ	/api/monitoring/health	POST /api/resilience/reset
Thời gian chờ kết nối	rateLimitedUntil trên các kết nối của nhà cung cấp	/api/rate-limits, /api/providers/[id]	(được bật lại khi cần; xóa thông qua PUT nhà cung cấp)
Khóa mô hình	Sổ đăng ký tính khả dụng của mô hình trong bộ nhớ	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience chấp nhận các giá trị ghi đè cho bộ ngắt mạch nhà cung cấp trong providerBreaker.oauth và providerBreaker.apikey. Mỗi hồ sơ hỗ trợ degradationThreshold, failureThreshold và resetTimeoutMs; các trường tương tự cũng có trong Bảng điều khiển → Cài đặt → Khả năng phục hồi.

# Xóa trạng thái khóa của một mô hình
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"}'

# Xóa toàn bộ trạng thái khóa
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Tài liệu tham khảo khái niệm đầy đủ và các giá trị mặc định của bộ ngắt mạch: xem CLAUDE.md → "Trạng thái thời gian chạy của khả năng phục hồi".

---

Kỹ năng

Khung kỹ năng để mở rộng OmniRoute bằng các trình xử lý thực thi tùy chỉnh, cùng với các tích hợp marketplace.

Phương thức	Đường dẫn	Mô tả
GET	/api/skills	Liệt kê các kỹ năng đã cài đặt — có thể lọc bằng ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, có phân trang
GET	/api/skills/[id]	Truy xuất một kỹ năng
PUT	/api/skills/[id]	Cập nhật kỹ năng (tên, mô tả, chế độ, lược đồ, trình xử lý, thẻ)
DELETE	/api/skills/[id]	Gỡ cài đặt một kỹ năng
POST	/api/skills/install	Cài đặt kỹ năng từ manifest thô — phần thân: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	Liệt kê các lần thực thi kỹ năng gần đây (nhật ký kiểm tra gồm đầu vào/đầu ra/thời lượng)
GET	/api/skills/marketplace?q=...	Tìm kiếm/danh sách phổ biến từ marketplace SkillsMP (yêu cầu cài đặt skillsmpApiKey)
POST	/api/skills/marketplace/install	Cài đặt kỹ năng theo id từ SkillsMP
GET	/api/skills/skillssh?q=&limit=	Tìm kiếm trong registry skills.sh
POST	/api/skills/skillssh/install	Cài đặt kỹ năng theo id từ skills.sh

Xác thực: phiên quản lý/khóa API. Các route tìm kiếm trên marketplace chấp nhận xác thực quản lý hoặc khóa API Bearer (isAuthenticated).

---

Bộ nhớ

Kho lưu trữ bộ nhớ hội thoại/thông tin thực tế lâu dài, được giới hạn theo khóa API / phiên.

Phương thức	Đường dẫn	Mô tả
GET	/api/memory	Liệt kê bộ nhớ — ?apiKeyId=, ?type=, ?sessionId=, ?q=, với phân trang offset/limit hoặc page/limit
POST	/api/memory	Tạo bộ nhớ — phần thân được Zod xác thực: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	Truy xuất một bộ nhớ
DELETE	/api/memory/[id]	Xóa một bộ nhớ
GET	/api/memory/health	Tình trạng của hệ thống con bộ nhớ (khả năng kết nối DB, backend embeddings, trạng thái chỉ mục vector)

Xác thực: phiên quản lý/khóa API (requireManagementAuth). Enum type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (xem MemoryType trong src/lib/memory/types.ts).

---

Máy chủ MCP

OmniRoute đi kèm một máy chủ Model Context Protocol tích hợp sẵn với 3 phương thức truyền tải (stdio, SSE, streamable-http) và các công cụ có phạm vi. Các endpoint bảng điều khiển bên dưới đọc dữ liệu trạng thái/kiểm tra và làm proxy cho các phương thức truyền tải HTTP.

Phương thức	Đường dẫn	Mô tả
GET	/api/mcp/status	Nhịp tim, phương thức truyền tải, trạng thái trực tuyến, lần gọi gần nhất, công cụ hàng đầu, tỷ lệ thành công trong 24 giờ
GET	/api/mcp/tools	Danh sách các công cụ MCP với name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	Mở luồng SSE cho phương thức truyền tải SSE (trả về 503 nếu MCP bị vô hiệu hóa hoặc phương thức truyền tải không khớp)
POST	/api/mcp/sse	Gửi khung JSON-RPC qua phương thức truyền tải SSE
GET	/api/mcp/stream	Mở phía SSE của phương thức truyền tải Streamable HTTP (thông báo do máy chủ khởi tạo)
POST	/api/mcp/stream	Gửi khung JSON-RPC qua phương thức truyền tải Streamable HTTP
DELETE	/api/mcp/stream	Kết thúc một phiên Streamable HTTP
GET	/api/mcp/audit	Truy vấn nhật ký kiểm tra — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Số liệu thống kê kiểm tra tổng hợp (tổng số, tỷ lệ thành công, thời lượng trung bình, công cụ hàng đầu)

Xác thực: các phương thức truyền tải sse/stream tuân theo cơ chế xác thực dành riêng cho MCP (khóa API Bearer có phạm vi mcp); các route status/tools/audit* có thể được đọc từ bảng điều khiển (không yêu cầu xác thực bổ sung ngoài khả năng truy cập máy chủ bảng điều khiển).

Cả hai phương thức truyền tải HTTP đều được kiểm soát bởi settings.mcpEnabled và settings.mcpTransport — phương thức truyền tải không khớp sẽ trả về 400, trạng thái MCP bị vô hiệu hóa sẽ trả về 503.

---

Máy chủ A2A

OmniRoute cung cấp một điểm cuối A2A (Agent-to-Agent) JSON-RPC 2.0 cùng với một lớp bọc REST dùng cho việc kiểm tra/bảng điều khiển.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # không bắt buộc trừ khi OMNIROUTE_API_KEY được thiết lập
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Định tuyến tác vụ lập trình này"}]
  }
}

Các phương thức được hỗ trợ (tất cả đều chịu sự kiểm soát của settings.a2aEnabled):

Phương thức	Mô tả
message/send	Thực thi kỹ năng đồng bộ; trả về {task, artifacts, metadata}
message/stream	Thực thi truyền luồng SSE cho cùng một tập hợp kỹ năng
tasks/get	Truy xuất một tác vụ theo taskId
tasks/cancel	Hủy một tác vụ theo taskId

Các kỹ năng tích hợp sẵn: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Thẻ tác nhân

GET /.well-known/agent.json

Trả về thẻ tác nhân A2A công khai (tên, mô tả, khả năng, danh mục kỹ năng, cơ chế xác thực) — được lưu vào bộ nhớ đệm công khai trong 1 giờ. Không yêu cầu xác thực.

Trình trợ giúp REST

Phương thức	Đường dẫn	Mô tả
GET	/api/a2a/status	Trạng thái bật A2A + thống kê tác vụ + bản tóm tắt thẻ tác nhân đã lưu trong bộ nhớ đệm
GET	/api/a2a/tasks	Liệt kê tác vụ — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(Chưa được triển khai dưới dạng trình trợ giúp REST — tạo qua JSON-RPC message/send)
GET	/api/a2a/tasks/[id]	Truy xuất một tác vụ
POST	/api/a2a/tasks/[id]/cancel	Hủy một tác vụ

Xác thực: các trình trợ giúp REST chạy mà không cần xác thực quản trị (bảng điều khiển có thể đọc); tuyến JSON-RPC /a2a sử dụng Bearer OMNIROUTE_API_KEY nếu được cấu hình.

---

Đám mây, Đánh giá & Thẩm định

Phương thức	Đường dẫn	Mô tả
POST	/api/cloud/auth	Xác minh khóa Bearer và trả về các kết nối nhà cung cấp đã che thông tin + bí danh mô hình cho các ứng dụng đồng bộ hóa đám mây
POST	/api/cloud/credentials/update	Cập nhật thông tin xác thực đã mã hóa cho một nhà cung cấp được đồng bộ hóa với đám mây
POST	/api/cloud/model/resolve	Phân giải ID mô hình logic thành nhà cung cấp/mô hình cụ thể bằng bảng định tuyến cục bộ
GET	/api/cloud/models/alias	Liệt kê các bí danh mô hình được cung cấp cho quá trình đồng bộ hóa đám mây
GET	/api/assess	Đọc các phân loại thẩm định mới nhất (theo từng nhà cung cấp/mô hình)
POST	/api/assess	Chạy một lần thẩm định — nội dung: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Liệt kê các bộ đánh giá tích hợp sẵn + những lần chạy gần đây nhất
POST	/api/evals	Kích hoạt một lần chạy đánh giá
POST	/api/evals/suites	Tạo một bộ đánh giá tùy chỉnh — nội dung được xác thực bởi evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Truy xuất một bộ đánh giá tùy chỉnh

Xác thực: /api/cloud/auth xác thực trực tiếp khóa Bearer; các tuyến /api/cloud/*, /api/evals/* và /api/assess khác yêu cầu phiên/khóa API quản trị. Phương thức POST của /api/assess sử dụng validateBody với lược đồ phạm vi hợp phân biệt.

---

Quản lý ACP (Agent Client Protocol)

dưới dạng các tiến trình con. Các endpoint này quản lý việc phát hiện agent ACP và đăng ký agent tùy chỉnh.

Phương thức	Đường dẫn	Mô tả
GET	/api/acp/agents	Liệt kê tất cả agent CLI đã biết (tích hợp sẵn + tùy chỉnh), cùng trạng thái cài đặt, phiên bản và tệp nhị phân
POST	/api/acp/agents	Đăng ký agent ACP tùy chỉnh hoặc làm mới bộ nhớ đệm — phần thân: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} hoặc {action: "refresh"}
DELETE	/api/acp/agents	Xóa agent ACP tùy chỉnh — tham số truy vấn: ?id=<agentId>

Ví dụ phản hồi (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
}

Xác thực: Yêu cầu phiên quản lý (cookie auth_token của bảng điều khiển) hoặc khóa API có phạm vi quản lý.

Xem Khung ACP để biết đầy đủ chi tiết.

---

Phân tích & Khả năng quan sát

Các endpoint phân tích theo thời gian thực để giám sát việc định tuyến, nén và mức độ đa dạng của nhà cung cấp. Đây là nguồn dữ liệu cho các trang /dashboard/analytics/*.

Phân tích định tuyến tự động

Phương thức	Đường dẫn	Mô tả
GET	/api/analytics/auto-routing	Số liệu thống kê định tuyến tự động tổng hợp: tổng số lệnh gọi, phân bố chiến lược, phân bố cấp độ, nhà cung cấp hàng đầu
GET	/api/analytics/auto-routing?days=7	Số liệu thống kê theo khoảng thời gian (mặc định 24 giờ)

Ví dụ phản hồi:

{
  "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 }
  ]
}

Phân tích nén

Phương thức	Đường dẫn	Mô tả
GET	/api/analytics/compression	Số liệu thống kê nén tổng hợp: số token tiết kiệm được, % tiết kiệm, phân bố chế độ, mức sử dụng công cụ

Ví dụ phản hồi:

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

Theo dõi mức độ đa dạng của nhà cung cấp

Phương thức	Đường dẫn	Mô tả
GET	/api/analytics/diversity	Theo dõi mức độ đa dạng dựa trên entropy Shannon: ngăn chặn điểm lỗi đơn bằng cách đo lường mức độ phân bổ giữa các nhà cung cấp

Ví dụ phản hồi:

{
  "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"]
}

Xác thực: Yêu cầu phiên quản lý hoặc khóa API có phạm vi quản lý.

---

Thao tác quản trị

Các endpoint chỉ dành cho quản trị viên để quản lý vận hành.

Phương thức	Đường dẫn	Mô tả
GET	/api/admin/concurrency	Đọc các giới hạn đồng thời hiện tại (toàn cục + theo từng nhà cung cấp)
POST	/api/admin/concurrency	Cập nhật các giới hạn đồng thời — nội dung: {global?: number, perProvider?: Record<string, number>}

Xác thực: Yêu cầu phiên quản lý có phạm vi quản trị viên.

---

Quản lý công cụ CLI

Quản lý các công cụ CLI tích hợp với OmniRoute (antigravity, chipotle, commandCode, devin-cli, v.v.). Xem Tài liệu tham khảo về nhà cung cấp để biết danh sách đầy đủ.

Phương thức	Đường dẫn	Mô tả
GET	/api/cli-tools/all-statuses	Trạng thái của tất cả công cụ CLI (đã cài đặt, phiên bản, lần cuối được ghi nhận)
GET	/api/cli-tools/status	Chi tiết trạng thái của một công cụ CLI (truy vấn ?tool=)
POST	/api/cli-tools/apply	Ghi cấu hình được tạo cho công cụ (dryRun để xem trước; 422 + containerEphemeralTarget khi được container hóa; migration ghi chú về YAML Codex cũ)
GET	/api/cli-tools/backups	Liệt kê các bản sao lưu cấu hình công cụ CLI
POST	/api/cli-tools/backups	Tạo bản sao lưu cho tất cả cấu hình công cụ CLI
POST	/api/cli-tools/backups	Khôi phục: cùng endpoint với {tool, backupId} trong nội dung yêu cầu sẽ khôi phục bản sao lưu đó
GET	/api/cli-tools/antigravity-mitm	Trạng thái proxy MITM Antigravity (công cụ CLI "antigravity-mitm")
POST	/api/cli-tools/antigravity-mitm/alias	Cấu hình các bí danh antigravity-mitm

Xác thực: Yêu cầu phiên quản lý.

---

Kỹ năng tác tử

Quản lý các kỹ năng của tác tử AI (tương tự GPT tùy chỉnh của OpenAI nhưng dành cho tác tử).

Phương thức	Đường dẫn	Mô tả
GET	/api/agent-skills	Liệt kê tất cả kỹ năng tác tử (tích hợp sẵn + tùy chỉnh)
GET	/api/agent-skills/[id]	Lấy một kỹ năng tác tử cụ thể
POST	/api/agent-skills	Tạo kỹ năng tác tử tùy chỉnh — nội dung: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Cập nhật một kỹ năng tác tử tùy chỉnh
DELETE	/api/agent-skills/[id]	Xóa một kỹ năng tác tử tùy chỉnh
GET	/api/agent-skills/[id]/raw	Lấy lời nhắc thô + siêu dữ liệu (không thực thi)
POST	/api/agent-skills/generate	Sử dụng AI để tạo kỹ năng mới từ mô tả bằng ngôn ngữ tự nhiên

Xác thực: Yêu cầu phiên quản lý hoặc khóa API có phạm vi quản lý.

---

Quản lý bộ nhớ đệm

Quản lý bộ nhớ đệm ngữ nghĩa và bộ nhớ đệm suy luận.

Phương thức	Đường dẫn	Mô tả
GET	/api/cache	Tổng quan bộ nhớ đệm: tổng số mục, tỷ lệ truy xuất thành công, kích thước trên ổ đĩa
GET	/api/cache/entries	Liệt kê các mục được lưu trong bộ nhớ đệm (có phân trang)
DELETE	/api/cache/entries	Xóa các mục trong bộ nhớ đệm (lọc theo tham số truy vấn)
GET	/api/cache/stats	Số liệu thống kê chi tiết về bộ nhớ đệm (theo từng nhà cung cấp, từng mô hình)
GET	/api/cache/reasoning	Trạng thái bộ nhớ đệm suy luận (để phát lại quá trình suy luận)
DELETE	/api/cache/reasoning	Xóa bộ nhớ đệm suy luận — tham số truy vấn: ?toolCallId=<id> (một mục), ?provider=<p> hoặc không có tham số (tất cả)

Xác thực: Yêu cầu phiên quản lý.

---

Hệ thống bộ nhớ

Quản lý bộ nhớ lâu dài (FTS5 + embedding vectơ).

Phương thức	Đường dẫn	Mô tả
GET	/api/memory	Liệt kê các mục bộ nhớ (lọc theo phạm vi, loại, truy vấn tìm kiếm)
POST	/api/memory	Tạo mục bộ nhớ mới — nội dung yêu cầu: {scope, type, content, metadata?}
GET	/api/memory/[id]	Lấy một mục bộ nhớ cụ thể
PUT	/api/memory/[id]	Cập nhật một mục bộ nhớ
DELETE	/api/memory/[id]	Xóa một mục bộ nhớ
GET	/api/memory?q=	Tìm kiếm bộ nhớ (FTS5 + vectơ) — số liệu thống kê được bao gồm trong cùng một phản hồi

Xác thực: Yêu cầu phiên quản lý hoặc khóa API có phạm vi quản lý.

---

Webhook

Quản lý đăng ký webhook cho các sự kiện.

Phương thức	Đường dẫn	Mô tả
GET	/api/webhooks	Liệt kê tất cả đăng ký webhook
POST	/api/webhooks	Tạo đăng ký webhook — nội dung yêu cầu: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Lấy một đăng ký webhook cụ thể
PUT	/api/webhooks/[id]	Cập nhật một đăng ký webhook
DELETE	/api/webhooks/[id]	Xóa một đăng ký webhook
GET	/api/webhooks/[id]/deliveries	Liệt kê lịch sử gửi của webhook (nhật ký thành công/thất bại)
POST	/api/webhooks/[id]/test	Gửi một sự kiện thử nghiệm đến webhook

Xác thực: Yêu cầu phiên quản lý.

Xem Khung Webhook để biết đầy đủ các loại sự kiện.

---

Khung Kỹ năng

Quản lý Kỹ năng (khung tiện ích mở rộng tác tử).

Phương thức	Đường dẫn	Mô tả
GET	/api/skills	Liệt kê tất cả kỹ năng đã cài đặt (tích hợp sẵn + tùy chỉnh)
POST	/api/skills/install	Cài đặt kỹ năng từ đường dẫn cục bộ hoặc URL
DELETE	/api/skills/[id]	Gỡ cài đặt kỹ năng
PUT	/api/skills/[id]	Bật hoặc tắt kỹ năng — nội dung yêu cầu: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Thực thi kỹ năng — nội dung yêu cầu: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	Liệt kê lịch sử thực thi của tất cả kỹ năng (lọc theo ?apiKeyId=)

Xác thực: Yêu cầu phiên quản lý hoặc khóa API có phạm vi quản lý.

Xem Khung Kỹ năng để biết đầy đủ chi tiết.

---

Plugin

Quản lý các plugin OmniRoute (tiện ích mở rộng của bên thứ ba).

Phương thức	Đường dẫn	Mô tả
GET	/api/plugins	Liệt kê các plugin đã cài đặt
POST	/api/plugins/marketplace/install	Cài đặt plugin từ marketplace
DELETE	/api/plugins/[name]	Gỡ cài đặt plugin
POST	/api/plugins/[name]/activate	Kích hoạt plugin
POST	/api/plugins/[name]/deactivate	Hủy kích hoạt plugin
GET	/api/plugins/[name]/config	Lấy cấu hình plugin
PUT	/api/plugins/[name]/config	Cập nhật cấu hình plugin

Xác thực: Yêu cầu phiên quản lý.

Xem Khung Plugin để biết đầy đủ chi tiết.

---

Định tuyến Bóng

Việc so sánh nhà cung cấp theo định tuyến bóng / A-B không phải là một bề mặt REST độc lập — tính năng này được cấu hình thông qua định tuyến tổ hợp (xem Tổ hợp Tự động). Các chỉ số so sánh theo từng tổ hợp được cung cấp bởi GET /api/combos/metrics.

---

Cơ chế Bảo vệ

Kiểm tra các cơ chế bảo vệ trong thời gian chạy (phát hiện PII, phát hiện chèn prompt, cầu nối thị giác). Các cơ chế bảo vệ chạy trên mọi yêu cầu; có thể từ chối tham gia theo từng lệnh gọi thông qua header yêu cầu x-omniroute-disabled-guardrails — không có giao diện bật/tắt được lưu cố định.

Phương thức	Đường dẫn	Mô tả
GET	/api/guardrails	Liệt kê các cơ chế bảo vệ đã đăng ký và trạng thái của chúng (tên / đã bật / mức ưu tiên)
POST	/api/guardrails/test	Chạy thử quy trình trước lệnh gọi trên một đầu vào mẫu — nội dung yêu cầu: {input, disabledGuardrails?}

Xác thực: Yêu cầu phiên quản lý.

Xem Bảo mật > Cơ chế Bảo vệ để biết đầy đủ chi tiết.

---

---

Xác thực

Xem Xác thực quản trị để biết bốn nhóm thông tin xác thực (phiên dashboard, token CLI cục bộ, Access Token oma_live_…, API key có phạm vi quản trị) và điểm khác biệt giữa chúng với các khóa suy luận.

• Các route của dashboard (/dashboard/*) sử dụng cookie auth_token
• Đăng nhập sử dụng hàm băm mật khẩu đã lưu; dự phòng bằng INITIAL_PASSWORD
• Có thể bật/tắt requireLogin qua /api/settings/require-login
• Các route /v1/* có thể yêu cầu Bearer API key khi REQUIRE_API_KEY=true
• “management token” / “management-scoped API key” trong tài liệu tham khảo này có nghĩa là một trong các nhóm được nêu trong hướng dẫn đó — không phải một loại bí mật bổ sung chưa được định nghĩa

Thay đổi không tương thích ngược (v3.8.0) — /api/v1/agents/tasks/* và các endpoint quản lý thời gian chờ hiện yêu cầu xác thực quản trị (cookie auth_token của dashboard hoặc API key có phạm vi quản trị). Các client trước đây gọi những route này mà không xác thực sẽ nhận được 401 Unauthorized. Xem commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).