198 KiB
API Reference (Filipino)
🌐 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 · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇱 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
🌐 Mga Wika: 🇺🇸 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á | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)
Pangunahing sanggunian para sa OmniRoute API. Saklaw nito ang pampublikong /v1 surface at ang mga pinakaginagamit na endpoint para sa pamamahala; ang machine-readable na docs/openapi.yaml at ang puno ng mga ruta sa ilalim ng src/app/api/ ang kumpletong mga sanggunian.
Para sa nakatuong protocol na katugma ng OpenAI at matrix ng mga kakayahan ng provider, tingnan ang
OPENAI_COMPATIBILITY.md.
Ang bawat deployment ay naghahatid ng sarili nitong kopya ng spec sa /openapi.yaml, na binubuo mula sa docs/openapi.yaml habang isinasagawa ang build. Taglay nito ang bersyon ng build at isang relative na server URL (./), kaya nananatili ang mga request sa host na naghatid ng dokumento. Walang ganoong host ang tool na nag-i-import ng na-download na file, kaya kailangang itakda nang manu-mano ang base URL.
Talaan ng mga Nilalaman
- Mga Chat Completion
- Mga Eksklusibong Lease ng Pinamamahalaang Session
- Mga Embedding
- Pagbuo ng Larawan
- OCR ng Dokumento
- Paglista ng mga Modelo
- Manifest ng Plugin ng Provider
- Mga Compatibility Endpoint
- API ng mga File
- API ng mga Batch
- API ng Paghahanap
- Pag-stream sa WebSocket
- Mga Quota at Pag-uulat ng Isyu
- Semantic Cache
- Compatibility ng Pamamahala ng CLIProxyAPI
- Dashboard at Pamamahala
- Pamamahala ng Combo
- Mga Webhook
- Mga Nakarehistrong Key (Awtomatikong Pamamahala)
- Protokol ng mga Agent
- Mga Proxy ng Pamamahala
- Resilience (pinalawig)
- Mga Skill
- Memory
- MCP Server
- A2A Server
- Cloud, Evals at Assess
- Pagproseso ng Request
- Authentication
Mga Chat Completion
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
}
Mga Custom Header
| Header | Direction | Description |
|---|---|---|
X-OmniRoute-No-Cache |
Kahilingan | Itakda sa true upang lampasan ang cache |
x-omniroute-no-memory |
Kahilingan | Itakda sa true upang laktawan ang pag-inject ng memory + skills para sa kahilingang ito (kapareho ng no-cache; iniiwasan ang overhead ng token/gastos sa bawat tawag) |
X-OmniRoute-Progress |
Kahilingan | Itakda sa true para sa mga event ng progreso |
X-Session-Id |
Kahilingan | Sticky session key para sa external session affinity |
x_session_id |
Kahilingan | Tinatanggap din ang variant na may underscore (direct HTTP) |
X-OmniRoute-Session-Id |
Kahilingan | Tag ng session/conversation na ibinibigay ng caller (ipinapasa rin sa memory). Kapag mayroon, sine-save nang eksakto sa call_logs.session_tag para sa pagtatalaga ng gastos kada session (#8249) — hindi kailanman ginagawa kapag wala |
Idempotency-Key |
Kahilingan | Dedup key (5s na palugit) |
X-Request-Id |
Kahilingan | Alternatibong dedup key |
x-omniroute-connection |
Kahilingan | I-pin ang isang single-model na kahilingan sa isang koneksyon ng provider (account) ayon sa ID nito — tingnan ang Pag-pin ng account kada kahilingan |
X-OmniRoute-Cache |
Tugon | HIT o MISS (hindi streaming) |
X-OmniRoute-Idempotent |
Tugon | true kung na-deduplicate |
X-OmniRoute-Progress |
Tugon | enabled kung naka-on ang pagsubaybay sa progreso |
X-OmniRoute-Session-Id |
Tugon | Aktuwal na session ID na ginamit ng OmniRoute |
X-OmniRoute-Request-Id |
Tugon | ID ng correlation ng kahilingan (kapag alam) |
X-OmniRoute-Version |
Tugon | Bersyon ng build ng OmniRoute (laging naroroon) |
X-OmniRoute-Cost-Saved |
Tugon | USD na naiwasan ng cache sa isang HIT (mga cache hit lamang) |
X-OmniRoute-Decision |
Tugon | Trace ng pagruruta: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> ang combo strategy, o single para sa kahilingang hindi combo) — laging naroroon sa mga response kapag kumpleto na |
Tala sa Nginx: kung umaasa ka sa mga header na may underscore (halimbawa,
x_session_id), paganahin angunderscores_in_headers on;.
Pag-pin ng account kada kahilingan
Kapag ang isang provider ay may ilang koneksyon (mga account o key), karaniwang pumipili ang OmniRoute ng isa
gamit ang strategy nito sa pagpili ng account. Sa halip, maaaring i-pin ng isang kahilingan ang isang partikular na koneksyon
gamit ang header na 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"}]}'
- Saan makikita ang id. Buksan ang provider page sa dashboard
(Dashboard → Providers → ) at i-click ang
xxxxxxxx…id chip sa isang connection row — kokopyahin nito ang buong connection id. - Aling mga request ang kumikilala rito. Mga single-model request (
provider/model) sa/v1/chat/completions,/v1/messagesat/v1/responses. Hindi pinapansin ng mga combo ang header: i-pin ang isang account para sa bawat combo step sa pamamagitan ng sariling connection ng step. - Mahigpit ang pin, hindi ito preference. Eksklusibong gagamitin ang naka-pin na connection. Kapag nagkaroon ng failure sa loob ng request, itatala ang cooldown ng account ngunit hindi lilipat sa sibling account ng parehong provider.
- Inaalis ng cooldown at quota ang pin. Habang naka-cooldown ang naka-pin na connection, naubusan ng quota o na-block ng quota policy, ang mga susunod na request ay gagamit ng ibang connection ng provider, gaya mismo ng unpinned traffic.
- Nagdudulot ng failure ang hindi kilala o disabled na id. Ang id na wala sa active pool ng provider (na-delete, na-deactivate, o kabilang sa ibang provider) ay walang ineligible na account, kaya magfa-fail ang request sa halip na tahimik na i-route sa ibang lugar.
Nagpapadala ang Claude Code ng mga custom header sa pamamagitan ng ANTHROPIC_CUSTOM_HEADERS. Ilagay ito sa env block
ng ~/.claude/settings.json, o sa project-level na .claude/settings.json para mag-pin ng ibang account bawat project:
{
"env": {
"ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
"ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
"ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>",
},
}
Source: src/sse/handlers/chat.ts (pagbasa ng header), src/sse/services/auth.ts at
src/sse/services/sessionAffinityPin.ts (pag-release ng pin at pag-check kung nawawala sa pool).
Mga header ng cost telemetry: ang mga non-streaming success response ay naglalaman din ng
X-OmniRoute-*cost-telemetry set —X-OmniRoute-Response-Cost(USD, fixed na 10 decimal;0.0000000000para sa libre/walang presyo),X-OmniRoute-Tokens-In/X-OmniRoute-Tokens-Out,X-OmniRoute-Model,X-OmniRoute-Provider,X-OmniRoute-Latency-Ms,X-OmniRoute-Cache-Hit, atX-OmniRoute-Fallback-Attempts(kapag > 0 lamang), patiX-OmniRoute-Request-IdatX-OmniRoute-Version. Ipinapadala ang mga ito ng chat completions,/v1/responses,/v1/messages, at ng mga media endpoint —/v1/embeddings,/v1/images/generations,/v1/audio/speech,/v1/audio/transcriptions,/v1/rerank,/v1/videos/generations,/v1/music/generations, at/v1/moderations(palaging cost na0). Kinakalkula ang media cost ayon sa modality (bawat larawan, bawat segundo, bawat character, bawat search-unit) kapag available ang pricing; kung hindi,0(fail-open).
Semantics ng cost kapag cache hit: kapag may semantic-cache HIT (
X-OmniRoute-Cache-Hit: true), walang upstream call na ginagawa, kaya angX-OmniRoute-Response-Costay0.0000000000(ang incremental na cost ng pag-serve sa hit). Hiwalay na iniuulat ang orihinal/would-have-been cost saX-OmniRoute-Cost-Saved. Dapat pagsamahin ng mga consumer ng billing angX-OmniRoute-Response-Cost(walang cost ang mga hit); maaaring i-aggregate ng cache analytics angX-OmniRoute-Cost-Saved.
Eksklusibong Pinamamahalaang Lease ng Session
Ang eksklusibong pinamamahalaang session leasing ay isang opt-in, client-neutral na routing contract: isang aktibong owner ang may hawak ng isang kwalipikadong OmniRoute connection. Hindi ito nagle-lease ng model, hindi nangangailangan ng OAuth, hindi tumutukoy sa isang partikular na client, at hindi nangangailangan ng isang partikular na provider.
Dapat ay may saklaw na lease:exclusive at tahasang hindi walang-laman na listahang allowedConnections ang API key na ginagamit sa authentication. Ipinatutupad ng hangganan ng database mutation ang parehong field nang sabay sa paggawa ng key at sa mga partial update.
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"}
Ang matagumpay na mga tugon para sa acquire, renew, at release ay naglalantad ng mga timestamp, state, at ng eksaktong positibong
generation, ngunit hindi kailanman ng napiling connection o mga credential. Ipinapadala ng renew at release ang
generation sa JSON body:
{ "action": "renew", "generation": 1 }
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
Ang isang aktibong lease owner ay maaaring tahasang humiling ng privacy-safe na display metadata para sa kasalukuyan nitong binding:
{ "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"
}
}
Ang opt-in na action na ito para sa status ay ipinapatupad gamit ang opaque owner, authenticated managed API key, at eksaktong
aktibong generation sa isang database transaction. Ang displayName ay ang na-trim lamang na naka-configure na pangalan ng
connection; null ito kapag walang ligtas na naka-configure na pangalan. Hindi kailanman pinapalitan ng OmniRoute ang pangalan
ng isang email o nabuong account identity. Ang provider value ay isang display label na hindi sensitibo at hindi kailanman
isang nabuong compatible-provider identifier. Hindi kasama rito ang mga credential, token, cookie, raw connection o API
key id, owner hash, fencing secret, at internal routing data.
Ang mga lookup na may maling key, maling owner, lipas na generation, nawawala, nag-expire, ni-release, o na-invalidate ay lahat
nagbabalik ng parehong 409 LEASE_FENCE_STALE error nang walang connection metadata. Ang client na nakatanggap ng capacity-wait
response ay walang aktibong binding na maaaring siyasatin. Kapag nag-transition ang routing ng isang aktibong lease,
nanatiling valid ang parehong generation at atomiko namang ibinabalik ng status ang bagong binding, hindi kailanman ang luma.
Hindi nagbabago ang mga kasalukuyang client dahil nananatili sa dati nilang hugis ang mga response para sa acquire, renew, release,
at waiting.
Hindi binabago ng server contract na ito ang stock OpenAI Codex /status. Kasalukuyang iniuulat ng stock Codex ang
model provider nito at ang built-in authentication/account state, ngunit hindi nito nirere-render ang arbitraryong custom
provider account metadata; kailangang tawagin ng isang susunod na client integration ang action na ito at magpasya kung paano
ipapakita ang connection.displayName.
Ang bawat managed inference request ay nagbibigay pagkatapos ng parehong control header:
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
Ang eksaktong owner, generation, aktibong connection, at authenticated API key ay agad na ipinapatupad bago ang bawat suportadong upstream attempt. Mabibigo ang pag-replay ng owner at generation gamit ang ibang key kahit pinapahintulutan ng key na iyon ang parehong connection. Hindi sine-save ang mga raw owner, hindi nilala-log, hindi pinananatili sa request snapshot, at hindi ipinapasa upstream.
Ang pansamantalang contention ay nagbabalik ng HTTP 429 na may Retry-After at:
{
"state": "WAITING_FOR_CAPACITY",
"error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
"reason": "NO_FREE_ELIGIBLE_CONNECTION",
"retryAfter": 30
}
Nangangahulugan lamang ang response na ito na hindi walang-laman ang ordinaryong eligible set at ang bawat libreng candidate ay hawak ng isang foreign active lease. Pinananatili ng mga hindi suportadong model/provider, policy mismatch, cooldown, quota, health, at iba pang karaniwang eligibility failure ang dati nilang mga response ng OmniRoute.
x-omniroute-compression
Per-request na override ng compression plan. Pinakamataas ang precedence — nangingibabaw sa routing-combo override, aktibong profile, auto-trigger, at Default ng panel. Mga value:
| Value | Effect |
|---|---|
off |
Walang compression para sa request na ito. |
default |
Ang Default profile na hinango mula sa panel (binabalewala ang aktibong profile). Nananatiling naka-off ang mga lossy engine. |
safe |
Dedup at whitespace folding lamang. |
allow-lossy |
Panatilihin ang operator plan para sa request na ito, kabilang ang mga summary at style rewrite. |
engine:<id> |
Isang engine kapag naka-enable, hal. engine:rtk. Per-request na opt-in para sa engine na iyon. |
<combo> |
Isang pinangalanang combo, na unang itinutugma ayon sa pangalan (case-insensitive), pagkatapos ay ayon sa id. |
Mga tala:
- Binabalewala ang mga hindi kilalang value (hindi kailanman nire-reject ang request); bumababa ang resolution sa normal na operator precedence.
- Kung maraming combo ang may parehong pangalan, ipasa ang combo id para sa deterministic na pagtutugma.
- Ang combo na ang pangalan ay
offodefaultay hindi maaaring piliin ayon sa pangalan (binibigyang-kahulugan muna ang mga keyword na ito); tukuyin ang naturang combo gamit ang id nito. - Ang master compression switch ay isang mahigpit na gate: kapag globally naka-disable ang compression, hindi ito maaaring i-enable ng header na ito.
Ibinabalik sa response header ang inilapat na plan:
X-OmniRoute-Compression: <mode>; source=<source>
kung saan ang <source> ay isa sa request-header, routing-override, active-profile, auto-trigger, default, o off.
Mga embedding
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "nebius/Qwen/Qwen3-Embedding-8B",
"input": "The food was delicious"
}
Mga available na provider: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.
Ang mga catalog ID ay provider/model (halimbawa: jina-ai/jina-embeddings-v5-omni-small). Nalulutas din ang mga bare Jina model ID na lumilitaw sa registry (halimbawa, jina-embeddings-v5-text-small, jina-reranker-v3.5). Ang Jina embed/rerank/classify/segment ay unang gumagamit ng mga credential na jina-ai mula sa dashboard; fallback lamang ang JINA_AI_API_KEY kapag walang dashboard key. Ang card na jina-reader ay para lamang sa Reader / r.jina.ai (POST /v1/web/fetch) at hindi kailanman nagsisilbi ng embeddings o rerank.
Ang mga registry model na nag-aanunsyo ng multimodal support ay tumatanggap din ng hanggang 32 provider-neutral na structured item. Ang mga uri ng media item ay text, image, audio, video, at document. Ang source ng kanilang media ay alinman sa {"type":"url","url":"https://..."} o {"type":"base64","data":"...","media_type":"..."}.
Ang Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano, at ang family alias na jina-ai/jina-embeddings-v5-omni → omni-small) ay tumatanggap din ng native na Jina
EmbeddingsV5Request docs at ipinapasa ang mga ito nang buo sa 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,..." }] }
]
}
Ang mga native na value na { image | audio | video | pdf } ay maaaring isang pampublikong HTTPS URL, isang data: URI, o raw base64. Hindi sini-stringify ng OmniRoute ang mga object na iyon o kinukuha ang mga native image URL — si Jina mismo ang kumukuha ng pampublikong media. Ipinapasa ang mga karagdagang field ng Jina (task, normalized, truncate, embedding_type). Tinatanggihan pa rin ng mga text-only Jina SKU ang mga non-text na dokumento.
Mga limitasyon sa seguridad at transportasyon:
- Dapat pampublikong HTTPS ang mga remote media URL. Ang mga canonical na
{type,source:url}item ay kinukuha sa server side (muling pag-validate ng redirect, timeout, mga limitasyon sa laki, pampublikong DNS, pag-pin ng koneksyon) at ini-inline bago ang tawag sa provider. Ipinapasa nang ganoon din ang mga Jina-native na{image:"https://..."}item matapos ang parehong pagsusuri sa pampublikong HTTPS; si Jina ang kumukuha ng URL. - Nililimitahan ang inline base64 media sa 8 MiB na decoded bawat item at 16 MiB na decoded sa buong request.
Pagsasalin para sa provider (hindi kailanman ipinapasa nang hindi binabago ang mga canonical item):
- Mga Jina multimodal model: ang bawat top-level item ay nagiging isang object na may modality key (
text/image/audio/video/pdf) gamit ang mga data URI para sa inline media; isang vector bawat top-level item. - Gemini Embedding 2 family: ang isang top-level array ay nagiging isang native na
models/{model}:embedContentrequest na maycontent.parts(textoinline_data). - llama.cpp (
llama-cpp/<model>, anumang model na na-load ng lokal na server): ang mga canonical natextitem ay nagiging mga plain string, at angimage/audio/videoay nagiging tig-isang{"content": [part]}object, gamit ang mga chat content part ng llama-server (image_url,input_audiona may format nawav/mp3/flac,input_video) na may inline data; isang vector bawat top-level item. Dapat tumakbo ang server gamit ang--embedding --mmproj …; kung walang projector, ito mismo ang tatanggi sa media. Hindi sinusuportahan angdocument. - Tinatanggihan ng mga unknown/dynamic model na walang tahasang modality metadata ang structured input gamit ang 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"
}
Ang mga hindi sinusuportahang kombinasyon ng model/modality ay nagbabalik ng HTTP 400 sa halip na piliting i-coerce ang item. Patuloy na ipinapasa nang hindi binabago ang mga non-input extension field sa mga legacy string/token request.
# Ilista ang lahat ng embedding model
GET /v1/embeddings
Pagbuo ng Larawan
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "openai/gpt-image-2",
"prompt": "A beautiful sunset over mountains",
"size": "1024x1024"
}
Kasama sa mga available na provider ang OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana,OpenRouter ,ZenMux , SD WebUI (lokal), ComfyUI (lokal).
ibinabalik n ang mga n na larawan sa data[]. Ang mga provider na ang upstream API ay nagbabalik ng isang larawan sa bawat tawag (Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI) ay nakakakuha ng n na magkakahiwalay na upstream na tawag, hindi hihigit sa 4 sa paglipad. Ang isang nakapirming seed ay na-offset ng call index (seed, seed + 1, …), kaya ang mga imahe ay naiiba ngunit nananatiling reproducible. n ay nililimitahan sa 10. Ang kahilingan ay nabigo sa kabuuan kung ang anumang tawag ay nabigo. Ang listahan ng mga fan-out na format ay SINGLE_IMAGE_FANOUT_FORMATS sa open-sse/handlers/imageGeneration/fanOut.ts.
Muling ginagamit ZenMux ang umiiral nang API-key na koneksyon at tumatanggap ng zenmux/ o zm/ prefix:
zenmux/openai/gpt-image-2ay gumagamit ng ZenMux's OpenAI Images API. Kasama sa mga opsyon angsize,quality,n,output_format,output_compression,background, atresponse_format.- Ang ibang mga publisher, gaya ng
zm/meta/muse-image-1.0, ay gumagamit ng ZenMux's Vertex AI:predictendpoint.nmapa sasampleCount,aspect_ratiosaaspectRatio, atimage_size(1K,2K,4K) sasampleImageSize. Ang isang pixelsizeay nagbibigay lamang ng isang aspect ratio, hindi garantisadong mga dimensyon ng pixel. Ang mga sinusuportahang ratio, resolusyon, at bilang ay nag-iiba ayon sa modelo. - pinipili
zm/inclusionai/ming-image-0.1-designang sarili nitong mga sukat. Alisinsize,aspect_ratio, atimage_size; Ang mga tahasang halaga ay nagbabalik HTTP 400. PNG, JPEG, at WebP ay maaaring hilingin gamit angoutput_format.
Sinusuportahan ng pagsasamang ito ang pagbuo ng text-to-image, hindi ang pag-edit ng reference-image. Ang output ng vertex ay na-normalize sa data[].b64_json; response_format: "url" ay nagbabalik ng upstream HTTPS URL o isang base64 na data URL kapag ang mga byte ng imahe lamang ang magagamit. Ang mga output Empty/filtered ay nagbabalik ng isang error sa halip na isang walang laman na tagumpay. Ang pag-access ng modelo ay depende sa ZenMux account. Tingnan ang ZenMux's Vertex API at OpenAI Images API.
Ang Microsoft 365 Copilot sign-in connection ay nagsisilbi copilot-m365-web/m365-copilot-image sa pamamagitan ng built-in na tool ng imahe ng Copilot: isang Copilot turn sa bawat larawan (n 1–4), size steering lang ang orientation, at mga larawang ibinalik inline (b64_json, o isang data URL para sa response_format: "url"). Tingnan ang Microsoft 365 Copilot.
# List all image models
GET /v1/images/generations
OCR ng Dokumento
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"
}
}
Pinipili ng model ang OCR provider sa pamamagitan ng prefix na provider/model; ang model id na walang prefix (hal.
mistral-ocr-latest) ay nire-resolve sa nakarehistrong provider nito, at ang hindi pagtukoy ng model ay nagde-default sa
Mistral (mistral-ocr-latest). Mga nakarehistrong provider (open-sse/config/ocrRegistry.ts):
| Provider id | Model id | model value |
Mga Tala |
|---|---|---|---|
mistral |
mistral-ocr-latest |
mistral/mistral-ocr-latest (o bare mistral-ocr-latest) |
Synchronous — direktang ibinabalik ang response mula sa iisang upstream call. |
azure-document-intelligence |
prebuilt-read |
azure-document-intelligence/prebuilt-read |
Asynchronous ang upstream (analyze + poll) — tingnan sa ibaba. |
vertex-deepseek-ocr |
deepseek-ocr-maas |
vertex-deepseek-ocr/deepseek-ocr-maas |
Synchronous, sa pamamagitan ng openapi/chat/completions partner endpoint ng Vertex AI — tingnan sa ibaba para sa auth/URL. |
Lahat ng tatlong provider ay tumutugon gamit ang iisang body na hugis-Mistral:
{
"pages": [{ "index": 0, "markdown": "# Extracted text..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
Poll flow ng Azure Document Intelligence
Asynchronous ang analyze API ng Azure Document Intelligence: ang paunang request ay nagbabalik ng
header na Operation-Location sa halip na body, at kailangang i-poll ang resulta. Ang handler
(open-sse/handlers/ocr.ts) ay nagpo-poll sa URL na iyon bawat segundo nang hanggang 30 pagtatangka, mabilis na nabibigo (hindi
nagpapatuloy sa pag-poll) kapag non-ok ang response ng poll o "failed" ang status, at nagbabalik ng 504 kung
tumatakbo pa rin ang operation matapos maubos ang budget ng mga pagtatangka. Ang huling Azure response ay
nino-normalize sa parehong hugis na pages/markdown na ginagamit ng Mistral bago ibalik sa caller, kaya hindi
kailangang gumawa ng espesyal na paghawak ang client code para sa provider.
Auth at pag-resolve ng endpoint para sa Vertex AI DeepSeek OCR
Muling ginagamit ng vertex-deepseek-ocr ang parehong authentication ng Vertex AI na sinusuportahan na ng OmniRoute para sa
chat/image traffic (open-sse/executors/vertex.ts): ang API key ng koneksyon ay maaaring isang kredensyal na
Service Account JSON (ipinagpapalit para sa panandaliang OAuth access token sa pamamagitan ng JWT-bearer
flow) o isang dati nang na-mint na OAuth access token na ginagamit ayon sa pagkakakuha. Ang upstream endpoint URL ay
generic na openapi/chat/completions partner endpoint ng Vertex, na binubuo mula sa project at region ng koneksyon —
palaging mananaig ang tahasang providerSpecificData.project/providerSpecificData.region; kung hindi,
kinukuha ang project mula sa project_id ng Service Account JSON at nagde-default ang region sa us-central1. Parehong
resolution ay nagaganap sa open-sse/handlers/ocr.ts
(resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), at ginagamit ng
src/app/api/v1/ocr/route.ts bago ipadala sa handleOcr.
Ilista ang mga Modelo
GET /v1/models
Authorization: Bearer your-api-key
→ Ibinabalik ang lahat ng chat, embedding, at image model + combo sa format ng OpenAI
Mga presyo ng modelo (pricing)
May dalang object na pricing ang isang entry kapag alam ng OmniRoute ang presyo ng modelo. Ang presyo ay
nagmumula sa talahanayan ng presyo na ginagamit ng cost accounting: mga built-in na default, mga
naka-sync na presyo, at mga override na itinakda sa pamamagitan ng /api/pricing. Mga list price
ang mga ito, kaya nagpapakita rin ang mga subscription provider ng presyo bawat token.
"pricing": {
"prompt": "0.000005",
"completion": "0.000025",
"input_cache_read": "0.0000005",
"input_cache_write": "0.00000625",
"input": 5,
"output": 25,
"cached": 0.5,
"cache_creation": 6.25
}
| Mga field | Unit | Mga tala |
|---|---|---|
prompt, completion, input_cache_read, input_cache_write |
USD bawat token, decimal string | Compatible sa OpenRouter, at hindi kailanman nasa exponent notation. Lumilitaw lamang ang dalawang cache field kapag may presyo ng cache. |
input, output, cached, cache_creation |
USD bawat 1M token, number | Mga field mula sa mga naunang bersyon ng catalog, na pinanatili para sa mga kasalukuyang client. Lumilitaw din ang reasoning at long_context kapag mayroon ang pricing row ng mga ito. |
- Taglay ng mga combo ang presyo ng una nilang nakikitang target. Pumipili ng target sa oras ng
request ang mga built-in na
auto/*combo, kaya wala silangpricing. - Ipinapakita ng mga libreng modelo ang
"0"(at0) kapag zero ang presyo ng mga ito. Ang modelong walang pricing row ay nagpapakita rin ng"0"kapag minamarkahan ito ng catalog bilang libre (free: true) o nakalista ito sa built-in na free-model catalog. - Hindi alam ang presyo: walang
pricingkey ang entry. - Ang mga provider na sinusukat ayon sa credit (tulad ng Kiro) ay naniningil bawat request sa halip na bawat token. Pinananatili ng kanilang mga entry ang numeric per-1M field na mayroon na sila dati at walang dalang per-token string field.
- Kinokopya ng mga variant (mga reasoning-effort id, mga no-thinking alias, at mga discovery at gateway mirror) ang presyo ng modelong dinadaanan nila.
- Mga base rate lamang ang dala ng mga field. Hindi binabago ng mga tier para sa long-context (ang numeric na
long_contextfield) at mga multiplier ng service tier (halimbawa, Codex fast o flex) angpromptocompletion. - Pareho ang object para sa bawat istilo ng authentication, kabilang ang isang Anthropic-style
request na may
x-api-keyatanthropic-version(nananatiling{ "object": "list", "data": [...] }ang response). Implementasyon:src/app/api/v1/models/catalogPricing.ts.
Mga prefix ng model id (?prefix=)
Karamihan sa mga modelo ay ina-advertise gamit ang prefix ng provider. Kinokontrol ng
feature flag na MODELS_CATALOG_PREFIX_MODE kung aling prefix ang makukuha mo, at maaari itong
i-override bawat request gamit ang query parameter — kapaki-pakinabang para sa client na
nais ng malinis na listahan nang hindi binabago ang setting na saklaw ng buong server para sa
lahat:
GET /v1/models?prefix=alias # isang id bawat modelo — ang maikling alias prefix
GET /v1/models?prefix=dual # parehong anyo (default ng server)
GET /v1/models?prefix=canonical # ang buong provider-id prefix lamang
| Mode | Ipinapadala | Mga tala |
|---|---|---|
dual |
cc/claude-sonnet-4-6 at claude/claude-sonnet-4-6 |
Default. Parehong id ang dumadaan sa iisang modelo; pinanatili ang mga ito upang patuloy na gumana ang mga client config na nag-hardcode sa alinman sa mga anyo. Halos nadodoble ang catalog. |
alias |
cc/claude-sonnet-4-6 |
Isang entry bawat modelo. Ipinapadala pa rin ang entry ng mga provider na walang natatanging alias, kaya walang nawawala. |
canonical |
claude/claude-sonnet-4-6 |
Isang entry bawat modelo sa ilalim ng buong provider-id prefix. Ipinapadala rin dito ng mga provider na walang natatanging alias (hal. antigravity/…, agy/…) ang kanilang iisang id, kaya walang nawawala. |
Makikilala rin ang isang mirror na nasa dual mode nang walang query parameter: mayroon itong
parent field na tumuturo sa pangunahing id.
Ang mga client na nagre-render ng model picker ay dapat humiling ng ?prefix=alias — ito ang ginagawa ng
OmniCopilot VS Code extension.
Mga filter sa discovery (?capability=, ?min_context=, ?kind=, ?q=)
Tumatanggap ang GET /v1/models ng mga opt-in na filter para sa discovery. Kung wala ang alinman sa mga ito, hindi nagbabago ang response. Pinapaliit ng mga ito ang catalog na nakikita na ng tumatawag (una munang inilalapat ang mga pahintulot ng API key),
at tumatakbo ang mga ito bago ang paging na limit / after na istilo ng OpenAI:
GET /v1/models?capability=vision&capability=tool_calling # dapat true ang bawat nakalistang capability
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding # catalog na `type`; ang mga row na walang isa ay `chat`
GET /v1/models?q=sonnet&limit=10 # case-insensitive na pagtutugma sa id o name
| Param | Mga value |
|---|---|
capability |
attachment, reasoning, structured_output, temperature, thinking, tool_calling, vision |
min_context |
non-negative integer, ikinukumpara sa context_length |
kind |
chat, audio, embedding, image, moderation, music, rerank, video |
q |
1–200 character |
Ang hindi kilalang value, o isang min_context na hindi non-negative integer (halimbawa, 1.5),
ay nagbabalik ng HTTP 400 at inililista ng mensahe ang mga valid na value. Implementasyon:
src/app/api/v1/models/catalogFilters.ts.
Maikling listahan ng modelo (POST /v1/models/query)
Ang POST /v1/models/query ay nagbabalik ng maikli at deterministic na listahan mula sa parehong catalog, na may parehong
auth at visibility bawat key gaya ng 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 ] }
Opsyonal ang bawat field. Ang capabilities at exclude ay tumatanggap ng array o string na pinaghihiwalay ng kuwit;
ikinukumpara ang max_output sa max_output_tokens. Ang mga resulta ay inaayos ayon sa owned_by, pagkatapos ay id.
Ang default ng limit ay 20 at nililimitahan sa 100 ang mga value na lampas sa 100. Ang invalid na JSON, hindi kilalang
field, o invalid na value ay nagbabalik ng HTTP 400.
Mga indibidwal na nakatagong chat model
Ang modelong minarkahang Nakatago sa pahina ng provider nito ay inaalis sa catalog at tinatanggihan
ng HTTP 404 / model_not_found kapag tahasang hiniling. Ginagamit ng pagsusuri ang naresolbang provider at modelo, kabilang
ang mga alias ng provider, mga prefix ng compatible-provider node, at mga default ng koneksyon. Nilalaktawan ng combo ang mga
nakatagong target at maaaring gumamit ng nakikitang sibling; kapag wala nang natitirang executable target, ibinabalik nito ang
parehong error code. Magkakabisa ang pag-alis sa pagkakatago sa susunod na request. Hindi itinatago ng mga override sa
visibility na pang-image lamang ang chat model na may parehong ID.
Hiwalay ang indibidwal na setting ng modelong ito sa
model exposure allow/deny lists, na nagsasala sa pag-aanunsyo sa catalog
at sa mga kandidato ng auto-routing habang pinananatili ang tahasang dispatch. Patuloy na hiwalay na inilalapat ang
mga pahintulot ng modelo para sa API key. Nanatiling dual ang default na catalog prefix mode.
Mga variant ng modelong walang thinking
Para sa mga Claude model na may kakayahang mag-thinking, nag-aanunsyo rin ang /v1/models ng variant na
walang thinking na ang id ay may prefix na claude-3-omniroute-no-thinking/:
claude-3-omniroute-no-thinking/<provider>/<model>
Kapag pinili ang id na ito (hal., sa isang configuration ng Claude Code na palaging naglalakip ng thinking block),
bumabalik ang resolution sa totoong <provider>/<model> na pinigilan ang reasoning — thinking:{type:"disabled"} sa
/v1/messages path, o inaalis ang mga field na reasoning/reasoning_effort sa
/v1/chat/completions path. Inililista lamang ang variant para sa mga modelong kabilang sa Claude family na sumusuporta sa thinking
at gumagalang sa disabled (kaya, halimbawa, hindi kasama ang mga modelong adaptive-only na tumatanggi sa disabled).
Maaaring pilitin ng mga operator na i-on o i-off ang variant para sa bawat modelo sa pamamagitan ng ModelSpec.noThinkingAlias.
Manifesto ng Provider Plugin
GET /api/v1/provider-plugin-manifest
Ibinabalik ang JSON-safe na manifesto ng provider plugin na ginagamit ng Bifrost, CLIProxyAPI, at mga hinaharap na sidecar router. Binubuo ang tugon mula sa TypeScript provider registry at sadyang hindi kasama rito ang mga OAuth client secret, runtime environment resolution, executor function, request header, at account data.
Gamitin ang endpoint na ito kapag tumatakbo ang isang sidecar nang out-of-process at hindi nito mai-import
nang direkta ang open-sse/config/providerPluginManifestRegistry.ts.
Pagbuo ng audio gamit ang ElevenLabs
Mag-configure ng koneksyon ng elevenlabs provider sa OmniRoute gamit ang iyong ElevenLabs API key.
Nag-a-authenticate ang mga client gamit ang iyong OmniRoute key (Authorization: Bearer $OMNIROUTE_API_KEY);
ibinibigay ng gateway ang nakaimbak na provider key bilang xi-api-key. Huwag kailanman magpadala ng ElevenLabs key
bilang bearer token ng gateway.
| Paraan | Path | Tugon | Kategorya ng endpoint ng API key |
|---|---|---|---|
| POST | /v1/sound-generation |
Mga native na audio byte | elevenlabs |
| POST | /v1/music |
Mga native na audio byte | music |
| POST | /v1/music/stream |
Mga streaming na audio byte | music |
| POST | /v1/music/detailed |
Native na multipart audio at composition plan | music |
| POST | /v1/music/detailed/stream |
Native na SSE metadata at mga audio chunk | music |
| POST | /v1/music/plan |
JSON composition plan | music |
Ang mga endpoint na ito ay karagdagan sa mga umiiral nang route na /v1/audio/speech, /v1/audio/transcriptions,
/v1/voices, /v1/text-to-speech/{voiceId} at /v1/speech-to-text. Pinananatili ang mga native JSON field
at query parameter gaya ng output_format at enable_logging.
Pinananatili ng mga tugon ng /v1/music/detailed ang mga multipart boundary; i-parse ang mga ito bilang multipart.
Nagbabalik ang /v1/music/detailed/stream ng text/event-stream na may composition metadata at
mga base64 audio chunk sa mga SSE event. Sinusuportahan ng lahat ng anim na route ang CORS preflight.
export OMNIROUTE_BASE_URL="http://localhost:20128"
export OMNIROUTE_API_KEY="your-omniroute-api-key"
# Isang maikling sound effect. Tagal: 0.5 hanggang 30 segundo.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/sound-generation?output_format=mp3_44100_128" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"A single soft bell chime","duration_seconds":1,"model_id":"eleven_text_to_sound_v2"}' \
--output effect.mp3
# Ang tagal ng musika ay ipinapahayag sa millisecond: 3000 hanggang 600000.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music?output_format=mp3_44100_128" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Gentle instrumental piano","music_length_ms":10000,"force_instrumental":true,"model_id":"music_v1"}' \
--output music.mp3
Gamitin ang /v1/music/stream kasama ang kaparehong JSON body para sa incremental na paghahatid ng audio. Ang composition
ay tumatanggap ng eksaktong isa sa prompt o composition_plan; kinakailangan ng /v1/music/plan ang prompt
at opsyonal nitong tinatanggap ang source_composition_plan. Pinananatili ng mga native schema ang mga karagdagang
field ng provider upang makarating sa ElevenLabs ang mga bersyon ng composition plan at mga opsyon sa fine-tuning.
Tumatanggap din ang pinag-isang endpoint na /v1/music/generations ng
elevenlabs/music_v1, elevenlabs/music_v2 at elevenlabs/music_v2_5. Kapag may aktibong koneksyon sa ElevenLabs,
inilalantad ang mga modelong ito ng music catalog. Ibinabalik ng endpoint na ito ang
{"created":...,"data":[{"b64_json":"...","format":"mp3"}]}. Ang field nitong duration ay nasa
segundo at itinatapat sa music_length_ms; nangunguna ang tahasang itinakdang music_length_ms.
Itinatapat ang instrumental sa force_instrumental, kung saan nangunguna ang native field.
Gamitin ang mga native streaming endpoint para sa streaming at ang native composition endpoint
para sa mga request na composition plan lamang ang pinagmumulan.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music/generations" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"elevenlabs/music_v1","prompt":"Gentle instrumental piano","duration":10,"instrumental":true}'
Ipinapatupad ang mga paghihigpit sa endpoint, model, budget, at koneksyon bago ang upstream call. Ibinabalik ng mga native
route ang mga status code at error body ng upstream nang hindi binabago, kabilang ang 402 para sa paghihigpit ng plan at
429 para sa limitasyon ng quota. Pinananatili ang mga header na character-cost, song-id, request-id at retry-after
kapag mayroon. Hindi ginagarantiya ng libreng credit balance ang access sa bawat
music model, output format o feature ng API: ElevenLabs ang nagpapasya sa entitlement para sa bawat request.
Pinananatili ng pinag-isang endpoint ang mga error status code sa normalized error envelope ng OmniRoute.
Mga upstream contract: mga sound effect, composition ng musika at mga detalye ng streaming music.
Mga Endpoint ng Compatibility
| Paraan | Path | Format |
|---|---|---|
| POST | /v1/chat/completions |
OpenAI |
| POST | /v1/messages |
Anthropic |
| POST | /v1/responses |
Mga Response ng OpenAI |
| POST | /v1/embeddings |
OpenAI |
| POST | /v1/images/generations |
Mga Larawan ng OpenAI |
| POST | /v1/images/edits |
Mga Larawan ng OpenAI (edit/inpaint) |
| POST | /v1/videos/generations |
Pagbuo ng video na istilong OpenAI |
| POST | /v1/music/generations |
Pagbuo ng musika na istilong OpenAI |
| POST | /v1/audio/transcriptions |
Audio ng OpenAI (STT) |
| POST | /v1/audio/speech |
TTS ng OpenAI (nagbabalik ng audio body) |
| POST | /v1/rerank |
Rerank na istilong Cohere/Voyage |
| POST | /v1/classify |
Jina classify (api.jina.ai) |
| POST | /v1/segment |
Jina segmenter (segment.jina.ai) |
| POST | /v1/moderations |
Mga Moderation ng OpenAI |
| GET | /v1/models |
OpenAI |
| POST | /v1/models/query |
Piniling listahan ng model na na-filter |
| 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 ng catalog ng OpenAI |
| GET | /api/v1/vscode/{token}/models |
Alias ng mga model ng OpenAI |
| POST | /api/v1/vscode/{token}/chat/completions |
Alias ng OpenAI na may token |
| POST | /api/v1/vscode/{token}/responses |
Alias ng OpenAI Responses na may token |
| POST | /api/v1/vscode/{token}/api/chat |
Alias ng Ollama na may token |
| GET | /api/v1/vscode/{token}/api/tags |
Alias ng mga tag ng Ollama na may token |
Pare-pareho ang hugis ng lahat ng POST route: Bearer your-api-key + JSON body na na-validate ng Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema, at iba pa; tingnan ang src/shared/validation/schemas.ts). Ibinabalik ang 4xx kapag nabigo ang schema.
Para sa mga client na hindi makapagdagdag ng Authorization: Bearer ..., tumatanggap din ang OmniRoute ng mga API key sa URL sa pamamagitan ng query-string compatibility (?token=..., ?apiKey=..., ?api_key=..., ?key=...) o ng nakalaang mga endpoint na /api/v1/vscode/{token}/... na nakadokumento sa ibaba.
# Rerank (provider mula sa cloud registry, o isang node ng provider na compatible sa OpenAI bilang "<prefix>/<model>")
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Jina classify (mga kredensyal ng Foundation API)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Jina segmenter
POST /v1/segment { "content": "...", "return_chunks": true }
# Jina search (s.jina.ai; mga alias ng provider: jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Mga moderation
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — nagbabalik ng audio/mpeg (o ang hinihinging format) na body
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# Nangangailangan ang Soniox TTS ng wika at boses: ang `language` ay default na "en"; ang nawawalang
# boses o pangalan ng stock voice ng OpenAI (alloy, nova, …) ay nagiging "Adrian"
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }
# Pag-edit ng larawan (multipart)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# Pagbuo ng video / musika (provider-prefixed na model id)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "kie/suno-v4.0", "prompt": "..." }
Mga node ng provider para sa rerank: Ang
POST /v1/rerankay nagre-route din sa mga node ng provider na compatible sa OpenAI (oMLX, vLLM, Infinity, TEI sa likod ng gateway, …) na tinutukoy bilang<node-prefix>/<model>. Palaging kwalipikado ang mga loopback node (localhost,127.0.0.1,172.16.0.0/12), gayundin ang mga hostname na inilista ng operator saOMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS(hal., pangalan ng serbisyo sa Docker/Compose gaya nghttp://reranker:8080/v1; direktang tinatawagan ang mga ito, hindi kailanman sa pamamagitan ngHTTP(S)_PROXYo ng naka-pin na proxy ng isang koneksyon). Ang mga node sa iba pang host — isang LAN box o Tailscale peer — ay kwalipikado lamang kapag pinagana ng operator ang feature flag naRERANK_REMOTE_PROVIDER_NODESat pumapasa ang base URL ng node sa outbound URL policy ng provider (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS/OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS). Tinatawagan ng memory engine ang rutang ito sa pamamagitan ng loopback sa hakbang na rerank, kaya ang parehong patakaran ang namamahala sarerankProviderModelsa mga setting ng Memory.Mga anyo ng lokal na server: Tinatawagan ang node sa
<base>/v1/rerankat, kapag 404, sa<base>/rerank(Infinity, TEI). Parehong spelling ng Cohere/OpenAI (documents,return_documents) at spelling ng TEI (texts,return_text) ang dala ng upstream body, at ang tugon mula sa upstream ay ginagawang pare-pareho sa Cohere envelope: ang bare na[{index, score, text}]ng TEI,{results: [{index, score}]}mula sa mga thin gateway, at ang Voyage-style na{data: [...]}ay ibinabalik sa client bilang{results: [{index, relevance_score, document?}]}, inayos ayon sa score at nilimitahan satop_n.
Pagtuklas ng mga node ng provider: Lumilitaw ang mga modelo sa isang provider node na compatible sa OpenAI sa
GET /v1/modelssa ilalim ng prefix ng node. Ang mga row na walang metadata ng endpoint (karaniwan sa mga lokal na listing ng/v1/models) ay nagmamana ngapiTypeng node, kaya ang mga modelo ng node naembeddingsay nagigingtype: "embedding"at ang mga modelo ng node narerankay nagigingtype: "rerank"sa halip na maging chat bilang default; mananaig pa rin ang isang tahasangsupportedEndpointssa isang naka-sync o manu-manong idinagdag na row.
Mga Dedicated na Ruta ng Provider
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
Awtomatikong idinadagdag ang prefix ng provider kapag wala ito. Nagbabalik ng 400 ang mga modelong hindi tugma.
Files API
Endpoint ng files na compatible sa OpenAI para sa batch input/output at mga upload na may layunin ng file.
| Method | Path | Description |
|---|---|---|
| POST | /v1/files |
Mag-upload ng file (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — maximum na 512 MiB |
| GET | /v1/files |
Ilista ang mga file para sa naka-authenticate na API key |
| GET | /v1/files/[id] |
Kunin ang metadata ng isang file |
| DELETE | /v1/files/[id] |
Mag-delete ng file |
| GET | /v1/files/[id]/content |
I-stream pabalik ang raw file body |
Auth: Bearer API key — ang mga file ay naka-scope sa bawat API key sa pamamagitan ng getApiKeyRequestScope. Isang key lamang ang
makakakita, makakapag-download, at makakapag-delete ng sarili nitong mga file; ang isang dashboard session na walang key ay makakabasa sa
buong instance; ang isang file na walang owner (na-upload nang anonymous o sa pamamagitan ng dashboard session) ay hindi maaaring ma-access ng
anumang caller na hindi session. Tinatanggihan ng GET /v1/files ang anonymous caller — at ang ipinakitang key na
hindi ma-resolve — gamit ang 401 kahit REQUIRE_API_KEY=false, sa halip na ilista ang mga file ng bawat tenant
(GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).
Batches API
Pagproseso ng batch na compatible sa OpenAI.
| Method | Path | Description |
|---|---|---|
| POST | /v1/batches |
Gumawa ng batch — bina-validate ang body ng v1BatchCreateSchema (input_file_id, endpoint, completion_window) |
| GET | /v1/batches |
Ilista ang mga batch |
| GET | /v1/batches/[id] |
Kunin ang status ng batch at ang request_counts |
| DELETE | /v1/batches/[id] |
Mag-delete ng natapos o nabigong batch |
| POST | /v1/batches/[id]/cancel |
Kanselahin ang kasalukuyang isinasagawang batch |
Auth: Bearer API key. Ang mga batch ay naka-scope sa bawat API key ayon sa parehong tatlong-daan na panuntunan tulad ng
files: sariling key lamang, dashboard session na sakop ang buong instance, at ang mga record na walang owner ay hindi maaaring ma-access ng
anumang caller na hindi session (retrieve, delete, cancel, at ang pagsusuri ng input_file_id sa create).
Tinatanggihan ng GET /v1/batches ang anonymous caller gamit ang 401 kahit REQUIRE_API_KEY=false.
Hanapin API
Web/search provider abstraction (Tavily, Brave, Exa, Serper, atbp.).
| Pamamaraan | Daan | Paglalarawan |
|---|---|---|
| GET | /v1/search |
Ilista ang mga naka-configure na search provider + na kakayahan |
| POST | /v1/search |
Magpatakbo ng query sa paghahanap — body na napatunayan ng v1SearchSchema, sumusuporta sa caching/coalescing |
| GET | /v1/search/analytics |
Bawat provider hit/latency/cache stats |
Awth: Tagadala ng API key (extractApiKey + isValidApiKey). Ipinatupad ang patakaran sa paghahanap sa pamamagitan ng enforceApiKeyPolicy.
Auto-select: nang walang provider, ang pinakamurang provider na may naka-configure na koneksyon ay tumatakbo muna at ang susunod na pinakamurang ay ang failover. Ang mga libreng last-resort provider (duckduckgo-free) ay ginagamit lamang kapag wala nang iba pang naka-configure. Ang isang self-hosted SearXNG ay binibilang bilang na-configure kapag ang koneksyon nito ay nag-imbak ng isang tunay baseUrl (hindi ang catalog default http(s) http://localhost:8888/search): ito ay nagraranggo bilang isang $0 na provider na nangunguna sa mga naka- baseUrl, na ang pinakamurang naka-key na URL bilang failover, kabilang ang kapag SearXNG ay sumagot ng 400, 401, 403 o 404. hindi mabilang. Ang koneksyong SearXNG na nag-iimbak ng token ay nasa ganitong paraan lamang sa https:// o loopback http://. Sa malayuang plain http:// hindi ito isang failover at nananatiling huling paraan, ginagamit lamang kapag walang ibang provider ang na-configure o kapag hiniling sa pamamagitan ng pangalan, kaya ipinapadala nito ang token sa cleartext sa dalawang sitwasyong iyon.
Exa at Tavily provider_options
Binabasa ng Exa at Tavily ang mga field na partikular sa provider mula sa isang namespaced na bag: provider_options.exa (o provider_options["exa-search"]) at provider_options.tavily (o provider_options["tavily-search"]). Ang mga susi lamang sa ibaba ang ipinapasa. Ang bawat isa ay sinusuri laban sa sarili nitong Zod schema sa open-sse/handlers/search/providerOptionsPassthrough.ts, at ang isang susi na may maling uri ay nahuhulog. Anumang iba pang susi ay binabalewala, kabilang ang auth, base URL, stream at outputSchema. Ang mga flat key na ginagamit ng ibang mga provider (cx, depth, ...) ay gumagana tulad ng dati.
| Provider | Mga patlang sa pinakamataas na antas | Nested |
|---|---|---|
| Exa | type, category, userLocation, moderation, additionalQueries, objective, systemPrompt, compliance (flat primitives), startPublishedDate, endPublishedDate |
Pinagsama contents.{text, highlights, summary, extras, livecrawlTimeout, maxAgeHours} sa 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 |
— |
Palaging panalo ang mga generic na field: query, max_results, filters (mga domain), country at ang paksang hinango mula sa search_type. Sa Exa, pinapanatili ng search_type: "news" category: "news". Tumatanggap din ang Tavily search_type: "finance" (topic: "finance").
Ang gastos sa paghahanap ng Firecrawl ay naitala sa bawat panimulang bloke ng 10 ibinalik na mga resulta, sa $0.002 (2 credits) isang bloke at hindi bababa sa isang bloke bawat tawag ( Firecrawl billing ): Ang 11 resulta ay nagkakahalaga ng $0.004.
Naabot na ngayon ng generic time_range ang parehong provider: Ang Exa ay nakakakuha ng startPublishedDate (ISO timestamp) at Tavily ay nakakakuha ng start_date (YYYY-MM-DD). Ino-override ng isang tahasang petsa sa provider_options ang naka-map.
Ang mga resulta ng Exa ay nagpapanatili id, highlights (bawat highlight, hindi lamang ang unang ginamit bilang snippet), highlight_scores, summary, subpages, entities at extras sa provider_raw. Ang mga resulta ng Tavily ay nagpapanatili images at favicon.
Ang gastos sa paghahanap ng linkup ay naitala sa $0.005 para sa depth fast at standard at $0.05 para sa deep ( Pagpepresyo ng linkup ), kung depth ay nanggaling sa provider_options o sa mga setting ng koneksyon.
Ang Exa type: "lite" (Exa 3.0) ay tumatanggap ng mas maliit na hanay ng mga field at tinatanggihan ang buong kahilingan kapag nakatakda ang anumang ibang field. Para sa lite, additionalQueries, systemPrompt at bawat contents key maliban text at highlights ay ibinababa bago ang tawag. Ang hindi na ginagamit na subpages, subpageTarget, highlights.numSentences at highlights.highlightsPerUrl ay hindi na naipapasa.
Ang cost accounting ay ang flat registry costPerQuery, maliban sa Exa, na sumusunod sa sariling pagpepresyo ng Exa: $0.007 bawat tawag para sa auto (at ang legacy fast) o $0.004 para sa lite (at ang legacy instant), na sumasaklaw sa 10 resulta; $0.001 para sa bawat karagdagang resulta; at $0.001 bawat ibinalik na resulta kapag itinakda ang contents.summary. Ang Tavily ay naitala sa 1 credit ($0.008) para sa search_depth basic, fast at ultra-fast, at 2 credits ($0.016) para sa advanced ( Tavily API credits ). Ang isang tawag na may auto_parameters: true na ina-upgrade ni Tavily sa advanced ay naitala pa rin sa 1 credit.
Web Fetch API
Mag-extract ng content mula sa isang URL sa pamamagitan ng naka-configure na web-fetch provider (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract).
Ang Parallel Extract (parallel-search, kaparehong API key ng Parallel Search) ay nagbabalik ng Markdown
lamang — anumang ibang format ay nagreresulta sa 400 — at nililimitahan ang content sa 100,000 character. Kapag hindi ma-extract ang target page mismo, iniuulat ito ng upstream sa loob ng HTTP 200;
ipinapakita iyon ng OmniRoute bilang 422 na may nakapirming mensahe.
| Method | Path | Description |
|---|---|---|
| POST | /v1/web/fetch |
Mag-fetch/mag-scrape ng URL — bina-validate ang body ng v1WebFetchSchema |
Auth: Bearer API key (extractApiKey + isValidApiKey). Ipinapatupad ang policy sa pamamagitan ng enforceApiKeyPolicy.
Quota-aware fallback (#8297): kapag walang ibinigay na tahasang provider, nilalakbay ang pool
(firecrawl → jina-reader → tavily-search → tinyfish → nimble-search →
parallel-search) sa nakapirming
priority order (fill-first) — nilalaktawan ang provider na may rate limit ngunit naka-configure
sa halip na agad wakasan ang request, at ang isang retryable/quota upstream failure
(HTTP 429 palagi; 402/403 para sa mga quota-style free tier ng Firecrawl/Tavily/TinyFish —
hindi para sa Jina Reader, at hindi kailanman para sa simpleng 400 na bad request) ay ipinapasa sa
susunod na hindi pa nasusubukang credentialed provider sa oras ng request. Kapag naubos ang lahat ng provider sa pool, nagbabalik ang endpoint ng isang 429 (na may Retry-After
header) sa halip na dating generic na 400. Kapag tahasang hiniling ang provider, walang
silent fallback — ipinapakita ng pumalya o na-rate-limit na tahasang provider ang sarili nitong error (429 kung rate-limited, kung hindi ay ang upstream status).
WebSocket Streaming
GET /v1/ws?handshake=1
Bine-validate ang WebSocket upgrade handshake at ibinabalik ang mga halimbawang mensahe ng wire protocol (request, cancel). Ang aktuwal na WS frames ay pinangangasiwaan ng bundled WS server sa labas ng Next.js route table.
Auth: Bearer API key habang isinasagawa ang handshake.
Responses API sa WebSocket (codex lamang)
# Parehong host:port ng HTTP API (default 20128); i-upgrade ang koneksyon:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (o: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
# DAPAT na response.create ang unang frame:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
Ang Responses-API-over-WebSocket proxy ay eksklusibong nakakabit sa codex (ChatGPT
backend). Nakikinig ito sa parehong port ng API/dashboard sa mga path na /v1/responses,
/responses, at /api/v1/responses. Sa unang response.create frame, nag-a-authenticate ito at naghahanda sa pamamagitan ng internal na codex-responses-ws bridge, pumipili ng codex OAuth connection, at nagtu-tunnel sa wss://chatgpt.com/backend-api/codex/responses
gamit ang wreq-js transport. Tinatanggihan ang mga non-codex model (codex_ws_provider_required).
Para sa quota-share routing, gamitin ang model: "qtSd/<group>/codex/<model>". Ipinatupad ito sa
app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.
Auth: Bearer API key habang isinasagawa ang handshake. Dapat na aktibong entrypoint ang bundled HTTP server (server-ws.mjs)
(ito ang default kapag umiiral ang app/server-ws.mjs).
Model id: gamitin ang bare ChatGPT id (walang codex/ prefix)
Bine-validate ng OpenAI Codex CLI ang pangalan ng model sa client-side kapag
supports_websockets = true at tinatanggihan ang provider-prefixed id gaya ng
codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Ipadala ang bare id (hal. gpt-5.5). Codex-only ang bridge ng OmniRoute, kaya muli nitong nireresolba ang bare id bilang codex model
(resolveCodexWsModelInfo) bago mag-tunnel upstream — kahit na ang bare na gpt-5.5 ay kung hindi man ay mairuruta sa ibang provider sa HTTP.
Pag-configure sa OpenAI Codex CLI
Ituro ang Codex CLI sa OmniRoute sa pamamagitan ng pagdaragdag ng custom provider na may WebSocket
support sa ~/.codex/config.toml (gumamit ng hiwalay na CODEX_HOME upang maiwasang galawin ang umiiral na config):
model = "gpt-5.5" # bare id — HINDI "codex/gpt-5.5"
model_provider = "omniroute"
[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1" # walang trailing slash; awtomatikong hinango ang WS URL (gumamit ng https/wss sa production)
wire_api = "responses" # tanging suportadong value mula Peb 2026
supports_websockets = true # pinapagana ang Responses-over-WS transport
env_key = "OMNIROUTE_API_KEY" # naglalaman ng OmniRoute API key (Bearer)
export OMNIROUTE_API_KEY=sk-... # isang OmniRoute API key (anumang key kung REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
Ina-upgrade ng CLI ang base_url + /responses bilang WebSocket at tina-tunnel ito ng OmniRoute
sa napiling codex OAuth connection. Na-validate ito end-to-end laban sa lokal na server: ibinabalik ng ChatGPT ang
codex.rate_limits + response.created at sini-stream ang completion.
Pag-uulat ng Mga Quota at Isyu
| Paraan | Path | Paglalarawan |
|---|---|---|
| GET | /v1/quotas/check |
Paunang pagpapatunay ng quota para sa provider + accountId bago mag-isyu ng nakarehistrong key |
| POST | /v1/issues/report |
Iulat sa GitHub ang pagkabigo sa pag-isyu ng quota/key (nangangailangan ng GITHUB_ISSUES_REPO + token) |
Auth: Bearer API key (isAuthenticated).
Pagbawi ng quota session (opsyonal)
Ang isang non-streaming na POST /v1/chat/completions o POST /v1/responses na nabigo dahil sa
terminal quota error (402/429/503 na ang body ay nagsasabing naubos na ang quota o credits)
ay maaaring iparada at i-replay sa ibang pagkakataon sa halip na ibalik ang error. Nag-o-opt in ang
caller sa bawat request gamit ang tatlong header:
| Header | Halaga |
|---|---|
x-omniroute-quota-recovery |
auto |
x-omniroute-session |
session id, [A-Za-z0-9._:-]{1,128} |
x-omniroute-recovery-turn |
turn id na natatangi sa loob ng session (parehong panuntunan) |
Ang mga turn lang na stream: false na walang tools, tool history o previous_response_id, at walang
x-omniroute-connection pin, ang kwalipikado, at dapat nakatakda ang STORAGE_ENCRYPTION_KEY (ang
request ay naka-store na encrypted nang hanggang 24 na oras). Ang response ay magiging 202 na may
recovery.poll; i-poll ang GET /v1/quota-recoveries/{id} (202 habang nakabinbin, 200 na may
recovered body kapag nakumpleto) o kanselahin gamit ang DELETE. Ang mga ticket ay makikita lamang ng
API key na lumikha sa mga ito. Ang replay na hindi tiyak ang kinalabasan ay nagtatapos sa
needs_confirmation sa halip na maipadala nang dalawang beses. Source: src/lib/quota/quotaSessionRecovery.ts.
Self-service na paggamit (/api/usage/om-usage)
Mababasa ang anumang API key** sarili nito** paggamit at quota — walang management auth. Ito ang endpoint na ginagamit ng isang kliyente (CLI, ang OmniCopilot panel) upang ipakita sa isang key holder ang kanilang paggastos.
# Text form (the historical contract — plain text for a terminal)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# Structured form — what a UI consumes
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
Dapat mayroon ang susi**allowUsageCommand** naka-enable (naka-off bilang default — i-toggle ito ng API-key manager ng dashboard sa bawat key). Kung wala ito ang endpoint ay sumasagot 403.
?format=json ay nagbabalik ng isang discriminated na hugis kaya ang isang tumatawag ay hindi kailanman nagbabasa ng field ng data sa isang pagtanggi. Sa tagumpay:
{
"allowed": true,
// present only when the key opted into per-key usage limits (daily/weekly/5-hour USD):
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// the selected provider quota snapshot, or null when nothing is cached yet:
"provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */} },
// every connection's snapshot, so a UI can render several providers side by side:
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
Sa pagtanggi (401 bad key / 403 not allowed) ang parehong ruta ay nagbabalik ng { "allowed": false, "error": { "message": "…" } } — a present-but-empty personal/provider (key allow, wala pang natutunan) ay ibang estado sa pagtanggi, at ang JSON form lang ang nagpapakilala sa kanila.
Awth: sariling Bearer API key ng tumatawag, na-validate sa isValidApiKey — ito ay hindi ang management surface (/api/keys/…), na nananatili sa likod requireManagementAuth.
Raw vs. Cutoff-Adjusted Quota Porsyento
Kapag gumagamit ng /api/usage/om-usage, dapat tandaan ng mga tumatawag ang pagkakaiba sa pagitan ng mga porsyentong ipinakita ng** plain-text na output** at ang nakabalangkasJSON output :
| Aspeto | Plain-text na format (/api/usage/om-usage / @@om-usage) |
JSON format (?format=json) |
|---|---|---|
| Output field | NN% left (hal., 20% left) |
provider.quotas / providers[].quotas |
| Pagsusukat | Cutoff-adjust na magagamit na allowance : natitirang kapasidad sa itaas ng cutoff threshold | Raw upstream quota : hindi nababagay na pagsukat ng provider |
| Cutoff scaling | Na-scale sa pamamagitan ng effectiveRemainingPercent() kaya ang protektadong reserba ay nagbabasa bilang 0% left |
Wala (mga raw snapshot value gaya ng iniulat ng provider) |
| Threshold data | Isinama sa ipinakitang porsyento | Naka-imbak sa quotaWindowThresholds bawat koneksyon (o mga default ng server) |
| Pangunahing mamimili | Interactive CLIs, terminal prompt, human operator | Mga programmatic na integration, dashboard, analytics, billing tracker |
Ang Cutoff Adjustment Formula
Sinusuportahan ng OmniRoute ang mga proactive na cutoff ng quota para maiwasan ang upstream exhaustion (na-configure sa pamamagitan ng koneksyon quotaWindowThresholds, mga default ng provider, o mga setting ng global resilience). Kapag ang isang cutoff threshold (hal., cutoff = 25%) ay aktibo sa isang quota window, kinakalkula ng text renderer ang natitirang allowance bilang:
- Kung
remaining <= cutoff: nagbabalik ng0%. - Kung
remaining > cutoff: nagbabalik ng((remaining - cutoff) / (100 - cutoff)) * 100.
Ang na-format na output ng text ay iniikot ito sa pinakamalapit na integer (Math.round(...)).
Mapaglarawang Halimbawa
Isaalang-alang ang isang window ng provider na may** 60% raw na paggamit** (kaya** 40% raw ang natitirang quota** ) at isang naka-configure** 25% na natitirang-quota cutoff** threshold:
| Representasyon | Pagkalkula | Natitira | Ipinahiwatig na Ginamit |
|---|---|---|---|
Raw JSON (?format=json) |
Upstream snapshot (quotas[window]) |
40% | 60% |
Format ng teksto (NN% left) |
((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100 |
20% | 80% (kung kinakalkula 100 - remaining) |
- Bakit ipinapakita ng text ang 20% na natitira: Mula sa 40% na pisikal na quota na natitira sa account, 25% ang nakalaan sa patakaran ng cutoff. Ang tumatawag ay mayroon na lamang 15% sa 75% magagamit na headroom na natitira bago huminto ang router sa pagruruta sa koneksyong ito. Tinitiyak ng pag-scale na ang koneksyon ay nagpapahiwatig ng pagkaubos (
0% left) nang eksakto kung kailan titigil ang pagruruta. - Bakit pinapanatili JSON ang mga hilaw na halaga: Ibinabalik ng JSON payload ang eksaktong snapshot ng provider (
UsageSnapshot) para magkaroon ng access ang mga external na tool sa paggamit ng ground-truth upstream atquotaWindowThresholdssa antas ng koneksyon nang walang lossy scaling sa panig ng server.
Patnubay sa Migrasyon ng Consumer
Kung ang isang panlabas na pagsasama (gaya ng isang editor plugin o extension ng ahente) ay dati nang nag-scrap sa text endpoint (NN% left) at nakalkula ang ginamit na porsyento bilang 100 - NN, ang pag-migrate sa ?format=json ay nangangahulugang:
- Ang pagbabasa ng mga hilaw na halaga JSON ay magpapakita** aktwal na upstream na pagkonsumo** (60% ang ginamit sa halimbawa sa itaas).
- Kung nais ng integration na mapanatili ang magagamit na allowance na semantics ng endpoint ng text, masusuri nito ang epektibong natitirang formula sa client-side gamit ang
quotaWindowThresholdspara sa mga override sa antas ng koneksyon.
Semantic Cache
# Kunin ang mga istatistika ng cache
GET /api/cache/stats
# I-clear ang lahat ng cache
DELETE /api/cache/stats
Halimbawa ng response:
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
Epekto sa latency
Ang isang semantic cache HIT ay naghahatid ng response mula sa cache nang walang upstream
call, kaya halos zero ang iniulat na X-OmniRoute-Response-Latency
(anuman ang orihinal na upstream latency). Dapat tingnan ng mga client na sensitibo sa latency
(gaya ng benchmarking at p50/p99 monitoring) ang response header na
X-OmniRoute-Cache-Latency:
| Value | Kahulugan |
|---|---|
synthetic |
Response na inihatid mula sa cache; hindi tunay na upstream time ang latency |
| (absent) | Response mula sa tunay na upstream call |
Pag-bypass ng cache sa bawat key
Maaaring mag-opt out ang mga API key sa mga semantic cache read sa pamamagitan ng cacheDefaultMode:
| Value | Gawi |
|---|---|
legacy |
Karaniwang gawi ng cache (default) |
bypass |
Laktawan nang buo ang cache lookup; palaging mag-hit sa upstream |
Itakda sa paggawa ng key (POST /api/keys) o pag-update (PATCH /api/keys/[id]):
{ "cacheDefaultMode": "bypass" }
Pag-bypass ng cache sa bawat request
Maaaring mag-bypass ng cache ang anumang request anuman ang mga setting ng key:
X-OmniRoute-No-Cache: true
Compatibility sa Pamamahala ng CLIProxyAPI
Sinasagot ng OmniRoute ang tatlong endpoint ng pamamahala ng CLIProxyAPI
na ginagamit ng mga usage dashboard upang basahin ang mga limitasyon ng subscription sa Claude at Codex
(halimbawa, ang cliproxy usage-limit source ng T3 Code). Ituro ang base URL ng client sa
OmniRoute at gumamit ng API key na may manage scope bilang management key nito. Inihahatid ang mga route
sa /v0/management/* at sa /api/v0/management/*.
| Method | Path | Paglalarawan |
|---|---|---|
| GET | /v0/management/auth-files |
Mga Claude at Codex OAuth connection bilang { files: [{ id, auth_index, provider, email, disabled, id_token }] }. Walang token |
| POST | /v0/management/api-call |
Body { auth_index, method, url, header?, data? }. Nagpapadala ng isang pinapayagang request gamit ang token ng account at nagbabalik ng { status_code, body } |
| POST | /v0/management/reset-quota |
Body { auth_index }. Nililinis ang connection cooldown, model lockout at mga Codex per-scope cooldown ng isang account |
- Ang
auth_indexay ang connection id ng OmniRoute. Angproviderayclaudeocodex(mga OAuth connection lamang; hindi nakalista anganthropicAPI-key provider). Para sa Codex, angid_token.chatgpt_account_iday ang nakaimbak na workspace id at angplan_typeang nakaimbak na plan. - Ang
api-callay hindi isang generic proxy. Tumatanggap lamang ito ng ClaudeGET https://api.anthropic.com/api/oauth/usageat CodexGET https://chatgpt.com/backend-api/wham/usage,GET .../wham/rate-limit-reset-creditsatPOST .../wham/rate-limit-reset-credits/consume, at bawat isa ay para lamang sa account ng katugmang provider. Anumang iba pa ay nagbabalik ng403nang hindi kumokontak sa upstream. Hindi pinapansin angAuthorizationheader ng tumatawag (kabilang ang placeholder na$TOKEN$): ini-inject ng OmniRoute ang access token ng connection, nire-refresh muna ito kapag malapit nang mag-expire, at ipinapasa lamang ang mga pinapayagang header (anthropic-beta;OpenAI-Beta,Originator,Chatgpt-Account-Id;Accept,Content-Type). Kung walangChatgpt-Account-Id, ginagamit bilang default ang nakaimbak na workspace id. Nagta-time out ang mga request makalipas ang 15 segundo at ginagamit ang proxy ng connection. - Iniiwan ng
reset-quotaang mga terminal state (banned, expired, credits_exhausted) na hindi nababago. Ang hindi kilalangauth_indexay nagbabalik ng404.
Auth: dashboard session o API key na may manage scope, na kinakailangan kahit naka-disable ang login
(nasa ALWAYS_PROTECTED_API_PATHS ang mga path). Nagkakakuha ng 403 ang mga key na para lamang sa inference. Source:
src/lib/cliproxyCompat/managementApi.ts.
Dashboard at Pamamahala
Ang mga ruta ng pamamahala (/api/* maliban sa pampublikong auth/login) ay** hindi** pinahintulutan ng ordinaryong inference API key. Mga pamilya ng kredensyal, saklaw, at mga halimbawa ng curl: Pagpapatunay ng Pamamahala.
Authentication
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/auth/login |
POST | Mag-login |
/api/auth/logout |
POST | Mag-logout |
/api/settings/require-login |
GET/POST | Katayuan sa pag-login (GET, pampubliko). itinatakda ng POST ang password / toggles login: operator-only once na may password (dashboard session, local CLI, o login disabled — API keys at oma_ token get 403); ang isang dashboard session ay nagpapadala ng currentPassword upang palitan ang password |
Pamamahala ng Provider
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/providers |
GET/POST | Maglista / gumawa ng mga provider |
/api/providers/[id] |
GET/PUT/DELETE | Pamahalaan ang isang provider |
/api/providers/[id]/test |
POST | Subukan ang koneksyon ng provider |
/api/providers/[id]/models |
GET | Maglista ng mga modelo ng provider |
/api/providers/validate |
POST | I-validate ang config ng provider |
/api/providers/bulk |
POST | Maramihang magdagdag ng mga API key para sa provider ONE |
/api/providers/import |
POST | Mag-import ng magkakaibang provider LIST mula sa na-parse CSV/JSON file (#6836); per-row partial-failure na mga resulta |
/api/provider-nodes* |
Iba't-ibang | Pamamahala ng node ng provider |
/api/provider-models |
GET/POST/PUT/PATCH/DELETE | Mga custom na modelo at mga override sa bawat modelo (idagdag, i-update, hide/show, tanggalin) |
/api/provider-models/validate-and-add |
POST | Pamamahala-authenticated, opt-in mahigpit na koneksyon validation at atomic custom-modelo pagpaparehistro; tingnan ang pagpapatunay ng modelo |
Para sa mga modelong synced/imported, tinatanggap ng PUT /api/provider-models provider, modelId, at maxOutputTokenOverride: isang positive integer ang nagtatakda ng manu-manong output-token cap, at ki-clear ito null para ibalik ang default. ibinabalik GET /api/provider-models?provider=<provider> ang mga value na ito sa modelOutputOverrides, kabilang ang mga modelong walang custom-model row. Ang override ay gumagamit ng runtime max_output_tokens na kakayahan at nakakaligtas sa isang muling pag-sync ng modelo. Ang pahina ng provider na katugma sa OpenAI ay nag-aalok ng parehong edit/clear na kontrol at pagmamarka ng mga modelo na may tahasang suporta sa paningin.
Sa isang katugmang node ng provider, iniimbak ng mga write path (POST, PUT, PATCH, DELETE at /api/provider-models/validate-and-add) ang modelong id bilang hubad na upstream id: ang isang id na na-paste mula sa isang prefix na listahan ay may anumang nangungunang stack ng sariling prefix ng node na na-collapse, at ang mga tugon ay nag-echo sa nakaimbak na id. Ang mga naka-slash na id ng Canonical providers (hal. nvidia/nemotron-…) ay iniimbak ng verbatim. /v1/models ay hindi kailanman naglalabas ng nakasalansan na <prefix>/<prefix>/<model> id.
Ang mga node ng Custom na Pagkumpleto ng Chat ay iniangkop ang mga tahasang pag-opt-out sa pangangatwiran sa upstream na backend. Awtomatikong pinipili ng matagumpay na pagsubok sa koneksyon ang mga kontrol sa chat-template para sa bawat eksaktong modelong ID na ang /models entry ay nagpapatunay ng kinikilalang halaga owned_by : vllm, sglang, o llamacpp. Maaaring mapanatili ng mga transparent na wrapper na tugma sa OpenAI ang orihinal na entry ng modelo sa loob ng isang nested openai object; ang pagtuklas ay sumusunod hanggang sa tatlong ganoong sobre. Ang mga modelong may nawawala, hindi alam, o sumasalungat na pagmamay-ari ay nagpapanatili ng ordinaryong OpenAI na gawi. Muling ginagamit ng Detection ang kasalukuyang kahilingan sa catalog, hindi bumubuo ng mga token sa pagkumpleto, at hindi wasto kapag nagbago ang endpoint ng koneksyon.
Upang i-pin ang gawi para sa isang backend na hindi naglalantad sa metadata na iyon, gamitin ang kasalukuyang bahagyang update ng provider API:
{
"providerSpecificData": {
"reasoningControl": "chat-template"
}
}
Ipadala ang katawan na iyon gamit ang PUT /api/providers/<connection-id>. Sa koneksyon na iyon, ang isang tahasang pagsisikap sa pangangatwiran ng none ay ipinapadala bilang chat_template_kwargs.thinking=false at chat_template_kwargs.enable_thinking=false. Ang mga tahasang halaga ng native na template ay nananatiling may awtoridad maliban kung ang isang server-side na panuntunan sa pangangatwiran ay pumipilit ng pagsisikap. Nalalapat lang ang setting kapag ang isang custom na koneksyon na katugma sa OpenAI ay nagpapadala ng katawan ng Mga Pagkumpleto ng Chat; Pinapanatili ng mga kahilingan sa pagtugon at ordinaryong provider ang hugis ng kanilang katutubong kahilingan. Itakda reasoningControl sa openai upang pilitin ang ordinaryong OpenAI reasoning_effort passthrough, o alisin ang it/set sa null upang gumamit ng awtomatikong pag-detect.
Claude Code auto-mode classifier ay humihiling ng default na katutubong pag-iisip na i-disable kapag wala silang mga tahasang kontrol sa pangangatwiran. Ginagamit ng detection ang system marker ng classifier sa mga kahilingan sa format ng Claude, hindi sa mga pangalan ng modelo o mga limitasyon sa pagkumpleto. Ang mga tahasang kontrol sa katawan, suportadong effort/thinking header, mga panuntunan sa pagruruta, at nalutas na pagsusumikap sa modelo ay nagpapanatili sa kanilang kasalukuyang priyoridad. Ang parehong mga yugto ng classifier ay nagpapanatili ng kanilang mga senyas, mga limitasyon sa pagkumpleto, mga pagkakasunud-sunod ng paghinto, at mga tunay na hatol ng pahintulot sa upstream; ang ikalawang yugto ay maaari pa ring gumawa ng hinihiling nitong nakikitang pangangatwiran bilang ordinaryong teksto.
OAuth dumadaloy
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/oauth/[provider]/[action] |
Iba't-ibang | OAuth na partikular sa provider |
Routing at Config
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/models |
GET/PUT | Listahan ng modelo / pag-update ng alyas |
/api/models/alias |
GET/POST | Mga alyas ng modelo |
/api/models/catalog |
GET | Lahat ng modelo ayon sa uri ng provider + |
/api/combos* |
Iba't-ibang | Pamamahala ng combo |
/api/keys* |
Iba't-ibang | API key na pamamahala |
/api/pricing |
GET | Pagpepresyo ng modelo |
Limitado ng modelo ang pinagmulan
GET /api/models?withLimits=1 ( true din ; 0/false o pag-alis dito ay nagpapanatili sa default na payload na hindi nagbabago) ay nagdaragdag ng contextWindow, maxInputTokens, maxOutputTokens at isang capsSource object sa bawat hilera ng modelo. Pinangalanan ng capsSource ang panuntunang nagbigay ng bawat limitasyon, kaya ang nakakagulat na limitasyon (halimbawa, 128k sa isang 1M na modelo) ay maaaring ma-trace sa pinagmulan nito. Ang mga nalutas na halaga ay pareho sa mga ginagamit sa pagruruta; ang bandila ay nagdaragdag lamang ng mga patlang at hindi kailanman nagbabago ng isang halaga. Anumang iba pang halaga withLimits ay tinanggihan ng 400.
halaga capsSource |
Pinagmulan |
|---|---|
override:context |
Patuloy na pag-override sa context-window override (model_context_overrides) |
override:max_input / override:max_output |
Patuloy na pag-override sa kakayahan ng max_input_tokens / max_output_tokens |
static-authoritative:<provider>/<model> |
Static authoritative context-window table |
synced:<provider>/<model> |
models.dev synced capability row |
registry:<provider>/<model> |
Entry sa pagpapatala ng provider |
spec:<model> |
Static modelo spec |
prefix effort-base: |
Row na hiniram mula sa base na modelo ng isang effort-suffixed na variant |
none |
Walang pinagmulan ang nagpahayag ng limitasyon (ang halaga ay null) |
Pagpapatupad: getResolvedModelCapabilitiesWithLimitSources() sa src/lib/modelCapabilities.ts at ang mga precedence chain sa src/lib/modelCapabilityLimits.ts.
Paggamit at Analytics
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/usage/history |
GET | Kasaysayan ng paggamit |
/api/usage/logs |
GET | Mga log ng paggamit |
/api/usage/request-logs |
GET | Mga log sa antas ng kahilingan |
/api/usage/[connectionId] |
GET | Paggamit sa bawat koneksyon |
/api/usage/token-limits |
GET/POST/DELETE | Per-API-key token-limit na mga badyet |
/api/usage/model-latency-stats |
GET | Rolling per-provider/model latency aggregate (avg/p50/p95/p99, rate ng tagumpay); mga filter: windowHours/minSamples/maxRows/provider/model (#6873) |
/api/usage/cache-health |
GET | Prompt-cache na buod ng kalusugan sa call_logs — write/read ratio, p50/p90/p99 write-size distribution, heavy-write concentration, per-model split, at isang healthy/degraded/thrash/no-data na hatol; query params range (1h| 24h| 7d| 30d, default 24h) at opsyonal model (#8827) |
API key na mga pahintulot
Ina-update PATCH /api/keys/{id} ang mga pahintulot ng umiiral nang key. Tulad ng bawat ruta /api/keys* kailangan nito ng pahintulot sa pamamahala (tingnan ang Management Authentication ), hindi isang inference key. Ipadala lamang ang mga field na gusto mong baguhin; ang isang kahilingan na wala sa kanila ay tinanggihan ng No valid fields to update. Ang mga tinanggap na field ay tinukoy ng updateKeyPermissionsSchema sa src/shared/validation/schemas/keys.ts.
| Patlang | Uri | Mga Tala |
|---|---|---|
name |
string, 1-200 character | |
isActive |
boolean | |
isBanned |
boolean | |
expiresAt |
ISO 8601 datetime o null |
nililinis null ang pag-expire |
modelAccessMode |
all | restricted |
Dapat walang laman allowedModels kapag all ang mode |
allowedModels, blockedModels |
hanay ng mga string, hanggang 1000 | |
allowedCombos |
hanay ng mga string, hanggang 500 | Maaaring tumawag ang mga gate na nagsasama ng susi; Ang mga direktang modelo ay pinamamahalaan ng modelAccessMode / allowedModels |
connectionAccessMode |
all | restricted |
allowedConnections ay dapat na walang laman kapag restricted at walang laman kapag all |
allowedConnections |
hanay ng UUIDs, hanggang 100 | |
allowAutoCombos |
boolean | tinatanggihan false ang mga kahilingan para sa mga modelong auto/* na may ganitong key; pinapayagan ang mga key na hindi kailanman nagtakda nito |
catalogScope |
all | combos | models |
Ano ang inilista ng GET /v1/models para sa key na ito (mga combos lang, mga modelo lang, o pareho); hindi nito binabago kung ano ang maaaring tawagin ng susi |
forcedModel |
string hanggang 300 char, o null |
Iruta ang mga kahilingan sa chat sa model/combo na ito, sa X-Route-Model at body.model; nalalapat pa rin ang mga limitasyon ng susi |
noLog, autoResolve |
boolean | |
throttleDelayMs |
integer, 0-300000 | |
maxSessions |
integer, 0-10000 | |
rateLimits |
array ng { limit, window } (positive integers, hanggang 50) o null |
nililimas null ang mga limitasyon |
accessSchedule |
bagay sa iskedyul o null |
nililinis null ang iskedyul |
scopes |
hanay ng mga string, hanggang 32 | |
allowedEndpoints |
hanay ng mga string, hanggang 20 | |
streamDefaultMode |
legacy | json |
|
cacheDefaultMode |
legacy | bypass |
Tingnan ang Per-key cache bypass |
compressionEnabled |
boolean | |
codexServiceMode |
isa sa mga mode ng serbisyo Codex | |
disableNonPublicModels |
boolean | |
allowUsageCommand |
boolean | |
usageLimitEnabled |
boolean | |
dailyUsageLimitUsd, weeklyUsageLimitUsd |
numero >= 0 o null |
|
fiveHourUsageLimitUsd |
numero >= 0 o null |
Rolling 5-hour USD budget, na ipinapatupad tulad ng pang-araw-araw at lingguhang limitasyon (usageLimitEnabled, UNPRICED_USAGE_BUDGET_POLICY). retry-after ay kapag ang pinakamatandang paggastos sa window ay lumampas, na maaaring mag-iwan ng key na lampas sa limitasyon nito na naka-block pa rin. |
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" }'
Mga setting
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/settings |
GET/PUT/PATCH | Pangkalahatang mga setting. Ang mga security-policy key (requireLogin, newPassword, oidc*, corsOrigins, bruteForceProtection) ay nangangailangan ng currentPassword at isang kredensyal ng operator — API key at oma_ token ay nakakakuha ng 403; bawat mutation ay nangangailangan ng admin access-token scope |
/api/settings/proxy |
GET/PUT | Config ng proxy ng network |
/api/settings/proxy/test |
POST | Subukan ang koneksyon ng proxy |
/api/settings/ip-filter |
GET/PUT | IP allowlist/blocklist |
/api/settings/thinking-budget |
GET/PUT | Thinking/reasoning** kahilingan** rewrite mode (passthrough / auto-strip / custom / adaptive). Malaya sa compression. Tingnan ang THINKING_BUDGET.md. |
/api/settings/system-prompt |
GET/PUT | Prompt ng pandaigdigang sistema |
/api/settings/compression |
GET/PUT | Global compression config |
/api/settings/purge-request-history |
POST | I-clear ang mga hilera ng log ng kahilingan at mga lokal na artifact ng call-log |
Konteksto at Compression
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/compression/preview |
POST | I-preview off/lite/standard/aggressive/ultra/RTK/stacked compression |
/api/compression/language-packs |
GET | Ilista ang mga available na pack ng wika ng Caveman |
/api/compression/rules |
GET | Ilista ang metadata ng panuntunan ng Caveman |
/api/context/caveman/config |
GET/PUT | alias ng mga setting na partikular sa Caveman |
/api/context/rtk/config |
GET/PUT | Mga setting na tukoy sa RTK, kabilang ang mga custom na filter at pagpapanatili ng raw-output |
/api/context/rtk/filters |
GET | RTK filter catalog at custom-filter diagnostics |
/api/context/rtk/test |
POST | Patakbuhin ang RTK preview/test laban sa isang text payload |
/api/context/rtk/raw-output/[id] |
GET | Basahin ang nananatiling na-redact na raw na output sa pamamagitan ng pointer id |
/api/context/combos |
GET/POST | Compression combo list/create |
/api/context/combos/[id] |
GET/PUT/DELETE | Compression combo detail/update/delete |
/api/context/combos/[id]/assignments |
GET/PUT | Magtalaga ng mga compression combo sa mga routing combo |
/api/context/analytics |
GET | alias ng compression analytics |
Pagsubaybay
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/sessions |
GET | Aktibong pagsubaybay sa session |
/api/rate-limits |
GET | Mga limitasyon sa rate ng bawat account |
/api/monitoring/health |
GET | Buod ng provider + sa pagsusuri sa kalusugan (catalogCount, configuredCount, activeCount, monitoredCount). Kasama sa view ng pamamahala ang credentialHealth: probe-cache scalars, failedConnections when failed>0, at staleDbNonOkCount (SQLite sticky test_status, hindi ang gauge). Tingnan ang MONITORING_GUIDE.md. |
/api/cache/stats |
GET/DELETE | Mga istatistika ng cache / malinaw |
/api/modality-bridge/stats |
GET | In-memory attempts, mga tagumpay/bridged, mga pagkabigo, mga hit sa cache, totalLatencyMs, latencySamples, sample-denominated averageLatencyMs, at oras ng huling paggamit (i-reset sa pag-restart; pamamahala ng auth) |
/api/modality-bridge/video/runtime |
GET | Mahigpit na pinagkakatiwalaang-loopback check bago pamamahala auth/probe; sanitized FFmpeg/ffprobe availability at mga bersyon (no-store) |
/api/modality-bridge/video/extract |
POST | Panloob na napatotohanan pinagkakatiwalaang-loopback byte broker; 50 MiB input, bounded queue/32 MiB output, 503 capacity, 499 disconnect, 504 deadline; hindi isang pampublikong pag-upload API |
Pag-drill-down ng video frame
Nabasa GET /api/v1/video-bridge/drilldown ang isang opaque na handle na ibinalik sa x-omniroute-video-drilldown pagkatapos ng tahasang pagpayag na kahilingan sa Video Bridge. Ang parehong pagbabasa at DELETE ay palaging nangangailangan ng isang wastong API key at ang independiyenteng pahintulot modalityBridgeVideoDrilldownRemoteEnabled ng operator. Ang pagpapanatili ng produksyon ay nangangailangan din modalityBridgeVideoDrilldownEnabled at mahigpit na per-part drilldown: true. Kung ang key ay may walang laman na endpoint allowlist, dapat itong may kasamang video para sa parehong GET at DELETE, gumagamit man ang tumatawag /v1 o /api/v1.
GET query: kinakailangan handle; opsyonal variant (preview, standard, detail), limit (1–8; tinatanggap ang legacy frames ngunit hindi maaaring pagsamahin sa limit), zero-based na page, at start/end na segundo. Kapag ang parehong mga hangganan ng focus ay ibinigay, end ay dapat na mas malaki kaysa sa start. Ang mga Duplicate/unknown query key ay tinanggihan. Ang mga matagumpay na tugon ay naglalaman ng derivation, durationSeconds, frames, hasMore, page, variant, at opsyonal focusWindow; Ang no-store JSON ay nililimitahan sa 32 MiB kasama ang Base64. Ang sobrang laki ng output ay nagbabalik ng 413; humiling ng mas kaunting mga frame.
ibinabalik ng DELETE /api/v1/video-bridge/drilldown?handle=... { "removed": 0|1 }. Hindi alam, nag-expire at cross-key GETs ay hindi nakikilala 404 mga tugon; hindi maalis ng cross-key DELETE ang entry ng may-ari. Ang disabled na pag-access ay nagbabalik ng 403, missing/invalid authentication 401, mga invalid na query 400, pagkansela 499 at mga pansamantalang error 503. Ang mga handle ay lokal na proseso, mag-e-expire pagkalipas ng sampung minuto, at hindi makakaligtas sa pag-restart. Gumagamit ang mga bagong handle v1. kasama ang isang 32-byte na random Base64URL token; mga token hash lang ang pinananatili. Ang mga legacy na 64-hex na token ay nananatiling syntactically readable para sa compatibility. Tingnan ang mga guardrail ng Video Bridge para sa pahintulot, mga quota at mga detalye ng derivation ng variant.
Backup at Export/Import
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/db-backups |
GET | Ilista ang mga available na backup |
/api/db-backups |
PUT | Gumawa ng manu-manong backup |
/api/db-backups |
POST | Ibalik mula sa isang partikular na backup |
/api/db-backups |
PATCH | I-save ang mga setting ng backup na pagpapanatili (operator-only) |
/api/db-backups |
DELETE | Putulin ang mga naka-imbak na backup sa mga setting ng pagpapanatili (operator-only) |
/api/db-backups/export |
GET | I-download ang database bilang .sqlite file |
/api/db-backups/import |
POST | Mag-upload ng .sqlite file para palitan ang database (?dryRun=true validates lang) |
/api/db-backups/exportAll |
GET | I-download ang buong backup bilang .tar.gz archive |
/api/db-backups/export, /api/db-backups/exportAll at /api/settings/export-json ibigay ang bawat naka-imbak na kredensyal, kaya kailangan nila ang session ng dashboard o ang lokal CLI (o hindi pinagana ang pag-login). API key ng anumang saklaw at oma_ access token ay makakakuha ng 403. Ang mga pagpapanumbalik ay may parehong hangganan: POST /api/db-backups/import (dryRun=true kasama), POST /api/db-backups (ibalik sa pamamagitan ng id) at POST /api/settings/import-json ay palitan ang live na database o mga setting, kaya ang isang kredensyal ng makina ay makakakuha din 403 doon; Ipinapadala ng omniroute sync import ang lokal na kredensyal CLI. Gayon din DELETE /api/db-backups (prune stored backups) at PATCH /api/db-backups (retention settings: ang mga persisted values ay nagtutulak ng awtomatikong pruning pagkatapos ng bawat backup). Ang listahan (GET) at paglikha ng manu-manong backup (PUT) ay nagpapanatili ng ordinaryong pamamahala ng auth.
Cloud Sync
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/sync/cloud |
Iba't-ibang | Mga pagpapatakbo ng cloud sync |
/api/sync/initialize |
POST | Simulan ang pag-sync |
/api/cloud/* |
Iba't-ibang | Pamamahala ng ulap |
Mga lagusan
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/tunnels/cloudflared |
GET | Basahin ang Cloudflare Quick Tunnel install/runtime status para sa dashboard |
/api/tunnels/cloudflared |
POST | Paganahin o huwag paganahin ang Cloudflare Quick Tunnel (action=enable/disable) |
/api/tunnels/ngrok |
GET | Basahin ang ngrok Tunnel runtime status para sa dashboard |
/api/tunnels/ngrok |
POST | Paganahin o huwag paganahin ang ngrok Tunnel (action=enable/disable) |
CLI Tools
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/cli-tools/claude-settings |
GET | katayuan Claude CLI |
/api/cli-tools/codex-settings |
GET | katayuan Codex CLI |
/api/cli-tools/droid-settings |
GET | Katayuan ng Droid CLI |
/api/cli-tools/openclaw-settings |
GET | katayuan OpenClaw CLI |
/api/cli-tools/runtime/[toolId] |
GET | Pangkaraniwang CLI runtime |
Kasama sa mga tugon CLI ang: installed, runnable, command, commandPath, runtimeMode, reason.
ACP Ahente
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/acp/agents |
GET | Ilista ang lahat ng nakitang ahente (built-in na + custom) na may status |
/api/acp/agents |
POST | Magdagdag ng custom na ahente o i-refresh ang detection cache |
/api/acp/agents |
DELETE | Mag-alis ng custom na ahente sa pamamagitan ng id query param |
Kasama sa tugon ng GET ang agents[] (id, pangalan, binary, bersyon, naka-install, protocol, isCustom) at summary (kabuuan, naka-install, notFound, builtIn, custom).
Mga Limitasyon sa Katatagan at Rate
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/resilience |
GET/PATCH | Get/update request queue, connection cooldown, provider breaker, at mga setting ng paghihintay |
/api/resilience/reset |
POST | I-reset ang mga circuit breaker ng provider |
/api/resilience/model-cooldowns |
GET | Maglista ng mga aktibong lockout sa bawat (provider, koneksyon, modelo), pinagsunod-sunod ayon sa natitirang oras |
/api/resilience/model-cooldowns |
DELETE | I-clear ang isang model lockout — body {provider, model} o {all: true} para i-wipe ang lahat |
/api/rate-limits |
GET/POST | Per-account rate limit status (GET) o toggle rate-limit na proteksyon para sa isang koneksyon (POST {connectionId, enabled}). Sinusuportahang write path para sa rateLimitProtection (hindi kailanman binago sa pamamagitan PUT /api/providers/[id]). Tandaan: hindi pinapagana enabled: false ang tahasang proteksyon ngunit hindi nag-o-opt ng aktibong koneksyon sa API-key mula sa pandaigdigang auto-enable na safety net (autoEnableApiKeyProviders). |
/api/rate-limit |
GET | Pangkalahatang pagsasaayos ng limitasyon sa rate (hindi na ginagamit; alias hanggang /api/rate-limits) |
Lahat ng apat na ruta
/api/resilience/*ay nangangailangan** pamamahala ng auth** (requireManagementAuth). Tingnan ang Resilience (extended) para sa kumpletong breakdown ng provider breaker vs connection cooldown vs model lockout.
Evals
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/evals |
GET/POST | Maglista ng mga eval suite / run evaluation |
Mga patakaran
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/policies |
GET/POST/DELETE | Pamahalaan ang mga patakaran sa pagruruta |
Pagsunod
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/compliance/audit-log |
GET | Log ng audit ng pagsunod (huling N) |
v1beta (Gemini-Compatible)
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/v1beta/models |
GET | Maglista ng mga modelo sa Gemini format |
/v1beta/models/{...path} |
POST | Gemini generateContent endpoint |
Ang mga endpoint na ito ay sumasalamin Gemini's API na format para sa mga kliyenteng umaasa sa native Gemini SDK compatibility.
Panloob / System APIs
| Endpoint | Pamamaraan | Paglalarawan |
|---|---|---|
/api/init |
GET | Simulan ang mga serbisyo sa pag-sync sa background (pamamahala ng auth) |
/api/tags |
GET | Mga tag ng modelong katugma sa Ollama (para sa mga kliyente Ollama ) |
/api/restart |
POST | I-trigger ang magandang pag-restart ng server |
/api/shutdown |
POST | Mag-trigger ng magandang pag-shutdown ng server |
/api/system/env/repair |
POST | Ayusin ang mga variable ng environment ng provider OAuth |
/api/system/version |
GET | Current/latest bersyon, i-update ang katayuan, release channel |
/api/system/version |
POST | Magsimula ng update sa deployment-aware sa pinakabagong bersyon |
Tandaan: Ang mga endpoint na ito ay panloob na ginagamit ng system o para sa Ollama client compatibility. Hindi sila karaniwang tinatawag ng mga end user.
OAuth Pag-aayos ng Kapaligiran (v3.6.1 +)
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
Nag-aayos ng nawawala o sira na mga variable ng kapaligiran OAuth para sa isang partikular na provider. Ibinabalik:
{
"success": true,
"repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
"backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}
Bersyon at Channel ng Paglabas
GET /api/system/version
Loopback-only na ruta ng pamamahala (admin auth). Ibinabalik ang tumatakbong bersyon, ang pinakabagong na-publish na bersyon at ang auto-update na katayuan. releaseChannel at channels ay mga additive field (rail 3.8.54); Pinapanatili channel ang kahulugan nito — ang deployment mode na ginagamit ng dashboard updater (npm, source o 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— npm channel ng tumatakbong build:nightlypara sa mga bersyon-nightly.*,nextpara sa iba pang mga pre-release (-rc.*,-beta.*,-alpha.*),ltspara sa isang stable na bersyon ng isang mas lumang major kaysa sachannels.latest, kung hindilatest. Parehong mga panuntunan tulad ngscripts/release/dist-tag.mjs, na pumipili ng npm dist-tag sa oras ng pag-publish.channels— na-publish na head ng bawat dist-tag, mula sanpm view omniroute dist-tags(registry HTTP fallback), naka-cache na may parehong 10 minutong TTL bilanglatest.latestay palaging naroroon (bumalik salatestfield, pagkatapos ay"unavailable");next,nightlyatltsay lilitaw lamang kapag umiiral ang dist-tag na iyon. Ang isangCache-Control: no-cachena kahilingan ay nagre-refresh ng parehong paghahanap.
Ang modelo ng channel (latest = v3 hanggang sa 4.0 GA, next = rc, nightly = develop build, lts = v3 patch pagkatapos ng 4.0 GA) ay inilalarawan sa docs/ops/RELEASE_STRATEGY.md.
Transkripsiyon ng Audio
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
Mag-transcribe ng mga audio file gamit ang anumang naka-configure na STT provider. Pinipili ng unang segment ng path ang native provider (openai/…, deepgram/…). Gumagamit ang mga gateway na muling nag-e-export ng modelo ng ibang vendor ng qualified id
(openrouter/deepgram/nova-3).
Request:
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "file=@recording.mp3" \
-F "model=openai/whisper-1"
Response:
{
"text": "Hello, this is the transcribed audio content.",
"task": "transcribe",
"language": "en",
"duration": 12.5
}
Mga halimbawa ng model id: openai/whisper-1 (nangangailangan ng OpenAI key),
openrouter/deepgram/nova-3 (nangangailangan ng OpenRouter key),
deepgram/nova-3 (nangangailangan ng native Deepgram key). Ang isang bare
deepgram/nova-3 request ay hindi gumagamit ng OpenRouter.
Mga sinusuportahang format: mp3, wav, m4a, flac, ogg, webm.
Gemini Live (gemini/gemini-3.5-transcribe-live): transkripsiyon sa file mode sa pamamagitan ng Gemini Live
WebSocket (nangangailangan ng Gemini API key). Kino-convert ang upload sa 16 kHz mono PCM gamit ang ffmpeg
(na dapat nasa PATH, maliban kung ang file ay isa nang 16 kHz mono PCM WAV), ini-stream sa session, at
ibinabalik ang pinal na text bilang { "text": "..." }. Ipinapasa ang mga opsyonal na language at prompt
form field. Mga limitasyon: ang mga upload na lampas sa 25 MiB o ang na-decode na audio na mas mahaba sa 10 minuto ay
tumutugon ng 413; kapag ang conversion ay tumakbo nang lampas sa 60 s, ihihinto ito at tutugon ng 504. Ipinapadala ang API key
sa x-goog-api-key header lamang, at hindi kailanman sa WebSocket URL.
Compatibility sa Ollama
Para sa mga client na gumagamit ng format ng API ng Ollama:
# Chat endpoint (format ng Ollama)
POST /v1/api/chat
# Listahan ng modelo (format ng Ollama)
GET /api/tags
Awtomatikong isinasalin ang mga kahilingan sa pagitan ng mga internal na format at format ng Ollama.
Mga Tokenized VS Code / Headerless Alias
Gamitin ang mga alias na ito kapag hindi makapag-inject ng Authorization header ang isang integration at kailangang i-embed ang API key sa base URL.
# Alias ng catalog na istilong OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# Mga chat alias na istilong OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Mga alias na istilong Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
Halimbawa:
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"}]}'
Mga tala:
- Muling ginagamit ng mga tokenized alias ang parehong handler gaya ng
/v1/*at/api/tags; nananatiling magkapareho ang mga anyo ng tugon. - Mas mainam ang
Authorization: Bearer ...kapag sinusuportahan ng client ang mga custom header. - Maaaring lumitaw ang mga token na nakabatay sa URL sa mga log ng reverse-proxy, history ng browser, at telemetry sa labas ng OmniRoute. Ituring ang mga ito bilang opsyon sa compatibility, hindi bilang default na mode ng authentication.
Telemetry
# Kumuha ng buod ng latency telemetry (p50/p95/p99 bawat provider)
GET /api/telemetry/summary
Tugon:
{
"providers": {
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
}
}
Badyet
# Kunin ang status ng badyet para sa lahat ng API key
GET /api/usage/budget
# Magtakda o mag-update ng badyet
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"
}
Mga tala sa schema (
setBudgetSchema): Kinakailangan angapiKeyId; dapat na mas malaki sa zero ang kahit isa sadailyLimitUsd,weeklyLimitUsd, omonthlyLimitUsd. Mga opsyonal na field:warningThreshold(0–1),resetInterval(daily|weekly|monthly),resetTime(HH:MM). Ang legacy na anyong{keyId, limit, period}ay nagbabalik ng400 Bad Request.
Mga Limitasyon sa Token
Mga badyet sa token bawat API key (hiwalay sa badyet na batay sa USD sa itaas). Ipinapatupad ang mga ito inline sa request path: kapag umabot sa limitasyon ang kasalukuyang paggamit ng window ng isang key, tatanggihan ang mga request na may 429 Too Many Requests. Maaaring i-scope ang mga limitasyon sa isang partikular na model, isang provider, o ilapat sa buong key gamit ang global; kapag maraming limitasyon ang tumugma sa isang request, mananaig ang pinakahigpit.
# Ilista ang mga limitasyon sa token ng isang key (kasama ang live na paggamit ng window)
GET /api/usage/token-limits?apiKeyId=key-123
# Lumikha o mag-update ng limitasyon sa 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
}
# Mag-delete ng limitasyon sa token ayon sa id
DELETE /api/usage/token-limits?id=tl-abc
Mga tala sa schema (
setTokenLimitSchema): Kinakailangan angapiKeyIdatscopeType(model|provider|global). Kinakailangan angscopeValuemaliban kungglobalangscopeType(hal., isang model id para sa saklaw namodel, o isang provider id para sa saklaw naprovider). Dapat positibong integer angtokenLimit(kino-coerce mula sa string). Opsyonal ang:id(iwanang blangko para lumikha, magbigay para mag-update),resetInterval(daily|weekly|monthly, default namonthly),resetTime(HH:MM), atenabled(default natrue). Pinayayaman ng mga tugon ngGETang bawat limitasyon gamit angtokensUsed,remaining,windowStart,periodStartAt, atnextResetAt. Endpoint ito na kabilang sa management class (sentral na ipinapatupad ng authz pipeline ang pagpapatotoo).
Pagproseso ng Request
- Nagpapadala ang client ng request sa
/v1/* - Tinatawag ng route handler ang
handleChat,handleEmbedding,handleAudioTranscription, ohandleImageGeneration - Nireresolba ang model (direktang provider/model o alias/combo)
- Pinipili ang mga credential mula sa lokal na DB gamit ang pag-filter ayon sa availability ng account
- Para sa chat: sinusuri ng
handleChatCoreang semantic/signature cache at nireresolba ang mga setting ng combo compression - Isinasagawa ang proactive compression bago ang provider translation kapag pinagana (
lite, Caveman, RTK, o stacked) - Nagpapadala ang provider executor ng upstream request
- Isinasalin pabalik ang tugon sa format ng client (chat) o ibinabalik ito nang hindi binabago (embeddings/images/audio)
- Itinatala ang paggamit, compression analytics, at mga log ng request
- Inilalapat ang fallback kapag may mga error ayon sa mga panuntunan ng combo
Buong sanggunian sa arkitektura: ARCHITECTURE.md
Pamamahala ng Combo
Ang mga higher-level routing combo (na naibuod na sa ilalim ng /api/combos*) ay maaari ring i-map nang 1:1 mula sa pattern ng model id, na nagbibigay-daan sa transparent na pag-redirect ng isang OpenAI-style model id patungo sa isang combo.
| Paraan | Path | Paglalarawan |
|---|---|---|
| GET | /api/model-combo-mappings |
Ilista ang lahat ng model→combo mapping |
| POST | /api/model-combo-mappings |
Lumikha ng mapping — body: {pattern, comboId, priority?, enabled?, description?} |
| GET | /api/model-combo-mappings/[id] |
Kunin ang isang mapping |
| PUT | /api/model-combo-mappings/[id] |
I-update ang mga field ng isang umiiral na mapping |
| DELETE | /api/model-combo-mappings/[id] |
Mag-alis ng mapping |
Pagpapatotoo: management session/API key (requireManagementAuth).
Mga Webhook
Mga outbound na subscription ng webhook para sa mga event ng OmniRoute (pagkumpleto ng request, pagkaubos ng quota, pag-ikot ng key, at iba pa).
| Paraan | Path | Paglalarawan |
|---|---|---|
| GET | /api/webhooks |
Ilista ang mga webhook (ang mga secret ay nakamaskara bilang <prefix>...) |
| POST | /api/webhooks |
Gumawa ng webhook — katawan: {url, events?: ["*"], secret?, description?} |
| GET | /api/webhooks/[id] |
Kunin ang isang webhook |
| PUT | /api/webhooks/[id] |
I-update ang url/events/secret/description |
| DELETE | /api/webhooks/[id] |
Alisin ang isang webhook |
| POST | /api/webhooks/[id]/test |
Magpadala ng test payload sa URL ng webhook at ibalik ang status ng delivery |
Pagpapatunay: management session/API key (requireManagementAuth).
Mga Nakarehistrong Key (Awtomatikong Pamamahala)
Ginagamit ng subsystem ng awtomatikong pamamahala ng key upang mag-isyu at magpaikot ng mga API key laban sa isang backing provider/account, na may mga quota bawat araw/oras.
| Paraan | Path | Paglalarawan |
|---|---|---|
| GET | /api/v1/registered-keys |
Ilista ang mga nakarehistrong key (masked prefix lamang) |
| POST | /api/v1/registered-keys |
Mag-isyu ng bagong nakarehistrong key — katawan: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Ibinabalik ang raw key nang isang beses lamang. Nagbabalik ng 429 kapag tinanggihan dahil sa quota. |
| GET | /api/v1/registered-keys/[id] |
Kunin ang metadata ng isang nakarehistrong key (walang raw material) |
| DELETE | /api/v1/registered-keys/[id] |
Bawiin ang isang nakarehistrong key |
| POST | /api/v1/registered-keys/[id]/revoke |
Tiyak na endpoint para sa pagbawi (kapareho ng epekto ng DELETE) |
Pagpapatunay: management session/API key (requireManagementAuth) — kaparehong guard ng /api/keys: isang dashboard session, ang lokal na CLI token, o isang API key na may manage/admin scope; ang mga API key na para lamang sa inference ay nakakakuha ng 403. Tingnan din ang /v1/quotas/check at /v1/issues/report.
Protocol ng mga Agent
Mga gawain ng cloud agent (Claude Code, Codex Cloud, OpenHands, atbp.) na isinasagawa nang malayuan para sa mga user ng OmniRoute.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/agents/tasks |
Maglista ng mga gawain — opsyonal ang ?provider=, ?status=, ?limit= (1–500, default na 50) |
| POST | /api/v1/agents/tasks |
Gumawa ng gawain — bino-validate ang body ng CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Nagbabalik ng 201 na may task envelope |
| DELETE | /api/v1/agents/tasks?id=... |
Mag-delete ng gawain |
| GET | /api/v1/agents/tasks/[id] |
Basahin ang gawain — sabay na nire-refresh ang status mula sa upstream cloud agent kapag nakatakda ang external_id |
| POST | /api/v1/agents/tasks/[id] |
Discriminated action: {action: "approve"}, {action: "message", message}, o {action: "cancel"} |
| DELETE | /api/v1/agents/tasks/[id] |
Mag-delete ng partikular na gawain ayon sa id |
Auth: kinakailangan ang management auth sa bawat method (
requireCloudAgentManagementAuth). Bago ang v3.8.0, hindi authenticated ang mga ito — tingnan ang commit na588a0333para sa breaking change.
# Gumawa ng cloud task ng 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":"..."}}'
Mga Proxy sa Pamamahala
Mga outbound HTTP(S)/SOCKS proxy na maaaring italaga sa mga provider, account, o sa buong system.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/management/proxies |
Maglista ng mga proxy (kapag may ?id=, isa ang ibinabalik; kapag may ?id=&where_used=1, ibinabalik ang assignment graph) |
| POST | /api/v1/management/proxies |
Gumawa ng proxy — bino-validate ang body ng createProxyRegistrySchema |
| PATCH | /api/v1/management/proxies |
I-update ang proxy — bino-validate ang body ng updateProxyRegistrySchema (kinakailangan ang id) |
| DELETE | /api/v1/management/proxies?id=...&force=1 |
Mag-delete ng proxy (gamitin ang force=1 upang alisin ang mga assignment) |
| GET | /api/v1/management/proxies/assignments |
Maglista ng mga assignment — maaaring i-filter ayon sa proxy_id, scope, scope_id; ipasa ang resolve_connection_id=<id> upang i-resolve ang aktibong proxy para sa isang connection |
| PUT | /api/v1/management/proxies/assignments |
Magtalaga — bino-validate ang body ng proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Nililinis ang dispatcher cache |
| PUT | /api/v1/management/proxies/bulk-assign |
Magtalaga nang maramihan — bino-validate ang body ng bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?}) |
| GET | /api/v1/management/proxies/health?hours=24 |
Pinagsama-samang kalusugan ng proxy (mga bilang ng tagumpay/pagkabigo, latency) sa loob ng isang window |
Auth: kinakailangan ang management session/API key sa bawat route (requireManagementAuth).
Ang
POST /api/v1/management/proxies/[id]/assignmentsatPOST /api/v1/management/proxies/[id]/healthna nasa paglalarawan ng task ay pinapangasiwaan ng flat na/assignmentsat/healthroute na ipinapakita sa itaas — walang mga per-id subroute sa codebase.
Katatagan (pinalawak)
Naglalantad ang OmniRoute ng tatlong magkakahiwalay na mekanismo para sa pansamantalang pagkabigo; hinahayaan ng mga management endpoint sa ibaba ang mga operator na basahin at i-override ang mga ito:
| Saklaw | Imbakan ng estado | Basahin | I-reset / i-clear |
|---|---|---|---|
| Breaker ng provider | domain_circuit_breakers + nasa memorya |
/api/monitoring/health |
POST /api/resilience/reset |
| Cooldown ng koneksiyon | rateLimitedUntil sa mga koneksiyon ng provider |
/api/rate-limits, /api/providers/[id] |
(muling pinapagana nang lazy; i-clear sa pamamagitan ng provider PUT) |
| Lockout ng modelo | Registry ng availability ng modelo na nasa memorya | GET /api/resilience/model-cooldowns |
DELETE /api/resilience/model-cooldowns |
Tumatanggap ang PATCH /api/resilience ng mga override para sa breaker ng provider sa ilalim ng providerBreaker.oauth at providerBreaker.apikey. Sinusuportahan ng bawat profile ang degradationThreshold, failureThreshold, at resetTimeoutMs; inilalantad din ang parehong mga field sa Dashboard → Mga Setting → Katatagan.
# I-clear ang lockout ng isang modelo
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"}'
# Burahin ang lahat ng lockout
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
Para sa buong konseptuwal na sanggunian at mga default ng breaker, tingnan ang CLAUDE.md → "Resilience Runtime State" at docs/architecture/RESILIENCE_GUIDE.md.
Queue ng Rate Limit at Pangkaligtasang Mekanismo ng Awtomatikong Pagpapagana
- Sinusuportahang path ng pagsulat: Ang
POST /api/rate-limitsna may body na{"connectionId": "<id>", "enabled": true|false}ang sinusuportahang management endpoint para i-toggle ang proteksiyon ng rate limit para sa isang koneksiyon. Sadyang hindi binabago o tina-toggle ngPUT /api/providers/[id]angrateLimitProtection(#11278). - Semantika ng
enabled: false: Ang pagtatakda ngenabled: falseay nag-aalis ng tahasang proteksiyon para sa koneksiyon, ngunit hindi nito inaalis sa pangkalahatang pangkaligtasang mekanismo ng awtomatikong pagpapagana (autoEnableApiKeyProviders = true) ang isang aktibong koneksiyong API-key. SareconcileEnabledConnections(open-sse/services/rateLimitManager.ts), magkapareho ang kahulugan ngfalseatundefined; nananatiling protektado sa ilalim ng pangkaligtasang mekanismo ng awtomatikong pagpapagana ang mga aktibong koneksiyong API-key na walang tahasang proteksiyon. - Pandaigdigang pag-disable: Para patakbuhin ang mga koneksiyong API-key nang walang mga queue ng rate limit, i-disable sa buong sistema ang pangkaligtasang mekanismo sa pamamagitan ng
RATE_LIMIT_AUTO_ENABLE=false(env) oresilienceSettings.requestQueue.autoEnableApiKeyProviders = false(Mga Setting → Katatagan /PATCH /api/resilience).
Mga Skill
Framework ng skill para sa pagpapalawak ng OmniRoute gamit ang mga custom na executable handler, kasama ang mga integrasyon sa marketplace.
| Paraan | Path | Paglalarawan |
|---|---|---|
| GET | /api/skills |
Ilista ang mga naka-install na skill — maaaring i-filter ayon sa ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, na may pagination |
| GET | /api/skills/[id] |
Kunin ang isang skill |
| PUT | /api/skills/[id] |
I-update ang skill (pangalan, paglalarawan, mode, schema, handler, mga tag) |
| DELETE | /api/skills/[id] |
I-uninstall ang isang skill |
| POST | /api/skills/install |
Mag-install ng skill mula sa isang raw manifest — body: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?} |
| GET | /api/skills/executions |
Ilista ang mga kamakailang execution ng skill (audit trail na may mga input/output/tagal) |
| GET | /api/skills/marketplace?q=... |
Maghanap/listahan ng mga sikat na skill mula sa marketplace ng SkillsMP (nangangailangan ng setting na skillsmpApiKey) |
| POST | /api/skills/marketplace/install |
Mag-install ng skill ayon sa id mula sa SkillsMP |
| GET | /api/skills/skillssh?q=&limit= |
Maghanap sa registry ng skills.sh |
| POST | /api/skills/skillssh/install |
Mag-install ng skill ayon sa id mula sa skills.sh |
Pagpapatunay: session/API key para sa pamamahala. Tumatanggap ang mga route ng paghahanap sa marketplace ng alinman sa auth para sa pamamahala o Bearer API key (isAuthenticated).
Memorya
Persistenteng tindahan ng memoryang pang-usap/pangkaalaman, saklaw bawat API key / session.
| Pamamaraan | Path | Paglalarawan |
|---|---|---|
| GET | /api/memory |
Ilista ang mga memorya — ?apiKeyId=, ?type=, ?sessionId=, ?q=, gamit ang pagination na offset/limit o page/limit |
| POST | /api/memory |
Gumawa ng memorya — vine-validate ng Zod ang body: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?} |
| GET | /api/memory/[id] |
Kunin ang isang memorya |
| DELETE | /api/memory/[id] |
Magtanggal ng isang memorya |
| GET | /api/memory/health |
Kalagayan ng subsystem ng memorya (pagkakakonekta sa DB, backend ng embeddings, status ng vector index) |
Pagpapatunay: management session/API key (requireManagementAuth). Enum ng type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (tingnan ang MemoryType sa src/lib/memory/types.ts).
Server ng MCP
Ang OmniRoute ay may kasamang naka-embed na Model Context Protocol server na may 3 transportasyon (stdio, SSE, streamable-http) at mga saklaw na tool. Binabasa ng mga endpoint ng dashboard sa ibaba ang status/data ng audit at ipinapasa ang mga HTTP transport.
| Pamamaraan | Path | Paglalarawan | |
|---|---|---|---|
| GET | /api/mcp/status |
Heartbeat, transport, online state, huling tawag, nangungunang mga tool, rate ng tagumpay sa loob ng 24 na oras | |
| GET | /api/mcp/tools |
Listahan ng mga MCP tool na may name, description, scopes, phase, auditLevel, sourceEndpoints |
|
| GET | /api/mcp/sse |
Magbukas ng SSE stream para sa SSE transport (nagbabalik ng 503 kung hindi pinagana ang MCP o hindi tugma ang transport) |
|
| POST | /api/mcp/sse |
Magpadala ng JSON-RPC frame sa SSE transport | |
| GET | /api/mcp/stream |
Magbukas ng SSE side ng Streamable HTTP transport (mga mensaheng sinimulan ng server) | |
| POST | /api/mcp/stream |
Magpadala ng JSON-RPC frame sa Streamable HTTP transport | |
| DELETE | /api/mcp/stream |
Tapusin ang isang Streamable HTTP session | |
| GET | /api/mcp/audit |
Mag-query ng audit log — ?limit=, ?offset=, ?tool=, `?success=true |
false, ?apiKeyId=` |
| GET | /api/mcp/audit/stats |
Pinagsama-samang audit stats (mga kabuuan, rate ng tagumpay, average na tagal, nangungunang mga tool) |
Pagpapatunay: sinusunod ng mga sse/stream transport ang partikular na auth surface ng MCP (Bearer API key na may saklaw na mcp); maaaring basahin mula sa dashboard ang mga rutang status/tools/audit* (walang karagdagang pagpapatunay maliban sa pag-abot sa dashboard host).
Ang parehong HTTP transport ay kinokontrol ng
settings.mcpEnabledatsettings.mcpTransport— nagbabalik ng400ang hindi tugmang transport, at nagbabalik ng503ang estadong hindi pinagana ang MCP.
A2A Server
Inilalantad ng OmniRoute ang isang A2A (Agent-to-Agent) JSON-RPC 2.0 endpoint kasama ang isang REST wrapper para sa inspeksyon/paggamit ng dashboard.
JSON-RPC
POST /a2a
Authorization: Bearer your-api-key # opsyonal maliban kung nakatakda ang OMNIROUTE_API_KEY
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "message/send",
"params": {
"skill": "smart-routing",
"messages": [{"role": "user", "content": "Route this coding task"}]
}
}
Mga sinusuportahang method (lahat ay nakadepende sa settings.a2aEnabled):
| Method | Paglalarawan |
|---|---|
message/send |
Synchronous na pagpapatupad ng skill; nagbabalik ng {task, artifacts, metadata} |
message/stream |
Streaming SSE na pagpapatupad ng parehong set ng skill |
tasks/get |
Kinukuha ang task ayon sa taskId |
tasks/cancel |
Kinakansela ang task ayon sa taskId |
Mga built-in na skill: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.
Agent Card
GET /.well-known/agent.json
Ibinabalik ang pampublikong A2A agent card (pangalan, paglalarawan, mga capability, katalogo ng skill, scheme ng authentication) — naka-cache sa publiko sa loob ng 1 oras. Hindi kailangan ng authentication.
Mga REST helper
| Method | Path | Paglalarawan |
|---|---|---|
| GET | /api/a2a/status |
Naka-enable ba ang A2A + mga istatistika ng task + buod ng naka-cache na agent card |
| GET | /api/a2a/tasks |
Maglista ng mga task — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset= |
| POST | /api/a2a/tasks |
(Hindi ipinatupad bilang REST helper — gumawa sa pamamagitan ng JSON-RPC message/send) |
| GET | /api/a2a/tasks/[id] |
Kunin ang isang task |
| POST | /api/a2a/tasks/[id]/cancel |
Kanselahin ang isang task |
Authentication: gumagana ang mga REST helper nang walang management authentication (nababasang ng dashboard); ginagamit ng JSON-RPC /a2a route ang Bearer OMNIROUTE_API_KEY kung na-configure.
Cloud, Evals at Assess
| Method | Path | Paglalarawan | ||
|---|---|---|---|---|
| POST | /api/cloud/auth |
Bine-verify ang isang Bearer key at ibinabalik ang mga naka-mask na koneksyon ng provider + mga alias ng modelo para sa mga client ng cloud sync | ||
| POST | /api/cloud/credentials/update |
Ina-update ang mga naka-encrypt na credential para sa isang provider na naka-sync sa cloud | ||
| POST | /api/cloud/model/resolve |
Nireresolba ang isang lohikal na model id sa isang partikular na provider/model gamit ang lokal na routing table | ||
| GET | /api/cloud/models/alias |
Naglilista ng mga alias ng modelo ayon sa pagkakalantad ng mga ito sa cloud sync | ||
| GET | /api/assess |
Binabasa ang pinakabagong mga kategorya ng assessment (bawat provider/model) | ||
| POST | /api/assess |
Nagpapatakbo ng assessment — katawan: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | /api/evals |
Naglilista ng mga built-in na eval suite + mga pinakabagong run | ||
| POST | /api/evals |
Nagti-trigger ng eval run | ||
| POST | /api/evals/suites |
Gumagawa ng custom na eval suite — bino-validate ang katawan ng evalSuiteSaveSchema |
||
| GET | /api/evals/suites/[id] |
Kinukuha ang isang custom na eval suite |
Authentication: direktang vine-validate ng /api/cloud/auth ang isang Bearer key at ibinabalik ang naka-mask na key at projectId ng bawat koneksyon para lamang sa isang key na may saklaw na manage / admin; nangangailangan ng management session/API key ang iba pang /api/cloud/*, /api/evals/*, at /api/assess route. Gumagamit ang POST ng /api/assess ng validateBody na may discriminated-union scope schema.
Pamamahala ng ACP (Agent Client Protocol)
bilang mga child process. Pinamamahalaan ng mga endpoint na ito ang pagtukoy sa mga ACP agent at pagpaparehistro ng mga custom agent.
| Paraan | Path | Paglalarawan |
|---|---|---|
| GET | /api/acp/agents |
Ilista ang lahat ng kilalang CLI agent (built-in + custom), kasama ang status ng pag-install, bersyon, at binary |
| POST | /api/acp/agents |
Magrehistro ng custom ACP agent o i-refresh ang cache — body: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} o {action: "refresh"} |
| DELETE | /api/acp/agents |
Mag-alis ng custom ACP agent — query param: ?id=<agentId> |
Halimbawa ng tugon (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
}
Pagpapatunay: Nangangailangan ng management session (dashboard na auth_token cookie) o API key na saklaw ng management.
Tingnan ang ACP Framework para sa buong detalye.
Analytics at Observability
Mga real-time analytics endpoint para sa pagsubaybay sa routing, compression, at pagkakaiba-iba ng provider. Pinapagana ng mga ito ang mga pahina sa /dashboard/analytics/*.
Analytics ng auto-routing
| Paraan | Path | Paglalarawan |
|---|---|---|
| GET | /api/analytics/auto-routing |
Pinagsama-samang istatistika ng auto-routing: kabuuang mga tawag, distribusyon ng strategy, distribusyon ng tier, mga pangunahing provider |
| GET | /api/analytics/auto-routing?days=7 |
Mga istatistikang nakabatay sa saklaw ng oras (default na 24h) |
Halimbawa ng tugon:
{
"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 }
]
}
Analytics ng compression
| Paraan | Path | Paglalarawan |
|---|---|---|
| GET | /api/analytics/compression |
Pinagsama-samang istatistika ng compression: mga token na natipid, porsyento ng natipid, distribusyon ng mode, paggamit ng engine |
Halimbawa ng tugon:
{
"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
}
}
Pagsubaybay sa pagkakaiba-iba ng provider
| Paraan | Path | Paglalarawan |
|---|---|---|
| GET | /api/analytics/diversity |
Pagsubaybay sa pagkakaiba-iba batay sa Shannon entropy: pinipigilan ang mga single point of failure sa pamamagitan ng pagsukat sa distribusyon ng mga provider |
Halimbawa ng tugon:
{
"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"]
}
Pagpapatunay: Nangangailangan ng management session o API key na saklaw ng management.
Mga Operasyong Pang-admin
Mga endpoint na para lamang sa admin para sa pamamahalang operasyon.
| Paraan | Path | Paglalarawan |
|---|---|---|
| GET | /api/admin/concurrency |
Basahin ang kasalukuyang limitasyon ng concurrency (global + bawat provider) |
| POST | /api/admin/concurrency |
I-update ang mga limitasyon ng concurrency — body: {global?: number, perProvider?: Record<string, number>} |
Pagpapatotoo: Nangangailangan ng management session na may saklaw na admin.
Pamamahala ng CLI Tools
Pamahalaan ang mga CLI tool na sumasama sa OmniRoute (antigravity, commandCode, devin-cli, atbp.). Tingnan ang Sanggunian ng Provider para sa kumpletong listahan.
| Paraan | Path | Paglalarawan |
|---|---|---|
| GET | /api/cli-tools/all-statuses |
Katayuan ng lahat ng CLI tool (naka-install, bersyon, huling nakita) |
| GET | /api/cli-tools/status |
Detalye ng katayuan para sa isang CLI tool (?tool= query) |
| POST | /api/cli-tools/apply |
Isulat ang nabuong configuration ng isang tool (dryRun ay nagbibigay ng preview; 422 + containerEphemeralTarget kapag containerized; migration ay nagtatalaga ng legacy Codex YAML) |
| GET | /api/cli-tools/backups |
Ilista ang mga backup ng configuration ng CLI tool |
| POST | /api/cli-tools/backups |
Gumawa ng backup ng lahat ng configuration ng CLI tool |
| POST | /api/cli-tools/backups |
I-restore: ang parehong endpoint na may {tool, backupId} sa body ay nagre-restore ng backup na iyon |
| GET | /api/cli-tools/antigravity-mitm |
Katayuan ng Antigravity MITM proxy (ang CLI tool na "antigravity-mitm") |
| POST | /api/cli-tools/antigravity-mitm/alias |
I-configure ang mga alias ng antigravity-mitm |
Pagpapatotoo: Nangangailangan ng management session.
Mga Kakayahan ng Agent
Pamahalaan ang mga kakayahan ng AI agent (katulad ng mga custom GPT ng OpenAI ngunit para sa mga agent).
| Paraan | Path | Paglalarawan |
|---|---|---|
| GET | /api/agent-skills |
Ilista ang lahat ng kakayahan ng agent (built-in + custom) |
| GET | /api/agent-skills/[id] |
Kunin ang isang partikular na kakayahan ng agent |
| POST | /api/agent-skills |
Gumawa ng custom na kakayahan ng agent — body: {name, description, prompt, model?, temperature?} |
| PUT | /api/agent-skills/[id] |
I-update ang isang custom na kakayahan ng agent |
| DELETE | /api/agent-skills/[id] |
Tanggalin ang isang custom na kakayahan ng agent |
| GET | /api/agent-skills/[id]/raw |
Kunin ang raw prompt + metadata (walang execution) |
| POST | /api/agent-skills/generate |
Bumuo ang AI ng bagong kakayahan mula sa paglalarawan sa natural na wika |
Pagpapatotoo: Nangangailangan ng management session o management-scoped API key.
Pamamahala ng Cache
Pamahalaan ang semantic cache at reasoning cache.
| Method | Path | Description |
|---|---|---|
| GET | /api/cache |
Pangkalahatang-ideya ng cache: kabuuang bilang ng entry, hit rate, laki sa disk |
| GET | /api/cache/entries |
Maglista ng mga naka-cache na entry (may pagination) |
| DELETE | /api/cache/entries |
Magtanggal ng mga cache entry (i-filter ayon sa mga query parameter) |
| GET | /api/cache/stats |
Detalyadong mga istatistika ng cache (bawat provider, bawat modelo) |
| GET | /api/cache/reasoning |
Status ng reasoning cache (para sa reasoning replay) |
| DELETE | /api/cache/reasoning |
I-clear ang reasoning cache — mga query param: ?toolCallId=<id> (isa) o ?provider=<p> o walang param (lahat) |
Auth: Nangangailangan ng management session.
Memory System
Pamahalaan ang persistent memory (FTS5 + vector embeddings).
| Method | Path | Description |
|---|---|---|
| GET | /api/memory |
Maglista ng mga memory entry (i-filter ayon sa scope, type, search query) |
| POST | /api/memory |
Gumawa ng bagong memory entry — body: {scope, type, content, metadata?} |
| GET | /api/memory/[id] |
Kunin ang partikular na memory entry |
| PUT | /api/memory/[id] |
I-update ang isang memory entry |
| DELETE | /api/memory/[id] |
Magtanggal ng memory entry |
| GET | /api/memory?q= |
Maghanap sa memory (FTS5 + vector) — kasama ang mga istatistika sa parehong response |
Auth: Nangangailangan ng management session o API key na may saklaw na management.
Webhooks
Pamahalaan ang mga subscription sa webhook para sa mga event.
| Method | Path | Description |
|---|---|---|
| GET | /api/webhooks |
Maglista ng lahat ng subscription sa webhook |
| POST | /api/webhooks |
Gumawa ng subscription sa webhook — body: {url, events[], secret?, active?} |
| GET | /api/webhooks/[id] |
Kunin ang partikular na subscription sa webhook |
| PUT | /api/webhooks/[id] |
I-update ang isang subscription sa webhook |
| DELETE | /api/webhooks/[id] |
Magtanggal ng subscription sa webhook |
| GET | /api/webhooks/[id]/deliveries |
Maglista ng history ng delivery para sa isang webhook (log ng tagumpay/pagkabigo) |
| POST | /api/webhooks/[id]/test |
Magpadala ng test event sa isang webhook |
Auth: Nangangailangan ng management session.
Tingnan ang Framework ng Webhooks para sa kumpletong mga uri ng event.
Framework ng Skills
Pamahalaan ang Skills (framework ng mga agentic extension).
| Method | Path | Description |
|---|---|---|
| GET | /api/skills |
Ilista ang lahat ng naka-install na skill (built-in + custom) |
| POST | /api/skills/install |
Mag-install ng skill mula sa lokal na path o URL |
| DELETE | /api/skills/[id] |
I-uninstall ang isang skill |
| PUT | /api/skills/[id] |
I-enable o i-disable ang isang skill — body: {enabled?: boolean, mode?: "on" | "off" | "auto"} |
| POST | /api/skills/executions |
Mag-execute ng skill — body: {skillName, apiKeyId, input?, sessionId?} |
| GET | /api/skills/executions |
Ilista ang history ng execution para sa lahat ng skill (i-filter gamit ang ?apiKeyId=) |
Auth: Nangangailangan ng management session o management-scoped API key.
Tingnan ang Skills Framework para sa kumpletong detalye.
Mga Plugin
Pamahalaan ang mga plugin ng OmniRoute (mga third-party extension).
| Method | Path | Description |
|---|---|---|
| GET | /api/plugins |
Ilista ang mga naka-install na plugin |
| POST | /api/plugins/marketplace/install |
Mag-install ng plugin mula sa marketplace |
| DELETE | /api/plugins/[name] |
I-uninstall ang isang plugin |
| POST | /api/plugins/[name]/activate |
I-activate ang isang plugin |
| POST | /api/plugins/[name]/deactivate |
I-deactivate ang isang plugin |
| GET | /api/plugins/[name]/config |
Kunin ang configuration ng plugin |
| PUT | /api/plugins/[name]/config |
I-update ang configuration ng plugin |
Auth: Nangangailangan ng management session.
Tingnan ang Plugins Framework para sa kumpletong detalye.
Shadow Routing
Ang Shadow / A-B comparison ng mga provider ay hindi isang standalone REST surface — kino-configure ito sa pamamagitan ng combo routing (tingnan ang Auto-Combo). Ang mga metric ng comparison para sa bawat combo ay ibinibigay ng GET /api/combos/metrics.
Mga Guardrail
Suriin ang mga runtime guardrail (PII detection, prompt injection detection, vision bridging). Tumatakbo ang mga guardrail sa bawat request; ang per-call opt-out ay sa pamamagitan ng request header na x-omniroute-disabled-guardrails — walang naka-persist na enable/disable surface.
| Method | Path | Description |
|---|---|---|
| GET | /api/guardrails |
Ilista ang mga nakarehistrong guardrail at ang status ng mga ito (name / enabled / priority) |
| POST | /api/guardrails/test |
Magsagawa ng dry-run ng pre-call pipeline gamit ang sample input — body: {input, disabledGuardrails?} |
Auth: Nangangailangan ng management session.
Tingnan ang Security > Guardrails para sa kumpletong detalye.
Pagpapatunay
Tingnan ang Management Authentication para sa apat na
pamilya ng kredensyal (dashboard session, lokal na CLI token, oma_live_… Access Token, manage-scoped API key) at kung paano naiiba ang mga ito sa mga inference key.
- Gumagamit ang mga dashboard route (
/dashboard/*) ngauth_tokencookie - Gumagamit ang login ng naka-save na password hash; fallback sa
INITIAL_PASSWORD - Maaaring i-toggle ang
requireLoginsa pamamagitan ng/api/settings/require-login - Opsyonal na nangangailangan ang mga
/v1/*route ng Bearer API key kapagREQUIRE_API_KEY=true - Ang "management token" / "management-scoped API key" sa sangguniang ito ay nangangahulugang isa sa mga pamilya sa gabay na iyon — hindi isang hindi tinukoy na karagdagang uri ng lihim
Breaking change (v3.8.0) — Nangangailangan na ngayon ang
/api/v1/agents/tasks/*at mga endpoint sa pamamahala ng cooldown ng management auth (dashboardauth_tokencookie o isang management-scoped API key). Makakatanggap ng401 Unauthorizedang mga client na dati nang tumatawag sa mga route na ito nang walang authentication. Tingnan ang commit588a0333(fix(auth): require management auth for agent and cooldown APIs).