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

---

🌐 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

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

---

Mục lục

• Hoàn thành hội thoại
• Quyền thuê phiên được quản lý độc quyền
• Nhúng
• 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
• Các 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ý tổ hợp
• Webhook
• Các 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í cho 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 cho tính liên kết phiên bên ngoài
x_session_id	Yêu cầu	Biến thể dùng 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 chuyển vào bộ nhớ). Khi có, giá trị được lưu nguyên trạng vào call_logs.session_tag để phân bổ chi phí theo phiên (#8249) — không bao giờ được tự tạo khi không có
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 được 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 có)
X-OmniRoute-Cost-Saved	Phản hồi	Số USD tiết kiệm được nhờ bộ nhớ đệm khi có HIT (chỉ đối với 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 tổ hợp, hoặc single đối với yêu cầu không phải tổ hợp) — luôn có trong các phản hồi hoàn tất

Lưu ý về Nginx: nếu bạn dựa vào 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ộ header đ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 API hoàn tất trò chuyện, /v1/responses, /v1/messages, và 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 (mỗi hình ảnh, mỗi giây, mỗi ký tự, mỗi đơn vị tìm kiếm) khi có thông tin định giá; nếu không, chi phí là 0 (cho phép tiếp tục khi không xác định được chi phí).

Ngữ nghĩa chi phí khi trúng bộ nhớ đệm: khi TRÚNG bộ nhớ đệm ngữ nghĩa (X-OmniRoute-Cache-Hit: true), không có lệnh gọi nào được gửi đến nhà cung cấp thượng nguồn, do đó X-OmniRoute-Response-Cost là 0.0000000000 (chi phí gia tăng để phục vụ kết quả trúng bộ nhớ đệm). Chi phí ban đầu/đáng lẽ 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 tính tổng X-OmniRoute-Response-Cost (kết quả trúng bộ nhớ đệm không phát sinh chi phí); các hệ thống phân tích bộ nhớ đệm có thể tổng hợp X-OmniRoute-Cost-Saved.

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

Thuê phiên được quản lý độc quyền là một hợp đồng định tuyến tùy chọn, không phụ thuộc vào ứng dụng khách: 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 thuê mô hình, không yêu cầu OAuth, không xác định một ứng dụng khách 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 rõ ràng, 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 lấy, gia hạn và giải phóng thành công cung cấp dấu thời gian, state và 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. Thao tác gia hạn và giải phóng cung cấp thế hệ trong nội dung JSON:

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

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

Chủ sở hữu phiên thuê đang hoạt động có thể yêu cầu rõ ràng siêu dữ liệu 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"
  }
}

Thao tác trạng thái tùy chọn này được bảo vệ bằng chủ sở hữu bất định, khóa API được quản lý đã xác thực và thế hệ đ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 sau khi loại bỏ khoảng trắng thừa; 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, mã định danh thô của kết nối hoặc khóa API, hàm băm chủ sở hữu, bí mật phân rào và dữ liệu định tuyến nội bộ đều bị loại trừ.

Các trường hợp sai khóa, sai chủ sở hữu, thế hệ lỗi thời, không tồn tại, hết hạn, đã giải phóng và đã bị vô hiệu hóa đều trả về cùng lỗi 409 LEASE_FENCE_STALE mà không có siêu dữ liệu kết nối. Ứng dụng khách nhận được phản hồi chờ dung lượng không có liên kết đang hoạt động để kiểm tra. Khi quá trình định tuyến chuyển đổi một phiên thuê đang hoạt động, cùng một thế hệ vẫn hợp lệ và trạng thái sẽ trả về liên kết mới theo cách nguyên tử, không bao giờ trả về liên kết cũ. Các ứng dụng khách hiện có không thay đổi vì phản hồi lấy, gia hạn, giải phóng và chờ vẫn giữ nguyên cấu trúc trước đây.

Hợp đồng máy chủ này không thay đổi /status tiêu chuẩn của OpenAI Codex. Codex tiêu chuẩ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ị siêu dữ liệu tài khoản tùy chỉnh tùy ý của nhà cung cấp; một tích hợp ứng dụng khách sau này phải gọi thao tác 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ý sẽ cung cấp cả hai tiêu đề đ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, thế hệ, kết nối đang hoạt động và khóa API đã xác thực được phân rào ngay trước mỗi lần thử ngược dòng được hỗ trợ. Việc phát lại chủ sở hữu và thế hệ với 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 ảnh chụp nhanh yêu cầu hoặc chuyển tiếp lên thượng nguồn.

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 đang được một phiên thuê đang hoạt động của chủ sở hữu khác 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 cấu hình ghi đè tổ hợp định tuyến, hồ sơ đang hoạt động, kích hoạt tự động và 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 tổ hợp có tên, trước tiên được khớp theo tên (không phân biệt hoa 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 tổ hợp có cùng tên, hãy truyền id của tổ hợp để khớp theo cách xác định.
• Không thể chọn theo tên một tổ hợp có tên là off hoặc default (các từ khóa đó được diễn giải trước); hãy tham chiếu tổ hợp đó bằng id.
• Công tắc nén chính là một cổng chặn bắt buộc: khi tính năng nén bị tắt trên toàn hệ thống, tiêu đề này không thể bật tính năng đó.

Kế hoạch đã áp dụng được phản hồi lại trong tiêu đề 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.

---

Embeddings

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 có tiền tố 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 tác vụ 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ụ embeddings 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 là text, image, audio, video và document. source của phương tiện có dạng {"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 tài liệu EmbeddingsV5Request gốc của Jina và chuyển tiếp nguyên vẹn đế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 base64 thô. OmniRoute không chuyển các đối tượng đó thành chuỗi và cũng không 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.

Các giới hạn về 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 nội tuyến trước khi gọi nhà cung cấp. Các mục gốc của Jina dạng {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ã trên 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ột vector cho mỗi mục cấp cao nhất.
• Họ Gemini Embedding 2: một mảng cấp cao nhất trở thành một yêu cầu gốc models/{model}:embedContent duy nhất 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 bằng 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 phải đầu vào trên những yêu cầu chuỗi/token cũ tiếp tục được truyền qua nguyên trạng.

# Liệt kê tất 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": "Hoàng hôn tuyệt đẹp trên những ngọ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ả cá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ã mô hình thuần túy (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 sẽ sử dụng Mistral (mistral-ocr-latest). Các nhà cung cấp đã đăng ký (open-sse/config/ocrRegistry.ts):

Mã nhà cung cấp	Mã mô hình	Giá trị model	Ghi chú
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (hoặc mistral-ocr-latest thuần túy)	Đồng bộ — phản hồi được trả về trực tiếp từ một lệnh gọi duy nhất tới dịch vụ thượng nguồn.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Dịch vụ thượng nguồn 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ộ, thông qua điểm cuối đối tác openapi/chat/completions của Vertex AI — xem bên dưới để biết thông tin xác thực/URL.

Cả ba nhà cung cấp đều phản hồi bằng cùng một nội dung có cấu trúc theo định dạng của 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ề tiêu đề Operation-Location thay vì nội dung phản hồi, 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 ngay khi gặp phản hồi thăm dò không phải ok hoặc trạng thái "failed" (không tiếp tục thăm dò), đồng thời trả về 504 nếu tác vụ vẫn đang chạy sau khi đã dùng hết số lần thử. Phản hồi Azure cuối cùng đượ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ã máy khách không cần xử lý riêng theo nhà cung cấp.

Xác thực và phân giải điểm cuối 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 mã thông báo truy cập OAuth ngắn hạn thông qua luồng JWT-bearer) hoặc mã thông báo truy cập OAuth đã được cấp sẵn và được sử dụng nguyên trạng. URL điểm cuối thượng nguồn là điểm cuối đối tác openapi/chat/completions 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 suy ra 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 tới 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ác tổ hợp theo định dạng OpenAI

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

Hầu hết 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 do cờ tính năng MODELS_CATALOG_PREFIX_MODE kiểm soát và có thể được ghi đè cho từng yêu cầu bằng tham số truy vấn — hữu ích cho ứng dụng khách muốn có 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ế độ	Kết quả trả về	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 giữ lại để các cấu hình ứng dụng khách đã mã hóa cứng một trong hai dạng vẫn tiếp tục hoạt động. Kích thước danh mục tăng gần 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 biệt vẫn trả về mục của họ, vì vậy không có nội dung nào 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 biệt (ví dụ: antigravity/…, agy/…) cũng trả về id duy nhất của họ ở đây, vì vậy không có gì bị mất.

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

Các ứng dụng khách hiển thị trình 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 tính năng suy luận bị tắt — thinking:{type:"disabled"} trên đường dẫn /v1/messages, hoặc các trường reasoning/reasoning_effort bị loại bỏ 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ụ như các mô hình chỉ hỗ trợ chế độ thích ứng và 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, việc 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 kiểu OpenAI
POST	/v1/music/generations	Tạo nhạc theo kiểu 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 kiểu Cohere/Voyage
POST	/v1/classify	Phân loại Jina (api.jina.ai)
POST	/v1/segment	Bộ 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 mô hình OpenAI
POST	/api/v1/vscode/{token}/chat/completions	Bí danh OpenAI được mã hóa bằng token
POST	/api/v1/vscode/{token}/responses	Bí danh OpenAI Responses được mã hóa bằng token
POST	/api/v1/vscode/{token}/api/chat	Bí danh Ollama được mã hóa bằng token
GET	/api/v1/vscode/{token}/api/tags	Bí danh thẻ Ollama được mã hóa bằng token

Tất cả các route POST đều tuân theo cùng một cấu trúc: Bearer your-api-key + phần 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 với chuỗi truy vấn (?token=..., ?apiKey=..., ?api_key=..., ?key=...) hoặc các endpoint chuyên dụng /api/v1/vscode/{token}/... được mô tả 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"] }

# Bộ 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 mô hình 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": "..." }

Route Chuyên dụng 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 bị thiếu. Các mô hình không khớp sẽ 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 một 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 khóa API đã xác thực
GET	/v1/files/[id]	Truy xuất siêu dữ liệu của một tệp
DELETE	/v1/files/[id]	Xóa một tệp
GET	/v1/files/[id]/content	Truyền trực tiếp nội dung thô của tệp trả về

Xác thực: Khóa API Bearer — các tệp được giới hạn phạm vi theo từng khóa API thông qua getApiKeyRequestScope. Một khóa chỉ xem, tải xuống và xóa được các tệp của chính nó; một phiên dashboard không có khóa 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ư khóa đượ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ê 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ô — phần thân đượ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 một lô đã hoàn tất/thất bại
POST	/v1/batches/[id]/cancel	Hủy một lô đang được xử lý

Xác thực: Khóa API Bearer. Các lô được giới hạn phạm vi theo từng khóa API theo cùng quy tắc ba trường hợp như tệp: chỉ khóa sở hữu, phiên dashboard trên toàn instance, các bản ghi không có chủ sở hữu 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 hóa 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 cùng các 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 yêu cầu
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ìm nạp Web

Trích xuất nội dung từ một URL thông qua nhà cung cấp tìm nạp 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ìm nạp/thu thập dữ liệu từ mộ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ó nhận biết hạn ngạch (#8297): khi không chỉ định rõ provider, 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) — nhà cung cấp đã cấu hình nhưng bị giới hạn tốc độ sẽ bị bỏ qua thay vì kết thúc sớm yêu cầu, và lỗi từ thượng nguồn có thể thử lại/liên quan đến hạn ngạch (luôn áp dụng với HTTP 429; áp dụng với 402/403 cho 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 nhưng 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 kiệt, endpoint trả về một mã 429 duy nhất (kèm header Retry-After) thay vì mã 400 chung chung như trước đây. Khi yêu cầu chỉ định rõ provider, sẽ không có chuyển đổi dự phòng ngầm — nhà cung cấp được chỉ định rõ nếu bị giới hạn tốc độ hoặc gặp lỗi sẽ trả về lỗi riêng của nhà cung cấp đó (429 nếu bị giới hạn tốc độ, nếu không thì là trạng thái từ thượng nguồn).

---

Truyền phát 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 báo ví dụ của giao thức truyền dẫ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 HTTP API (mặc định 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" } ] }

Proxy Responses-API-qua-WebSocket được kết nối chỉ 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. Ở frame response.create đầu tiên, proxy xác thực + chuẩn bị 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 đến wss://chatgpt.com/backend-api/codex/responses qua phương thức truyền tải wreq-js. Các model không phải codex sẽ bị từ chối (codex_ws_provider_required). Để định tuyến chia sẻ 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à điểm vào đang hoạt động (theo mặc định là như vậy khi app/server-ws.mjs tồn tại).

ID model: sử dụng ID ChatGPT thuần túy (không có tiền tố codex/)

Codex CLI của OpenAI xác thực tên model ở 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 (Model 'codex/gpt-5.5' không được hỗ trợ khi sử dụng Codex với tài khoản ChatGPT). Hãy gửi ID thuần túy (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 túy thành model codex (resolveCodexWsModelInfo) trước khi tạo đường hầm đến thượng nguồn — mặc dù một ID thuần túy gpt-5.5 nếu không sẽ được định tuyến đến một 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 (sử dụng CODEX_HOME riêng để tránh sửa đổi cấu hình hiện có):

model = "gpt-5.5"                 # ID thuần túy — 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 (sử 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 tải Responses-qua-WS
env_key = "OMNIROUTE_API_KEY"             # chứa khóa API OmniRoute (Bearer)

export OMNIROUTE_API_KEY=sk-...           # 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 đó đến 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 phát 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 hạn mức/cấp 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 xác thực quản trị. Đâ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 người giữ khóa.

# Dạng văn bản (quy ước trước đây — 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 — định 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 bật allowUsageCommand (mặc định tắt — trình quản lý khóa API của bảng điều khiển bật/tắt tùy theo 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 để bên 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 hạn mức 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ó dữ liệu nào đượ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": "…" } } — trạng thái có personal/provider nhưng rỗng (khóa được phép, nhưng chưa thu thập được dữ liệu) khác với trạng thá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 bên gọi, được xác thực bằng isValidApiKey — đây không phải là bề mặt quản trị (/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 tất cả 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ễ

Khi bộ nhớ đệm ngữ nghĩa HIT, phản hồi được trả về từ bộ nhớ đệm mà không có 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 trả 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. Để biết các nhóm thông tin xác thực, phạm vi và ví dụ curl, hãy xem: 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ý node của nhà cung cấp
/api/provider-models	GET/POST/PATCH/DELETE	Các 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

Endpoint	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 biến động 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	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 chia 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

Endpoint	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 IP cho phép/chặn
/api/settings/thinking-budget	GET/PUT	Chế độ ghi lại yêu cầu về ngân sách suy nghĩ/lập luận (chuyển tiếp nguyên trạng / tự động loại bỏ / tùy chỉnh / thích ứng). Độc lập với việc 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à các tệp nhật ký cuộc gọi cục bộ

Ngữ cảnh & Nén

Endpoint	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 khả dụng
/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ác cài đặt dành riêng cho RTK, bao gồm bộ lọc tùy chỉnh và việc 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 tải văn bản
/api/context/rtk/raw-output/[id]	GET	Đọc đầu ra thô đã được biên tập và 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

Endpoint	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 + thông tin tóm tắt về 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 đồng hồ đ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 truy cập bộ nhớ đệm, totalLatencyMs, latencySamples, averageLatencyMs được tính theo số lượng mẫu và thời điểm sử dụng gần nhất (đặt lại khi khởi động lại; yêu cầu xác thực quản lý)
/api/modality-bridge/video/runtime	GET	Kiểm tra loopback đáng tin cậy nghiêm ngặt trước khi xác thực/thăm dò quản lý; thông tin về tính 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	Trình môi giới byte nội bộ đã xác thực qua loopback đá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 hết thời 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 có sẵn
/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 xuống cơ sở dữ liệu dưới dạng tệp .sqlite
/api/db-backups/import	POST	Tải lên tệp .sqlite để thay thế cơ sở dữ liệu
/api/db-backups/exportAll	GET	Tải xuống 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	Các thao tác đồng bộ đám mây
/api/sync/initialize	POST	Khởi tạo đồng bộ
/api/cloud/*	Nhiều	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/thời gian chạy 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 thời gian chạy 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, name, binary, version, installed, protocol, isCustom) và summary (total, installed, notFound, builtIn, custom).

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ài đặt 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 — nội dung {provider, model} hoặc {all: true} để xóa mọi thứ
/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 thông tin phân tích đầy đủ về bộ ngắt nhà cung cấp so với 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 những máy khách cần khả năng tương thích với Gemini SDK nguyên bản.

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	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 nhằm đả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 trực tiếp gọi chúng.

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 đường dẫn đầu tiên chọn nhà cung cấp gốc (openai/…, deepgram/…). Các gateway tái xuất 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
}

Các id mô hình ví dụ: 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). Một yêu cầu deepgram/nova-3 thuần túy sẽ 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

Đối với các máy khách 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

# Liệt kê 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 VS Code có token / Không có 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 kiểu OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

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

# Bí danh 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ó token sử dụng lại cùng các trình xử lý như /v1/* và /api/tags; cấu trúc phản hồi vẫn giống hệt nhau.
• Ưu tiên Authorization: Bearer ... bất cứ khi nào máy khách 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 xem đây 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. Giới hạn có thể được áp dụng cho một model cụ thể, một provider, 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ề lược đồ (setTokenLimitSchema): Bắt buộc phải có apiKeyId và scopeType (model | provider | global). Bắt buộc phải có scopeValue, 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 nhóm quản lý (việc xác thực được thực thi tập trung bởi pipeline 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 trạng thái khả dụng của tài khoản
5. Đối với trò chuyện: handleChatCore kiểm tra bộ nhớ đệm ngữ nghĩa/chữ ký và phân giải các thiết lập nén của combo
6. Quá trình 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 xếp chồng)
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 (trò chuyện) hoặc được trả về nguyên trạng (embedding/hình ảnh/âm thanh)
9. Dữ liệu sử dụng, số liệu phân tích 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 có 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ạ — nội dung: {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/khóa API quản lý (requireManagementAuth).

---

Webhook

Đăng ký webhook gửi đi cho các sự kiện OmniRoute (hoàn tất yêu cầu, hết hạn ngạch, luân phiên 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 kiểm thử đến URL webhook và trả về trạng thái phân phối

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

---

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

Được hệ thống con tự động quản lý khóa sử dụng để cấp và luân phiên khóa API với nhà cung cấp/tài khoản phụ trợ, 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ố đã 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?}. Chỉ trả về khóa thô một lần. 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 tường minh (có tác dụng tương tự 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 tử

Các tác vụ tác tử đám mây (Claude Code, Codex Cloud, OpenHands, v.v.) được thực thi từ xa thay mặt cho 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 trạng thái đồng bộ từ tác tử đám mây thượng nguồn khi external_id được thiết lập
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: mọi phương thức đều yêu cầu xác thực quản lý (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 không tương thích này.

# 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 gửi đi có thể được gán cho nhà cung cấp, tài khoản hoặc trên toàn hệ thống.

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 để hủy các phân công)
GET	/api/v1/management/proxies/assignments	Liệt kê 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 trình đ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 tuyến (requireManagementAuth).

POST /api/v1/management/proxies/[id]/assignments và POST /api/v1/management/proxies/[id]/health trong mô tả tác vụ được phục vụ bởi các tuyến phẳng /assignments và /health nêu trên — không có tuyến 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ý dưới đây cho phép người vận hành đọc và ghi đè chúng:

Phạm vi	Nơi lưu trữ trạng thái	Đọc	Đặ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 nhà cung cấp	/api/rate-limits, /api/providers/[id]	(được bật lại khi cần; xóa qua PUT của nhà cung cấp)
Khóa mô hình	Sổ đăng ký trạng thái 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 tại providerBreaker.oauth và providerBreaker.apikey. Mỗi cấu hình hỗ trợ degradationThreshold, failureThreshold và resetTimeoutMs; các trường tương tự cũng được hiển thị 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}'

Để xem tài liệu tham khảo đầy đủ về khái niệm 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 theo ?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ế độ, schema, 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ô — nội dung: {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=...	Danh sách tìm kiếm/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 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ế bền vững, được phân phạm vi 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 bằng offset/limit hoặc page/limit
POST	/api/memory	Tạo bộ nhớ — nội dung yêu cầu đượ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	Trạng thái của hệ thống con bộ nhớ (kết nối DB, backend embeddings, trạng thái chỉ mục vector)

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

---

Máy chủ MCP

OmniRoute cung cấp 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ân phạm vi. Các endpoint dashboard bên dưới đọc dữ liệu trạng thái/kiểm toán và proxy 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ác công cụ hàng đầu, tỷ lệ thành công trong 24 giờ
GET	/api/mcp/tools	Danh sách 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ị tắt 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 (các 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 toán — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Số liệu thống kê kiểm toán tổng hợp (tổng số, tỷ lệ thành công, thời lượng trung bình, các 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 với phạm vi mcp); các route status/tools/audit* có thể được đọc từ dashboard (không yêu cầu xác thực bổ sung ngoài khả năng truy cập máy chủ dashboard).

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 trả về 400, trạng thái MCP bị tắt 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 trình bao bọc REST để phục vụ việc kiểm tra/sử dụng 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": "Route this coding task"}]
  }
}

Các phương thức được hỗ trợ (tất cả đều phụ thuộc vào 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 SSE dạng luồng 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.

Cá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 vào 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 thông 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 hoạt động mà không cần xác thực quản lý (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 máy khách đồng bộ hóa đám mây
POST	/api/cloud/credentials/update	Cập nhật thông tin xác thực đượ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 tính năng đồ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ượt thẩm định — phần thân: `{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ượt chạy gần đây nhất
POST	/api/evals	Kích hoạt một lượt chạy đánh giá
POST	/api/evals/suites	Tạo một bộ đánh giá tùy chỉnh — phần thân đượ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 quản lý/khóa API. Yêu cầu POST đến /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ý một 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 một 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 một 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 hoạt động định tuyến, nén và mức độ đa dạng của nhà cung cấp. Các endpoint này hỗ trợ 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	Thống kê tổng hợp về định tuyến tự động: 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	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 hoạt động nén

Phương thức	Đường dẫn	Mô tả
GET	/api/analytics/compression	Thống kê tổng hợp về hoạt động nén: số token tiết kiệm được, tỷ lệ tiết kiệm, phân bổ chế độ, mức sử dụng engine

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 ngừa các điểm lỗi đơn lẻ bằng cách đo lường mức độ phân tán 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 yêu cầu: {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, 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 phát hiệ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 đã tạo của công cụ (dryRun dùng để xem trước; 422 + containerEphemeralTarget khi chạy trong container; 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 nhân

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

Phương thức	Đường dẫn	Mô tả
GET	/api/agent-skills	Liệt kê tất cả kỹ năng tác nhân (tích hợp sẵn + tùy chỉnh)
GET	/api/agent-skills/[id]	Lấy một kỹ năng tác nhân cụ thể
POST	/api/agent-skills	Tạo kỹ năng tác nhân tùy chỉnh — nội dung yêu cầu: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Cập nhật một kỹ năng tác nhân tùy chỉnh
DELETE	/api/agent-skills/[id]	Xóa một kỹ năng tác nhân tùy chỉnh
GET	/api/agent-skills/[id]/raw	Lấy prompt thô + siêu dữ liệu (không thực thi)
POST	/api/agent-skills/generate	Dùng AI để tạo kỹ năng mới từ mộ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 cập 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	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 (dùng để 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 trong bộ nhớ (FTS5 + vectơ) — số liệu thống kê được bao gồm trong cùng 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ý các đăng ký webhook cho 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ý các 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	Vô hiệu hóa 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 kiểu 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 kế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.

---

Rào chắn

Kiểm tra các rào chắn thời gian chạy (phát hiện PII, phát hiện chèn prompt, kết nối xử lý hình ảnh). Các rào chắn chạy trên mọi yêu cầu; việc chọn không áp dụng cho từng lệnh gọi được thực hiện thông qua header yêu cầu x-omniroute-disabled-guardrails — không có bề mặt bật/tắt được lưu trữ lâu dài.

Phương thức	Đường dẫn	Mô tả
GET	/api/guardrails	Liệt kê các rào chắn đã đă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 tiền xử lý lệnh gọi trên dữ liệu đầ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 > Rào chắn để 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à sự khác biệt giữa chúng với các khóa suy luận.

• Các route 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
• Trong tài liệu tham chiếu này, "management token" / "management-scoped API key" 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 secret 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).