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

API Reference (Bahasa Melayu)

🌐 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 · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

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

Rujukan teras untuk API OmniRoute. Ia merangkumi permukaan awam /v1 dan titik akhir pengurusan yang paling kerap digunakan; fail docs/openapi.yaml yang boleh dibaca mesin dan pepohon laluan di bawah src/app/api/ merupakan sumber yang lengkap.

---

Kandungan

• Pelengkapan Sembang
• Pajakan Sesi Terurus Eksklusif
• Pembenaman
• Penjanaan Imej
• OCR Dokumen
• Senarai Model
• Manifes Pemalam Penyedia
• Titik Akhir Keserasian
• API Fail
• API Kelompok
• API Carian
• Penstriman WebSocket
• Pelaporan Kuota & Isu
• Cache Semantik
• Papan Pemuka & Pengurusan
• Pengurusan Kombo
• Webhook
• Kunci Berdaftar (Pengurusan Automatik)
• Protokol Ejen
• Proksi Pengurusan
• Ketahanan (lanjutan)
• Kemahiran
• Memori
• Pelayan MCP
• Pelayan A2A
• Awan, Penilaian & Pentaksiran
• Pemprosesan Permintaan
• Pengesahan

---

Pelengkapan Sembang

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Write a function to..."}
  ],
  "stream": true
}

Pengepala Tersuai

Pengepala	Arah	Penerangan
X-OmniRoute-No-Cache	Permintaan	Tetapkan kepada true untuk memintas cache
x-omniroute-no-memory	Permintaan	Tetapkan kepada true untuk melangkau suntikan memori + kemahiran bagi permintaan ini (mencerminkan no-cache; mengelakkan overhed token/kos bagi setiap panggilan)
X-OmniRoute-Progress	Permintaan	Tetapkan kepada true untuk peristiwa kemajuan
X-Session-Id	Permintaan	Kunci sesi melekat untuk afiniti sesi luaran
x_session_id	Permintaan	Varian garis bawah turut diterima (HTTP langsung)
X-OmniRoute-Session-Id	Permintaan	Tag sesi/perbualan yang dibekalkan oleh pemanggil (turut disalurkan kepada memori). Apabila tersedia, disimpan kata demi kata ke call_logs.session_tag untuk pengagihan kos bagi setiap sesi (#8249) — tidak pernah dijana apabila tiada
Idempotency-Key	Permintaan	Kunci penyahduaan (tetingkap 5s)
X-Request-Id	Permintaan	Kunci penyahduaan alternatif
X-OmniRoute-Cache	Respons	HIT atau MISS (tanpa penstriman)
X-OmniRoute-Idempotent	Respons	true jika dinyahduakan
X-OmniRoute-Progress	Respons	enabled jika penjejakan kemajuan diaktifkan
X-OmniRoute-Session-Id	Respons	ID sesi berkesan yang digunakan oleh OmniRoute
X-OmniRoute-Request-Id	Respons	ID korelasi permintaan (apabila diketahui)
X-OmniRoute-Version	Respons	Versi binaan OmniRoute (sentiasa tersedia)
X-OmniRoute-Cost-Saved	Respons	Amaun USD yang dijimatkan oleh cache apabila berlaku HIT (cache hit sahaja)
X-OmniRoute-Decision	Respons	Jejak penghalaan: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> ialah strategi kombo, atau single untuk permintaan bukan kombo) — sentiasa tersedia dalam respons pelengkapan

Nota Nginx: jika anda bergantung pada pengepala garis bawah (contohnya x_session_id), dayakan underscores_in_headers on;.

Pengepala telemetri kos: respons berjaya tanpa penstriman turut membawa set telemetri kos X-OmniRoute-* — X-OmniRoute-Response-Cost (USD, tetap 10 tempat perpuluhan; 0.0000000000 untuk percuma/tanpa harga), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit, dan X-OmniRoute-Fallback-Attempts (hanya apabila > 0), serta X-OmniRoute-Request-Id dan X-OmniRoute-Version. Pengepala ini dipancarkan oleh pelengkapan sembang, /v1/responses, /v1/messages, dan titik akhir media — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations, dan /v1/moderations (kos sentiasa 0). Kos media dikira mengikut modaliti (setiap imej, setiap saat, setiap aksara, setiap unit carian) apabila harga tersedia; jika tidak, nilainya ialah 0 (teruskan operasi jika gagal).

Semantik kos capaian cache: pada Capaian cache semantik (X-OmniRoute-Cache-Hit: true), tiada panggilan huluan dibuat, maka X-OmniRoute-Response-Cost ialah 0.0000000000 (kos tambahan untuk menyediakan capaian tersebut). Kos asal/kos yang sepatutnya dikenakan dilaporkan secara berasingan dalam X-OmniRoute-Cost-Saved. Pengguna pengebilan hendaklah menjumlahkan X-OmniRoute-Response-Cost (capaian tidak melibatkan kos); analitik cache boleh mengagregatkan X-OmniRoute-Cost-Saved.

Pajakan Sesi Terurus Eksklusif

Pajakan sesi terurus eksklusif ialah kontrak penghalaan ikut serta yang neutral terhadap klien: satu pemilik aktif memegang satu sambungan OmniRoute yang layak. Ia tidak memajak model, memerlukan OAuth, mengenal pasti klien tertentu atau memerlukan penyedia tertentu.

Kunci API yang mengesahkan identiti mesti mempunyai skop lease:exclusive dan senarai allowedConnections eksplisit yang tidak kosong. Sempadan mutasi pangkalan data menguatkuasakan kedua-dua medan secara bersama ketika penciptaan kunci dan kemas kini separa.

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

Respons pemerolehan, pembaharuan dan pelepasan yang berjaya mendedahkan cap masa, state dan nilai positif tepat generation, tetapi tidak pernah mendedahkan sambungan atau bukti kelayakan yang dipilih. Pembaharuan dan pelepasan membekalkan generasi dalam badan JSON:

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

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

Pemilik pajakan aktif boleh meminta secara eksplisit metadata paparan yang selamat dari segi privasi untuk pengikatan semasanya:

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

Tindakan status ikut serta ini dipagari oleh pemilik legap, kunci API terurus yang disahkan dan generasi aktif yang tepat dalam satu transaksi pangkalan data. displayName hanyalah nama sambungan dikonfigurasikan yang telah dirapikan; nilainya ialah null apabila tiada nama dikonfigurasikan yang selamat. OmniRoute tidak pernah menggantikannya dengan e-mel atau identiti akaun yang dijana. Nilai penyedia ialah label paparan tidak sensitif dan tidak pernah merupakan pengecam penyedia serasi yang dijana. Bukti kelayakan, token, kuki, ID sambungan atau kunci API mentah, cincangan pemilik, rahsia pemagaran dan data penghalaan dalaman dikecualikan.

Carian dengan kunci salah, pemilik salah, generasi lapuk, tiada, tamat tempoh, dilepaskan atau dibatalkan semuanya mengembalikan ralat 409 LEASE_FENCE_STALE yang sama tanpa metadata sambungan. Klien yang menerima respons menunggu kapasiti tidak mempunyai pengikatan aktif untuk diperiksa. Apabila penghalaan mengalihkan pajakan aktif, generasi yang sama kekal sah dan status mengembalikan pengikatan baharu secara atomik, bukan yang lama. Klien sedia ada kekal tidak berubah kerana respons pemerolehan, pembaharuan, pelepasan dan penantian mengekalkan bentuknya yang terdahulu.

Kontrak pelayan ini tidak mengubah /status OpenAI Codex standard. Codex standard pada masa ini melaporkan penyedia modelnya serta keadaan pengesahan/akaun terbina dalam tetapi tidak memaparkan metadata akaun penyedia tersuai sewenang-wenangnya; penyepaduan klien pada masa hadapan mesti memanggil tindakan ini dan menentukan cara untuk memaparkan connection.displayName.

Setiap permintaan inferens terurus kemudiannya membekalkan kedua-dua pengepala kawalan:

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

Pemilik tepat, generasi, sambungan aktif dan kunci API yang disahkan dipagari serta-merta sebelum setiap percubaan huluan yang disokong. Memainkan semula pemilik dan generasi dengan kunci lain akan gagal walaupun kunci tersebut membenarkan sambungan yang sama. Pemilik mentah tidak disimpan secara berterusan, dilog, dikekalkan dalam petikan permintaan atau dimajukan ke huluan.

Pertikaian sementara mengembalikan HTTP 429 dengan Retry-After dan:

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

Respons ini hanya bermaksud bahawa set layak biasa tidak kosong dan setiap calon bebas sedang dipegang oleh pajakan aktif asing. Model/penyedia yang tidak disokong, ketidakpadanan dasar, tempoh bertenang, kuota, kesihatan dan kegagalan kelayakan biasa yang lain mengekalkan respons OmniRoute sedia ada.

x-omniroute-compression

Penggantian pelan pemampatan bagi setiap permintaan. Keutamaan tertinggi — mengatasi penggantian gabungan penghalaan, profil aktif, pencetus automatik dan Lalai panel. Nilai:

Nilai	Kesan
off	Tiada pemampatan untuk permintaan ini.
default	Profil Lalai yang diperoleh daripada panel (mengabaikan profil aktif).
engine:<id>	Satu enjin apabila didayakan, cth. engine:rtk.
<combo>	Gabungan bernama, dipadankan mengikut nama (tidak sensitif huruf besar/kecil) terlebih dahulu, kemudian mengikut ID.

Nota:

• Nilai yang tidak diketahui diabaikan (permintaan tidak pernah ditolak); penyelesaian diteruskan mengikut keutamaan operator biasa.
• Jika berbilang gabungan berkongsi nama, berikan id gabungan untuk padanan deterministik.
• Gabungan yang namanya ialah off atau default tidak boleh dipilih mengikut nama (kata kunci tersebut ditafsirkan terlebih dahulu); rujuk gabungan tersebut melalui ID-nya.
• Suis pemampatan induk ialah gerbang mutlak: apabila pemampatan dilumpuhkan secara global, pengepala ini tidak boleh mendayakannya.

Pelan yang digunakan dicerminkan kembali dalam pengepala respons:

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

dengan <source> ialah salah satu daripada request-header, routing-override, active-profile, auto-trigger, default atau off.

---

Pembenaman

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

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

Penyedia yang tersedia: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

ID katalog menggunakan format provider/model (contoh: jina-ai/jina-embeddings-v5-omni-small). ID model Jina tanpa nama penyedia yang terdapat dalam daftar pendaftaran (contohnya jina-embeddings-v5-text-small, jina-reranker-v3.5) turut dapat diselesaikan. Operasi embed/rerank/classify/segment Jina menggunakan kelayakan jina-ai daripada papan pemuka terlebih dahulu; JINA_AI_API_KEY digunakan sebagai pilihan sandaran hanya apabila tiada kunci papan pemuka tersedia. Kad jina-reader hanya untuk Reader / r.jina.ai (POST /v1/web/fetch) dan tidak pernah menyediakan pembenaman atau penyusunan semula kedudukan.

Model dalam daftar pendaftaran yang menyatakan sokongan multimodal turut menerima sehingga 32 item berstruktur yang neutral penyedia. Jenis item media ialah text, image, audio, video, dan document. source media tersebut sama ada {"type":"url","url":"https://..."} atau {"type":"base64","data":"...","media_type":"..."}.

Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano, dan alias keluarga jina-ai/jina-embeddings-v5-omni → omni-small) turut menerima dokumen EmbeddingsV5Request asli Jina dan memajukannya tanpa perubahan kepada 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,..." }]
    }
  ]
}

Nilai asli { image | audio | video | pdf } boleh berupa URL HTTPS awam, URI data:, atau base64 mentah. OmniRoute tidak menukarkan objek tersebut kepada rentetan atau mengambil URL imej asli — Jina mendapatkan media awam itu sendiri. Medan tambahan Jina (task, normalized, truncate, embedding_type) dimajukan. SKU Jina teks sahaja masih menolak dokumen bukan teks.

Had keselamatan dan pengangkutan:

• URL media jauh mestilah HTTPS awam. Item kanonik {type,source:url} diambil pada bahagian pelayan (pengesahan semula penghalaan semula, tamat masa, had saiz, DNS awam, penetapan sambungan) dan disisipkan sebelum panggilan penyedia. Item asli Jina {image:"https://..."} dimajukan seperti sedia ada selepas semakan HTTPS awam yang sama; Jina mengambil URL tersebut.
• Media base64 sebaris dihadkan kepada 8 MiB selepas dinyahkod bagi setiap item dan 16 MiB selepas dinyahkod bagi keseluruhan permintaan.

Terjemahan penyedia (item kanonik tidak pernah dimajukan tanpa perubahan):

• Model multimodal Jina: setiap item peringkat teratas menjadi satu objek berkekunci modaliti (text / image / audio / video / pdf) yang menggunakan URI data untuk media sebaris; satu vektor bagi setiap item peringkat teratas.
• Keluarga Gemini Embedding 2: satu tatasusunan peringkat teratas menjadi satu permintaan asli models/{model}:embedContent dengan content.parts (text atau inline_data).
• Model tidak diketahui/dinamik tanpa metadata modaliti yang jelas menolak input berstruktur dengan 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"
}

Gabungan model/modaliti yang tidak disokong mengembalikan HTTP 400 dan bukannya memaksa penukaran item tersebut. Medan sambungan bukan input pada permintaan rentetan/token lama terus diluluskan tanpa perubahan.

# Senaraikan semua model pembenaman
GET /v1/embeddings

---

Penjanaan Imej

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

{
  "model": "openai/gpt-image-2",
  "prompt": "Matahari terbenam yang indah di sebalik pergunungan",
  "size": "1024x1024"
}

Penyedia yang tersedia: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (setempat), ComfyUI (setempat).

# Senaraikan semua model imej
GET /v1/images/generations

---

OCR Dokumen

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 memilih penyedia OCR melalui awalan provider/model; id model tanpa awalan (cth. mistral-ocr-latest) dipadankan dengan penyedia berdaftarnya, manakala jika model tidak dinyatakan, nilai lalainya ialah Mistral (mistral-ocr-latest). Penyedia berdaftar (open-sse/config/ocrRegistry.ts):

Id penyedia	Id model	Nilai model	Catatan
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (atau mistral-ocr-latest tanpa awalan)	Segerak — respons dikembalikan terus daripada satu panggilan huluan.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Huluan tak segerak (analyze + peninjauan) — lihat di bawah.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Segerak, melalui titik akhir rakan kongsi openapi/chat/completions Vertex AI — lihat di bawah untuk pengesahan/URL.

Ketiga-tiga penyedia memberikan respons dalam kandungan berbentuk Mistral yang sama:

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

Aliran peninjauan Azure Document Intelligence

API analyze Azure Document Intelligence adalah tak segerak: permintaan awal mengembalikan pengepala Operation-Location dan bukannya kandungan, dan hasilnya mesti ditinjau. Pengendali (open-sse/handlers/ocr.ts) meninjau URL tersebut setiap saat sehingga 30 percubaan, gagal serta-merta (tidak meneruskan peninjauan) apabila menerima respons peninjauan bukan ok atau status "failed", dan mengembalikan 504 jika operasi masih berjalan selepas had percubaan habis. Respons akhir Azure dinormalkan kepada bentuk pages/markdown yang sama seperti yang digunakan oleh Mistral sebelum dikembalikan kepada pemanggil, jadi kod klien tidak perlu mengendalikan penyedia secara khusus.

Pengesahan dan peleraian titik akhir OCR DeepSeek Vertex AI

vertex-deepseek-ocr menggunakan semula pengesahan Vertex AI yang sama yang sudah disokong oleh OmniRoute untuk trafik sembang/imej (open-sse/executors/vertex.ts): kunci API sambungan sama ada merupakan kelayakan JSON Service Account (ditukar dengan token akses OAuth jangka pendek melalui aliran JWT-bearer) atau token akses OAuth sedia ada yang digunakan tanpa perubahan. URL titik akhir huluan ialah titik akhir rakan kongsi openapi/chat/completions generik Vertex, yang dibina daripada projek dan rantau sambungan — providerSpecificData.project/providerSpecificData.region yang dinyatakan secara jelas sentiasa diutamakan; jika tidak, projek diperoleh daripada project_id JSON Service Account dan rantau ditetapkan secara lalai kepada us-central1. Kedua-dua peleraian dilakukan dalam open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), yang digunakan oleh src/app/api/v1/ocr/route.ts sebelum dihantar kepada handleOcr.

---

Senaraikan Model

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

→ Mengembalikan semua model sembang, pembenaman dan imej + gabungan dalam format OpenAI

Awalan ID model (?prefix=)

Kebanyakan model dipaparkan di bawah awalan penyedia. Awalan yang anda peroleh dikawal oleh bendera ciri MODELS_CATALOG_PREFIX_MODE dan boleh ditindih bagi setiap permintaan dengan parameter pertanyaan — berguna untuk klien yang mahukan senarai yang kemas tanpa mengubah tetapan seluruh pelayan untuk pengguna lain:

GET /v1/models?prefix=alias        # satu ID bagi setiap model — awalan alias pendek
GET /v1/models?prefix=dual         # kedua-dua bentuk (lalai pelayan)
GET /v1/models?prefix=canonical    # hanya awalan ID penyedia penuh

Mod	Mengeluarkan	Nota
dual	cc/claude-sonnet-4-6 dan claude/claude-sonnet-4-6	Lalai. Kedua-dua ID menghala ke model yang sama; dikekalkan supaya konfigurasi klien yang mengekod keras mana-mana bentuk terus berfungsi. Saiz katalog menjadi kira-kira dua kali ganda.
alias	cc/claude-sonnet-4-6	Satu entri bagi setiap model. Penyedia tanpa alias berbeza masih mengeluarkan entri mereka, jadi tiada apa-apa yang hilang.
canonical	claude/claude-sonnet-4-6	Satu entri bagi setiap model di bawah awalan ID penyedia penuh. Penyedia tanpa alias berbeza (cth. antigravity/…, agy/…) turut mengeluarkan ID tunggal mereka di sini, jadi tiada apa-apa yang hilang.

Cermin mod dual juga boleh dikenal pasti tanpa parameter pertanyaan: ia membawa medan parent yang menunjuk kepada ID utama.

Klien yang memaparkan pemilih model hendaklah meminta ?prefix=alias — inilah yang dilakukan oleh sambungan OmniCopilot VS Code.

Varian model tanpa pemikiran

Bagi model Claude yang berkeupayaan berfikir, /v1/models turut memaparkan varian tanpa pemikiran yang ID-nya diawali dengan claude-3-omniroute-no-thinking/:

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

Pemilihan ID ini (cth. dalam konfigurasi Claude Code yang sentiasa melampirkan blok thinking) akan mengembalikannya kepada <provider>/<model> sebenar dengan penaakulan dinyahdayakan — thinking:{type:"disabled"} pada laluan /v1/messages, atau medan reasoning/reasoning_effort digugurkan pada laluan /v1/chat/completions. Varian ini hanya disenaraikan untuk model keluarga Claude yang menyokong pemikiran dan mematuhi disabled (jadi, sebagai contoh, model adaptif sahaja yang menolak disabled dikecualikan). Pengendali boleh memaksa varian ini dihidupkan atau dimatikan bagi setiap model melalui ModelSpec.noThinkingAlias.

---

Manifes Pemalam Penyedia

GET /api/v1/provider-plugin-manifest

Mengembalikan manifes pemalam penyedia selamat JSON yang digunakan oleh Bifrost, CLIProxyAPI dan penghala sidecar akan datang. Respons dijana daripada daftar penyedia TypeScript dan dengan sengaja mengecualikan rahsia klien OAuth, resolusi persekitaran masa jalan, fungsi pelaksana, pengepala permintaan dan data akaun.

Gunakan titik akhir ini apabila sidecar berjalan di luar proses dan tidak dapat mengimport open-sse/config/providerPluginManifestRegistry.ts secara langsung.

---

Titik Akhir Keserasian

Kaedah	Laluan	Format
POST	/v1/chat/completions	OpenAI
POST	/v1/messages	Anthropic
POST	/v1/responses	Respons OpenAI
POST	/v1/embeddings	OpenAI
POST	/v1/images/generations	Imej OpenAI
POST	/v1/images/edits	Imej OpenAI (edit/inpaint)
POST	/v1/videos/generations	Penjanaan video gaya OpenAI
POST	/v1/music/generations	Penjanaan muzik gaya OpenAI
POST	/v1/audio/transcriptions	Audio OpenAI (STT)
POST	/v1/audio/speech	TTS OpenAI (mengembalikan isi audio)
POST	/v1/rerank	Penyusunan semula gaya Cohere/Voyage
POST	/v1/classify	Pengelasan Jina (api.jina.ai)
POST	/v1/segment	Pensegmen Jina (segment.jina.ai)
POST	/v1/moderations	Moderasi OpenAI
GET	/v1/models	OpenAI
POST	/v1/messages/count_tokens	Anthropic
GET	/v1beta/models	Gemini
POST	/v1beta/models/{...path}	Gemini generateContent
POST	/v1/api/chat	Ollama
GET	/api/v1/vscode/{token}/	Alias katalog OpenAI
GET	/api/v1/vscode/{token}/models	Alias model OpenAI
POST	/api/v1/vscode/{token}/chat/completions	Alias bertoken OpenAI
POST	/api/v1/vscode/{token}/responses	Alias bertoken Respons OpenAI
POST	/api/v1/vscode/{token}/api/chat	Alias bertoken Ollama
GET	/api/v1/vscode/{token}/api/tags	Alias teg bertoken Ollama

Semua laluan POST mengikut bentuk yang sama: Bearer your-api-key + isi JSON yang disahkan oleh Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema dan sebagainya, lihat src/shared/validation/schemas.ts). 4xx dikembalikan apabila pengesahan skema gagal.

Bagi klien yang tidak dapat melampirkan Authorization: Bearer ..., OmniRoute turut menerima kunci API dalam URL sama ada melalui keserasian rentetan pertanyaan (?token=..., ?apiKey=..., ?api_key=..., ?key=...) atau titik akhir khusus /api/v1/vscode/{token}/... yang didokumenkan di bawah.

# Susun semula
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Pengelasan Jina (kelayakan API Foundation)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Pensegmen Jina
POST /v1/segment     { "content": "...", "return_chunks": true }

# Carian Jina (s.jina.ai; alias penyedia: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Moderasi
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — mengembalikan isi audio/mpeg (atau format yang diminta)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Edit imej (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Penjanaan video / muzik (ID model berawalan penyedia)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Laluan Penyedia Khusus

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

Awalan penyedia ditambahkan secara automatik jika tiada. Model yang tidak sepadan mengembalikan 400.

---

API Fail

Titik akhir fail yang serasi dengan OpenAI untuk input/output kelompok dan muat naik berdasarkan tujuan fail.

Kaedah	Laluan	Penerangan
POST	/v1/files	Muat naik fail (berbilang bahagian: file, purpose, expires_after[anchor], expires_after[seconds]) — maksimum 512 MiB
GET	/v1/files	Senaraikan fail untuk kunci API yang disahkan
GET	/v1/files/[id]	Dapatkan metadata fail
DELETE	/v1/files/[id]	Padam fail
GET	/v1/files/[id]/content	Strim kembali kandungan mentah fail

Pengesahan: Kunci API Bearer — fail diskopkan mengikut kunci API melalui getApiKeyRequestScope. Sesuatu kunci hanya boleh melihat, memuat turun dan memadam fail miliknya sendiri; sesi papan pemuka tanpa kunci boleh membaca keseluruhan tika; fail tanpa pemilik (muat naik tanpa nama atau melalui sesi papan pemuka) tidak boleh diakses oleh setiap pemanggil tanpa sesi. GET /v1/files menolak pemanggil tanpa nama — dan kunci yang dikemukakan tetapi tidak dapat dikenal pasti — dengan 401 walaupun REQUIRE_API_KEY=false, dan bukannya menyenaraikan fail setiap penyewa (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

API Kelompok

Pemprosesan kelompok yang serasi dengan OpenAI.

Kaedah	Laluan	Penerangan
POST	/v1/batches	Cipta kelompok — isi disahkan oleh v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET	/v1/batches	Senaraikan kelompok
GET	/v1/batches/[id]	Dapatkan status kelompok + request_counts
DELETE	/v1/batches/[id]	Padam kelompok yang telah selesai/gagal
POST	/v1/batches/[id]/cancel	Batalkan kelompok yang sedang diproses

Pengesahan: Kunci API Bearer. Kelompok diskopkan mengikut kunci API berdasarkan peraturan tiga hala yang sama seperti fail: kunci sendiri sahaja, sesi papan pemuka merangkumi seluruh tika, rekod tanpa pemilik tidak boleh diakses oleh setiap pemanggil tanpa sesi (dapatkan, padam, batalkan dan semakan input_file_id semasa penciptaan). GET /v1/batches menolak pemanggil tanpa nama dengan 401 walaupun REQUIRE_API_KEY=false.

---

API Carian

Abstraksi penyedia web/carian (Tavily, Brave, Exa, Serper, dll.).

Kaedah	Laluan	Penerangan
GET	/v1/search	Senaraikan penyedia carian yang dikonfigurasikan + keupayaan
POST	/v1/search	Jalankan pertanyaan carian — badan disahkan oleh v1SearchSchema, menyokong cache/penggabungan
GET	/v1/search/analytics	Statistik hit/kependaman/cache bagi setiap penyedia

Pengesahan: Kunci API Bearer (extractApiKey + isValidApiKey). Dasar carian dikuatkuasakan melalui enforceApiKeyPolicy.

---

API Pengambilan Web

Ekstrak kandungan daripada URL melalui penyedia pengambilan web yang dikonfigurasikan (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Kaedah	Laluan	Penerangan
POST	/v1/web/fetch	Ambil/kikis URL — badan disahkan oleh v1WebFetchSchema

Pengesahan: Kunci API Bearer (extractApiKey + isValidApiKey). Dasar dikuatkuasakan melalui enforceApiKeyPolicy.

Sandaran peka kuota (#8297): apabila tiada provider eksplisit diberikan, kumpulan (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) dilalui mengikut urutan keutamaan tetap (isi dahulu) — penyedia yang dikonfigurasikan tetapi dikenakan had kadar dilangkau dan bukannya menghentikan permintaan, manakala kegagalan huluan yang boleh dicuba semula/berkaitan kuota (HTTP 429 sentiasa; 402/403 untuk peringkat percuma bercorak kuota Firecrawl/Tavily/TinyFish — bukan untuk Jina Reader, dan tidak sekali-kali untuk permintaan tidak sah 400 biasa) akan beralih kepada penyedia seterusnya yang belum dicuba dan mempunyai kelayakan pada masa permintaan. Apabila setiap penyedia dalam kumpulan telah habis dicuba, titik akhir mengembalikan satu 429 (dengan pengepala Retry-After) dan bukannya 400 generik yang terdahulu. Apabila provider eksplisit diminta, tiada sandaran senyap — penyedia eksplisit yang dikenakan had kadar atau gagal akan memaparkan ralatnya sendiri (429 jika dikenakan had kadar, selainnya status huluan).

---

Penstriman WebSocket

GET /v1/ws?handshake=1

Mengesahkan jabat tangan peningkatan WebSocket dan mengembalikan mesej contoh protokol wayar (request, cancel). Bingkai WS sebenar dikendalikan oleh pelayan WS terbina di luar jadual laluan Next.js.

Pengesahan: Kunci API Bearer semasa jabat tangan.

Responses API melalui WebSocket (codex sahaja)

# Hos:port yang sama dengan API HTTP (lalai 20128); tingkatkan sambungan:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (atau: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Bingkai pertama MESTILAH response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Proksi Responses-API-melalui-WebSocket disambungkan secara eksklusif kepada codex (bahagian belakang ChatGPT). Ia mendengar pada port yang sama seperti API/papan pemuka di laluan /v1/responses, /responses, dan /api/v1/responses. Pada bingkai response.create pertama, ia mengesahkan + menyediakan melalui jambatan dalaman codex-responses-ws, memilih sambungan OAuth codex, dan membuat terowong ke wss://chatgpt.com/backend-api/codex/responses melalui pengangkutan wreq-js. Model bukan codex ditolak (codex_ws_provider_required). Untuk penghalaan perkongsian kuota, gunakan model: "qtSd/<group>/codex/<model>". Dilaksanakan dalam app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Pengesahan: Kunci API Bearer semasa jabat tangan. Pelayan HTTP terbina (server-ws.mjs) mestilah titik masuk yang aktif (dan sememangnya begitu secara lalai apabila app/server-ws.mjs wujud).

ID model: gunakan ID ChatGPT biasa (tanpa awalan codex/)

Codex CLI OpenAI mengesahkan nama model pada bahagian klien apabila supports_websockets = true dan menolak ID berawalan penyedia seperti codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Hantar ID biasa (cth. gpt-5.5). Jambatan OmniRoute adalah untuk codex sahaja, jadi ia menyelesaikan semula ID biasa sebagai model codex (resolveCodexWsModelInfo) sebelum membuat terowong ke huluan — walaupun gpt-5.5 biasa sebaliknya akan dihalakan kepada penyedia lain melalui HTTP.

Mengkonfigurasikan OpenAI Codex CLI

Halakan Codex CLI kepada OmniRoute dengan menambahkan penyedia tersuai yang mempunyai sokongan WebSocket ke ~/.codex/config.toml (gunakan CODEX_HOME yang berasingan untuk mengelakkan perubahan pada konfigurasi sedia ada):

model = "gpt-5.5"                 # ID biasa — BUKAN "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # tanpa garis miring penutup; URL WS diterbitkan daripadanya (gunakan https/wss dalam pengeluaran)
wire_api = "responses"                    # satu-satunya nilai yang disokong sejak Feb 2026
supports_websockets = true                # mendayakan pengangkutan Responses-melalui-WS
env_key = "OMNIROUTE_API_KEY"             # menyimpan kunci API OmniRoute (Bearer)

export OMNIROUTE_API_KEY=sk-...           # kunci API OmniRoute (sebarang kunci jika REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

CLI menaik taraf base_url + /responses kepada WebSocket dan OmniRoute membuat terowongnya ke sambungan OAuth codex yang dipilih. Disahkan dari hujung ke hujung terhadap pelayan setempat: ChatGPT mengembalikan codex.rate_limits + response.created dan menstrim pelengkapan.

---

Kuota & Pelaporan Isu

Kaedah	Laluan	Penerangan
GET	/v1/quotas/check	Prapengesahan kuota untuk provider + accountId sebelum mengeluarkan kunci berdaftar
POST	/v1/issues/report	Laporkan kegagalan kuota/pengeluaran kunci kepada GitHub (memerlukan GITHUB_ISSUES_REPO + token)

Pengesahan: Kunci API Bearer (isAuthenticated).

---

Penggunaan layan diri (/api/usage/om-usage)

Mana-mana kunci API boleh membaca penggunaan dan kuota miliknya sendiri — tanpa pengesahan pengurusan. Ini ialah titik akhir yang digunakan oleh klien (CLI, panel OmniCopilot) untuk menunjukkan perbelanjaan kepada pemegang kunci.

# Bentuk teks (kontrak terdahulu — teks biasa untuk terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Bentuk berstruktur — yang digunakan oleh UI
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Kunci tersebut mesti mengaktifkan allowUsageCommand (dimatikan secara lalai — pengurus kunci API papan pemuka menogolnya bagi setiap kunci). Tanpanya, titik akhir memberikan respons 403.

?format=json mengembalikan bentuk terdiskriminasi supaya pemanggil tidak sekali-kali membaca medan data daripada respons penolakan. Apabila berjaya:

{
  "allowed": true,
  // hadir hanya apabila kunci mengikut serta dalam had penggunaan setiap kunci (USD harian/mingguan):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // petikan kuota penyedia yang dipilih, atau null apabila belum ada apa-apa yang dicache:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // petikan bagi setiap sambungan, supaya UI boleh memaparkan beberapa penyedia secara bersebelahan:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

Apabila ditolak (401 kunci tidak sah / 403 tidak dibenarkan), laluan yang sama mengembalikan { "allowed": false, "error": { "message": "…" } } — personal/provider yang hadir tetapi kosong (kunci dibenarkan, tetapi belum memperoleh sebarang data) merupakan keadaan yang berbeza daripada penolakan, dan hanya bentuk JSON yang membezakannya.

Pengesahan: kunci API Bearer milik pemanggil sendiri, disahkan dengan isValidApiKey — ini bukan antara muka pengurusan (/api/keys/…), yang kekal dilindungi oleh requireManagementAuth.

---

Cache Semantik

# Dapatkan statistik cache
GET /api/cache/stats

# Kosongkan semua cache
DELETE /api/cache/stats

Contoh respons:

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

Kesan kependaman

HIT cache semantik menyampaikan respons daripada cache tanpa panggilan huluan, maka X-OmniRoute-Response-Latency yang dilaporkan menghampiri sifar (tanpa mengira kependaman huluan asal). Klien yang sensitif terhadap kependaman (penanda aras, pemantauan p50/p99) hendaklah memeriksa pengepala respons X-OmniRoute-Cache-Latency:

Nilai	Maksud
synthetic	Respons disampaikan daripada cache; kependaman bukan masa huluan sebenar
(tiada)	Respons daripada panggilan huluan sebenar

Pintasan cache setiap kunci

Kunci API boleh memilih untuk tidak menggunakan bacaan cache semantik melalui cacheDefaultMode:

Nilai	Tingkah laku
legacy	Tingkah laku cache biasa (lalai)
bypass	Langkau carian cache sepenuhnya; sentiasa gunakan huluan

Tetapkan ketika penciptaan kunci (POST /api/keys) atau kemas kini (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Pintasan setiap permintaan

Sebarang permintaan boleh memintas cache tanpa mengira tetapan kunci:

X-OmniRoute-No-Cache: true

---

Papan Pemuka & Pengurusan

Laluan pengurusan (/api/* kecuali pengesahan/log masuk awam) tidak dibenarkan menggunakan kunci API inferens biasa. Keluarga kelayakan, skop dan contoh curl: Pengesahan Pengurusan.

Pengesahan

Titik Akhir	Kaedah	Penerangan
/api/auth/login	POST	Log masuk
/api/auth/logout	POST	Log keluar
/api/settings/require-login	GET/PUT	Togol keperluan log masuk

Pengurusan Penyedia

Titik Akhir	Kaedah	Penerangan
/api/providers	GET/POST	Senaraikan / cipta penyedia
/api/providers/[id]	GET/PUT/DELETE	Urus penyedia
/api/providers/[id]/test	POST	Uji sambungan penyedia
/api/providers/[id]/models	GET	Senaraikan model penyedia
/api/providers/validate	POST	Sahkan konfigurasi penyedia
/api/providers/bulk	POST	Tambah kunci API secara pukal untuk SATU penyedia
/api/providers/import	POST	Import SENARAI penyedia beraneka daripada fail CSV/JSON yang telah dihuraikan (#6836); hasil kegagalan separa bagi setiap baris
/api/provider-nodes*	Pelbagai	Pengurusan nod penyedia
/api/provider-models	GET/POST/PATCH/DELETE	Model tersuai (tambah, kemas kini, sembunyikan/tunjukkan, padam)

Aliran OAuth

Titik Akhir	Kaedah	Penerangan
/api/oauth/[provider]/[action]	Pelbagai	OAuth khusus penyedia

Penghalaan & Konfigurasi

Titik Akhir	Kaedah	Penerangan
/api/models/alias	GET/POST	Alias model
/api/models/catalog	GET	Semua model mengikut penyedia + jenis
/api/combos*	Pelbagai	Pengurusan gabungan
/api/keys*	Pelbagai	Pengurusan kunci API
/api/pricing	GET	Harga model

Penggunaan & Analitis

Titik akhir	Kaedah	Penerangan
/api/usage/history	GET	Sejarah penggunaan
/api/usage/logs	GET	Log penggunaan
/api/usage/request-logs	GET	Log peringkat permintaan
/api/usage/[connectionId]	GET	Penggunaan bagi setiap sambungan
/api/usage/token-limits	GET/POST/DELETE	Belanjawan had token bagi setiap kunci API
/api/usage/model-latency-stats	GET	Agregat kependaman berterusan bagi setiap penyedia/model (purata/p50/p95/p99, kadar kejayaan); penapis: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	Ringkasan kesihatan cache gesaan berdasarkan call_logs — nisbah tulis/baca, taburan saiz tulis p50/p90/p99, kepekatan penulisan berat, pecahan bagi setiap model dan keputusan healthy/degraded/thrash/no-data; parameter pertanyaan range (1h|24h|7d|30d, lalai 24h) dan model pilihan (#8827)

Tetapan

Titik akhir	Kaedah	Penerangan
/api/settings	GET/PUT/PATCH	Tetapan umum
/api/settings/proxy	GET/PUT	Konfigurasi proksi rangkaian
/api/settings/proxy/test	POST	Uji sambungan proksi
/api/settings/ip-filter	GET/PUT	Senarai dibenarkan/senarai disekat IP
/api/settings/thinking-budget	GET/PUT	Mod penulisan semula permintaan pemikiran/penaakulan (passthrough / auto-strip / custom / adaptive). Tidak bergantung pada pemampatan. Lihat THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Gesaan sistem global
/api/settings/compression	GET/PUT	Konfigurasi pemampatan global
/api/settings/purge-request-history	POST	Kosongkan baris log permintaan dan artifak log panggilan setempat

Konteks & Pemampatan

Titik Akhir	Kaedah	Penerangan
/api/compression/preview	POST	Pratonton pemampatan off/lite/standard/aggressive/ultra/RTK/stacked
/api/compression/language-packs	GET	Senaraikan pek bahasa Caveman yang tersedia
/api/compression/rules	GET	Senaraikan metadata peraturan Caveman
/api/context/caveman/config	GET/PUT	Alias tetapan khusus Caveman
/api/context/rtk/config	GET/PUT	Tetapan khusus RTK, termasuk penapis tersuai dan pengekalan output mentah
/api/context/rtk/filters	GET	Katalog penapis RTK dan diagnostik penapis tersuai
/api/context/rtk/test	POST	Jalankan pratonton/ujian RTK terhadap muatan teks
/api/context/rtk/raw-output/[id]	GET	Baca output mentah tersunting yang dikekalkan mengikut ID penuding
/api/context/combos	GET/POST	Senaraikan/cipta kombo pemampatan
/api/context/combos/[id]	GET/PUT/DELETE	Butiran/kemas kini/padam kombo pemampatan
/api/context/combos/[id]/assignments	GET/PUT	Tetapkan kombo pemampatan kepada kombo penghalaan
/api/context/analytics	GET	Alias analitik pemampatan

Pemantauan

Titik Akhir	Kaedah	Penerangan
/api/sessions	GET	Penjejakan sesi aktif
/api/rate-limits	GET	Had kadar bagi setiap akaun
/api/monitoring/health	GET	Semakan kesihatan + ringkasan penyedia (catalogCount, configuredCount, activeCount, monitoredCount). Paparan pengurusan merangkumi credentialHealth: nilai skalar cache prob, failedConnections apabila failed>0, dan staleDbNonOkCount (test_status melekat SQLite, bukan tolok). Lihat MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Statistik cache / kosongkan
/api/modality-bridge/stats	GET	attempts dalam memori, kejayaan/bridged, kegagalan, capaian cache, totalLatencyMs, latencySamples, averageLatencyMs berasaskan bilangan sampel, dan masa penggunaan terakhir (ditetapkan semula apabila dimulakan semula; pengesahan pengurusan)
/api/modality-bridge/video/runtime	GET	Semakan gelung balik dipercayai yang ketat sebelum pengesahan/prob pengurusan; ketersediaan dan versi FFmpeg/ffprobe yang disanitasi (no-store)
/api/modality-bridge/video/extract	POST	Broker bait gelung balik dipercayai dalaman yang disahkan; input 50 MiB, baris gilir terhad/output 32 MiB, kapasiti 503, pemutusan sambungan 499, tarikh akhir 504; bukan API muat naik awam

Sandaran & Eksport/Import

Titik Akhir	Kaedah	Penerangan
/api/db-backups	GET	Senaraikan sandaran yang tersedia
/api/db-backups	PUT	Cipta sandaran manual
/api/db-backups	POST	Pulihkan daripada sandaran tertentu
/api/db-backups/export	GET	Muat turun pangkalan data sebagai fail .sqlite
/api/db-backups/import	POST	Muat naik fail .sqlite untuk menggantikan pangkalan data
/api/db-backups/exportAll	GET	Muat turun sandaran penuh sebagai arkib .tar.gz

Penyegerakan Awan

Titik Akhir	Kaedah	Penerangan
/api/sync/cloud	Pelbagai	Operasi penyegerakan awan
/api/sync/initialize	POST	Mulakan penyegerakan
/api/cloud/*	Pelbagai	Pengurusan awan

Terowong

Titik Akhir	Kaedah	Penerangan
/api/tunnels/cloudflared	GET	Baca status pemasangan/masa jalan Cloudflare Quick Tunnel untuk papan pemuka
/api/tunnels/cloudflared	POST	Dayakan atau nyahdayakan Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok	GET	Baca status masa jalan ngrok Tunnel untuk papan pemuka
/api/tunnels/ngrok	POST	Dayakan atau nyahdayakan ngrok Tunnel (action=enable/disable)

Alat CLI

Titik Akhir	Kaedah	Penerangan
/api/cli-tools/claude-settings	GET	Status CLI Claude
/api/cli-tools/codex-settings	GET	Status CLI Codex
/api/cli-tools/droid-settings	GET	Status CLI Droid
/api/cli-tools/openclaw-settings	GET	Status CLI OpenClaw
/api/cli-tools/runtime/[toolId]	GET	Masa jalan CLI umum

Respons CLI merangkumi: installed, runnable, command, commandPath, runtimeMode, reason.

Ejen ACP

Titik Akhir	Kaedah	Penerangan
/api/acp/agents	GET	Senaraikan semua ejen yang dikesan (terbina dalam + tersuai) berserta status
/api/acp/agents	POST	Tambah ejen tersuai atau segarkan semula cache pengesanan
/api/acp/agents	DELETE	Alih keluar ejen tersuai menggunakan parameter pertanyaan id

Respons GET merangkumi agents[] (id, name, binary, version, installed, protocol, isCustom) dan summary (total, installed, notFound, builtIn, custom).

Ketahanan & Had Kadar

Titik Akhir	Kaedah	Penerangan
/api/resilience	GET/PATCH	Dapatkan/kemas kini baris gilir permintaan, tempoh bertenang sambungan, pemutus penyedia dan tetapan menunggu
/api/resilience/reset	POST	Tetapkan semula pemutus litar penyedia
/api/resilience/model-cooldowns	GET	Senaraikan sekatan aktif bagi setiap (penyedia, sambungan, model), disusun mengikut baki masa
/api/resilience/model-cooldowns	DELETE	Kosongkan sekatan model — isi {provider, model} atau {all: true} untuk memadamkan semuanya
/api/rate-limits	GET	Status had kadar bagi setiap akaun
/api/rate-limit	GET	Konfigurasi had kadar global

Keempat-empat laluan /api/resilience/* memerlukan pengesahan pengurusan (requireManagementAuth). Lihat Ketahanan (lanjutan) untuk huraian penuh tentang pemutus penyedia berbanding tempoh bertenang sambungan berbanding sekatan model.

Penilaian

Titik Akhir	Kaedah	Penerangan
/api/evals	GET/POST	Senaraikan suit penilaian / jalankan penilaian

Dasar

Titik Akhir	Kaedah	Penerangan
/api/policies	GET/POST/DELETE	Urus dasar penghalaan

Pematuhan

Titik Akhir	Kaedah	Penerangan
/api/compliance/audit-log	GET	Log audit pematuhan (N terakhir)

v1beta (Serasi dengan Gemini)

Titik Akhir	Kaedah	Penerangan
/v1beta/models	GET	Senaraikan model dalam format Gemini
/v1beta/models/{...path}	POST	Titik akhir generateContent Gemini

Titik akhir ini mencerminkan format API Gemini untuk klien yang memerlukan keserasian SDK Gemini natif.

API Dalaman / Sistem

Titik akhir	Kaedah	Penerangan
/api/init	GET	Semakan permulaan aplikasi (digunakan pada pelaksanaan pertama)
/api/tags	GET	Tag model yang serasi dengan Ollama (untuk klien Ollama)
/api/restart	POST	Cetuskan mula semula pelayan secara tertib
/api/shutdown	POST	Cetuskan penutupan pelayan secara tertib
/api/system/env/repair	POST	Baiki pemboleh ubah persekitaran penyedia OAuth

Nota: Titik akhir ini digunakan secara dalaman oleh sistem atau untuk keserasian klien Ollama. Titik akhir ini biasanya tidak dipanggil oleh pengguna akhir.

Pembaikan Persekitaran OAuth (v3.6.1+)

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

{
  "provider": "claude-code"
}

Membaiki pemboleh ubah persekitaran OAuth yang hilang atau rosak untuk penyedia tertentu. Mengembalikan:

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

---

Transkripsi Audio

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

Transkripsikan fail audio menggunakan mana-mana penyedia STT yang dikonfigurasikan. Segmen laluan pertama memilih penyedia natif (openai/…, deepgram/…). Gerbang yang mengeksport semula model vendor lain menggunakan id berkelayakan (openrouter/deepgram/nova-3).

Permintaan:

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

Respons:

{
  "text": "Helo, ini ialah kandungan audio yang telah ditranskripsikan.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}

Contoh id model: openai/whisper-1 (memerlukan kunci OpenAI), openrouter/deepgram/nova-3 (memerlukan kunci OpenRouter), deepgram/nova-3 (memerlukan kunci Deepgram natif). Permintaan deepgram/nova-3 biasa tidak menggunakan OpenRouter.

Format yang disokong: mp3, wav, m4a, flac, ogg, webm.

---

Keserasian Ollama

Untuk klien yang menggunakan format API Ollama:

# Titik akhir sembang (format Ollama)
POST /v1/api/chat

# Penyenaraian model (format Ollama)
GET /api/tags

Permintaan diterjemahkan secara automatik antara format Ollama dengan format dalaman.

Alias VS Code Bertoken / Tanpa Pengepala

Gunakan alias ini apabila sesuatu integrasi tidak dapat menyuntik pengepala Authorization dan memerlukan kunci API dibenamkan dalam URL asas.

# Alias katalog gaya OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Alias sembang gaya OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Alias gaya Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Contoh:

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

Catatan:

• Alias bertoken menggunakan semula pengendali yang sama seperti /v1/* dan /api/tags; bentuk respons kekal sama.
• Utamakan Authorization: Bearer ... apabila klien menyokong pengepala tersuai.
• Token berasaskan URL mungkin muncul dalam log proksi songsang, sejarah pelayar dan telemetri di luar OmniRoute. Anggap token tersebut sebagai pilihan keserasian, bukan mod pengesahan lalai.

---

Telemetri

# Dapatkan ringkasan telemetri kependaman (p50/p95/p99 bagi setiap penyedia)
GET /api/telemetry/summary

Respons:

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

---

Bajet

# Dapatkan status bajet untuk semua kunci API
GET /api/usage/budget

# Tetapkan atau kemas kini bajet
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"
}

Catatan skema (setBudgetSchema): apiKeyId diperlukan; sekurang-kurangnya satu daripada dailyLimitUsd, weeklyLimitUsd atau monthlyLimitUsd mestilah lebih besar daripada sifar. Medan pilihan: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Bentuk legasi {keyId, limit, period} mengembalikan 400 Bad Request.

Had Token

Bajet token bagi setiap kunci API (berbeza daripada Bajet berasaskan USD di atas). Dikuatkuasakan secara terus pada laluan permintaan: apabila penggunaan tetingkap semasa sesuatu kunci mencapai hadnya, permintaan ditolak dengan 429 Too Many Requests. Had boleh dikhususkan kepada model tertentu, provider, atau digunakan secara global merentas kunci tersebut; apabila beberapa had sepadan dengan sesuatu permintaan, had yang paling ketat akan digunakan.

# Senaraikan had token sesuatu kunci (termasuk penggunaan tetingkap semasa)
GET /api/usage/token-limits?apiKeyId=key-123

# Cipta atau kemas kini had 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
}

# Padam had token mengikut id
DELETE /api/usage/token-limits?id=tl-abc

Nota skema (setTokenLimitSchema): apiKeyId dan scopeType (model | provider | global) diperlukan. scopeValue diperlukan melainkan scopeType ialah global (contohnya id model untuk skop model, id penyedia untuk skop provider). tokenLimit mestilah integer positif (ditukar secara paksa daripada rentetan). Pilihan: id (abaikan untuk mencipta, sertakan untuk mengemas kini), resetInterval (daily | weekly | monthly, lalai monthly), resetTime (HH:MM), enabled (lalai true). Respons GET memperkaya setiap had dengan tokensUsed, remaining, windowStart, periodStartAt, dan nextResetAt. Ini ialah titik akhir kelas pengurusan (pengesahan dikuatkuasakan secara berpusat oleh talian paip authz).

Pemprosesan Permintaan

1. Klien menghantar permintaan kepada /v1/*
2. Pengendali laluan memanggil handleChat, handleEmbedding, handleAudioTranscription, atau handleImageGeneration
3. Model ditentukan (penyedia/model langsung atau alias/kombo)
4. Bukti kelayakan dipilih daripada DB setempat dengan penapisan ketersediaan akaun
5. Untuk sembang: handleChatCore menyemak cache semantik/tandatangan dan menentukan tetapan pemampatan kombo
6. Pemampatan proaktif dijalankan sebelum penterjemahan penyedia apabila didayakan (lite, Caveman, RTK, atau bertindan)
7. Pelaksana penyedia menghantar permintaan ke huluan
8. Respons diterjemahkan kembali kepada format klien (sembang) atau dikembalikan seadanya (pembenaman/imej/audio)
9. Penggunaan, analitik pemampatan, dan log permintaan direkodkan
10. Sandaran digunakan apabila berlaku ralat mengikut peraturan kombo

Rujukan seni bina penuh: ARCHITECTURE.md

---

Pengurusan Kombo

Kombo penghalaan aras lebih tinggi (yang telah diringkaskan di bawah /api/combos*) juga boleh dipetakan 1:1 daripada corak id model, membolehkan pengalihan telus bagi id model gaya OpenAI kepada kombo.

Kaedah	Laluan	Penerangan
GET	/api/model-combo-mappings	Senaraikan semua pemetaan model→kombo
POST	/api/model-combo-mappings	Cipta pemetaan — kandungan: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	Dapatkan satu pemetaan
PUT	/api/model-combo-mappings/[id]	Kemas kini medan bagi pemetaan sedia ada
DELETE	/api/model-combo-mappings/[id]	Alih keluar pemetaan

Pengesahan: sesi/kunci API pengurusan (requireManagementAuth).

---

Webhook

Langganan webhook keluar untuk acara OmniRoute (penyelesaian permintaan, kehabisan kuota, penggiliran kunci, dan sebagainya).

Kaedah	Laluan	Penerangan
GET	/api/webhooks	Senaraikan webhook (rahsia disamarkan sebagai <prefix>...)
POST	/api/webhooks	Cipta webhook — badan: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Dapatkan webhook
PUT	/api/webhooks/[id]	Kemas kini url/events/secret/description
DELETE	/api/webhooks/[id]	Alih keluar webhook
POST	/api/webhooks/[id]/test	Hantar muatan ujian ke URL webhook dan kembalikan status penghantaran

Pengesahan: sesi pengurusan/kunci API (requireManagementAuth).

---

Kunci Berdaftar (Pengurusan Automatik)

Digunakan oleh subsistem pengurusan kunci automatik untuk mengeluarkan dan menggilirkan kunci API melalui penyedia/akaun sandaran, dengan kuota harian/setiap jam.

Kaedah	Laluan	Penerangan
GET	/api/v1/registered-keys	Senaraikan kunci berdaftar (awalan disamarkan sahaja)
POST	/api/v1/registered-keys	Keluarkan kunci berdaftar baharu — badan: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Mengembalikan kunci mentah sekali sahaja. Mengembalikan 429 jika kuota ditolak.
GET	/api/v1/registered-keys/[id]	Dapatkan metadata kunci berdaftar (tanpa bahan mentah)
DELETE	/api/v1/registered-keys/[id]	Batalkan kunci berdaftar
POST	/api/v1/registered-keys/[id]/revoke	Titik akhir pembatalan eksplisit (kesan yang sama seperti DELETE)

Pengesahan: Kunci API Bearer (isAuthenticated). Lihat juga /v1/quotas/check dan /v1/issues/report.

---

Protokol Ejen

Tugas ejen awan (Claude Code, Codex Cloud, OpenHands, dll.) yang dilaksanakan dari jauh bagi pihak pengguna OmniRoute.

Kaedah	Laluan	Penerangan
GET	/api/v1/agents/tasks	Senaraikan tugas — ?provider=, ?status=, ?limit= adalah pilihan (1–500, lalai 50)
POST	/api/v1/agents/tasks	Cipta tugas — isi disahkan oleh CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Mengembalikan 201 dengan sampul tugas
DELETE	/api/v1/agents/tasks?id=...	Padam tugas
GET	/api/v1/agents/tasks/[id]	Baca tugas — menyegarkan status secara segerak daripada ejen awan huluan apabila external_id ditetapkan
POST	/api/v1/agents/tasks/[id]	Tindakan berpilih: {action: "approve"}, {action: "message", message}, atau {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	Padam tugas tertentu mengikut id

Pengesahan: pengesahan pengurusan diperlukan untuk setiap kaedah (requireCloudAgentManagementAuth). Sebelum v3.8.0, kaedah ini tidak memerlukan pengesahan — lihat komit 588a0333 untuk perubahan yang memecahkan keserasian.

# Cipta tugas awan 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":"..."}}'

---

Proksi Pengurusan

Proksi HTTP(S)/SOCKS keluar yang boleh diperuntukkan kepada penyedia, akaun atau secara global.

Kaedah	Laluan	Penerangan
GET	/api/v1/management/proxies	Senaraikan proksi (dengan ?id= mengembalikan satu; dengan ?id=&where_used=1 mengembalikan graf peruntukan)
POST	/api/v1/management/proxies	Cipta proksi — isi disahkan oleh createProxyRegistrySchema
PATCH	/api/v1/management/proxies	Kemas kini proksi — isi disahkan oleh updateProxyRegistrySchema (memerlukan id)
DELETE	/api/v1/management/proxies?id=...&force=1	Padam proksi (gunakan force=1 untuk menanggalkan peruntukan)
GET	/api/v1/management/proxies/assignments	Senaraikan peruntukan — boleh ditapis mengikut proxy_id, scope, scope_id; berikan resolve_connection_id=<id> untuk menentukan proksi aktif bagi sambungan
PUT	/api/v1/management/proxies/assignments	Peruntukkan — isi disahkan oleh proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Mengosongkan cache penghantar
PUT	/api/v1/management/proxies/bulk-assign	Peruntukkan secara pukal — isi disahkan oleh bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Agregat kesihatan proksi (bilangan berjaya/gagal, kependaman) sepanjang suatu tempoh

Pengesahan: sesi pengurusan/kunci API diperlukan pada setiap laluan (requireManagementAuth).

POST /api/v1/management/proxies/[id]/assignments dan POST /api/v1/management/proxies/[id]/health dalam penerangan tugas disediakan oleh laluan rata /assignments dan /health yang ditunjukkan di atas — tiada sublaluan khusus bagi setiap id dalam pangkalan kod.

---

Ketahanan (lanjutan)

OmniRoute menyediakan tiga mekanisme kegagalan sementara yang bebas antara satu sama lain; titik akhir pengurusan di bawah membolehkan pengendali membaca dan mengatasinya:

Skop	Storan keadaan	Baca	Tetapkan semula / kosongkan
Pemutus penyedia	domain_circuit_breakers + dalam memori	/api/monitoring/health	POST /api/resilience/reset
Tempoh bertenang sambungan	rateLimitedUntil pada sambungan penyedia	/api/rate-limits, /api/providers/[id]	(didayakan semula secara malas; kosongkan melalui PUT penyedia)
Sekatan model	Pendaftar ketersediaan model dalam memori	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience menerima penggantian pemutus penyedia di bawah providerBreaker.oauth dan providerBreaker.apikey. Setiap profil menyokong degradationThreshold, failureThreshold, dan resetTimeoutMs; medan yang sama tersedia dalam Papan Pemuka → Tetapan → Ketahanan.

# Kosongkan sekatan untuk satu model
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"}'

# Kosongkan semua sekatan
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Untuk rujukan konseptual penuh dan nilai lalai pemutus, lihat CLAUDE.md → "Keadaan Masa Jalan Ketahanan".

---

Kemahiran

Rangka kerja kemahiran untuk memperluas OmniRoute dengan pengendali boleh laksana tersuai, serta integrasi pasaran.

Kaedah	Laluan	Penerangan
GET	/api/skills	Senaraikan kemahiran yang dipasang — boleh ditapis mengikut ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, dengan penomboran halaman
GET	/api/skills/[id]	Dapatkan satu kemahiran
PUT	/api/skills/[id]	Kemas kini kemahiran (nama, penerangan, mod, skema, pengendali, tag)
DELETE	/api/skills/[id]	Nyahpasang kemahiran
POST	/api/skills/install	Pasang kemahiran daripada manifes mentah — isi: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	Senaraikan pelaksanaan kemahiran terkini (jejak audit dengan input/output/tempoh)
GET	/api/skills/marketplace?q=...	Carian/senarai popular daripada pasaran SkillsMP (memerlukan tetapan skillsmpApiKey)
POST	/api/skills/marketplace/install	Pasang kemahiran mengikut id daripada SkillsMP
GET	/api/skills/skillssh?q=&limit=	Cari dalam pendaftar skills.sh
POST	/api/skills/skillssh/install	Pasang kemahiran mengikut id daripada skills.sh

Pengesahan: sesi pengurusan/kunci API. Laluan carian pasaran menerima sama ada pengesahan pengurusan atau kunci API Bearer (isAuthenticated).

---

Memori

Storan memori perbualan/fakta yang berterusan, dengan skop bagi setiap kunci API / sesi.

Kaedah	Laluan	Penerangan
GET	/api/memory	Senaraikan memori — ?apiKeyId=, ?type=, ?sessionId=, ?q=, dengan penomboran halaman offset/limit atau page/limit
POST	/api/memory	Cipta memori — kandungan permintaan disahkan oleh Zod: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	Dapatkan satu memori
DELETE	/api/memory/[id]	Padam memori
GET	/api/memory/health	Kesihatan subsistem memori (kesambungan DB, bahagian belakang pembenaman, status indeks vektor)

Pengesahan: sesi pengurusan/kunci API (requireManagementAuth). Enum type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (lihat MemoryType dalam src/lib/memory/types.ts).

---

Pelayan MCP

OmniRoute disertakan dengan pelayan Model Context Protocol terbenam yang mempunyai 3 pengangkutan (stdio, SSE, streamable-http) dan alat dengan skop tertentu. Titik akhir papan pemuka di bawah membaca data status/audit dan memproksikan pengangkutan HTTP.

Kaedah	Laluan	Penerangan
GET	/api/mcp/status	Denyutan, pengangkutan, keadaan dalam talian, panggilan terakhir, alat teratas, kadar kejayaan 24 jam
GET	/api/mcp/tools	Senarai alat MCP dengan name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	Buka strim SSE untuk pengangkutan SSE (mengembalikan 503 jika MCP dilumpuhkan atau pengangkutan tidak sepadan)
POST	/api/mcp/sse	Hantar bingkai JSON-RPC melalui pengangkutan SSE
GET	/api/mcp/stream	Buka bahagian SSE bagi pengangkutan HTTP Boleh Distrim (mesej yang dimulakan oleh pelayan)
POST	/api/mcp/stream	Hantar bingkai JSON-RPC melalui pengangkutan HTTP Boleh Distrim
DELETE	/api/mcp/stream	Tamatkan sesi HTTP Boleh Distrim
GET	/api/mcp/audit	Kueri log audit — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Statistik audit agregat (jumlah, kadar kejayaan, purata tempoh, alat teratas)

Pengesahan: pengangkutan sse/stream mematuhi permukaan pengesahan khusus MCP (kunci API Bearer dengan skop mcp); laluan status/tools/audit* boleh dibaca daripada papan pemuka (tiada pengesahan tambahan diperlukan selain daripada dapat mencapai hos papan pemuka).

Kedua-dua pengangkutan HTTP dikawal oleh settings.mcpEnabled dan settings.mcpTransport — ketidakpadanan pengangkutan mengembalikan 400, manakala keadaan MCP yang dilumpuhkan mengembalikan 503.

---

Pelayan A2A

OmniRoute menyediakan titik akhir A2A (Ejen-ke-Ejen) JSON-RPC 2.0 serta pembalut REST untuk tujuan pemeriksaan/papan pemuka.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # pilihan melainkan OMNIROUTE_API_KEY ditetapkan
Content-Type: application/json

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

Kaedah yang disokong (semuanya bergantung pada settings.a2aEnabled):

Kaedah	Penerangan
message/send	Pelaksanaan kemahiran segerak; mengembalikan {task, artifacts, metadata}
message/stream	Pelaksanaan penstriman SSE bagi set kemahiran yang sama
tasks/get	Dapatkan tugas berdasarkan taskId
tasks/cancel	Batalkan tugas berdasarkan taskId

Kemahiran terbina dalam: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Kad Ejen

GET /.well-known/agent.json

Mengembalikan kad ejen A2A awam (nama, penerangan, keupayaan, katalog kemahiran, skema pengesahan) — dicache secara awam selama 1j. Pengesahan tidak diperlukan.

Pembantu REST

Kaedah	Laluan	Penerangan
GET	/api/a2a/status	Status A2A didayakan + statistik tugas + ringkasan kad ejen yang dicache
GET	/api/a2a/tasks	Senaraikan tugas — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(Tidak dilaksanakan sebagai pembantu REST — cipta melalui JSON-RPC message/send)
GET	/api/a2a/tasks/[id]	Dapatkan satu tugas
POST	/api/a2a/tasks/[id]/cancel	Batalkan tugas

Pengesahan: pembantu REST berjalan tanpa pengesahan pengurusan (boleh dibaca oleh papan pemuka); laluan JSON-RPC /a2a menggunakan Bearer OMNIROUTE_API_KEY jika dikonfigurasikan.

---

Awan, Penilaian & Pentaksiran

Kaedah	Laluan	Penerangan
POST	/api/cloud/auth	Sahkan kunci Bearer dan kembalikan sambungan penyedia yang disamarkan + alias model untuk klien penyegerakan awan
POST	/api/cloud/credentials/update	Kemas kini kelayakan yang disulitkan untuk penyedia yang disegerakkan dengan awan
POST	/api/cloud/model/resolve	Petakan ID model logik kepada penyedia/model konkrit menggunakan jadual penghalaan setempat
GET	/api/cloud/models/alias	Senaraikan alias model seperti yang didedahkan kepada penyegerakan awan
GET	/api/assess	Baca pengkategorian pentaksiran terkini (mengikut penyedia/model)
POST	/api/assess	Jalankan pentaksiran — isi: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Senaraikan suit penilaian terbina dalam + pelaksanaan terkini
POST	/api/evals	Cetuskan pelaksanaan penilaian
POST	/api/evals/suites	Cipta suit penilaian tersuai — isi disahkan oleh evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Dapatkan suit penilaian tersuai

Pengesahan: /api/cloud/auth mengesahkan kunci Bearer secara langsung; laluan /api/cloud/*, /api/evals/*, dan /api/assess yang lain memerlukan sesi pengurusan/kunci API. POST /api/assess menggunakan validateBody dengan skema skop kesatuan berbeza.

Pengurusan ACP (Agent Client Protocol)

sebagai proses anak. Titik akhir ini mengurus pengesanan ejen ACP dan pendaftaran ejen tersuai.

Kaedah	Laluan	Penerangan
GET	/api/acp/agents	Senaraikan semua ejen CLI yang diketahui (terbina dalam + tersuai) berserta status pemasangan, versi dan perduaan
POST	/api/acp/agents	Daftarkan ejen ACP tersuai atau segarkan semula cache — isi: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} atau {action: "refresh"}
DELETE	/api/acp/agents	Alih keluar ejen ACP tersuai — parameter pertanyaan: ?id=<agentId>

Contoh respons (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
}

Pengesahan: Memerlukan sesi pengurusan (kuki auth_token papan pemuka) atau kunci API dengan skop pengurusan.

Lihat Rangka Kerja ACP untuk butiran lengkap.

---

Analitik & Kebolehcerapan

Titik akhir analitik masa nyata untuk memantau penghalaan, pemampatan dan kepelbagaian penyedia. Titik akhir ini menguasakan halaman /dashboard/analytics/*.

Analitik penghalaan automatik

Kaedah	Laluan	Penerangan
GET	/api/analytics/auto-routing	Statistik penghalaan automatik agregat: jumlah panggilan, taburan strategi, taburan peringkat, penyedia teratas
GET	/api/analytics/auto-routing?days=7	Statistik mengikut tetingkap masa (lalai 24j)

Contoh respons:

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

Analitik pemampatan

Kaedah	Laluan	Penerangan
GET	/api/analytics/compression	Statistik pemampatan agregat: token dijimatkan, % penjimatan, taburan mod, penggunaan enjin

Contoh respons:

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

Penjejakan kepelbagaian penyedia

Kaedah	Laluan	Penerangan
GET	/api/analytics/diversity	Penjejakan kepelbagaian berasaskan entropi Shannon: mencegah titik kegagalan tunggal dengan mengukur taburan penggunaan penyedia

Contoh respons:

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

Pengesahan: Memerlukan sesi pengurusan atau kunci API dengan skop pengurusan.

---

Operasi Pentadbir

Titik akhir khusus pentadbir untuk pengurusan operasi.

Kaedah	Laluan	Penerangan
GET	/api/admin/concurrency	Baca had konkurensi semasa (global + mengikut penyedia)
POST	/api/admin/concurrency	Kemas kini had konkurensi — badan: {global?: number, perProvider?: Record<string, number>}

Pengesahan: Memerlukan sesi pengurusan dengan skop pentadbir.

---

Pengurusan Alat CLI

Urus alat CLI yang berintegrasi dengan OmniRoute (antigravity, chipotle, commandCode, devin-cli, dll.). Lihat Rujukan Penyedia untuk senarai penuh.

Kaedah	Laluan	Penerangan
GET	/api/cli-tools/all-statuses	Status semua alat CLI (dipasang, versi, kali terakhir dilihat)
GET	/api/cli-tools/status	Butiran status untuk satu alat CLI (pertanyaan ?tool=)
POST	/api/cli-tools/apply	Tulis konfigurasi terjana alat (dryRun menyediakan pratonton; 422 + containerEphemeralTarget apabila dikontena; migration mencatatkan YAML Codex legasi)
GET	/api/cli-tools/backups	Senaraikan sandaran konfigurasi alat CLI
POST	/api/cli-tools/backups	Cipta sandaran bagi semua konfigurasi alat CLI
POST	/api/cli-tools/backups	Pulihkan: titik akhir yang sama dengan {tool, backupId} dalam badan akan memulihkan sandaran tersebut
GET	/api/cli-tools/antigravity-mitm	Status proksi MITM Antigravity (alat CLI "antigravity-mitm")
POST	/api/cli-tools/antigravity-mitm/alias	Konfigurasikan alias antigravity-mitm

Pengesahan: Memerlukan sesi pengurusan.

---

Kemahiran Ejen

Urus kemahiran ejen AI (serupa dengan GPT tersuai OpenAI tetapi untuk ejen).

Kaedah	Laluan	Penerangan
GET	/api/agent-skills	Senaraikan semua kemahiran ejen (terbina dalam + tersuai)
GET	/api/agent-skills/[id]	Dapatkan kemahiran ejen tertentu
POST	/api/agent-skills	Cipta kemahiran ejen tersuai — badan: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Kemas kini kemahiran ejen tersuai
DELETE	/api/agent-skills/[id]	Padam kemahiran ejen tersuai
GET	/api/agent-skills/[id]/raw	Dapatkan gesaan mentah + metadata (tanpa pelaksanaan)
POST	/api/agent-skills/generate	Jana kemahiran baharu menggunakan AI daripada penerangan bahasa semula jadi

Pengesahan: Memerlukan sesi pengurusan atau kunci API dengan skop pengurusan.

---

Pengurusan Cache

Urus cache semantik dan cache penaakulan.

Kaedah	Laluan	Penerangan
GET	/api/cache	Gambaran keseluruhan cache: jumlah entri, kadar padanan, saiz pada cakera
GET	/api/cache/entries	Senaraikan entri yang dicache (dengan penomboran halaman)
DELETE	/api/cache/entries	Padam entri cache (tapis mengikut parameter pertanyaan)
GET	/api/cache/stats	Statistik cache terperinci (mengikut penyedia, mengikut model)
GET	/api/cache/reasoning	Status cache penaakulan (untuk main semula penaakulan)
DELETE	/api/cache/reasoning	Kosongkan cache penaakulan — parameter pertanyaan: ?toolCallId=<id> (tunggal) atau ?provider=<p> atau tanpa parameter (semua)

Pengesahan: Memerlukan sesi pengurusan.

---

Sistem Memori

Urus memori berterusan (FTS5 + pembenaman vektor).

Kaedah	Laluan	Penerangan
GET	/api/memory	Senaraikan entri memori (tapis mengikut skop, jenis, pertanyaan carian)
POST	/api/memory	Cipta entri memori baharu — isi: {scope, type, content, metadata?}
GET	/api/memory/[id]	Dapatkan entri memori tertentu
PUT	/api/memory/[id]	Kemas kini entri memori
DELETE	/api/memory/[id]	Padam entri memori
GET	/api/memory?q=	Cari memori (FTS5 + vektor) — statistik disertakan dalam respons yang sama

Pengesahan: Memerlukan sesi pengurusan atau kunci API dengan skop pengurusan.

---

Webhook

Urus langganan webhook untuk acara.

Kaedah	Laluan	Penerangan
GET	/api/webhooks	Senaraikan semua langganan webhook
POST	/api/webhooks	Cipta langganan webhook — isi: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Dapatkan langganan webhook tertentu
PUT	/api/webhooks/[id]	Kemas kini langganan webhook
DELETE	/api/webhooks/[id]	Padam langganan webhook
GET	/api/webhooks/[id]/deliveries	Senaraikan sejarah penghantaran untuk webhook (log kejayaan/kegagalan)
POST	/api/webhooks/[id]/test	Hantar acara ujian kepada webhook

Pengesahan: Memerlukan sesi pengurusan.

Lihat Rangka Kerja Webhook untuk jenis acara yang lengkap.

---

Rangka Kerja Skills

Urus Skills (rangka kerja sambungan berasaskan ejen).

Kaedah	Laluan	Penerangan
GET	/api/skills	Senaraikan semua skill yang dipasang (terbina dalam + tersuai)
POST	/api/skills/install	Pasang skill daripada laluan setempat atau URL
DELETE	/api/skills/[id]	Nyahpasang skill
PUT	/api/skills/[id]	Dayakan atau nyahdayakan skill — isi: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Laksanakan skill — isi: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	Senaraikan sejarah pelaksanaan untuk semua skill (tapis mengikut ?apiKeyId=)

Pengesahan: Memerlukan sesi pengurusan atau kunci API dengan skop pengurusan.

Lihat Rangka Kerja Skills untuk butiran lengkap.

---

Plugin

Urus plugin OmniRoute (sambungan pihak ketiga).

Kaedah	Laluan	Penerangan
GET	/api/plugins	Senaraikan plugin yang dipasang
POST	/api/plugins/marketplace/install	Pasang plugin daripada marketplace
DELETE	/api/plugins/[name]	Nyahpasang plugin
POST	/api/plugins/[name]/activate	Aktifkan plugin
POST	/api/plugins/[name]/deactivate	Nyahaktifkan plugin
GET	/api/plugins/[name]/config	Dapatkan konfigurasi plugin
PUT	/api/plugins/[name]/config	Kemas kini konfigurasi plugin

Pengesahan: Memerlukan sesi pengurusan.

Lihat Rangka Kerja Plugin untuk butiran lengkap.

---

Penghalaan Bayangan

Perbandingan bayangan / A-B bagi penyedia bukan permukaan REST kendiri — ia dikonfigurasikan melalui penghalaan kombo (lihat Auto-Combo). Metrik perbandingan bagi setiap kombo disediakan oleh GET /api/combos/metrics.

---

Kawalan Keselamatan

Periksa kawalan keselamatan masa jalan (pengesanan PII, pengesanan suntikan gesaan, perantaraan visi). Kawalan keselamatan dijalankan pada setiap permintaan; pengecualian bagi setiap panggilan dilakukan melalui pengepala permintaan x-omniroute-disabled-guardrails — tiada permukaan daya/nyahdaya yang disimpan.

Kaedah	Laluan	Penerangan
GET	/api/guardrails	Senaraikan kawalan keselamatan yang didaftarkan dan statusnya (nama / didayakan / keutamaan)
POST	/api/guardrails/test	Jalankan percubaan kering bagi saluran paip prapanggilan pada input sampel — isi: {input, disabledGuardrails?}

Pengesahan: Memerlukan sesi pengurusan.

Lihat Keselamatan > Kawalan Keselamatan untuk butiran lengkap.

---

---

Pengesahan

Lihat Pengesahan Pengurusan untuk empat keluarga bukti kelayakan (sesi papan pemuka, token CLI setempat, Token Akses oma_live_…, kunci API berskop pengurusan) dan perbezaannya daripada kunci inferens.

• Laluan papan pemuka (/dashboard/*) menggunakan kuki auth_token
• Log masuk menggunakan cincangan kata laluan yang disimpan; sandaran kepada INITIAL_PASSWORD
• requireLogin boleh ditogol melalui /api/settings/require-login
• Laluan /v1/* secara pilihan memerlukan kunci API Bearer apabila REQUIRE_API_KEY=true
• "token pengurusan" / "kunci API berskop pengurusan" dalam rujukan ini bermaksud salah satu keluarga dalam panduan tersebut — bukan jenis rahsia tambahan yang tidak ditakrifkan

Perubahan yang memecahkan keserasian (v3.8.0) — /api/v1/agents/tasks/* dan titik akhir pengurusan tempoh bertenang kini memerlukan pengesahan pengurusan (kuki auth_token papan pemuka atau kunci API berskop pengurusan). Klien yang sebelum ini memanggil laluan ini tanpa pengesahan akan menerima 401 Unauthorized. Lihat komit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).