Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
API Reference (Bahasa Indonesia)
🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW
🌐 Bahasa: 🇺🇸 English | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇧🇦 Bosanski | 🇨🇿 Č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á | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)
Referensi inti untuk API OmniRoute. Dokumen ini mencakup antarmuka publik /v1 dan endpoint manajemen yang paling sering digunakan; docs/openapi.yaml yang dapat dibaca mesin serta pohon rute di bawah src/app/api/ merupakan sumber yang lengkap.
Untuk protokol khusus yang kompatibel dengan OpenAI dan matriks kemampuan penyedia, lihat
OPENAI_COMPATIBILITY.md.
Daftar Isi
- Penyelesaian Chat
- Lease Sesi Terkelola Eksklusif
- Embedding
- Pembuatan Gambar
- OCR Dokumen
- Daftar Model
- Manifes Plugin Penyedia
- Endpoint Kompatibilitas
- API File
- API Batch
- API Pencarian
- Streaming WebSocket
- Pelaporan Kuota & Masalah
- Cache Semantik
- Dasbor & Pengelolaan
- Pengelolaan Combo
- Webhook
- Kunci Terdaftar (Pengelolaan Otomatis)
- Protokol Agen
- Proksi Pengelolaan
- Ketahanan (diperluas)
- Keterampilan
- Memori
- Server MCP
- Server A2A
- Cloud, Evaluasi & Penilaian
- Pemrosesan Permintaan
- Autentikasi
Penyelesaian Percakapan
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
}
Header Khusus
| Header | Arah | Deskripsi |
|---|---|---|
X-OmniRoute-No-Cache |
Permintaan | Atur ke true untuk melewati cache |
x-omniroute-no-memory |
Permintaan | Atur ke true untuk melewati injeksi memori + keterampilan pada permintaan ini (mencerminkan no-cache; menghindari overhead token/biaya per panggilan) |
X-OmniRoute-Progress |
Permintaan | Atur ke true untuk peristiwa progres |
X-Session-Id |
Permintaan | Kunci sesi tetap untuk afinitas sesi eksternal |
x_session_id |
Permintaan | Varian dengan garis bawah juga diterima (HTTP langsung) |
X-OmniRoute-Session-Id |
Permintaan | Tag sesi/percakapan yang diberikan pemanggil (juga digunakan oleh memori). Jika tersedia, disimpan apa adanya ke call_logs.session_tag untuk atribusi biaya per sesi (#8249) — tidak pernah dibuat jika tidak tersedia |
Idempotency-Key |
Permintaan | Kunci deduplikasi (jendela 5 detik) |
X-Request-Id |
Permintaan | Kunci deduplikasi alternatif |
x-omniroute-connection |
Permintaan | Sematkan permintaan model tunggal ke satu koneksi penyedia (akun) berdasarkan id-nya — lihat Penyematan akun per permintaan |
X-OmniRoute-Cache |
Respons | HIT atau MISS (non-streaming) |
X-OmniRoute-Idempotent |
Respons | true jika dideduplikasi |
X-OmniRoute-Progress |
Respons | enabled jika pelacakan progres aktif |
X-OmniRoute-Session-Id |
Respons | ID sesi efektif yang digunakan oleh OmniRoute |
X-OmniRoute-Request-Id |
Respons | ID korelasi permintaan (jika diketahui) |
X-OmniRoute-Version |
Respons | Versi build OmniRoute (selalu tersedia) |
X-OmniRoute-Cost-Saved |
Respons | Jumlah USD yang dihemat cache pada HIT (khusus cache hit) |
X-OmniRoute-Decision |
Respons | Jejak perutean: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> adalah strategi kombinasi, atau single untuk permintaan non-kombinasi) — selalu tersedia pada respons penyelesaian |
Catatan Nginx: jika Anda mengandalkan header dengan garis bawah (misalnya
x_session_id), aktifkanunderscores_in_headers on;.
Penyematan akun per permintaan
Ketika penyedia memiliki beberapa koneksi (akun atau kunci), OmniRoute biasanya memilih salah satunya
melalui strategi pemilihan akunnya. Sebagai alternatif, permintaan dapat disematkan ke satu koneksi tertentu
dengan header x-omniroute-connection:
curl http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer <your OmniRoute API key>" \
-H "Content-Type: application/json" \
-H "x-omniroute-connection: <connection id>" \
-d '{"model": "codex/gpt-5.5", "messages": [{"role": "user", "content": "hi"}]}'
- Tempat menemukan id. Buka halaman penyedia di dasbor
(Dasbor → Penyedia → ) dan klik chip id
xxxxxxxx…pada baris koneksi — tindakan ini akan menyalin id koneksi lengkap. - Permintaan yang mematuhinya. Permintaan model tunggal (
provider/model) pada/v1/chat/completions,/v1/messages, dan/v1/responses. Kombo mengabaikan header tersebut: sematkan akun untuk setiap langkah kombo melalui koneksi milik langkah itu sendiri. - Penyematan bersifat ketat, bukan preferensi. Koneksi yang disematkan digunakan secara eksklusif. Kegagalan di dalam permintaan akan mencatat masa cooldown akun, tetapi tidak beralih ke akun lain dari penyedia yang sama.
- Cooldown dan kuota melepaskan penyematan. Saat koneksi yang disematkan sedang dalam masa cooldown, kehabisan kuota, atau diblokir oleh kebijakan kuota, permintaan berikutnya akan beralih ke koneksi lain milik penyedia tersebut, sama persis seperti lalu lintas tanpa penyematan.
- Id yang tidak dikenal atau dinonaktifkan akan gagal. Id yang tidak berada dalam kumpulan aktif penyedia (dihapus, dinonaktifkan, atau merupakan milik penyedia lain) tidak menyisakan akun yang memenuhi syarat, sehingga permintaan akan gagal alih-alih secara diam-diam dirutekan ke tempat lain.
Claude Code mengirimkan header khusus melalui ANTHROPIC_CUSTOM_HEADERS. Letakkan variabel tersebut
di blok env dalam ~/.claude/settings.json, atau di .claude/settings.json tingkat proyek untuk
menyematkan akun yang berbeda bagi setiap proyek:
{
"env": {
"ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
"ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
"ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>",
},
}
Sumber: src/sse/handlers/chat.ts (pembacaan header), src/sse/services/auth.ts, dan
src/sse/services/sessionAffinityPin.ts (pelepasan penyematan dan pemeriksaan ketiadaan dari kumpulan).
Header telemetri biaya: respons berhasil non-streaming juga menyertakan rangkaian telemetri biaya
X-OmniRoute-*—X-OmniRoute-Response-Cost(USD, tetap 10 angka desimal;0.0000000000untuk yang gratis/tanpa harga),X-OmniRoute-Tokens-In/X-OmniRoute-Tokens-Out,X-OmniRoute-Model,X-OmniRoute-Provider,X-OmniRoute-Latency-Ms,X-OmniRoute-Cache-Hit, danX-OmniRoute-Fallback-Attempts(hanya jika > 0), sertaX-OmniRoute-Request-IddanX-OmniRoute-Version. Header tersebut dihasilkan oleh penyelesaian chat,/v1/responses,/v1/messages, dan endpoint media —/v1/embeddings,/v1/images/generations,/v1/audio/speech,/v1/audio/transcriptions,/v1/rerank,/v1/videos/generations,/v1/music/generations, dan/v1/moderations(biaya selalu0). Biaya media dihitung per modalitas (per gambar, per detik, per karakter, per unit pencarian) jika informasi harga tersedia; jika tidak, nilainya0(fail-open).
Semantik biaya cache hit: pada HIT cache semantik (
X-OmniRoute-Cache-Hit: true), tidak ada panggilan upstream yang dilakukan, sehinggaX-OmniRoute-Response-Costbernilai0.0000000000(biaya inkremental untuk menyajikan hit tersebut). Biaya asli/yang seharusnya dikeluarkan dilaporkan secara terpisah dalamX-OmniRoute-Cost-Saved. Konsumen penagihan harus menjumlahkanX-OmniRoute-Response-Cost(hit tidak menimbulkan biaya); analitik cache dapat mengagregasiX-OmniRoute-Cost-Saved.
Sewa Sesi Terkelola Eksklusif
Penyewaan sesi terkelola eksklusif adalah kontrak perutean yang bersifat opt-in dan netral klien: satu pemilik aktif memegang satu koneksi OmniRoute yang memenuhi syarat. Ini tidak menyewakan model, memerlukan OAuth, mengidentifikasi klien tertentu, atau memerlukan penyedia tertentu.
Kunci API yang mengautentikasi harus memiliki cakupan lease:exclusive dan daftar allowedConnections yang eksplisit dan tidak kosong. Batas mutasi database memberlakukan kedua bidang secara bersamaan pada pembuatan kunci dan pembaruan parsial.
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 akuisisi, perpanjangan, dan pelepasan yang berhasil menampilkan stempel waktu, state, dan generation positif yang tepat, tetapi tidak pernah koneksi atau kredensial yang dipilih. Perpanjangan dan pelepasan menyediakan generasi dalam badan JSON:
{ "action": "renew", "generation": 1 }
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
Pemilik sewa aktif dapat secara eksplisit meminta metadata tampilan yang aman privasi untuk pengikatan saat ini:
{ "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 opt-in ini dibatasi oleh pemilik buram, kunci API terkelola yang diautentikasi, dan generasi aktif yang tepat dalam satu transaksi database. displayName hanyalah nama koneksi yang dikonfigurasi yang dipangkas; ini null ketika tidak ada nama yang dikonfigurasi yang aman. OmniRoute tidak pernah mengganti email atau identitas akun yang dihasilkan. Nilai penyedia adalah label tampilan yang tidak sensitif dan tidak pernah menjadi pengidentifikasi penyedia yang kompatibel yang dihasilkan. Kredensial, token, cookie, ID koneksi mentah atau kunci API, hash pemilik, rahasia pembatasan, dan data perutean internal dikecualikan.
Pencarian kunci yang salah, pemilik yang salah, generasi yang usang, hilang, kedaluwarsa, dilepaskan, dan tidak valid semuanya mengembalikan kesalahan 409 LEASE_FENCE_STALE yang sama tanpa metadata koneksi. Klien yang menerima respons tunggu kapasitas tidak memiliki pengikatan aktif untuk diperiksa. Ketika perutean mentransisikan sewa aktif, generasi yang sama tetap valid dan status secara atomik mengembalikan pengikatan baru, tidak pernah yang lama. Klien yang ada tetap tidak berubah karena respons akuisisi, perpanjangan, pelepasan, dan tunggu mempertahankan bentuk sebelumnya.
Kontrak server ini tidak mengubah stok OpenAI Codex /status. Stok Codex saat ini melaporkan penyedia modelnya dan status autentikasi/akun bawaan tetapi tidak merender metadata akun penyedia kustom arbitrer; integrasi klien selanjutnya harus memanggil tindakan ini dan memutuskan cara menampilkan connection.displayName.
Setiap permintaan inferensi terkelola kemudian menyediakan kedua header kontrol:
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
Pemilik yang tepat, generasi, koneksi aktif, dan kunci API yang diautentikasi dibatasi segera sebelum setiap upaya upstream yang didukung. Memutar ulang pemilik dan generasi dengan kunci lain gagal bahkan ketika kunci tersebut mengizinkan koneksi yang sama. Pemilik mentah tidak disimpan, dicatat, dipertahankan dalam snapshot permintaan, atau diteruskan ke upstream.
Pertentangan 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 berarti bahwa set yang memenuhi syarat biasa tidak kosong dan setiap kandidat bebas dipegang oleh sewa aktif asing. Model/penyedia yang tidak didukung, ketidakcocokan kebijakan, pendinginan, kuota, kesehatan, dan kegagalan kelayakan biasa lainnya mempertahankan respons OmniRoute yang ada.
x-omniroute-compression
Penggantian per-permintaan dari rencana kompresi. Prioritas tertinggi — mengalahkan penggantian kombo perutean, profil aktif, pemicu otomatis, dan panel Default. Nilai:
| Nilai | Efek |
|---|---|
off |
Tidak ada kompresi untuk permintaan ini. |
default |
Profil Default yang berasal dari panel (mengabaikan profil aktif). Mesin lossy dibiarkan mati. |
safe |
Hanya dedup dan pelipatan spasi. |
allow-lossy |
Pertahankan rencana operator untuk permintaan ini, termasuk ringkasan dan penulisan ulang gaya. |
engine:<id> |
Satu mesin saat diaktifkan, mis. engine:rtk. Opt-in per-permintaan untuk mesin itu. |
<combo> |
Kombo bernama, dicocokkan berdasarkan nama (tidak peka huruf besar/kecil) terlebih dahulu, lalu berdasarkan id. |
Catatan:
- Nilai yang tidak dikenal diabaikan (permintaan tidak pernah ditolak); resolusi jatuh ke prioritas operator normal.
- Jika beberapa kombo memiliki nama yang sama, berikan id kombo untuk kecocokan yang deterministik.
- Kombo yang namanya
offataudefaulttidak dapat dipilih berdasarkan nama (kata kunci tersebut diinterpretasikan terlebih dahulu); referensikan kombo tersebut berdasarkan id-nya. - Sakelar kompresi master adalah gerbang keras: ketika kompresi dinonaktifkan secara global, header ini tidak dapat mengaktifkannya.
Rencana yang diterapkan diulang kembali di header respons:
X-OmniRoute-Compression: <mode>; source=<source>
di mana <source> adalah salah satu dari request-header, routing-override, active-profile, auto-trigger, default, atau off.
Embedding
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "nebius/Qwen/Qwen3-Embedding-8B",
"input": "The food was delicious"
}
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 awalan yang tercantum dalam registri (misalnya jina-embeddings-v5-text-small, jina-reranker-v3.5) juga dapat diresolusikan. Operasi embed/rerank/classify/segment Jina terlebih dahulu menggunakan kredensial jina-ai dari dasbor; JINA_AI_API_KEY hanya digunakan sebagai fallback jika tidak ada kunci dasbor. Kartu jina-reader hanya untuk Reader / r.jina.ai (POST /v1/web/fetch) dan tidak pernah melayani embedding atau rerank.
Model registri yang menyatakan dukungan multimodal juga menerima hingga 32 item terstruktur yang netral terhadap penyedia. Jenis item media adalah text, image, audio, video, dan document. source media tersebut berupa {"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 famili jina-ai/jina-embeddings-v5-omni → omni-small) juga menerima dokumen EmbeddingsV5Request native milik Jina dan meneruskannya secara utuh ke 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 native { image | audio | video | pdf } dapat berupa URL HTTPS publik, URI data:, atau base64 mentah. OmniRoute tidak mengubah objek tersebut menjadi string ataupun mengambil URL gambar native—Jina sendiri yang mengambil media publik. Bidang tambahan Jina (task, normalized, truncate, embedding_type) diteruskan. SKU Jina yang hanya mendukung teks tetap menolak dokumen nonteks.
Batasan keamanan dan transportasi:
- URL media jarak jauh harus berupa HTTPS publik. Item kanonis
{type,source:url}diambil di sisi server (dengan validasi ulang pengalihan, batas waktu, batas ukuran, DNS publik, dan penguncian koneksi), lalu disisipkan sebelum pemanggilan penyedia. Item native Jina{image:"https://..."}diteruskan apa adanya setelah pemeriksaan HTTPS publik yang sama; Jina yang mengambil URL tersebut. - Media base64 inline dibatasi hingga 8 MiB hasil dekode per item dan 16 MiB hasil dekode untuk seluruh permintaan.
Penerjemahan format penyedia (item kanonis tidak pernah diteruskan tanpa perubahan):
- Model multimodal Jina: setiap item tingkat teratas menjadi satu objek dengan kunci modalitas (
text/image/audio/video/pdf) menggunakan URI data untuk media inline; satu vektor per item tingkat teratas. - Famili Gemini Embedding 2: satu array tingkat teratas menjadi satu permintaan native
models/{model}:embedContentdengancontent.parts(textatauinline_data). - llama.cpp (
llama-cpp/<model>, model apa pun yang dimuat oleh server lokal): itemtextkanonis menjadi string biasa, sedangkanimage/audio/videomasing-masing menjadi satu objek{"content": [part]}, menggunakan bagian konten percakapan llama-server (image_url,input_audiodengan formatwav/mp3/flac,input_video) dengan data inline; satu vektor per item tingkat teratas. Server harus dijalankan dengan--embedding --mmproj …; tanpa proyektor, server akan menolak media tersebut.documenttidak didukung. - Model tidak dikenal/dinamis tanpa metadata modalitas eksplisit menolak input terstruktur 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"
}
Kombinasi model/modalitas yang tidak didukung mengembalikan HTTP 400 alih-alih mengonversi item secara paksa. Bidang ekstensi selain input pada permintaan string/token lama tetap diteruskan tanpa perubahan.
# Cantumkan semua model embedding
GET /v1/embeddings
Pembuatan Gambar
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "openai/gpt-image-2",
"prompt": "Pemandangan matahari terbenam yang indah di atas pegunungan",
"size": "1024x1024"
}
Penyedia yang tersedia mencakup OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, ZenMux, SD WebUI (lokal), ComfyUI (lokal).
n mengembalikan n gambar dalam data[]. Penyedia yang API upstream-nya mengembalikan satu gambar per panggilan
(Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik,
NVIDIA NIM, Cloudflare Workers AI) akan mendapatkan n panggilan upstream terpisah, dengan maksimal 4 panggilan berlangsung bersamaan. Nilai
seed yang tetap digeser berdasarkan indeks panggilan (seed, seed + 1, …), sehingga gambar yang dihasilkan berbeda tetapi tetap
dapat direproduksi. n dibatasi hingga 10. Permintaan akan gagal secara keseluruhan jika salah satu panggilan gagal. Daftar
format fan-out adalah SINGLE_IMAGE_FANOUT_FORMATS dalam
open-sse/handlers/imageGeneration/fanOut.ts.
ZenMux menggunakan kembali koneksi kunci API yang ada dan menerima awalan zenmux/ atau zm/:
zenmux/openai/gpt-image-2menggunakan OpenAI Images API milik ZenMux. Opsi yang tersedia mencakupsize,quality,n,output_format,output_compression,background, danresponse_format.- Penerbit lain, seperti
zm/meta/muse-image-1.0, menggunakan endpoint:predictVertex AI milik ZenMux.ndipetakan kesampleCount,aspect_ratiokeaspectRatio, danimage_size(1K,2K,4K) kesampleImageSize.sizeberbasis piksel hanya menentukan rasio aspek, bukan dimensi piksel yang dijamin. Rasio, resolusi, dan jumlah yang didukung berbeda-beda menurut model. zm/inclusionai/ming-image-0.1-designmenentukan dimensinya sendiri. Jangan sertakansize,aspect_ratio, danimage_size; nilai eksplisit akan menghasilkan HTTP 400. PNG, JPEG, dan WebP dapat diminta melaluioutput_format.
Integrasi ini mendukung pembuatan gambar dari teks, bukan pengeditan gambar referensi. Output Vertex
dinormalisasi menjadi data[].b64_json; response_format: "url" mengembalikan URL HTTPS upstream
atau URL data base64 ketika hanya byte gambar yang tersedia. Output kosong/terfilter
akan menghasilkan kesalahan alih-alih respons sukses kosong. Akses model bergantung pada akun ZenMux.
Lihat Vertex API ZenMux dan
OpenAI Images API.
# Cantumkan semua model gambar
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 (misalnya
mistral-ocr-latest) akan diarahkan ke penyedia yang terdaftar, dan jika model tidak dicantumkan, nilai default-nya adalah
Mistral (mistral-ocr-latest). Penyedia yang terdaftar (open-sse/config/ocrRegistry.ts):
| Id penyedia | Id model | Nilai model |
Catatan |
|---|---|---|---|
mistral |
mistral-ocr-latest |
mistral/mistral-ocr-latest (atau tanpa awalan mistral-ocr-latest) |
Sinkron — respons dikembalikan langsung dari satu panggilan upstream. |
azure-document-intelligence |
prebuilt-read |
azure-document-intelligence/prebuilt-read |
Upstream asinkron (analyze + polling) — lihat di bawah. |
vertex-deepseek-ocr |
deepseek-ocr-maas |
vertex-deepseek-ocr/deepseek-ocr-maas |
Sinkron, melalui endpoint mitra openapi/chat/completions milik Vertex AI — lihat di bawah untuk autentikasi/URL. |
Ketiga penyedia memberikan respons dengan struktur yang sama seperti Mistral:
{
"pages": [{ "index": 0, "markdown": "# Teks yang diekstrak..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
Alur polling Azure Document Intelligence
API analyze Azure Document Intelligence bersifat asinkron: permintaan awal mengembalikan header
Operation-Location, bukan isi respons, dan hasilnya harus diperiksa melalui polling. Handler
(open-sse/handlers/ocr.ts) melakukan polling terhadap URL tersebut setiap detik hingga maksimal 30 percobaan, langsung gagal (tidak
melanjutkan polling) jika respons polling bukan ok atau statusnya "failed", dan mengembalikan 504 jika
operasi masih berjalan setelah jatah percobaan habis. Respons akhir Azure
dinormalisasi ke dalam struktur pages/markdown yang sama dengan yang digunakan Mistral sebelum dikembalikan kepada
pemanggil, sehingga kode klien tidak perlu menangani penyedia secara khusus.
Autentikasi dan resolusi endpoint OCR DeepSeek Vertex AI
vertex-deepseek-ocr menggunakan kembali autentikasi Vertex AI yang sudah didukung OmniRoute untuk
lalu lintas percakapan/gambar (open-sse/executors/vertex.ts): kunci API koneksi dapat berupa
kredensial JSON Service Account (ditukar dengan token akses OAuth berumur pendek melalui alur JWT-bearer)
atau token akses OAuth yang sudah diterbitkan dan digunakan apa adanya. URL endpoint upstream adalah endpoint
mitra generik openapi/chat/completions milik Vertex, yang dibuat berdasarkan proyek dan
wilayah koneksi — providerSpecificData.project/providerSpecificData.region yang ditentukan secara eksplisit selalu diprioritaskan;
jika tidak, proyek diturunkan dari project_id dalam JSON Service Account dan wilayah
secara default menggunakan us-central1. Kedua resolusi berlangsung di open-sse/handlers/ocr.ts
(resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), lalu digunakan oleh
src/app/api/v1/ocr/route.ts sebelum diteruskan ke handleOcr.
Daftar Model
GET /v1/models
Authorization: Bearer your-api-key
→ Mengembalikan semua model chat, embedding, dan gambar + combo dalam format OpenAI
Prefiks id model (?prefix=)
Sebagian besar model ditampilkan di bawah prefiks penyedia. Prefiks yang Anda dapatkan dikontrol oleh
feature flag MODELS_CATALOG_PREFIX_MODE, dan dapat diganti per permintaan dengan
parameter kueri — berguna bagi klien yang menginginkan daftar bersih tanpa mengubah pengaturan
seluruh server untuk pengguna lain:
GET /v1/models?prefix=alias # satu id per model — prefiks alias singkat
GET /v1/models?prefix=dual # kedua bentuk (default server)
GET /v1/models?prefix=canonical # hanya prefiks lengkap id penyedia
| Mode | Menghasilkan | Catatan |
|---|---|---|
dual |
cc/claude-sonnet-4-6 dan claude/claude-sonnet-4-6 |
Default. Kedua id diarahkan ke model yang sama; dipertahankan agar konfigurasi klien yang mengodekan salah satu bentuk secara tetap dapat terus berfungsi. Kira-kira menggandakan katalog. |
alias |
cc/claude-sonnet-4-6 |
Satu entri per model. Penyedia tanpa alias yang berbeda tetap menghasilkan entrinya, sehingga tidak ada yang hilang. |
canonical |
claude/claude-sonnet-4-6 |
Satu entri per model di bawah prefiks lengkap id penyedia. Penyedia tanpa alias yang berbeda (misalnya antigravity/…, agy/…) juga menghasilkan id tunggalnya di sini, sehingga tidak ada yang hilang. |
Mirror mode dual juga dapat dikenali tanpa parameter kueri: mirror tersebut memiliki field parent
yang menunjuk ke id utama.
Klien yang merender pemilih model sebaiknya meminta ?prefix=alias — inilah yang dilakukan oleh
ekstensi OmniCopilot VS Code.
Filter penemuan (?capability=, ?min_context=, ?kind=, ?q=)
GET /v1/models menerima filter penemuan opsional. Tanpa filter tersebut, respons
tidak berubah. Filter tersebut mempersempit katalog yang sudah dapat dilihat pemanggil (izin kunci API diterapkan terlebih dahulu),
dan dijalankan sebelum paginasi bergaya OpenAI limit / after:
GET /v1/models?capability=vision&capability=tool_calling # setiap kapabilitas yang dicantumkan harus bernilai true
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding # `type` katalog; baris tanpa nilai tersebut dianggap `chat`
GET /v1/models?q=sonnet&limit=10 # pencocokan id atau nama tanpa membedakan huruf besar-kecil
| Param | Nilai |
|---|---|
capability |
attachment, reasoning, structured_output, temperature, thinking, tool_calling, vision |
min_context |
bilangan bulat nonnegatif, dibandingkan dengan context_length |
kind |
chat, audio, embedding, image, moderation, music, rerank, video |
q |
1–200 karakter |
Nilai yang tidak dikenal, atau min_context yang bukan bilangan bulat nonnegatif (misalnya 1.5),
mengembalikan HTTP 400 dan pesan yang mencantumkan nilai-nilai yang valid. Implementasi:
src/app/api/v1/models/catalogFilters.ts.
Daftar pendek model (POST /v1/models/query)
POST /v1/models/query mengembalikan daftar pendek yang deterministik dari katalog yang sama, dengan autentikasi
dan visibilitas per kunci yang sama seperti GET /v1/models:
POST /v1/models/query
Authorization: Bearer your-api-key
Content-Type: application/json
{ "capabilities": ["vision", "tool_calling"], "min_context": 128000, "max_output": 16000,
"kind": "chat", "q": "gpt", "owned_by": "openai", "exclude": ["openai/gpt-4o"], "limit": 5 }
→ { "object": "list", "data": [ ...models ] }
Setiap field bersifat opsional. capabilities dan exclude menerima array atau string yang dipisahkan koma;
max_output dibandingkan dengan max_output_tokens. Hasil diurutkan berdasarkan owned_by, lalu id.
Nilai default limit adalah 20 dan nilai di atas 100 dibatasi menjadi 100. JSON yang tidak valid, field yang tidak dikenal,
atau nilai yang tidak valid akan mengembalikan HTTP 400.
Model chat yang disembunyikan secara individual
Model yang ditandai Tersembunyi pada halaman penyedianya dikecualikan dari katalog dan ditolak
dengan HTTP 404 / model_not_found saat diminta secara eksplisit. Pemeriksaan menggunakan
penyedia dan model yang telah di-resolve, termasuk alias penyedia, prefiks node penyedia yang kompatibel, dan
default koneksi. Combo melewati target tersembunyi dan dapat menggunakan model lain yang terlihat; jika tidak ada
target yang dapat dieksekusi, combo tersebut mengembalikan kode kesalahan yang sama. Membatalkan penyembunyian mulai berlaku pada
permintaan berikutnya. Penggantian visibilitas khusus gambar tidak menyembunyikan model chat dengan ID yang sama.
Pengaturan model individual ini terpisah dari
daftar izinkan/tolak eksposur model, yang memfilter model yang ditampilkan dalam katalog
dan kandidat perutean otomatis, sambil tetap mempertahankan dispatch eksplisit. Izin model
kunci API tetap diterapkan secara independen. Mode prefiks katalog default tetap dual.
Varian model tanpa thinking
Untuk model Claude yang mendukung thinking, /v1/models juga menampilkan varian tanpa thinking dengan id yang diawali claude-3-omniroute-no-thinking/:
claude-3-omniroute-no-thinking/<provider>/<model>
Memilih id ini (misalnya dalam konfigurasi Claude Code yang selalu menyertakan blok thinking) akan kembali merujuk ke <provider>/<model> yang sebenarnya dengan penalaran dinonaktifkan — thinking:{type:"disabled"} pada jalur /v1/messages, atau kolom reasoning/reasoning_effort dihapus pada jalur /v1/chat/completions. Varian ini hanya dicantumkan untuk model keluarga Claude yang mendukung thinking dan mematuhi disabled (sehingga, misalnya, model khusus adaptif yang menolak disabled tidak disertakan). Operator dapat mengaktifkan atau menonaktifkan varian ini secara paksa untuk setiap model melalui ModelSpec.noThinkingAlias.
Manifes Plugin Penyedia
GET /api/v1/provider-plugin-manifest
Mengembalikan manifes plugin penyedia yang aman untuk JSON dan digunakan oleh Bifrost, CLIProxyAPI, serta router sidecar pada masa mendatang. Respons dihasilkan dari registri penyedia TypeScript dan sengaja mengecualikan rahasia klien OAuth, resolusi lingkungan runtime, fungsi eksekutor, header permintaan, dan data akun.
Gunakan endpoint ini ketika sidecar berjalan di luar proses dan tidak dapat mengimpor open-sse/config/providerPluginManifestRegistry.ts secara langsung.
Endpoint Kompatibilitas
| Metode | Jalur | Format |
|---|---|---|
| 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 (edit/inpaint) |
| POST | /v1/videos/generations |
Pembuatan video bergaya OpenAI |
| POST | /v1/music/generations |
Pembuatan musik bergaya OpenAI |
| POST | /v1/audio/transcriptions |
OpenAI Audio (STT) |
| POST | /v1/audio/speech |
OpenAI TTS (mengembalikan isi audio) |
| POST | /v1/rerank |
Pemeringkatan ulang bergaya Cohere/Voyage |
| POST | /v1/classify |
Klasifikasi Jina (api.jina.ai) |
| POST | /v1/segment |
Segmenter Jina (segment.jina.ai) |
| POST | /v1/moderations |
OpenAI Moderations |
| GET | /v1/models |
OpenAI |
| POST | /v1/models/query |
Daftar pilihan model terfilter |
| 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 OpenAI bertoken |
| POST | /api/v1/vscode/{token}/responses |
Alias OpenAI Responses bertoken |
| POST | /api/v1/vscode/{token}/api/chat |
Alias Ollama bertoken |
| GET | /api/v1/vscode/{token}/api/tags |
Alias tag Ollama bertoken |
Semua rute POST mengikuti struktur yang sama: Bearer your-api-key + isi JSON yang divalidasi oleh Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema, dan sebagainya; lihat src/shared/validation/schemas.ts). 4xx dikembalikan jika validasi skema gagal.
Untuk klien yang tidak dapat menyertakan Authorization: Bearer ..., OmniRoute juga menerima kunci API di URL melalui kompatibilitas string kueri (?token=..., ?apiKey=..., ?api_key=..., ?key=...) atau endpoint khusus /api/v1/vscode/{token}/... yang didokumentasikan di bawah ini.
# Pemeringkatan ulang (penyedia registri cloud, atau node penyedia yang kompatibel dengan OpenAI sebagai "<prefix>/<model>")
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Klasifikasi Jina (kredensial Foundation API)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Segmenter Jina
POST /v1/segment { "content": "...", "return_chunks": true }
# Pencarian 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" }
# Soniox TTS memerlukan bahasa dan suara: `language` secara default adalah "en"; jika
# suara tidak diberikan atau menggunakan nama suara bawaan OpenAI (alloy, nova, …), nilainya menjadi "Adrian"
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }
# Pengeditan gambar (multipart)
POST /v1/images/edits -F [email protected] -F prompt="..." -F [email protected]
# Pembuatan video/musik (ID model dengan prefiks penyedia)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "kie/suno-v4.0", "prompt": "..." }
Node penyedia pemeringkatan ulang:
POST /v1/rerankjuga merutekan ke node penyedia yang kompatibel dengan OpenAI (oMLX, vLLM, Infinity, TEI di belakang gateway, …) yang dialamatkan sebagai<node-prefix>/<model>. Node loopback (localhost,127.0.0.1,172.16.0.0/12) selalu memenuhi syarat, begitu pula nama host yang dicantumkan operator dalamOMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS(misalnya nama layanan Docker/Compose sepertihttp://reranker:8080/v1; node ini dipanggil secara langsung, tidak pernah melaluiHTTP(S)_PROXYatau proksi tersemat milik koneksi). Node pada host lain mana pun — perangkat LAN atau peer Tailscale — hanya memenuhi syarat jika operator mengaktifkan feature flagRERANK_REMOTE_PROVIDER_NODESdan URL dasar node lolos kebijakan URL keluar penyedia (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS/OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS). Langkah pemeringkatan ulang milik mesin memori memanggil rute ini melalui loopback, sehingga aturan yang sama berlaku untukrerankProviderModeldalam pengaturan Memori.Bentuk server lokal: node dipanggil pada
<base>/v1/rerankdan, jika menerima 404, pada<base>/rerank(Infinity, TEI). Isi upstream membawa ejaan Cohere/OpenAI (documents,return_documents) dan ejaan TEI (texts,return_text), dan respons upstream dinormalisasi ke dalam amplop Cohere: array polos TEI[{index, score, text}],{results: [{index, score}]}dari gateway tipis, dan{data: [...]}bergaya Voyage semuanya dikembalikan kepada klien sebagai{results: [{index, relevance_score, document?}]}, diurutkan berdasarkan skor dan dibatasi hinggatop_n.
Penemuan node penyedia: model pada node penyedia yang kompatibel dengan OpenAI muncul dalam
GET /v1/modelsdi bawah prefiks node. Baris yang tidak memiliki metadata endpoint (umumnya pada daftar/v1/modelslokal) mewarisiapiTypenode, sehingga model milik nodeembeddingsmemilikitype: "embedding"dan model milik nodererankmemilikitype: "rerank", alih-alih secara default dianggap sebagai chat; nilaisupportedEndpointseksplisit pada baris yang disinkronkan atau ditambahkan secara manual tetap diutamakan.
Rute Penyedia Khusus
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
Prefiks penyedia ditambahkan secara otomatis jika tidak ada. Model yang tidak cocok mengembalikan 400.
Files API
Endpoint file yang kompatibel dengan OpenAI untuk input/output batch dan unggahan berdasarkan tujuan file.
| Metode | Path | Deskripsi |
|---|---|---|
| POST | /v1/files |
Unggah file (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — maks. 512 MiB |
| GET | /v1/files |
Cantumkan file untuk kunci API yang terautentikasi |
| GET | /v1/files/[id] |
Ambil metadata file |
| DELETE | /v1/files/[id] |
Hapus file |
| GET | /v1/files/[id]/content |
Streaming isi mentah file kembali |
Autentikasi: Kunci API Bearer — file dicakup per kunci API melalui getApiKeyRequestScope. Sebuah kunci
hanya dapat melihat, mengunduh, dan menghapus filenya sendiri; sesi dasbor tanpa kunci dapat membaca
seluruh instans; file tanpa pemilik (unggahan anonim atau melalui sesi dasbor) ditolak untuk setiap
pemanggil tanpa sesi. GET /v1/files menolak pemanggil anonim — serta kunci yang diberikan tetapi
tidak dapat diidentifikasi — dengan 401 meskipun REQUIRE_API_KEY=false, alih-alih mencantumkan file
milik semua tenant (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).
Batches API
Pemrosesan batch yang kompatibel dengan OpenAI.
| Metode | Path | Deskripsi |
|---|---|---|
| POST | /v1/batches |
Buat batch — isi divalidasi oleh v1BatchCreateSchema (input_file_id, endpoint, completion_window) |
| GET | /v1/batches |
Cantumkan batch |
| GET | /v1/batches/[id] |
Ambil status batch + request_counts |
| DELETE | /v1/batches/[id] |
Hapus batch yang selesai/gagal |
| POST | /v1/batches/[id]/cancel |
Batalkan batch yang sedang diproses |
Autentikasi: Kunci API Bearer. Batch dicakup per kunci API berdasarkan aturan tiga arah yang sama seperti
file: hanya kunci sendiri, sesi dasbor mencakup seluruh instans, rekaman tanpa pemilik ditolak untuk setiap
pemanggil tanpa sesi (pengambilan, penghapusan, pembatalan, dan pemeriksaan input_file_id saat pembuatan).
GET /v1/batches menolak pemanggil anonim dengan 401 meskipun REQUIRE_API_KEY=false.
API Pencarian
Abstraksi penyedia web/pencarian (Tavily, Brave, Exa, Serper, dll.).
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /v1/search |
Mencantumkan penyedia pencarian yang dikonfigurasi + kapabilitasnya |
| POST | /v1/search |
Menjalankan kueri pencarian — isi divalidasi oleh v1SearchSchema, mendukung cache/penggabungan |
| GET | /v1/search/analytics |
Statistik hit/latensi/cache per penyedia |
Autentikasi: Kunci API Bearer (extractApiKey + isValidApiKey). Kebijakan pencarian diberlakukan melalui enforceApiKeyPolicy.
provider_options Exa dan Tavily
Exa dan Tavily membaca kolom khusus penyedia dari sebuah wadah dengan namespace:
provider_options.exa (atau provider_options["exa-search"]) dan provider_options.tavily
(atau provider_options["tavily-search"]). Hanya kunci di bawah ini yang diteruskan. Setiap kunci
diperiksa terhadap skema Zod-nya sendiri di open-sse/handlers/search/providerOptionsPassthrough.ts,
dan kunci dengan tipe yang salah akan dihapus. Kunci lainnya akan diabaikan, termasuk autentikasi, URL dasar,
stream, dan outputSchema. Kunci datar yang digunakan oleh penyedia lain (cx, depth, ...) tetap berfungsi
seperti sebelumnya.
| Penyedia | Kolom tingkat atas | Bersarang |
|---|---|---|
| Exa | type, category, userLocation, moderation, additionalQueries, objective, systemPrompt, compliance (primitif datar), startPublishedDate, endPublishedDate |
contents.{text, highlights, summary, extras, subpages, subpageTarget, livecrawlTimeout, maxAgeHours} digabungkan di atas nilai default { text: true, highlights: true } |
| Tavily | search_depth, chunks_per_source, time_range, start_date, end_date, include_published_date, filter_by_published_date, include_answer, include_raw_content, include_images, include_image_descriptions, include_favicon, include_domains_mode, language, filter_by_language, auto_parameters, exact_match, include_usage, safe_search |
— |
Kolom generik selalu diutamakan: query, max_results, filters (domain), country, dan
topik yang diturunkan dari search_type. Pada Exa, search_type: "news" mempertahankan category: "news".
Tavily juga menerima search_type: "finance" (topic: "finance").
time_range generik kini diteruskan ke kedua penyedia: Exa menerima startPublishedDate (stempel waktu
ISO) dan Tavily menerima start_date (YYYY-MM-DD). Tanggal eksplisit dalam provider_options
menggantikan tanggal hasil pemetaan.
Hasil Exa mempertahankan id, highlight_scores, summary, subpages, entities, dan extras dalam
provider_raw. Hasil Tavily mempertahankan images dan favicon.
Penghitungan biaya tetap menggunakan registri datar costPerQuery. Tavily mengenakan biaya
lebih banyak kredit per panggilan untuk search_depth: "advanced", dan perbedaan tersebut tidak tercermin dalam
usage.search_cost_usd.
API Web Fetch
Ekstrak konten dari URL melalui penyedia web-fetch yang telah dikonfigurasi (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract).
Parallel Extract (parallel-search, menggunakan kunci API yang sama dengan Parallel Search) hanya
mengembalikan Markdown — format lain akan menghasilkan 400 — dan membatasi konten hingga 100.000 karakter. Jika
halaman target itu sendiri tidak dapat diekstrak, layanan hulu melaporkannya dalam HTTP 200;
OmniRoute menampilkannya sebagai 422 dengan pesan tetap.
| Metode | Jalur | Deskripsi |
|---|---|---|
| POST | /v1/web/fetch |
Ambil/scrape URL — body divalidasi oleh v1WebFetchSchema |
Autentikasi: Kunci API Bearer (extractApiKey + isValidApiKey). Kebijakan diterapkan melalui enforceApiKeyPolicy.
Fallback berbasis kuota (#8297): jika provider tidak diberikan secara eksplisit, pool
(firecrawl → jina-reader → tavily-search → tinyfish → nimble-search →
parallel-search) ditelusuri dalam
urutan prioritas tetap
(fill-first) — penyedia yang telah dikonfigurasi tetapi terkena batas laju akan dilewati
alih-alih langsung menghentikan permintaan, dan kegagalan layanan hulu yang dapat dicoba ulang/terkait kuota
(HTTP 429 selalu; 402/403 untuk tingkat gratis bergaya kuota Firecrawl/Tavily/TinyFish —
tidak untuk Jina Reader, dan tidak pernah untuk permintaan buruk 400 biasa) akan beralih ke
penyedia berikutnya yang belum dicoba dan memiliki kredensial saat permintaan berlangsung. Jika setiap penyedia dalam
pool telah habis, endpoint mengembalikan satu 429 (dengan header Retry-After)
alih-alih 400 generik sebelumnya. Jika provider eksplisit
diminta, tidak ada fallback diam-diam — penyedia eksplisit yang terkena batas laju atau gagal
akan menampilkan error-nya sendiri (429 jika terkena batas laju, selain itu status
layanan hulu).
Streaming WebSocket
GET /v1/ws?handshake=1
Memvalidasi handshake upgrade WebSocket dan mengembalikan pesan contoh protokol wire (request, cancel). Frame WS aktual ditangani oleh server WS bawaan di luar tabel rute Next.js.
Autentikasi: Kunci API Bearer selama handshake.
Responses API melalui WebSocket (khusus codex)
# Host:port yang sama dengan API HTTP (default 20128); upgrade koneksi:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (atau: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
# Frame pertama HARUS berupa response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
Proksi Responses-API-over-WebSocket terhubung secara eksklusif ke codex (backend
ChatGPT). Proksi ini mendengarkan pada port yang sama dengan API/dashboard di jalur /v1/responses,
/responses, dan /api/v1/responses. Pada frame response.create pertama, proksi
melakukan autentikasi + persiapan melalui bridge internal codex-responses-ws, memilih
koneksi OAuth codex, dan membuat tunnel ke wss://chatgpt.com/backend-api/codex/responses
melalui transport wreq-js. Model non-codex ditolak (codex_ws_provider_required).
Untuk routing quota-share, gunakan model: "qtSd/<group>/codex/<model>". Diimplementasikan di
app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.
Autentikasi: Kunci API Bearer selama handshake. Server HTTP bawaan (server-ws.mjs)
harus menjadi entrypoint aktif (dan memang demikian secara default ketika app/server-ws.mjs tersedia).
ID model: gunakan ID ChatGPT polos (tanpa prefiks codex/)
Codex CLI OpenAI memvalidasi nama model di sisi klien ketika
supports_websockets = true dan menolak ID yang diawali nama penyedia seperti
codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Kirim ID polos (misalnya gpt-5.5). Bridge OmniRoute
hanya mendukung codex, sehingga bridge tersebut me-resolve ulang ID polos sebagai model codex
(resolveCodexWsModelInfo) sebelum membuat tunnel ke upstream — meskipun
gpt-5.5 polos seharusnya dirutekan ke penyedia lain melalui HTTP.
Mengonfigurasi OpenAI Codex CLI
Arahkan Codex CLI ke OmniRoute dengan menambahkan penyedia kustom yang mendukung WebSocket
ke ~/.codex/config.toml (gunakan CODEX_HOME terpisah agar tidak mengubah
konfigurasi yang sudah ada):
model = "gpt-5.5" # ID polos — 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 diturunkan darinya (gunakan https/wss di produksi)
wire_api = "responses" # satu-satunya nilai yang didukung sejak Feb 2026
supports_websockets = true # mengaktifkan transport Responses-over-WS
env_key = "OMNIROUTE_API_KEY" # menyimpan kunci API OmniRoute (Bearer)
export OMNIROUTE_API_KEY=sk-... # kunci API OmniRoute (kunci apa pun jika REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
CLI meng-upgrade base_url + /responses menjadi WebSocket dan OmniRoute membuat tunnel
ke koneksi OAuth codex yang dipilih. Telah divalidasi secara end-to-end terhadap server
lokal: ChatGPT mengembalikan codex.rate_limits + response.created dan melakukan streaming
completion.
Kuota & Pelaporan Masalah
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /v1/quotas/check |
Memvalidasi kuota terlebih dahulu untuk provider + accountId sebelum menerbitkan kunci terdaftar |
| POST | /v1/issues/report |
Melaporkan kegagalan kuota/penerbitan kunci ke GitHub (memerlukan GITHUB_ISSUES_REPO + token) |
Autentikasi: Kunci API Bearer (isAuthenticated).
Penggunaan mandiri (/api/usage/om-usage)
Setiap kunci API dapat membaca penggunaan dan kuotanya sendiri — tanpa autentikasi manajemen. Ini adalah endpoint yang digunakan klien (CLI, panel OmniCopilot) untuk menunjukkan pengeluaran kepada pemegang kunci.
# Format teks (kontrak historis — teks biasa untuk terminal)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# Format terstruktur — yang digunakan oleh UI
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
Kunci tersebut harus mengaktifkan allowUsageCommand (dinonaktifkan secara default — pengelola kunci API di dasbor
mengaktifkan atau menonaktifkannya untuk setiap kunci). Tanpa itu, endpoint akan merespons dengan 403.
?format=json mengembalikan struktur terdiskriminasi sehingga pemanggil tidak akan pernah membaca bidang data dari
respons penolakan. Jika berhasil:
{
"allowed": true,
// hanya tersedia ketika kunci memilih untuk menggunakan batas penggunaan per kunci (USD harian/mingguan):
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// snapshot kuota penyedia yang dipilih, atau null jika belum ada yang di-cache:
"provider": {
"connectionId": "…",
"provider": "claude",
"plan": "…",
"quotas": {/* … */},
},
// snapshot setiap koneksi, sehingga UI dapat merender beberapa penyedia secara berdampingan:
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
Jika ditolak (401 kunci tidak valid / 403 tidak diizinkan), rute yang sama mengembalikan
{ "allowed": false, "error": { "message": "…" } } — personal/provider yang ada tetapi kosong
(kunci diizinkan, tetapi belum ada data yang diperoleh) merupakan status yang berbeda dari penolakan, dan hanya format JSON
yang dapat membedakannya.
Autentikasi: kunci API Bearer milik pemanggil sendiri, divalidasi dengan isValidApiKey — ini bukan
permukaan manajemen (/api/keys/…), yang tetap dilindungi oleh requireManagementAuth.
Persentase Kuota Mentah vs. yang Disesuaikan dengan Batas Penghentian
Saat menggunakan /api/usage/om-usage, pemanggil harus memperhatikan perbedaan antara
persentase yang ditampilkan oleh output teks biasa dan output JSON terstruktur:
| Aspek | Format teks biasa (/api/usage/om-usage / @@om-usage) |
Format JSON (?format=json) |
|---|---|---|
| Bidang output | NN% left (misalnya, 20% left) |
provider.quotas / providers[].quotas |
| Pengukuran | Jatah yang dapat digunakan setelah disesuaikan dengan batas penghentian: kapasitas tersisa di atas ambang batas penghentian | Kuota upstream mentah: pengukuran penyedia yang belum disesuaikan |
| Penskalaan batas penghentian | Diskalakan melalui effectiveRemainingPercent() sehingga cadangan yang dilindungi terbaca sebagai 0% left |
Tidak ada (nilai snapshot mentah sebagaimana dilaporkan oleh penyedia) |
| Data ambang batas | Diperhitungkan dalam persentase yang ditampilkan | Disimpan dalam quotaWindowThresholds per koneksi (atau default server) |
| Konsumen utama | CLI interaktif, prompt terminal, operator manusia | Integrasi terprogram, dasbor, analitik, pelacak penagihan |
Rumus Penyesuaian Batas Penghentian
OmniRoute mendukung batas penghentian kuota proaktif untuk mencegah habisnya kuota upstream (dikonfigurasi melalui
quotaWindowThresholds koneksi, default penyedia, atau pengaturan ketahanan global). Ketika ambang batas penghentian
(misalnya, cutoff = 25%) aktif pada jendela kuota, perender teks menghitung jatah tersisa sebagai berikut:
- Jika
remaining <= cutoff: mengembalikan0%. - Jika
remaining > cutoff: mengembalikan((remaining - cutoff) / (100 - cutoff)) * 100.
Output teks yang diformat membulatkan hasil ini ke bilangan bulat terdekat (Math.round(...)).
Contoh Ilustratif
Pertimbangkan jendela penyedia dengan penggunaan mentah 60% (sehingga kuota mentah tersisa 40%) dan ambang batas penghentian pada 25% kuota tersisa yang dikonfigurasi:
| Representasi | Perhitungan | Tersisa | Penggunaan Tersirat |
|---|---|---|---|
JSON mentah (?format=json) |
Snapshot upstream (quotas[window]) |
40% | 60% |
Format teks (NN% left) |
((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100 |
20% | 80% (jika menghitung 100 - remaining) |
- Mengapa teks menampilkan 20% tersisa: Dari 40% kuota fisik yang tersisa pada akun, 25% dicadangkan oleh
kebijakan batas penghentian. Pemanggil hanya memiliki 15% dari total ruang pemakaian 75% yang masih dapat digunakan sebelum router berhenti
merutekan ke koneksi ini. Penskalaan memastikan koneksi menandakan kehabisan kuota (
0% left) tepat ketika perutean akan dihentikan. - Mengapa JSON mempertahankan nilai mentah: Payload JSON mengembalikan snapshot penyedia secara persis (
UsageSnapshot) sehingga alat eksternal memiliki akses ke penggunaan upstream yang sebenarnya danquotaWindowThresholdstingkat koneksi tanpa penskalaan lossy di sisi server.
Panduan Migrasi Konsumen
Jika integrasi eksternal (seperti plugin editor atau ekstensi agen) sebelumnya mengambil data dari endpoint teks
(NN% left) dan menghitung persentase penggunaan sebagai 100 - NN, migrasi ke ?format=json berarti:
- Membaca nilai JSON mentah akan mencerminkan konsumsi upstream yang sebenarnya (60% digunakan dalam contoh di atas).
- Jika integrasi ingin mempertahankan semantik jatah-yang-dapat-digunakan dari endpoint teks, integrasi tersebut dapat mengevaluasi
rumus sisa efektif di sisi klien menggunakan
quotaWindowThresholdsuntuk penggantian tingkat koneksi.
Cache Semantik
# Mendapatkan statistik cache
GET /api/cache/stats
# Menghapus semua cache
DELETE /api/cache/stats
Contoh respons:
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
Dampak latensi
HIT cache semantik menyajikan respons dari cache tanpa panggilan ke upstream,
sehingga X-OmniRoute-Response-Latency yang dilaporkan mendekati nol
(terlepas dari latensi upstream awal). Klien yang sensitif terhadap latensi
(benchmark, pemantauan p50/p99) sebaiknya memeriksa header respons
X-OmniRoute-Cache-Latency:
| Nilai | Arti |
|---|---|
synthetic |
Respons disajikan dari cache; latensi bukan waktu upstream sebenarnya |
| (tidak ada) | Respons dari panggilan upstream yang sebenarnya |
Melewati cache per kunci
Kunci API dapat memilih untuk tidak menggunakan pembacaan cache semantik melalui cacheDefaultMode:
| Nilai | Perilaku |
|---|---|
legacy |
Perilaku cache normal (default) |
bypass |
Melewati pencarian cache sepenuhnya; selalu mengakses upstream |
Tetapkan saat pembuatan kunci (POST /api/keys) atau pembaruan (PATCH /api/keys/[id]):
{ "cacheDefaultMode": "bypass" }
Melewati cache per permintaan
Permintaan apa pun dapat melewati cache tanpa bergantung pada pengaturan kunci:
X-OmniRoute-No-Cache: true
Dasbor & Manajemen
Rute manajemen (/api/* kecuali autentikasi/login publik) tidak diotorisasi oleh
kunci API inferensi biasa. Kelompok kredensial, cakupan, dan contoh curl:
Autentikasi Manajemen.
Autentikasi
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/auth/login |
POST | Masuk |
/api/auth/logout |
POST | Keluar |
/api/settings/require-login |
GET/POST | Status masuk (GET, publik). POST menetapkan kata sandi / mengaktifkan atau menonaktifkan login: hanya operator setelah kata sandi tersedia (sesi dasbor, CLI lokal, atau login dinonaktifkan — kunci API dan token oma_ mendapatkan 403); sesi dasbor mengirimkan currentPassword untuk mengganti kata sandi |
Manajemen Penyedia
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/providers |
GET/POST | Mencantumkan / membuat penyedia |
/api/providers/[id] |
GET/PUT/DELETE | Mengelola penyedia |
/api/providers/[id]/test |
POST | Menguji koneksi penyedia |
/api/providers/[id]/models |
GET | Mencantumkan model penyedia |
/api/providers/validate |
POST | Memvalidasi konfigurasi penyedia |
/api/providers/bulk |
POST | Menambahkan kunci API secara massal untuk SATU penyedia |
/api/providers/import |
POST | Mengimpor DAFTAR penyedia heterogen dari file CSV/JSON yang telah diurai (#6836); hasil kegagalan parsial per baris |
/api/provider-nodes* |
Beragam | Manajemen node penyedia |
/api/provider-models |
GET/POST/PUT/PATCH/DELETE | Model kustom dan penggantian per model (tambah, perbarui, sembunyikan/tampilkan, hapus) |
/api/provider-models/validate-and-add |
POST | Validasi koneksi ketat yang memerlukan autentikasi manajemen dan bersifat opsional, serta pendaftaran model kustom atomik; lihat Validasi model |
Untuk model yang disinkronkan/diimpor, PUT /api/provider-models menerima provider, modelId, dan
maxOutputTokenOverride: bilangan bulat positif menetapkan batas token keluaran manual, sedangkan null
menghapusnya untuk memulihkan nilai bawaan. GET /api/provider-models?provider=<provider> mengembalikan
nilai-nilai ini dalam modelOutputOverrides, termasuk model tanpa baris model kustom. Penggantian ini
menggunakan kemampuan runtime max_output_tokens dan tetap tersedia setelah sinkronisasi ulang model. Halaman
penyedia yang kompatibel dengan OpenAI menawarkan kontrol edit/hapus yang sama dan menandai model dengan dukungan visi eksplisit.
Node Chat Completions kustom menyesuaikan penolakan penalaran eksplisit dengan backend upstream. Pengujian
koneksi yang berhasil secara otomatis memilih kontrol templat chat untuk setiap ID model yang sama persis
yang entri /models-nya membuktikan nilai owned_by yang dikenali: vllm, sglang, atau llamacpp.
Wrapper transparan yang kompatibel dengan OpenAI dapat mempertahankan entri model asli di dalam objek
openai bertingkat; deteksi mengikuti hingga tiga pembungkus semacam itu. Model dengan kepemilikan yang
tidak ada, tidak diketahui, atau bertentangan tetap menggunakan perilaku OpenAI biasa. Deteksi menggunakan
kembali permintaan katalog yang ada, tidak menghasilkan token penyelesaian, dan menjadi tidak valid ketika
endpoint koneksi berubah.
Untuk menetapkan perilaku bagi backend yang tidak mengekspos metadata tersebut, gunakan API pembaruan penyedia parsial yang ada:
{
"providerSpecificData": {
"reasoningControl": "chat-template"
}
}
Kirim body tersebut dengan PUT /api/providers/<connection-id>. Pada koneksi itu, upaya
penalaran eksplisit sebesar none dikirim sebagai chat_template_kwargs.thinking=false dan
chat_template_kwargs.enable_thinking=false. Nilai template native yang eksplisit tetap menjadi acuan
kecuali aturan penalaran sisi server memaksakan suatu upaya. Pengaturan ini hanya berlaku saat koneksi
khusus yang kompatibel dengan OpenAI mengirimkan body Chat Completions; permintaan Responses dan
penyedia biasa tetap menggunakan bentuk permintaan native mereka. Atur reasoningControl ke openai
untuk memaksakan penerusan reasoning_effort OpenAI biasa, atau hilangkan/atur ke null untuk
menggunakan deteksi otomatis.
Permintaan pengklasifikasi mode otomatis Claude Code secara default menonaktifkan pemikiran native jika tidak memuat kontrol penalaran eksplisit. Deteksi menggunakan penanda sistem pengklasifikasi dalam permintaan berformat Claude, bukan nama model atau batas penyelesaian. Kontrol body eksplisit, header upaya/pemikiran yang didukung, aturan perutean, dan upaya model yang telah ditentukan tetap mempertahankan prioritasnya. Kedua tahap pengklasifikasi mempertahankan prompt, batas penyelesaian, urutan penghentian, dan keputusan izin upstream yang sebenarnya; tahap kedua tetap dapat menghasilkan penalaran terlihat yang diminta sebagai teks biasa.
Alur OAuth
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/oauth/[provider]/[action] |
Beragam | OAuth khusus penyedia |
Perutean & Konfigurasi
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/models/alias |
GET/POST | Alias model |
/api/models/catalog |
GET | Semua model berdasarkan penyedia + jenis |
/api/combos* |
Beragam | Pengelolaan kombinasi |
/api/keys* |
Beragam | Pengelolaan kunci API |
/api/pricing |
GET | Harga model |
Penggunaan & Analitik
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/usage/history |
GET | Riwayat penggunaan |
/api/usage/logs |
GET | Log penggunaan |
/api/usage/request-logs |
GET | Log tingkat permintaan |
/api/usage/[connectionId] |
GET | Penggunaan per koneksi |
/api/usage/token-limits |
GET/POST/DELETE | Anggaran batas token per kunci API |
/api/usage/model-latency-stats |
GET | Agregat latensi berjalan per penyedia/model (rata-rata/p50/p95/p99, tingkat keberhasilan); filter: windowHours/minSamples/maxRows/provider/model (#6873) |
/api/usage/cache-health |
GET | Ringkasan kesehatan cache prompt di seluruh call_logs — rasio tulis/baca, distribusi ukuran tulis p50/p90/p99, konsentrasi penulisan berat, pembagian per model, dan keputusan healthy/degraded/thrash/no-data; parameter kueri range (1h|24h|7d|30d, default 24h) dan model opsional (#8827) |
Izin kunci API
PATCH /api/keys/{id} memperbarui izin kunci yang sudah ada. Seperti setiap rute /api/keys*, rute ini memerlukan otorisasi pengelolaan (lihat Autentikasi Pengelolaan), bukan kunci inferensi. Kirim hanya bidang yang ingin Anda ubah; permintaan tanpa satu pun bidang tersebut akan ditolak dengan No valid fields to update. Bidang yang diterima ditentukan oleh updateKeyPermissionsSchema dalam src/shared/validation/schemas/keys.ts.
| Bidang | Tipe | Catatan |
|---|---|---|
name |
string, 1-200 karakter | |
isActive |
boolean | |
isBanned |
boolean | |
expiresAt |
datetime ISO 8601 atau null |
null menghapus waktu kedaluwarsa |
modelAccessMode |
all | restricted |
allowedModels harus kosong ketika modenya adalah all |
allowedModels, blockedModels |
array string, hingga 1000 | |
allowedCombos |
array string, hingga 500 | Membatasi combo yang dapat dipanggil oleh kunci; model langsung diatur oleh modelAccessMode / allowedModels |
connectionAccessMode |
all | restricted |
allowedConnections tidak boleh kosong ketika restricted dan harus kosong ketika all |
allowedConnections |
array UUID, hingga 100 | |
allowAutoCombos |
boolean | false menolak permintaan untuk model auto/* dengan kunci ini; kunci yang belum pernah mengaturnya tetap diizinkan |
catalogScope |
all | combos | models |
Daftar yang ditampilkan GET /v1/models untuk kunci ini (hanya combo, hanya model, atau keduanya); ini tidak mengubah apa yang dapat dipanggil oleh kunci |
forcedModel |
string hingga 300 karakter, atau null |
Mengarahkan permintaan chat ke model/combo ini, mengesampingkan X-Route-Model dan body.model; batasan kunci tetap berlaku |
noLog, autoResolve |
boolean | |
throttleDelayMs |
integer, 0-300000 | |
maxSessions |
integer, 0-10000 | |
rateLimits |
array { limit, window } (integer positif, hingga 50) atau null |
null menghapus batasan |
accessSchedule |
objek jadwal atau null |
null menghapus jadwal |
scopes |
array string, hingga 32 | |
allowedEndpoints |
array string, hingga 20 | |
streamDefaultMode |
legacy | json |
|
cacheDefaultMode |
legacy | bypass |
Lihat Pengabaian cache per kunci |
compressionEnabled |
boolean | |
codexServiceMode |
salah satu mode layanan Codex | |
disableNonPublicModels |
boolean | |
allowUsageCommand |
boolean | |
usageLimitEnabled |
boolean | |
dailyUsageLimitUsd, weeklyUsageLimitUsd |
number >= 0 atau null |
|
chaosModeEnabled |
boolean |
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
-H "Authorization: Bearer <management-credential>" \
-H "Content-Type: application/json" \
-d '{ "allowAutoCombos": false, "catalogScope": "combos" }'
Pengaturan
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/settings |
GET/PUT/PATCH | Pengaturan umum. Kunci kebijakan keamanan (requireLogin, newPassword, oidc*, corsOrigins, bruteForceProtection) memerlukan currentPassword dan kredensial operator — kunci API dan token oma_ akan mendapatkan 403; setiap perubahan memerlukan cakupan token akses admin |
/api/settings/proxy |
GET/PUT | Konfigurasi proksi jaringan |
/api/settings/proxy/test |
POST | Menguji koneksi proksi |
/api/settings/ip-filter |
GET/PUT | Daftar izin/daftar blokir IP |
/api/settings/thinking-budget |
GET/PUT | Mode penulisan ulang permintaan untuk proses berpikir/penalaran (passthrough / auto-strip / custom / adaptive). Tidak bergantung pada kompresi. Lihat THINKING_BUDGET.md. |
/api/settings/system-prompt |
GET/PUT | Prompt sistem global |
/api/settings/compression |
GET/PUT | Konfigurasi kompresi global |
/api/settings/purge-request-history |
POST | Menghapus baris log permintaan dan artefak log panggilan lokal |
Konteks & Kompresi
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/compression/preview |
POST | Pratinjau kompresi off/lite/standard/aggressive/ultra/RTK/stacked |
/api/compression/language-packs |
GET | Daftar paket bahasa Caveman yang tersedia |
/api/compression/rules |
GET | Daftar metadata aturan Caveman |
/api/context/caveman/config |
GET/PUT | Alias pengaturan khusus Caveman |
/api/context/rtk/config |
GET/PUT | Pengaturan khusus RTK, termasuk filter kustom dan penyimpanan output mentah |
/api/context/rtk/filters |
GET | Katalog filter RTK dan diagnostik filter kustom |
/api/context/rtk/test |
POST | Jalankan pratinjau/pengujian RTK terhadap payload teks |
/api/context/rtk/raw-output/[id] |
GET | Baca output mentah tersensor yang disimpan berdasarkan id penunjuk |
/api/context/combos |
GET/POST | Buat/daftar kombo kompresi |
/api/context/combos/[id] |
GET/PUT/DELETE | Detail/perbarui/hapus kombo kompresi |
/api/context/combos/[id]/assignments |
GET/PUT | Tetapkan kombo kompresi ke kombo perutean |
/api/context/analytics |
GET | Alias analitik kompresi |
Pemantauan
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/sessions |
GET | Pelacakan sesi aktif |
/api/rate-limits |
GET | Batas laju per akun |
/api/monitoring/health |
GET | Pemeriksaan kesehatan + ringkasan penyedia (catalogCount, configuredCount, activeCount, monitoredCount). Tampilan manajemen mencakup credentialHealth: nilai skalar cache probe, failedConnections ketika failed>0, dan staleDbNonOkCount (test_status persisten SQLite, bukan pengukur). Lihat MONITORING_GUIDE.md. |
/api/cache/stats |
GET/DELETE | Statistik cache / kosongkan |
/api/modality-bridge/stats |
GET | attempts dalam memori, keberhasilan/bridged, kegagalan, cache hit, totalLatencyMs, latencySamples, averageLatencyMs berbasis jumlah sampel, dan waktu penggunaan terakhir (diatur ulang saat dimulai ulang; autentikasi manajemen) |
/api/modality-bridge/video/runtime |
GET | Pemeriksaan loopback tepercaya yang ketat sebelum autentikasi/probe manajemen; ketersediaan dan versi FFmpeg/ffprobe yang telah disanitasi (no-store) |
/api/modality-bridge/video/extract |
POST | Broker byte loopback tepercaya internal yang diautentikasi; input 50 MiB, antrean terbatas/output 32 MiB, kapasitas 503, pemutusan koneksi 499, tenggat waktu 504; bukan API unggahan publik |
Pencadangan & Ekspor/Impor
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/db-backups |
GET | Mencantumkan cadangan yang tersedia |
/api/db-backups |
PUT | Membuat cadangan manual |
/api/db-backups |
POST | Memulihkan dari cadangan tertentu |
/api/db-backups |
PATCH | Menyimpan pengaturan retensi cadangan (khusus operator) |
/api/db-backups |
DELETE | Memangkas cadangan tersimpan sesuai pengaturan retensi (khusus operator) |
/api/db-backups/export |
GET | Mengunduh basis data sebagai file .sqlite |
/api/db-backups/import |
POST | Mengunggah file .sqlite untuk mengganti basis data (?dryRun=true hanya memvalidasi) |
/api/db-backups/exportAll |
GET | Mengunduh cadangan lengkap sebagai arsip .tar.gz |
/api/db-backups/export, /api/db-backups/exportAll, dan /api/settings/export-json memberikan
setiap kredensial yang tersimpan, sehingga memerlukan sesi dasbor atau CLI lokal (atau login
dinonaktifkan). Kunci API dengan cakupan apa pun dan token akses oma_ akan mendapatkan 403.
Pemulihan memiliki batasan yang sama: POST /api/db-backups/import (termasuk dryRun=true),
POST /api/db-backups (pemulihan berdasarkan id), dan POST /api/settings/import-json mengganti
basis data atau pengaturan aktif, sehingga kredensial mesin juga akan mendapatkan 403 di sana;
omniroute sync import mengirimkan kredensial CLI lokal. Hal yang sama berlaku untuk
DELETE /api/db-backups (memangkas cadangan tersimpan) dan PATCH /api/db-backups (pengaturan
retensi: nilai yang dipertahankan mengendalikan pemangkasan otomatis setelah setiap pencadangan).
Pencantuman (GET) dan pembuatan cadangan manual (PUT) tetap menggunakan autentikasi manajemen biasa.
Sinkronisasi Cloud
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/sync/cloud |
Beragam | Operasi sinkronisasi cloud |
/api/sync/initialize |
POST | Menginisialisasi sinkronisasi |
/api/cloud/* |
Beragam | Pengelolaan cloud |
Tunnel
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/tunnels/cloudflared |
GET | Membaca status instalasi/runtime Cloudflare Quick Tunnel untuk dasbor |
/api/tunnels/cloudflared |
POST | Mengaktifkan atau menonaktifkan Cloudflare Quick Tunnel (action=enable/disable) |
/api/tunnels/ngrok |
GET | Membaca status runtime ngrok Tunnel untuk dasbor |
/api/tunnels/ngrok |
POST | Mengaktifkan atau menonaktifkan ngrok Tunnel (action=enable/disable) |
Alat CLI
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/cli-tools/claude-settings |
GET | Status Claude CLI |
/api/cli-tools/codex-settings |
GET | Status Codex CLI |
/api/cli-tools/droid-settings |
GET | Status Droid CLI |
/api/cli-tools/openclaw-settings |
GET | Status OpenClaw CLI |
/api/cli-tools/runtime/[toolId] |
GET | Runtime CLI generik |
Respons CLI mencakup: installed, runnable, command, commandPath, runtimeMode, reason.
Agen ACP
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/acp/agents |
GET | Mencantumkan semua agen yang terdeteksi (bawaan + khusus) beserta statusnya |
/api/acp/agents |
POST | Menambahkan agen khusus atau menyegarkan cache deteksi |
/api/acp/agents |
DELETE | Menghapus agen khusus berdasarkan parameter kueri id |
Respons GET mencakup agents[] (id, nama, biner, versi, terinstal, protokol, kustom) dan summary (total, terinstal, tidak ditemukan, bawaan, kustom).
Ketahanan & Batas Laju
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/resilience |
GET/PATCH | Mendapatkan/memperbarui antrean permintaan, cooldown koneksi, pemutus penyedia, dan pengaturan tunggu |
/api/resilience/reset |
POST | Mereset pemutus sirkuit penyedia |
/api/resilience/model-cooldowns |
GET | Mencantumkan penguncian aktif per-(penyedia, koneksi, model), diurutkan berdasarkan waktu tersisa |
/api/resilience/model-cooldowns |
DELETE | Menghapus penguncian model — isi {provider, model} atau {all: true} untuk menghapus semuanya |
/api/rate-limits |
GET | Status batas laju per akun |
/api/rate-limit |
GET | Konfigurasi batas laju global |
Keempat rute
/api/resilience/*memerlukan autentikasi manajemen (requireManagementAuth). Lihat Ketahanan (diperluas) untuk uraian lengkap mengenai pemutus penyedia vs cooldown koneksi vs penguncian model.
Evaluasi
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/evals |
GET/POST | Mencantumkan rangkaian evaluasi / menjalankan evaluasi |
Kebijakan
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/policies |
GET/POST/DELETE | Mengelola kebijakan perutean |
Kepatuhan
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/compliance/audit-log |
GET | Log audit kepatuhan (N terakhir) |
v1beta (Kompatibel dengan Gemini)
| Endpoint | Metode | Deskripsi |
|---|---|---|
/v1beta/models |
GET | Daftar model dalam format Gemini |
/v1beta/models/{...path} |
POST | Endpoint generateContent Gemini |
Endpoint-endpoint ini mencerminkan format API Gemini untuk klien yang memerlukan kompatibilitas SDK Gemini native.
API Internal / Sistem
| Endpoint | Metode | Deskripsi |
|---|---|---|
/api/init |
GET | Pemeriksaan inisialisasi aplikasi (digunakan saat pertama kali dijalankan) |
/api/tags |
GET | Tag model yang kompatibel dengan Ollama (untuk klien Ollama) |
/api/restart |
POST | Memicu mulai ulang server secara aman |
/api/shutdown |
POST | Memicu penghentian server secara aman |
/api/system/env/repair |
POST | Memperbaiki variabel lingkungan penyedia OAuth |
/api/system/version |
GET | Versi saat ini/terbaru, status pembaruan, saluran rilis |
/api/system/version |
POST | Memulai pembaruan yang menyesuaikan deployment ke versi terbaru |
Catatan: Endpoint-endpoint ini digunakan secara internal oleh sistem atau untuk kompatibilitas klien Ollama. Endpoint tersebut biasanya tidak dipanggil oleh pengguna akhir.
Perbaikan Lingkungan OAuth (v3.6.1+)
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
Memperbaiki variabel lingkungan OAuth yang hilang atau rusak 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"
}
Versi dan Saluran Rilis
GET /api/system/version
Rute pengelolaan khusus loopback (autentikasi admin). Mengembalikan versi yang sedang berjalan, versi terbaru yang
dipublikasikan, dan status pembaruan otomatis. releaseChannel dan channels merupakan
kolom tambahan (rail 3.8.54); channel tetap mempertahankan maknanya — mode deployment yang digunakan
oleh pembaru dasbor (npm, source, atau docker-compose).
{
"current": "3.8.52",
"latest": "3.8.52",
"updateAvailable": false,
"channel": "npm",
"autoUpdateSupported": true,
"autoUpdateError": null,
"news": null,
"releaseChannel": "latest",
"channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" }
}
releaseChannel— saluran npm dari build yang sedang berjalan:nightlyuntuk versi-nightly.*,nextuntuk pra-rilis lainnya (-rc.*,-beta.*,-alpha.*),ltsuntuk versi stabil dari versi mayor yang lebih lama daripadachannels.latest, dan selain itulatest. Aturannya sama denganscripts/release/dist-tag.mjs, yang memilih dist-tag npm pada saat publikasi.channels— versi terdepan yang dipublikasikan dari setiap dist-tag, darinpm view omniroute dist-tags(fallback HTTP registry), disimpan dalam cache dengan TTL 10 menit yang sama sepertilatest.latestselalu tersedia (beralih ke kolomlatest, lalu"unavailable");next,nightly, danltshanya muncul jika dist-tag tersebut tersedia. PermintaanCache-Control: no-cachemenyegarkan kedua pencarian.
Model saluran (latest = v3 hingga 4.0 GA, next = rc, nightly = build develop,
lts = patch v3 setelah 4.0 GA) dijelaskan dalam docs/ops/RELEASE_STRATEGY.md.
Transkripsi Audio
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
Transkripsikan file audio menggunakan penyedia STT mana pun yang telah dikonfigurasi. Segmen jalur pertama
memilih penyedia asli (openai/…, deepgram/…). Gateway yang
mengekspor ulang model vendor lain menggunakan id yang memenuhi syarat
(openrouter/deepgram/nova-3).
Permintaan:
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "[email protected]" \
-F "model=openai/whisper-1"
Respons:
{
"text": "Halo, ini adalah konten 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 asli Deepgram). Permintaan langsung
deepgram/nova-3 tidak menggunakan OpenRouter.
Format yang didukung: mp3, wav, m4a, flac, ogg, webm.
Kompatibilitas Ollama
Untuk klien yang menggunakan format API Ollama:
# Endpoint percakapan (format Ollama)
POST /v1/api/chat
# Daftar model (format Ollama)
GET /api/tags
Permintaan secara otomatis diterjemahkan antara format Ollama dan format internal.
Alias VS Code Bertoken / Tanpa Header
Gunakan alias ini jika integrasi tidak dapat menyisipkan header Authorization dan memerlukan kunci API yang disematkan dalam URL dasar.
# Alias katalog bergaya OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# Alias percakapan bergaya OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Alias bergaya 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 kembali handler yang sama dengan
/v1/*dan/api/tags; struktur respons tetap identik. - Utamakan
Authorization: Bearer ...jika klien mendukung header khusus. - Token berbasis URL dapat muncul dalam log reverse proxy, riwayat browser, dan telemetri di luar OmniRoute. Perlakukan token tersebut sebagai opsi kompatibilitas, bukan mode autentikasi default.
Telemetri
# Dapatkan ringkasan telemetri latensi (p50/p95/p99 per 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 }
}
}
Anggaran
# Dapatkan status anggaran untuk semua kunci API
GET /api/usage/budget
# Tetapkan atau perbarui anggaran
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):apiKeyIdwajib diisi; setidaknya salah satu daridailyLimitUsd,weeklyLimitUsd, ataumonthlyLimitUsdharus lebih besar dari nol. Bidang opsional:warningThreshold(0–1),resetInterval(daily|weekly|monthly),resetTime(HH:MM). Format lama{keyId, limit, period}mengembalikan400 Bad Request.
Batas Token
Anggaran token per kunci API (berbeda dari Anggaran berbasis USD di atas). Diberlakukan langsung pada jalur permintaan: ketika penggunaan pada jendela saat ini untuk suatu kunci mencapai batasnya, permintaan akan ditolak dengan 429 Too Many Requests. Batas dapat dicakup ke model tertentu, provider, atau diterapkan secara global di seluruh kunci; ketika beberapa batas cocok dengan suatu permintaan, batas yang paling ketat akan berlaku.
# Menampilkan batas token suatu kunci (termasuk penggunaan jendela secara langsung)
GET /api/usage/token-limits?apiKeyId=key-123
# Membuat atau memperbarui batas 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
}
# Menghapus batas token berdasarkan id
DELETE /api/usage/token-limits?id=tl-abc
Catatan skema (
setTokenLimitSchema):apiKeyIddanscopeType(model|provider|global) wajib diisi.scopeValuewajib diisi kecuali jikascopeTypeadalahglobal(misalnya id model untuk cakupanmodel, atau id penyedia untuk cakupanprovider).tokenLimitharus berupa bilangan bulat positif (dikonversi dari string). Opsional:id(hilangkan untuk membuat, sertakan untuk memperbarui),resetInterval(daily|weekly|monthly, nilai bawaanmonthly),resetTime(HH:MM),enabled(nilai bawaantrue). ResponsGETmemperkaya setiap batas dengantokensUsed,remaining,windowStart,periodStartAt, dannextResetAt. Ini adalah endpoint kelas manajemen (autentikasi diberlakukan secara terpusat oleh pipeline otorisasi).
Pemrosesan Permintaan
- Klien mengirim permintaan ke
/v1/* - Penangan rute memanggil
handleChat,handleEmbedding,handleAudioTranscription, atauhandleImageGeneration - Model ditentukan (penyedia/model langsung atau alias/kombo)
- Kredensial dipilih dari DB lokal dengan pemfilteran ketersediaan akun
- Untuk percakapan:
handleChatCorememeriksa cache semantik/tanda tangan dan menentukan pengaturan kompresi kombo - Kompresi proaktif berjalan sebelum penerjemahan penyedia ketika diaktifkan (
lite, Caveman, RTK, atau bertumpuk) - Eksekutor penyedia mengirim permintaan ke hulu
- Respons diterjemahkan kembali ke format klien (percakapan) atau dikembalikan apa adanya (embedding/gambar/audio)
- Penggunaan, analitik kompresi, dan log permintaan dicatat
- Fallback diterapkan saat terjadi kesalahan sesuai dengan aturan kombo
Referensi arsitektur lengkap: ARCHITECTURE.md
Manajemen Kombo
Kombo perutean tingkat tinggi (yang telah dirangkum di bawah /api/combos*) juga dapat dipetakan 1:1 dari pola id model, sehingga memungkinkan pengalihan transparan dari id model bergaya OpenAI ke suatu kombo.
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /api/model-combo-mappings |
Menampilkan semua pemetaan model→kombo |
| POST | /api/model-combo-mappings |
Membuat pemetaan — isi: {pattern, comboId, priority?, enabled?, description?} |
| GET | /api/model-combo-mappings/[id] |
Mengambil satu pemetaan |
| PUT | /api/model-combo-mappings/[id] |
Memperbarui bidang dari pemetaan yang sudah ada |
| DELETE | /api/model-combo-mappings/[id] |
Menghapus pemetaan |
Autentikasi: sesi/kunci API manajemen (requireManagementAuth).
Webhook
Langganan webhook keluar untuk peristiwa OmniRoute (penyelesaian permintaan, habisnya kuota, rotasi kunci, dll.).
| Metode | Path | Deskripsi |
|---|---|---|
| GET | /api/webhooks |
Mencantumkan webhook (rahasia disamarkan menjadi <prefix>...) |
| POST | /api/webhooks |
Membuat webhook — body: {url, events?: ["*"], secret?, description?} |
| GET | /api/webhooks/[id] |
Mengambil webhook |
| PUT | /api/webhooks/[id] |
Memperbarui url/events/secret/description |
| DELETE | /api/webhooks/[id] |
Menghapus webhook |
| POST | /api/webhooks/[id]/test |
Mengirim payload pengujian ke URL webhook dan mengembalikan status pengiriman |
Autentikasi: sesi manajemen/kunci API (requireManagementAuth).
Kunci Terdaftar (Pengelolaan Otomatis)
Digunakan oleh subsistem pengelolaan kunci otomatis untuk menerbitkan dan merotasi kunci API pada penyedia/akun pendukung, dengan kuota harian/per jam.
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /api/v1/registered-keys |
Menampilkan daftar kunci terdaftar (hanya prefiks yang disamarkan) |
| POST | /api/v1/registered-keys |
Menerbitkan kunci terdaftar baru — isi: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Mengembalikan kunci mentah satu kali. Mengembalikan 429 jika kuota ditolak. |
| GET | /api/v1/registered-keys/[id] |
Mengambil metadata kunci terdaftar (tanpa materi kunci mentah) |
| DELETE | /api/v1/registered-keys/[id] |
Mencabut kunci terdaftar |
| POST | /api/v1/registered-keys/[id]/revoke |
Endpoint pencabutan eksplisit (efeknya sama dengan DELETE) |
Autentikasi: sesi manajemen/kunci API (requireManagementAuth) — menggunakan mekanisme perlindungan yang sama seperti /api/keys: sesi dasbor, token CLI lokal, atau kunci API dengan cakupan manage/admin; kunci API khusus inferensi akan mendapatkan 403. Lihat juga /v1/quotas/check dan /v1/issues/report.
Protokol Agen
Tugas agen cloud (Claude Code, Codex Cloud, OpenHands, dll.) yang dijalankan dari jarak jauh atas nama pengguna OmniRoute.
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /api/v1/agents/tasks |
Daftar tugas — opsional ?provider=, ?status=, ?limit= (1–500, default 50) |
| POST | /api/v1/agents/tasks |
Buat tugas — isi divalidasi oleh CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Mengembalikan 201 dengan amplop tugas |
| DELETE | /api/v1/agents/tasks?id=... |
Hapus tugas |
| GET | /api/v1/agents/tasks/[id] |
Baca tugas — menyegarkan status secara sinkron dari agen cloud upstream saat external_id ditetapkan |
| POST | /api/v1/agents/tasks/[id] |
Tindakan terdiskriminasi: {action: "approve"}, {action: "message", message}, atau {action: "cancel"} |
| DELETE | /api/v1/agents/tasks/[id] |
Hapus tugas tertentu berdasarkan id |
Autentikasi: autentikasi manajemen diwajibkan pada setiap metode (
requireCloudAgentManagementAuth). Sebelum v3.8.0, metode-metode ini tidak memerlukan autentikasi — lihat commit588a0333untuk perubahan yang merusak kompatibilitas tersebut.
# Buat tugas cloud 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 Manajemen
Proksi HTTP(S)/SOCKS keluar yang dapat ditetapkan ke penyedia, akun, atau secara global.
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /api/v1/management/proxies |
Daftar proksi (dengan ?id= mengembalikan satu proksi; dengan ?id=&where_used=1 mengembalikan grafik penetapan) |
| POST | /api/v1/management/proxies |
Buat proksi — isi divalidasi oleh createProxyRegistrySchema |
| PATCH | /api/v1/management/proxies |
Perbarui proksi — isi divalidasi oleh updateProxyRegistrySchema (memerlukan id) |
| DELETE | /api/v1/management/proxies?id=...&force=1 |
Hapus proksi (gunakan force=1 untuk melepaskan penetapan) |
| GET | /api/v1/management/proxies/assignments |
Daftar penetapan — dapat difilter berdasarkan proxy_id, scope, scope_id; teruskan resolve_connection_id=<id> untuk menentukan proksi aktif bagi suatu koneksi |
| PUT | /api/v1/management/proxies/assignments |
Tetapkan — isi divalidasi oleh proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Menghapus cache dispatcher |
| PUT | /api/v1/management/proxies/bulk-assign |
Tetapkan secara massal — isi divalidasi oleh bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?}) |
| GET | /api/v1/management/proxies/health?hours=24 |
Agregat kesehatan proksi (jumlah berhasil/gagal, latensi) selama suatu rentang waktu |
Autentikasi: sesi manajemen/kunci API pada setiap rute (requireManagementAuth).
POST /api/v1/management/proxies/[id]/assignmentsdanPOST /api/v1/management/proxies/[id]/healthdalam deskripsi tugas dilayani oleh rute datar/assignmentsdan/healthyang ditampilkan di atas — tidak ada subrute per-id dalam basis kode.
Ketahanan (diperluas)
OmniRoute menyediakan tiga mekanisme kegagalan sementara yang independen; endpoint pengelolaan di bawah ini memungkinkan operator melihat dan mengganti pengaturannya:
| Cakupan | Penyimpanan status | Baca | Atur ulang / hapus |
|---|---|---|---|
| Pemutus sirkuit penyedia | domain_circuit_breakers + dalam memori |
/api/monitoring/health |
POST /api/resilience/reset |
| Masa tunggu koneksi | rateLimitedUntil pada koneksi penyedia |
/api/rate-limits, /api/providers/[id] |
(diaktifkan kembali secara malas; hapus melalui PUT penyedia) |
| Penguncian model | Registri ketersediaan model dalam memori | GET /api/resilience/model-cooldowns |
DELETE /api/resilience/model-cooldowns |
PATCH /api/resilience menerima penggantian pemutus sirkuit penyedia melalui providerBreaker.oauth dan providerBreaker.apikey. Setiap profil mendukung degradationThreshold, failureThreshold, dan resetTimeoutMs; kolom yang sama tersedia di Dasbor → Pengaturan → Ketahanan.
# Hapus penguncian 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"}'
# Hapus semua penguncian
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
Untuk referensi konseptual lengkap dan nilai default pemutus sirkuit, lihat CLAUDE.md → "Status Runtime Ketahanan".
Keterampilan
Kerangka kerja keterampilan untuk memperluas OmniRoute dengan handler khusus yang dapat dieksekusi, beserta integrasi marketplace.
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /api/skills |
Cantumkan keterampilan yang terinstal — dapat difilter berdasarkan ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, dengan paginasi |
| GET | /api/skills/[id] |
Ambil satu keterampilan |
| PUT | /api/skills/[id] |
Perbarui keterampilan (nama, deskripsi, mode, skema, handler, tag) |
| DELETE | /api/skills/[id] |
Hapus instalasi keterampilan |
| POST | /api/skills/install |
Instal keterampilan dari manifes mentah — isi: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?} |
| GET | /api/skills/executions |
Cantumkan eksekusi keterampilan terbaru (jejak audit dengan input/output/durasi) |
| GET | /api/skills/marketplace?q=... |
Cari/daftar populer dari marketplace SkillsMP (memerlukan pengaturan skillsmpApiKey) |
| POST | /api/skills/marketplace/install |
Instal keterampilan berdasarkan id dari SkillsMP |
| GET | /api/skills/skillssh?q=&limit= |
Cari registri skills.sh |
| POST | /api/skills/skillssh/install |
Instal keterampilan berdasarkan id dari skills.sh |
Autentikasi: sesi pengelolaan/kunci API. Rute pencarian marketplace menerima autentikasi pengelolaan atau kunci API Bearer (isAuthenticated).
Memori
Penyimpanan memori percakapan/faktual persisten, dengan cakupan per kunci API / sesi.
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /api/memory |
Mencantumkan memori — ?apiKeyId=, ?type=, ?sessionId=, ?q=, dengan paginasi offset/limit atau page/limit |
| POST | /api/memory |
Membuat memori — isi permintaan divalidasi oleh Zod: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?} |
| GET | /api/memory/[id] |
Mengambil satu memori |
| DELETE | /api/memory/[id] |
Menghapus memori |
| GET | /api/memory/health |
Kesehatan subsistem memori (konektivitas DB, backend embedding, status indeks vektor) |
Autentikasi: sesi manajemen/kunci API (requireManagementAuth). Enum type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (lihat MemoryType di src/lib/memory/types.ts).
Server MCP
OmniRoute menyertakan server Model Context Protocol tersemat dengan 3 transportasi (stdio, SSE, streamable-http) dan alat dengan cakupan tertentu. Endpoint dasbor di bawah ini membaca data status/audit dan mem-proxy transportasi HTTP.
| Metode | Jalur | Deskripsi |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | /api/mcp/status | Heartbeat, transportasi, status daring, panggilan terakhir, alat teratas, tingkat keberhasilan 24 jam |
| GET | /api/mcp/tools | Daftar alat MCP dengan name, description, scopes, phase, auditLevel, sourceEndpoints |
| GET | /api/mcp/sse | Membuka aliran SSE untuk transportasi SSE (mengembalikan 503 jika MCP dinonaktifkan atau transportasi tidak cocok) |
| POST | /api/mcp/sse | Mengirim frame JSON-RPC melalui transportasi SSE |
| GET | /api/mcp/stream | Membuka sisi SSE dari transportasi Streamable HTTP (pesan yang dimulai oleh server) |
| POST | /api/mcp/stream | Mengirim frame JSON-RPC melalui transportasi Streamable HTTP |
| DELETE | /api/mcp/stream | Mengakhiri sesi Streamable HTTP |
| GET | /api/mcp/audit | Mengueri log audit — ?limit=, ?offset=, ?tool=, ?success=true | false, ?apiKeyId= |
| GET | /api/mcp/audit/stats | Statistik audit agregat (total, tingkat keberhasilan, durasi rata-rata, alat teratas) |
Autentikasi: transportasi sse/stream mengikuti mekanisme autentikasi khusus MCP (kunci API Bearer dengan cakupan mcp); rute status/tools/audit* dapat dibaca dari dasbor (tidak diperlukan autentikasi tambahan selain kemampuan mengakses host dasbor).
Kedua transportasi HTTP dikontrol oleh
settings.mcpEnableddansettings.mcpTransport— ketidakcocokan transportasi mengembalikan400, sedangkan status MCP yang dinonaktifkan mengembalikan503.
Server A2A
OmniRoute menyediakan endpoint A2A (Agent-to-Agent) JSON-RPC 2.0 beserta pembungkus REST untuk keperluan inspeksi/dasbor.
JSON-RPC
POST /a2a
Authorization: Bearer your-api-key # opsional kecuali 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"}]
}
}
Metode yang didukung (semuanya bergantung pada settings.a2aEnabled):
| Metode | Deskripsi |
|---|---|
message/send |
Eksekusi skill sinkron; mengembalikan {task, artifacts, metadata} |
message/stream |
Eksekusi SSE streaming dari kumpulan skill yang sama |
tasks/get |
Mengambil tugas berdasarkan taskId |
tasks/cancel |
Membatalkan tugas berdasarkan taskId |
Skill bawaan: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.
Kartu Agen
GET /.well-known/agent.json
Mengembalikan kartu agen A2A publik (nama, deskripsi, kapabilitas, katalog skill, skema autentikasi) — disimpan dalam cache publik selama 1 jam. Tidak memerlukan autentikasi.
Pembantu REST
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /api/a2a/status |
Status aktif A2A + statistik tugas + ringkasan kartu agen yang di-cache |
| GET | /api/a2a/tasks |
Mencantumkan tugas — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset= |
| POST | /api/a2a/tasks |
(Tidak diimplementasikan sebagai pembantu REST — buat melalui JSON-RPC message/send) |
| GET | /api/a2a/tasks/[id] |
Mengambil satu tugas |
| POST | /api/a2a/tasks/[id]/cancel |
Membatalkan tugas |
Autentikasi: pembantu REST berjalan tanpa autentikasi manajemen (dapat dibaca dasbor); rute JSON-RPC /a2a menggunakan Bearer OMNIROUTE_API_KEY jika dikonfigurasi.
Cloud, Evaluasi & Penilaian
| Metode | Jalur | Deskripsi |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | /api/cloud/auth | Verifikasi kunci Bearer dan kembalikan koneksi penyedia yang disamarkan + alias model untuk klien sinkronisasi cloud |
| POST | /api/cloud/credentials/update | Perbarui kredensial terenkripsi untuk penyedia yang disinkronkan dengan cloud |
| POST | /api/cloud/model/resolve | Petakan ID model logis ke penyedia/model konkret menggunakan tabel perutean lokal |
| GET | /api/cloud/models/alias | Cantumkan alias model sebagaimana diekspos ke sinkronisasi cloud |
| GET | /api/assess | Baca kategorisasi penilaian terbaru (per penyedia/model) |
| POST | /api/assess | Jalankan penilaian — isi: {scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?} |
| GET | /api/evals | Cantumkan suite evaluasi bawaan + eksekusi terbaru |
| POST | /api/evals | Picu eksekusi evaluasi |
| POST | /api/evals/suites | Buat suite evaluasi khusus — isi divalidasi oleh evalSuiteSaveSchema |
| GET | /api/evals/suites/[id] | Ambil suite evaluasi khusus |
Autentikasi: /api/cloud/auth memvalidasi kunci Bearer secara langsung dan hanya mengembalikan kunci yang disamarkan serta projectId dari setiap koneksi untuk kunci dengan cakupan manage / admin; rute /api/cloud/*, /api/evals/*, dan /api/assess lainnya memerlukan sesi manajemen/kunci API. POST /api/assess menggunakan validateBody dengan skema cakupan gabungan terdiskriminasi.
Pengelolaan ACP (Agent Client Protocol)
sebagai proses anak. Endpoint ini mengelola deteksi agen ACP dan pendaftaran agen khusus.
| Metode | Path | Deskripsi |
|---|---|---|
| GET | /api/acp/agents |
Mencantumkan semua agen CLI yang diketahui (bawaan + khusus) beserta status instalasi, versi, dan biner |
| POST | /api/acp/agents |
Mendaftarkan agen ACP khusus atau menyegarkan cache — isi: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} atau {action: "refresh"} |
| DELETE | /api/acp/agents |
Menghapus agen ACP khusus — parameter kueri: ?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
}
Autentikasi: Memerlukan sesi pengelolaan (cookie auth_token dasbor) atau
kunci API dengan cakupan pengelolaan.
Lihat Kerangka Kerja ACP untuk detail lengkap.
Analitik & Observabilitas
Endpoint analitik real-time untuk memantau perutean, kompresi, dan keragaman
penyedia. Endpoint ini mendukung halaman /dashboard/analytics/*.
Analitik perutean otomatis
| Metode | Path | Deskripsi |
|---|---|---|
| GET | /api/analytics/auto-routing |
Statistik agregat perutean otomatis: total panggilan, distribusi strategi, distribusi tingkat, penyedia teratas |
| GET | /api/analytics/auto-routing?days=7 |
Statistik berdasarkan rentang waktu (default 24 jam) |
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 kompresi
| Metode | Path | Deskripsi |
|---|---|---|
| GET | /api/analytics/compression |
Statistik agregat kompresi: token yang dihemat, persentase penghematan, distribusi mode, penggunaan mesin |
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
}
}
Pelacakan keragaman penyedia
| Metode | Path | Deskripsi |
|---|---|---|
| GET | /api/analytics/diversity |
Pelacakan keragaman berbasis entropi Shannon: mencegah titik kegagalan tunggal dengan mengukur persebaran 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"]
}
Autentikasi: Memerlukan sesi pengelolaan atau kunci API dengan cakupan pengelolaan.
Operasi Admin
Endpoint khusus admin untuk manajemen operasional.
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /api/admin/concurrency |
Membaca batas konkurensi saat ini (global + per penyedia) |
| POST | /api/admin/concurrency |
Memperbarui batas konkurensi — isi: {global?: number, perProvider?: Record<string, number>} |
Autentikasi: Memerlukan sesi manajemen dengan cakupan admin.
Pengelolaan Alat CLI
Kelola alat CLI yang terintegrasi dengan OmniRoute (antigravity, commandCode, devin-cli, dll.). Lihat Referensi Penyedia untuk daftar lengkap.
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /api/cli-tools/all-statuses |
Status semua alat CLI (terinstal, versi, terakhir terlihat) |
| GET | /api/cli-tools/status |
Detail status untuk satu alat CLI (kueri ?tool=) |
| POST | /api/cli-tools/apply |
Menulis konfigurasi alat yang dihasilkan (dryRun menampilkan pratinjau; 422 + containerEphemeralTarget saat berada dalam kontainer; migration mencatat YAML Codex lama) |
| GET | /api/cli-tools/backups |
Mencantumkan cadangan konfigurasi alat CLI |
| POST | /api/cli-tools/backups |
Membuat cadangan semua konfigurasi alat CLI |
| POST | /api/cli-tools/backups |
Memulihkan: endpoint yang sama dengan {tool, backupId} dalam isi permintaan akan memulihkan cadangan tersebut |
| GET | /api/cli-tools/antigravity-mitm |
Status proksi MITM Antigravity (alat CLI "antigravity-mitm") |
| POST | /api/cli-tools/antigravity-mitm/alias |
Mengonfigurasi alias antigravity-mitm |
Autentikasi: Memerlukan sesi pengelolaan.
Keterampilan Agen
Kelola keterampilan agen AI (serupa dengan GPT khusus milik OpenAI, tetapi untuk agen).
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /api/agent-skills |
Mencantumkan semua keterampilan agen (bawaan + kustom) |
| GET | /api/agent-skills/[id] |
Mendapatkan keterampilan agen tertentu |
| POST | /api/agent-skills |
Membuat keterampilan agen kustom — isi: {name, description, prompt, model?, temperature?} |
| PUT | /api/agent-skills/[id] |
Memperbarui keterampilan agen kustom |
| DELETE | /api/agent-skills/[id] |
Menghapus keterampilan agen kustom |
| GET | /api/agent-skills/[id]/raw |
Mendapatkan prompt mentah + metadata (tanpa eksekusi) |
| POST | /api/agent-skills/generate |
Menghasilkan keterampilan baru dengan AI dari deskripsi bahasa alami |
Autentikasi: Memerlukan sesi manajemen atau kunci API dengan cakupan manajemen.
Manajemen Cache
Kelola cache semantik dan cache penalaran.
| Metode | Path | Deskripsi |
|---|---|---|
| GET | /api/cache |
Ikhtisar cache: jumlah total entri, tingkat hit, ukuran pada disk |
| GET | /api/cache/entries |
Daftar entri yang disimpan dalam cache (dengan paginasi) |
| DELETE | /api/cache/entries |
Hapus entri cache (filter berdasarkan parameter kueri) |
| GET | /api/cache/stats |
Statistik cache terperinci (per penyedia, per model) |
| GET | /api/cache/reasoning |
Status cache penalaran (untuk pemutaran ulang penalaran) |
| DELETE | /api/cache/reasoning |
Bersihkan cache penalaran — parameter kueri: ?toolCallId=<id> (tunggal), ?provider=<p>, atau tanpa parameter (semua) |
Autentikasi: Memerlukan sesi manajemen.
Sistem Memori
Kelola memori persisten (FTS5 + embedding vektor).
| Metode | Path | Deskripsi |
|---|---|---|
| GET | /api/memory |
Daftar entri memori (filter berdasarkan cakupan, jenis, dan kueri pencarian) |
| POST | /api/memory |
Buat entri memori baru — isi: {scope, type, content, metadata?} |
| GET | /api/memory/[id] |
Dapatkan entri memori tertentu |
| PUT | /api/memory/[id] |
Perbarui entri memori |
| DELETE | /api/memory/[id] |
Hapus entri memori |
| GET | /api/memory?q= |
Cari memori (FTS5 + vektor) — statistik disertakan dalam respons yang sama |
Autentikasi: Memerlukan sesi manajemen atau kunci API dengan cakupan manajemen.
Webhook
Kelola langganan webhook untuk berbagai peristiwa.
| Metode | Path | Deskripsi |
|---|---|---|
| GET | /api/webhooks |
Daftar semua langganan webhook |
| POST | /api/webhooks |
Buat langganan webhook — isi: {url, events[], secret?, active?} |
| GET | /api/webhooks/[id] |
Dapatkan langganan webhook tertentu |
| PUT | /api/webhooks/[id] |
Perbarui langganan webhook |
| DELETE | /api/webhooks/[id] |
Hapus langganan webhook |
| GET | /api/webhooks/[id]/deliveries |
Daftar riwayat pengiriman webhook (log keberhasilan/kegagalan) |
| POST | /api/webhooks/[id]/test |
Kirim peristiwa pengujian ke webhook |
Autentikasi: Memerlukan sesi manajemen.
Lihat Kerangka Kerja Webhook untuk daftar lengkap jenis peristiwa.
Kerangka Kerja Skills
Kelola Skills (kerangka kerja ekstensi agentik).
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /api/skills |
Cantumkan semua skill yang terinstal (bawaan + kustom) |
| POST | /api/skills/install |
Instal skill dari jalur lokal atau URL |
| DELETE | /api/skills/[id] |
Hapus instalasi skill |
| PUT | /api/skills/[id] |
Aktifkan atau nonaktifkan skill — body: {enabled?: boolean, mode?: "on" | "off" | "auto"} |
| POST | /api/skills/executions |
Jalankan skill — body: {skillName, apiKeyId, input?, sessionId?} |
| GET | /api/skills/executions |
Cantumkan riwayat eksekusi untuk semua skill (filter berdasarkan ?apiKeyId=) |
Autentikasi: Memerlukan sesi manajemen atau kunci API dengan cakupan manajemen.
Lihat Kerangka Kerja Skills untuk detail lengkap.
Plugin
Kelola plugin OmniRoute (ekstensi pihak ketiga).
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /api/plugins |
Cantumkan plugin yang terinstal |
| POST | /api/plugins/marketplace/install |
Instal plugin dari marketplace |
| DELETE | /api/plugins/[name] |
Hapus instalasi plugin |
| POST | /api/plugins/[name]/activate |
Aktifkan plugin |
| POST | /api/plugins/[name]/deactivate |
Nonaktifkan plugin |
| GET | /api/plugins/[name]/config |
Dapatkan konfigurasi plugin |
| PUT | /api/plugins/[name]/config |
Perbarui konfigurasi plugin |
Autentikasi: Memerlukan sesi manajemen.
Lihat Kerangka Kerja Plugin untuk detail lengkap.
Shadow Routing
Perbandingan shadow/A-B antarpenyedia bukan antarmuka REST mandiri — ini dikonfigurasi melalui combo routing (lihat Auto-Combo). Metrik perbandingan per combo disediakan oleh GET /api/combos/metrics.
Guardrail
Periksa guardrail runtime (deteksi PII, deteksi prompt injection, vision bridging). Guardrail dijalankan pada setiap permintaan; penonaktifan per panggilan dilakukan melalui header permintaan x-omniroute-disabled-guardrails — tidak tersedia antarmuka pengaktifan/penonaktifan yang persisten.
| Metode | Jalur | Deskripsi |
|---|---|---|
| GET | /api/guardrails |
Cantumkan guardrail yang terdaftar beserta statusnya (nama/diaktifkan/prioritas) |
| POST | /api/guardrails/test |
Lakukan uji coba pipeline prapanggilan pada input sampel — body: {input, disabledGuardrails?} |
Autentikasi: Memerlukan sesi manajemen.
Lihat Keamanan > Guardrail untuk detail lengkap.
Autentikasi
Lihat Autentikasi Manajemen untuk empat
kelompok kredensial (sesi dashboard, token CLI lokal, Token Akses oma_live_…,
kunci API dengan cakupan manajemen) dan perbedaannya dengan kunci inferensi.
- Rute dashboard (
/dashboard/*) menggunakan cookieauth_token - Login menggunakan hash kata sandi yang tersimpan; dengan fallback ke
INITIAL_PASSWORD requireLogindapat diaktifkan atau dinonaktifkan melalui/api/settings/require-login- Rute
/v1/*secara opsional memerlukan kunci API Bearer ketikaREQUIRE_API_KEY=true - "token manajemen" / "kunci API dengan cakupan manajemen" dalam referensi ini berarti salah satu kelompok dalam panduan tersebut — bukan jenis rahasia tambahan yang tidak didefinisikan
Perubahan yang merusak kompatibilitas (v3.8.0) —
/api/v1/agents/tasks/*dan endpoint manajemen cooldown kini memerlukan autentikasi manajemen (cookieauth_tokendashboard atau kunci API dengan cakupan manajemen). Klien yang sebelumnya memanggil rute-rute ini tanpa autentikasi akan menerima401 Unauthorized. Lihat commit588a0333(fix(auth): require management auth for agent and cooldown APIs).