Skip to content

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

159 KB
Raw Blame

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 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), aktifkan underscores_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.0000000000 untuk 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, dan X-OmniRoute-Fallback-Attempts (hanya jika > 0), serta X-OmniRoute-Request-Id dan X-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 selalu 0). Biaya media dihitung per modalitas (per gambar, per detik, per karakter, per unit pencarian) jika informasi harga tersedia; jika tidak, nilainya 0 (fail-open).

Semantik biaya cache hit: pada HIT cache semantik (X-OmniRoute-Cache-Hit: true), tidak ada panggilan upstream yang dilakukan, sehingga X-OmniRoute-Response-Cost bernilai 0.0000000000 (biaya inkremental untuk menyajikan hit tersebut). Biaya asli/yang seharusnya dikeluarkan dilaporkan secara terpisah dalam X-OmniRoute-Cost-Saved. Konsumen penagihan harus menjumlahkan X-OmniRoute-Response-Cost (hit tidak menimbulkan biaya); analitik cache dapat mengagregasi X-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 off atau default tidak 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}:embedContent dengan content.parts (text atau inline_data).
  • llama.cpp (llama-cpp/<model>, model apa pun yang dimuat oleh server lokal): item text kanonis menjadi string biasa, sedangkan image / audio / video masing-masing menjadi satu objek {"content": [part]}, menggunakan bagian konten percakapan llama-server (image_url, input_audio dengan format wav / 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. document tidak 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-2 menggunakan OpenAI Images API milik ZenMux. Opsi yang tersedia mencakup size, quality, n, output_format, output_compression, background, dan response_format.
  • Penerbit lain, seperti zm/meta/muse-image-1.0, menggunakan endpoint :predict Vertex AI milik ZenMux. n dipetakan ke sampleCount, aspect_ratio ke aspectRatio, dan image_size (1K, 2K, 4K) ke sampleImageSize. size berbasis 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-design menentukan dimensinya sendiri. Jangan sertakan size, aspect_ratio, dan image_size; nilai eksplisit akan menghasilkan HTTP 400. PNG, JPEG, dan WebP dapat diminta melalui output_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/rerank juga 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 dalam OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS (misalnya nama layanan Docker/Compose seperti http://reranker:8080/v1; node ini dipanggil secara langsung, tidak pernah melalui HTTP(S)_PROXY atau proksi tersemat milik koneksi). Node pada host lain mana pun — perangkat LAN atau peer Tailscale — hanya memenuhi syarat jika operator mengaktifkan feature flag RERANK_REMOTE_PROVIDER_NODES dan 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 untuk rerankProviderModel dalam pengaturan Memori.

Bentuk server lokal: node dipanggil pada <base>/v1/rerank dan, 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 hingga top_n.

Penemuan node penyedia: model pada node penyedia yang kompatibel dengan OpenAI muncul dalam GET /v1/models di bawah prefiks node. Baris yang tidak memiliki metadata endpoint (umumnya pada daftar /v1/models lokal) mewarisi apiType node, sehingga model milik node embeddings memiliki type: "embedding" dan model milik node rerank memiliki type: "rerank", alih-alih secara default dianggap sebagai chat; nilai supportedEndpoints eksplisit 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: mengembalikan 0%.
  • 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 dan quotaWindowThresholds tingkat 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 quotaWindowThresholds untuk 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: nightly untuk versi -nightly.*, next untuk pra-rilis lainnya (-rc.*, -beta.*, -alpha.*), lts untuk versi stabil dari versi mayor yang lebih lama daripada channels.latest, dan selain itu latest. Aturannya sama dengan scripts/release/dist-tag.mjs, yang memilih dist-tag npm pada saat publikasi.
  • channels — versi terdepan yang dipublikasikan dari setiap dist-tag, dari npm view omniroute dist-tags (fallback HTTP registry), disimpan dalam cache dengan TTL 10 menit yang sama seperti latest. latest selalu tersedia (beralih ke kolom latest, lalu "unavailable"); next, nightly, dan lts hanya muncul jika dist-tag tersebut tersedia. Permintaan Cache-Control: no-cache menyegarkan 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): apiKeyId wajib diisi; setidaknya salah satu dari dailyLimitUsd, weeklyLimitUsd, atau monthlyLimitUsd harus lebih besar dari nol. Bidang opsional: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Format lama {keyId, limit, period} mengembalikan 400 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): apiKeyId dan scopeType (model | provider | global) wajib diisi. scopeValue wajib diisi kecuali jika scopeType adalah global (misalnya id model untuk cakupan model, atau id penyedia untuk cakupan provider). tokenLimit harus berupa bilangan bulat positif (dikonversi dari string). Opsional: id (hilangkan untuk membuat, sertakan untuk memperbarui), resetInterval (daily | weekly | monthly, nilai bawaan monthly), resetTime (HH:MM), enabled (nilai bawaan true). Respons GET memperkaya setiap batas dengan tokensUsed, remaining, windowStart, periodStartAt, dan nextResetAt. Ini adalah endpoint kelas manajemen (autentikasi diberlakukan secara terpusat oleh pipeline otorisasi).

Pemrosesan Permintaan

  1. Klien mengirim permintaan ke /v1/*
  2. Penangan rute memanggil handleChat, handleEmbedding, handleAudioTranscription, atau handleImageGeneration
  3. Model ditentukan (penyedia/model langsung atau alias/kombo)
  4. Kredensial dipilih dari DB lokal dengan pemfilteran ketersediaan akun
  5. Untuk percakapan: handleChatCore memeriksa cache semantik/tanda tangan dan menentukan pengaturan kompresi kombo
  6. Kompresi proaktif berjalan sebelum penerjemahan penyedia ketika diaktifkan (lite, Caveman, RTK, atau bertumpuk)
  7. Eksekutor penyedia mengirim permintaan ke hulu
  8. Respons diterjemahkan kembali ke format klien (percakapan) atau dikembalikan apa adanya (embedding/gambar/audio)
  9. Penggunaan, analitik kompresi, dan log permintaan dicatat
  10. 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 commit 588a0333 untuk 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]/assignments dan POST /api/v1/management/proxies/[id]/health dalam deskripsi tugas dilayani oleh rute datar /assignments dan /health yang 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.mcpEnabled dan settings.mcpTransport — ketidakcocokan transportasi mengembalikan 400, sedangkan status MCP yang dinonaktifkan mengembalikan 503.


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 cookie auth_token
  • Login menggunakan hash kata sandi yang tersimpan; dengan fallback ke INITIAL_PASSWORD
  • requireLogin dapat diaktifkan atau dinonaktifkan melalui /api/settings/require-login
  • Rute /v1/* secara opsional memerlukan kunci API Bearer ketika REQUIRE_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 (cookie auth_token dashboard atau kunci API dengan cakupan manajemen). Klien yang sebelumnya memanggil rute-rute ini tanpa autentikasi akan menerima 401 Unauthorized. Lihat commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).