205 KiB
API Reference (Magyar)
🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW
🌐 Nyelvek: 🇺🇸 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á | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)
Az OmniRoute API alapvető referenciája. A nyilvános /v1 felületet és a leggyakrabban használt felügyeleti végpontokat ismerteti; a géppel olvasható docs/openapi.yaml, valamint a src/app/api/ alatti útvonalfa a teljes körű forrás.
A célzott, OpenAI-kompatibilis protokollért és a szolgáltatói képességek mátrixáért lásd:
OPENAI_COMPATIBILITY.md.
Minden telepítés a specifikáció saját példányát szolgálja ki a /openapi.yaml útvonalon, amely a build során a docs/openapi.yaml fájlból jön létre. Ez tartalmazza a build verzióját és egy relatív szerver-URL-t (./), így a kérések annál a hosztnál maradnak, amely a dokumentumot kiszolgálta. A letöltött fájlt importáló eszköz nem rendelkezik ilyen hosttal, ezért az alap-URL-t manuálisan kell beállítani.
Tartalomjegyzék
- Chat completions
- Kizárólagos kezelt munkamenet-bérletek
- Beágyazások
- Képgenerálás
- Dokumentum-OCR
- Modellek listázása
- Szolgáltatói bővítményjegyzék
- Kompatibilitási végpontok
- Files API
- Batches API
- Search API
- WebSocket-adatfolyam
- Kvóták és problémák jelentése
- Szemantikus gyorsítótár
- CLIProxyAPI-kezelési kompatibilitás
- Irányítópult és kezelés
- Kombókezelés
- Webhookok
- Regisztrált kulcsok (automatikus kezelés)
- Agents protokoll
- Kezelési proxyk
- Rugalmasság (kibővített)
- Képességek
- Memória
- MCP-szerver
- A2A-szerver
- Cloud, Evals és Assess
- Kérésfeldolgozás
- Hitelesítés
Chat completions
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
}
Egyéni fejlécek
| Header | Irány | Leírás |
|---|---|---|
X-OmniRoute-No-Cache |
Kérés | Állítsa true értékre a gyorsítótár megkerüléséhez |
x-omniroute-no-memory |
Kérés | Állítsa true értékre, ha ki szeretné hagyni a memória + képességek beinjektálását ennél a kérésnél (a no-cache működését tükrözi; elkerüli a hívásonkénti token-/költségtöbbletet) |
X-OmniRoute-Progress |
Kérés | Állítsa true értékre az előrehaladási események engedélyezéséhez |
X-Session-Id |
Kérés | Ragasztott munkamenetkulcs külső munkamenet-affinitáshoz |
x_session_id |
Kérés | Az aláhúzásos változat szintén elfogadott (közvetlen HTTP) |
X-OmniRoute-Session-Id |
Kérés | A hívó által megadott munkamenet-/beszélgetéscímke (a memóriába is bekerül). Ha jelen van, változtatás nélkül kerül a call_logs.session_tag mezőbe munkamenetenkénti költség-hozzárendeléshez (#8249) — hiányzásakor soha nem generálódik |
Idempotency-Key |
Kérés | Duplikációszűrési kulcs (5 másodperces időablak) |
X-Request-Id |
Kérés | Alternatív duplikációszűrési kulcs |
x-omniroute-connection |
Kérés | Egy modellt használó kérést egyetlen szolgáltatói kapcsolathoz (fiókhoz) köt annak azonosítója alapján — lásd: Fiók hozzárendelése kérésenként |
X-OmniRoute-Cache |
Válasz | HIT vagy MISS (nem streamelt) |
X-OmniRoute-Idempotent |
Válasz | true, ha a kérés duplikációszűrése megtörtént |
X-OmniRoute-Progress |
Válasz | enabled, ha az előrehaladáskövetés aktív |
X-OmniRoute-Session-Id |
Válasz | Az OmniRoute által használt tényleges munkamenet-azonosító |
X-OmniRoute-Request-Id |
Válasz | Kéréskorrelációs azonosító (ha ismert) |
X-OmniRoute-Version |
Válasz | Az OmniRoute buildverziója (mindig jelen van) |
X-OmniRoute-Cost-Saved |
Válasz | A gyorsítótár-találatkor elkerült költség USD-ben (csak gyorsítótár-találatok esetén) |
X-OmniRoute-Decision |
Válasz | Útválasztási nyomkövetés: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> a kombinált stratégia, illetve single nem kombinált kérés esetén) — a befejezési válaszokban mindig jelen van |
Nginx-megjegyzés: ha aláhúzásjelet tartalmazó fejlécekre támaszkodik (például
x_session_id), engedélyezze azunderscores_in_headers on;beállítást.
Fiók hozzárendelése kérésenként
Ha egy szolgáltató több kapcsolattal (fiókkal vagy kulccsal) rendelkezik, az OmniRoute normál esetben
a fiókválasztási stratégiája segítségével választ közülük. Egy kérés ehelyett egy adott kapcsolatot is
rögzíthet az x-omniroute-connection fejléccel:
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"}]}'
- Hol található az azonosító? Nyissa meg a szolgáltató oldalát az irányítópulton
(Dashboard → Providers → ), majd kattintson a kapcsolat sorában található
xxxxxxxx…azonosítóchipre — ez a teljes kapcsolat-azonosítót a vágólapra másolja. - Mely kérések veszik figyelembe? Az egyetlen modellt használó kérések (
provider/model) a/v1/chat/completions,/v1/messagesés/v1/responsesvégpontokon. A kombinációk figyelmen kívül hagyják a fejlécet: minden kombinációs lépéshez külön rögzítsen egy fiókot a lépés saját kapcsolatán keresztül. - A rögzítés szigorú, nem csupán preferencia. A rögzített kapcsolat kizárólagosan használatos. A kérésen belüli hiba rögzíti a fiók lehűlési állapotát, de nem vált át ugyanazon szolgáltató testvérfiókjára.
- A lehűlés és a kvóta feloldja a rögzítést. Amíg a rögzített kapcsolat lehűl, kvótakimerülés esetén vagy ha egy kvótaszabályzat blokkolja, a későbbi kérések visszatérnek a szolgáltató más kapcsolataihoz, pontosan úgy, mint a nem rögzített forgalom esetében.
- Az ismeretlen vagy letiltott azonosítók hibát okoznak. Ha egy azonosító nem szerepel a szolgáltató aktív készletében (törölték, deaktiválták, vagy egy másik szolgáltatóhoz tartozik), nem marad jogosult fiók, ezért a kérés meghiúsul ahelyett, hogy csendben máshová lenne irányítva.
A Claude Code egyéni fejléceket küld az ANTHROPIC_CUSTOM_HEADERS használatával. Adja hozzá a
~/.claude/settings.json fájl env blokkjához, vagy egy projekt szintű
.claude/settings.json fájlhoz, ha projektenként eltérő fiókot szeretne rögzíteni:
{
"env": {
"ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
"ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
"ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>",
},
}
Forrás: src/sse/handlers/chat.ts (a fejléc beolvasása), src/sse/services/auth.ts és
src/sse/services/sessionAffinityPin.ts (a rögzítés feloldása és a készletből hiányzó azonosító
ellenőrzése).
Költségtelemetriai fejlécek: a nem streamelt sikeres válaszok szintén tartalmazzák az
X-OmniRoute-*költségtelemetriai készletet —X-OmniRoute-Response-Cost(USD, rögzített 10 tizedesjeggyel;0.0000000000ingyenes vagy nem árazott esetben),X-OmniRoute-Tokens-In/X-OmniRoute-Tokens-Out,X-OmniRoute-Model,X-OmniRoute-Provider,X-OmniRoute-Latency-Ms,X-OmniRoute-Cache-HitésX-OmniRoute-Fallback-Attempts(csak ha0), továbbá
X-OmniRoute-Request-IdésX-OmniRoute-Version. Ezeket a chat completions, a/v1/responses, a/v1/messagesés a média-végpontok bocsátják ki —/v1/embeddings,/v1/images/generations,/v1/audio/speech,/v1/audio/transcriptions,/v1/rerank,/v1/videos/generations,/v1/music/generationsés/v1/moderations(mindig0költséggel). A médiaköltséget modalitásonként számítják (képenként, másodpercenként, karakterenként, keresési egységenként), ha az árazás elérhető, ellenkező esetben0(hibabiztos működés).
A gyorsítótár-találat költségszemantikája: szemantikus gyorsítótárbeli TALÁLAT esetén (
X-OmniRoute-Cache-Hit: true) nem történik upstream-hívás, ezért azX-OmniRoute-Response-Costértéke0.0000000000(a találat kiszolgálásának inkrementális költsége). Az eredeti/feltételezett költséget külön azX-OmniRoute-Cost-Savedtartalmazza. A számlázási fogyasztóknak azX-OmniRoute-Response-Costértékét kell összesíteniük (a találatok költsége nulla); a gyorsítótár-elemzések azX-OmniRoute-Cost-Savedértékét aggregálhatják.
Kizárólagos kezelt munkamenet-bérletek
A kizárólagos kezelt munkamenet-bérlés választható, klienssemleges útválasztási szerződés: egy aktív tulajdonos egy jogosult OmniRoute-kapcsolatot tart fenn. Nem bérel modellt, nem igényel OAuthot, nem azonosít konkrét klienst, és nem követel meg konkrét szolgáltatót.
A hitelesítő API-kulcsnak rendelkeznie kell a lease:exclusive hatókörrel és explicit, nem üres
allowedConnections listával. Az adatbázis-módosítási határ mindkét mező együttes meglétét
érvényesíti a kulcs létrehozásakor és részleges frissítésekor.
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"}
A sikeres acquire, renew és release válaszok időbélyegeket, state értéket és a pontos pozitív
generation értéket jelenítik meg, de soha nem tartalmazzák a kiválasztott kapcsolatot vagy a
hitelesítő adatokat. A renew és release a generációt a JSON-törzsben adja meg:
{ "action": "renew", "generation": 1 }
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
Egy aktív bérlettulajdonos kifejezetten kérhet adatvédelmi szempontból biztonságos megjelenítési metaadatokat az aktuális hozzárendeléséhez:
{ "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"
}
}
Ezt a választható állapotműveletet az átlátszatlan tulajdonos, a hitelesített kezelt API-kulcs és a
pontos aktív generáció egyetlen adatbázis-tranzakcióban védi. A displayName kizárólag a
konfigurált kapcsolat nevének eltávolított szóközökkel rendelkező változata; értéke null, ha nem
létezik biztonságosan használható konfigurált név. Az OmniRoute soha nem helyettesíti ezt e-mail-
címmel vagy generált fiókazonosítóval. A szolgáltató értéke nem érzékeny megjelenítési címke, és
soha nem generált kompatibilis-szolgáltató-azonosító. A hitelesítő adatok, tokenek, cookie-k, nyers
kapcsolat- vagy API-kulcs-azonosítók, tulajdonoshasek, kerítési titkok és belső útválasztási adatok
kimaradnak.
A hibás kulcshoz, hibás tulajdonoshoz, elavult generációhoz, hiányzó, lejárt, feloldott vagy
érvénytelenített keresésekhez ugyanaz a 409 LEASE_FENCE_STALE hiba tartozik, kapcsolati metaadatok
nélkül. Annak a kliensnek, amely kapacitásra várakozó választ kapott, nincs vizsgálható aktív
hozzárendelése. Amikor az útválasztás egy aktív bérletet átállít, ugyanaz a generáció marad érvényes,
és az állapot atomikusan az új hozzárendelést adja vissza, soha nem a régit. A meglévő kliensek
változatlanok maradnak, mert az acquire, renew, release és várakozási válaszok megtartják korábbi
formájukat.
Ez a szerveroldali szerződés nem módosítja a beépített OpenAI Codex /status működését. A beépített
Codex jelenleg a modell szolgáltatóját, valamint a beépített hitelesítési- és fiókállapotot jelenti,
de nem jelenít meg tetszőleges egyéni szolgáltatói fiókmetaadatokat; egy későbbi kliensintegrációnak
meg kell hívnia ezt a műveletet, és el kell döntenie, hogyan jelenítse meg a
connection.displayName értékét.
Ezután minden kezelt következtetési kérés mindkét vezérlőfejlécet megadja:
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
A pontos tulajdonost, generációt, aktív kapcsolatot és hitelesített API-kulcsot a rendszer közvetlenül minden támogatott upstream-próbálkozás előtt ellenőrzi. A tulajdonos és a generáció másik kulccsal történő újrajátszása akkor is sikertelen, ha az a kulcs ugyanahhoz a kapcsolathoz engedélyez hozzáférést. A nyers tulajdonosok nem kerülnek megőrzésre, naplózásra, megtartásra a kérés pillanatképében, és nem továbbítódnak upstream felé.
Az ideiglenes versengés HTTP 429 választ ad Retry-After fejléccel és:
{
"state": "WAITING_FOR_CAPACITY",
"error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
"reason": "NO_FREE_ELIGIBLE_CONNECTION",
"retryAfter": 30
}
Ez a válasz csak azt jelenti, hogy a szokásos jogosult halmaz nem volt üres, és minden szabad jelöltet egy másik aktív bérlet tartott fogva. A nem támogatott modellek/szolgáltatók, a szabályzat eltérése, a lehűlési idő, a kvóta, az állapotellenőrzés és az egyéb szokásos jogosultsági hibák megtartják meglévő OmniRoute-válaszaikat.
x-omniroute-compression
A tömörítési terv kérésenkénti felülbírálása. A legmagasabb prioritású — megelőzi az útválasztási kombináció felülbírálását, az aktív profilt, az automatikus aktiválást és a panel Alapértelmezett értékét. Értékek:
| Érték | Hatás |
|---|---|
off |
Ehhez a kéréshez nincs tömörítés. |
default |
A panelből származtatott Alapértelmezett profil (figyelmen kívül hagyja az aktív profilt). A veszteséges motorok kikapcsolva maradnak. |
safe |
Csak a duplikátumok eltávolítása és a szóközök összevonása. |
allow-lossy |
A kezelői terv megtartása ehhez a kéréshez, beleértve az összefoglalókat és a stílusátírásokat is. |
engine:<id> |
Egyetlen motor, ha engedélyezve van, például engine:rtk. Az adott motor kérésenkénti engedélyezése. |
<combo> |
Egy elnevezett kombináció, először név (kis- és nagybetűtől függetlenül), majd azonosító alapján illesztve. |
Megjegyzések:
- Az ismeretlen értékeket a rendszer figyelmen kívül hagyja (a kérés soha nem kerül elutasításra); a feloldás a szokásos kezelői prioritási sorrendben folytatódik.
- Ha több kombináció neve azonos, a determinisztikus illesztéshez a kombináció id értékét adja meg.
- Az olyan kombináció, amelynek neve
offvagydefault, nem választható ki név alapján (ezeket a kulcsszavakat a rendszer először értelmezi); az ilyen kombinációra azonosítójával hivatkozzon. - A fő tömörítési kapcsoló kényszerített korlát: ha a tömörítés globálisan le van tiltva, ez a fejléc nem engedélyezheti.
Az alkalmazott tervet a rendszer visszaadja a válasz fejlécében:
X-OmniRoute-Compression: <mode>; source=<source>
ahol a <source> értéke a következők egyike: request-header, routing-override, active-profile, auto-trigger, default vagy off.
Embeddingek
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "nebius/Qwen/Qwen3-Embedding-8B",
"input": "The food was delicious"
}
Elérhető szolgáltatók: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.
A katalógusazonosítók formátuma provider/model (például: jina-ai/jina-embeddings-v5-omni-small). A regisztrációs adatbázisban szereplő önálló Jina-modellazonosítók (például jina-embeddings-v5-text-small, jina-reranker-v3.5) szintén feloldhatók. A Jina embed/rerank/classify/segment először a vezérlőpult jina-ai hitelesítő adatait használja; a JINA_AI_API_KEY csak akkor tartalék, ha nincs vezérlőpulti kulcs. A jina-reader kártya kizárólag a Reader / r.jina.ai szolgáltatáshoz tartozik (POST /v1/web/fetch), és soha nem szolgál ki embeddingeket vagy rerankelést.
A multimodális támogatást hirdető regisztrációs modellek legfeljebb 32 szolgáltatófüggetlen, strukturált elemet is elfogadnak. A médiatípusok: text, image, audio, video és document. A média source értéke vagy {"type":"url","url":"https://..."}, vagy {"type":"base64","data":"...","media_type":"..."}.
A Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano és a család aliasa, jina-ai/jina-embeddings-v5-omni → omni-small) a Jina natív EmbeddingsV5Request-dokumentációja szerinti kéréseket is elfogadja, és változatlanul továbbítja őket ide: 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,..." }] }
]
}
A natív { image | audio | video | pdf } értékek lehetnek nyilvános HTTPS-URL-ek, data: URI-k vagy nyers base64-adatok. Az OmniRoute nem alakítja ezeket az objektumokat karakterlánccá, és nem tölti le a natív kép-URL-eket – a nyilvános médiát maga a Jina tölti le. A további Jina-mezők (task, normalized, truncate, embedding_type) továbbításra kerülnek. A csak szöveget támogató Jina SKU-k továbbra is elutasítják a nem szöveges dokumentumokat.
Biztonsági és átviteli korlátok:
- A távoli média-URL-eknek nyilvános HTTPS-URL-eknek kell lenniük. A kanonikus
{type,source:url}elemeket a szerver tölti le (átirányítás-újraellenőrzéssel, időkorláttal, méretkorlátokkal, nyilvános DNS-sel és kapcsolat-rögzítéssel), majd a szolgáltató meghívása előtt beágyazza őket. A Jina natív{image:"https://..."}elemei változatlanul kerülnek továbbításra ugyanazon nyilvános HTTPS-ellenőrzés után; az URL-t a Jina tölti le. - A beágyazott base64-média elemenként legfeljebb 8 MiB, a teljes kérésben pedig dekódolva legfeljebb 16 MiB lehet.
Szolgáltatói fordítás (a kanonikus elemek soha nem kerülnek továbbításra változtatás nélkül):
- Jina multimodális modellek: minden legfelső szintű elem egyetlen, modalitáskulccsal ellátott objektummá (
text/image/audio/video/pdf) alakul, a beágyazott médiához data URI-k használatával; minden legfelső szintű elemhez egy vektor tartozik. - Gemini Embedding 2 család: egy legfelső szintű tömb egyetlen natív
models/{model}:embedContentkéréssé alakul,content.partselemekkel (textvagyinline_data). - llama.cpp (
llama-cpp/<model>, illetve bármely, a helyi szerver által betöltött modell): a kanonikustextelemek egyszerű karakterláncokká alakulnak, azimage/audio/videoelemek pedig egy-egy{"content": [part]}objektummá, a llama-server csevegési tartalomrészeit használva (image_url,input_audiowav/mp3/flacformátummal,input_video), beágyazott adatokkal; minden legfelső szintű elemhez egy vektor tartozik. A szervert a--embedding --mmproj …beállítással kell futtatni; projektor nélkül maga a szerver utasítja el a médiát. Adocumentnem támogatott. - A kifejezett modalitás-metaadatokkal nem rendelkező ismeretlen/dinamikus modellek HTTP 400-as hibával utasítják el a strukturált bemenetet.
{
"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"
}
A nem támogatott modell/modalitás-kombinációk HTTP 400-as hibát adnak vissza az elem kényszerített átalakítása helyett. A régi, karakterlánc- vagy tokenalapú kérések nem bemeneti kiterjesztési mezői továbbra is változtatás nélkül kerülnek továbbításra.
# Összes embeddingmodell listázása
GET /v1/embeddings
Képgenerálás
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"
}
Az elérhető szolgáltatók közé tartozik OpenAI (GPT Image 2 ), xAI (Grok Image ), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana,OpenRouter ,ZenMux , SD WebUI (helyi), ComfyUI (helyi).
n n képeket ad vissza data[]. Azok a szolgáltatók, akiknek az upstream API hívásonként egy képet ad vissza (Black Forest Labs, Stabilitás AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI) n külön felfelé irányuló hívást kapnak, legfeljebb 4-et repülés közben. A rögzített seed a hívásindex (seed, seed + 1, …) eltolja, így a képek különböznek, de reprodukálhatók maradnak. n felső határa 10. A kérés összességében meghiúsul, ha bármelyik hívás meghiúsul. A fan-out formátumok listája a SINGLE_IMAGE_FANOUT_FORMATS open-sse/handlers/imageGeneration/fanOut.ts.
ZenMux újrafelhasználja a meglévő API-kulcs kapcsolatot, és elfogadja zenmux/ vagy zm/ előtagokat:
zenmux/openai/gpt-image-2ZenMuxOpenAI API képeit használja. A lehetőségek közé tartoziksize,quality,n,output_format,output_compression,backgroundésresponse_format.- Más kiadók, például
zm/meta/muse-image-1.0, a ZenMux Vertex AI:predictvégpontját használják.nleképezsampleCount,aspect_ratiotaspectRatioésimage_size(1K,2K,4K)sampleImageSize. A pixelsizecsak képarányt biztosít, nem garantált pixelméreteket. A támogatott arányok, felbontások és számok típusonként változnak. zm/inclusionai/ming-image-0.1-designsaját maga választja ki a méreteit.size,aspect_ratioésimage_sizekihagyása; Az explicit értékek HTTP 400-at adnak vissza. PNG, JPEG és WebPoutput_format-vel kérhető.
Ez az integráció támogatja a szöveg-kép létrehozását, nem pedig a referencia-képszerkesztést. A csúcs kimenete data[].b64_json-ra normalizálva; response_format: "url" egy upstream HTTPS URL vagy egy base64 adat URL ad vissza, ha csak képbájtok állnak rendelkezésre. Empty/filtered kimenetek inkább hibát adnak vissza, mint üres sikert. A modellelérés a ZenMux fióktól függ. Lásd ZenMux Vertex API és OpenAI Images API.
A Microsoft 365 Copilot bejelentkezési kapcsolat copilot-m365-web/m365-copilot-image szolgálja ki Copilot beépített képeszközén keresztül: képenként egy Copilot fordulat (n 1–4), size csak a tájolást irányítja, és a képeket inline küldi vissza (b64_json vagy egy URL adat response_format: "url" esetén). Lásd: Microsoft 365 Copilot.
# List all image models
GET /v1/images/generations
Dokumentum-OCR
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"
}
}
A model egy provider/model előtagon keresztül választja ki az OCR-szolgáltatót; a puszta modellazonosító (például
mistral-ocr-latest) a regisztrált szolgáltatójához oldódik fel, a kihagyott model pedig alapértelmezés szerint a
Mistralra (mistral-ocr-latest) áll be. A regisztrált szolgáltatók (open-sse/config/ocrRegistry.ts):
| Szolgáltatóazonosító | Modellazonosító | model értéke |
Megjegyzések |
|---|---|---|---|
mistral |
mistral-ocr-latest |
mistral/mistral-ocr-latest (vagy puszta mistral-ocr-latest) |
Szinkron — a válasz közvetlenül az egyetlen upstream hívásból érkezik. |
azure-document-intelligence |
prebuilt-read |
azure-document-intelligence/prebuilt-read |
Aszinkron upstream (analyze + lekérdezés) — lásd alább. |
vertex-deepseek-ocr |
deepseek-ocr-maas |
vertex-deepseek-ocr/deepseek-ocr-maas |
Szinkron, a Vertex AI openapi/chat/completions partner-végpontján keresztül — a hitelesítésről és az URL-ről lásd alább. |
Mindhárom szolgáltató ugyanabban a Mistral-formátumú törzsben válaszol:
{
"pages": [{ "index": 0, "markdown": "# Extracted text..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
Azure Document Intelligence lekérdezési folyamat
Az Azure Document Intelligence analyze API-ja aszinkron: a kezdeti kérés törzs helyett egy
Operation-Location fejlécet ad vissza, és az eredményt le kell kérdezni. A kezelő
(open-sse/handlers/ocr.ts) másodpercenként lekérdezi ezt az URL-t, legfeljebb 30 próbálkozáson keresztül, azonnal hibát jelez (nem
folytatja a lekérdezést) nem-ok lekérdezési válasz vagy "failed" állapot esetén, és 504 választ ad vissza, ha a művelet
a próbálkozási keret kimerülése után is fut. A végső Azure-válasz a visszaadás előtt ugyanabba a
pages/markdown struktúrába normalizálódik, amelyet a Mistral használ, így az ügyfélkódnak nem kell
szolgáltatóspecifikus kivételeket kezelnie.
A Vertex AI DeepSeek OCR hitelesítése és végpontfeloldása
A vertex-deepseek-ocr ugyanazt a Vertex AI-hitelesítést használja, amelyet az OmniRoute már támogat
a csevegési/képes forgalomhoz (open-sse/executors/vertex.ts): a kapcsolat API-kulcsa vagy egy
Service Account JSON hitelesítő adat (amelyet a JWT-bearer folyamaton keresztül rövid élettartamú OAuth hozzáférési tokenre cserél),
vagy egy már létrehozott OAuth hozzáférési token, amelyet változtatás nélkül használ. Az upstream végpont URL-je a Vertex általános
openapi/chat/completions partner-végpontja, amelyet a kapcsolat projektjéből és régiójából állít elő — egy explicit
providerSpecificData.project/providerSpecificData.region érték mindig elsőbbséget élvez;
ellenkező esetben a projekt a Service Account JSON project_id értékéből származik, a régió pedig alapértelmezés szerint
us-central1. Mindkét feloldás az open-sse/handlers/ocr.ts
fájlban történik (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), és a
src/app/api/v1/ocr/route.ts használja őket az handleOcr meghívása előtti feldolgozás során.
Modellek listázása
GET /v1/models
Authorization: Bearer your-api-key
→ Visszaadja az összes chat-, embedding- és képmodellt, valamint a kombinációkat OpenAI-formátumban
Modellárak (pricing)
Egy bejegyzés pricing objektumot tartalmaz, amikor az OmniRoute ismeri a modell árát. Az ár
abból az árlistából származik, amelyet a költségelszámolás használ: beépített alapértékekből,
szinkronizált árakból és a /api/pricing útvonalon beállított felülírásokból. Ezek listaárak,
ezért az előfizetéses szolgáltatók esetében is tokenenkénti ár jelenik meg.
"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
}
| Mezők | Egység | Megjegyzések |
|---|---|---|
prompt, completion, input_cache_read, input_cache_write |
USD tokenenként, decimális karakterlánc | OpenRouter-kompatibilis, soha nem kitevős jelölésben. A két gyorsítótármező csak akkor jelenik meg, ha van gyorsítótárár. |
input, output, cached, cache_creation |
USD 1M tokenenként, szám | Korábbi katalógusverziókból származó mezők, amelyeket a meglévő kliensek miatt megőriztünk. A reasoning és a long_context szintén megjelenik, ha az ártáblázat sora tartalmazza ezeket. |
- A kombinációk az első látható cél árát hordozzák. A beépített
auto/*kombinációk futás közben választanak célt, ezért nincspricingértékük. - Az ingyenes modellek
"0"(és0) értéket jelenítenek meg, amikor az áruk nulla. Az ár nélküli modellek szintén"0"értéket jelenítenek meg, amikor a katalógus ingyenesként jelöli őket (free: true), vagy a beépített ingyenesmodell-katalógus felsorolja őket. - Ismeretlen ár: a bejegyzés nem tartalmaz
pricingkulcsot. - Kreditalapú elszámolást használó szolgáltatók (például a Kiro) kérésenként, nem tokenenként számláznak. A hozzájuk tartozó bejegyzések megtartják a korábban meglévő, 1 millió tokenenkénti numerikus mezőket, és nem tartalmaznak tokenenkénti karakterláncmezőket.
- A változatok (gondolkodási erőfeszítésre utaló azonosítók, gondolkodás nélküli aliasok, felderítési és átjárótükrök) annak a modellnek az árát másolják, amelyhez továbbítják a kérést.
- A mezők csak az alapárakat tartalmazzák. A hosszú kontextusra vonatkozó szintek (a numerikus
long_contextmező) és a szolgáltatási szint szorzói (például a Codex fast vagy flex) nem módosítják apromptvagy acompletionértékét. - Az objektum minden hitelesítési stílus esetében azonos, beleértve az
x-api-keyés azanthropic-versionfejléceket használó Anthropic-stílusú kérést is (a válasz továbbra is{ "object": "list", "data": [...] }). Implementáció:src/app/api/v1/models/catalogPricing.ts.
Modellazonosító-előtagok (?prefix=)
A legtöbb modell szolgáltatói előtag alatt jelenik meg. A kapott előtagot a
MODELS_CATALOG_PREFIX_MODE funkciójelző vezérli, és kérésenként felülírható egy
lekérdezési paraméterrel — ez hasznos egy olyan kliens számára, amely tiszta listát szeretne
kapni anélkül, hogy a kiszolgáló minden felhasználóra érvényes beállítását módosítaná:
GET /v1/models?prefix=alias # modellenként egy azonosító — a rövid aliaselőtag
GET /v1/models?prefix=dual # mindkét forma (kiszolgálóalapértelmezés)
GET /v1/models?prefix=canonical # csak a teljes szolgáltatóazonosító-előtag
| Mód | Kibocsátott azonosító | Megjegyzések |
|---|---|---|
dual |
cc/claude-sonnet-4-6 és claude/claude-sonnet-4-6 |
Alapértelmezett. Mindkét azonosító ugyanahhoz a modellhez irányít; azért maradtak meg, hogy azok a klienskonfigurációk is tovább működjenek, amelyek bármelyik formát rögzítették. Nagyjából megduplázza a katalógust. |
alias |
cc/claude-sonnet-4-6 |
Modellként egy bejegyzés. A külön alias nélküli szolgáltatók szintén kibocsátják a hozzájuk tartozó bejegyzést, így semmi sem vész el. |
canonical |
claude/claude-sonnet-4-6 |
Modellként egy bejegyzés a teljes szolgáltatóazonosító-előtag alatt. A külön alias nélküli szolgáltatók (például antigravity/…, agy/…) itt is kibocsátják egyetlen azonosítójukat, így semmi sem vész el. |
A dual módú tükör a lekérdezési paraméter nélkül is felismerhető: egy elsődleges azonosítóra
mutató parent mezőt tartalmaz.
A modellválasztót megjelenítő klienseknek a ?prefix=alias paramétert kell kérniük — ezt teszi
az OmniCopilot VS Code-bővítmény is.
Felderítési szűrők (?capability=, ?min_context=, ?kind=, ?q=)
A GET /v1/models opcionális felderítési szűrőket fogad. Ha egyiket sem adják meg, a válasz
változatlan marad. Ezek a hívó által már látható katalógust szűkítik (az API-kulcs jogosultságai
alkalmazódnak először), és az OpenAI-stílusú limit / after lapozás előtt futnak le:
GET /v1/models?capability=vision&capability=tool_calling # minden felsorolt képességnek igaznak kell lennie
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding # a katalógus `type` értéke; a nélküle rendelkező sorok `chat` típusúak
GET /v1/models?q=sonnet&limit=10 # kis- és nagybetűtől független egyezés az azonosítón vagy a néven
| Paraméter | Értékek |
|---|---|
capability |
attachment, reasoning, structured_output, temperature, thinking, tool_calling, vision |
min_context |
nem negatív egész szám, összehasonlítva a context_length értékével |
kind |
chat, audio, embedding, image, moderation, music, rerank, video |
q |
1–200 karakter |
Ismeretlen érték, illetve a nem nemnegatív egész számként megadott min_context (például 1.5)
HTTP 400 választ ad, az üzenet pedig felsorolja az érvényes értékeket. Implementáció:
src/app/api/v1/models/catalogFilters.ts.
Modellrövidlista (POST /v1/models/query)
A POST /v1/models/query determinisztikus, rövid listát ad vissza ugyanabból a katalógusból, ugyanazzal
a hitelesítéssel és kulcsonkénti láthatósággal, mint a 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 ] }
Minden mező opcionális. A capabilities és az exclude tömbként vagy vesszővel elválasztott karakterláncként adható meg;
a max_output összehasonlítása a max_output_tokens értékével történik. Az eredmények rendezése először
az owned_by, majd az id szerint történik. A limit alapértelmezett értéke 20, a 100 feletti értékeket
pedig 100-ra korlátozza a rendszer. Érvénytelen JSON, ismeretlen mező vagy érvénytelen érték HTTP 400 választ ad.
Egyenként elrejtett csevegési modellek
A szolgáltató oldalán Rejtett jelöléssel ellátott modell kikerül a katalógusból, és explicit kérés esetén
HTTP 404 / model_not_found hibával kerül elutasításra. Az ellenőrzés a feloldott szolgáltatót és modellt
használja, beleértve a szolgáltatói aliasokat, a kompatibilis szolgáltatói csomópont-előtagokat és a
kapcsolati alapértelmezéseket. Egy kombináció kihagyja a rejtett célpontokat, és használhat látható testvért;
ha nem marad végrehajtható célpont, ugyanazt a hibakódot adja vissza. A rejtés megszüntetése a következő
kérésben lép érvénybe. A csak képekre vonatkozó láthatósági felülbírálások nem rejtik el az azonos azonosítójú
csevegési modellt.
Ez az egyéni modellbeállítás különálló a
modellkitettségi engedélyezési/tiltási listáktól, amelyek szűrik a katalógus
hirdetését és az automatikus útválasztás jelöltjeit, miközben megtartják az explicit diszpécselést. Az API-kulcs
modellengedélyei továbbra is ettől függetlenül érvényesülnek. Az alapértelmezett katalógus-előtag módja továbbra is dual.
Gondolkodás nélküli modellváltozatok
A gondolkodásra képes Claude-modellek esetén a /v1/models egy gondolkodás nélküli változatot is hirdet,
amelynek azonosítója a claude-3-omniroute-no-thinking/ előtaggal kezdődik:
claude-3-omniroute-no-thinking/<provider>/<model>
Ennek az azonosítónak a kiválasztása (például egy olyan Claude Code-konfigurációban, amely mindig hozzáad egy
thinking blokkot) visszafejtéskor a valódi <provider>/<model> modellhez vezet, kikapcsolt gondolkodással —
thinking:{type:"disabled"} a /v1/messages útvonalon, illetve a reasoning/reasoning_effort mezők
elhagyásával a /v1/chat/completions útvonalon. A változat csak azokhoz a Claude-családba tartozó modellekhez
jelenik meg, amelyek támogatják a gondolkodást és figyelembe veszik a disabled értéket (így például az
olyan, csak adaptív működést támogató modellek, amelyek elutasítják a disabled értéket, ki vannak zárva).
Az üzemeltetők modellenként a ModelSpec.noThinkingAlias segítségével kényszeríthetik ki vagy kapcsolhatják be
a változatot.
Szolgáltatói bővítményjegyzéke
GET /api/v1/provider-plugin-manifest
Visszaadja a Bifrost, a CLIProxyAPI és a jövőbeli sidecar-útválasztók által használt, JSON-kompatibilis szolgáltatói bővítményjegyzéket. A válasz a TypeScript szolgáltatói nyilvántartásából készül, és szándékosan kizárja az OAuth-ügyfél titkait, a futásidejű környezeti feloldást, a végrehajtófüggvényeket, a kérésfejléceket és a fiókadatokat.
Ezt a végpontot akkor használja, amikor egy sidecar külön folyamatban fut, és közvetlenül
nem tudja importálni az
open-sse/config/providerPluginManifestRegistry.ts fájlt.
ElevenLabs hanggenerálás
Állítson be egy elevenlabs szolgáltatói kapcsolatot az OmniRoute-ban az ElevenLabs API-kulcsával.
Az ügyfelek a OmniRoute-kulccsal hitelesítik magukat (Authorization: Bearer $OMNIROUTE_API_KEY);
az átjáró a tárolt szolgáltatói kulcsot xi-api-key értékként továbbítja. Soha ne küldjön ElevenLabs-kulcsot
az átjáró bearer-tokenjeként.
| Metódus | Útvonal | Válasz | API-kulcs végpontkategóriája |
|---|---|---|---|
| POST | /v1/sound-generation |
Natív hangbájtok | elevenlabs |
| POST | /v1/music |
Natív hangbájtok | music |
| POST | /v1/music/stream |
Folyamatos hangbájtok | music |
| POST | /v1/music/detailed |
Natív többrészes hang és kompozíciós terv | music |
| POST | /v1/music/detailed/stream |
Natív SSE-metaadatok és hangdarabok | music |
| POST | /v1/music/plan |
JSON-kompozíciós terv | music |
Ezek a végpontok kiegészítik a meglévő /v1/audio/speech, /v1/audio/transcriptions,
/v1/voices, /v1/text-to-speech/{voiceId} és /v1/speech-to-text útvonalakat. A natív JSON-mezők
és az olyan lekérdezési paraméterek, mint az output_format és az enable_logging, megmaradnak.
A /v1/music/detailed válaszai megőrzik a többrészes határolókat; ezeket többrészes formátumként
értelmezze.
A /v1/music/detailed/stream text/event-stream formátumban ad vissza kompozíciós metaadatokat és
base64-kódolású hangdarabokat az SSE-eseményekben. Mind a hat útvonal támogatja a CORS-előzetes kéréseket.
export OMNIROUTE_BASE_URL="http://localhost:20128"
export OMNIROUTE_API_KEY="your-omniroute-api-key"
# Rövid hangeffektus. Időtartam: 0,5–30 másodperc.
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
# A zene időtartamát ezredmásodpercben kell megadni: 3000–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
A fokozatos hangátadáshoz használja a /v1/music/stream végpontot ugyanazzal a JSON-törzzsel. A kompozíció
pontosan a prompt vagy a composition_plan egyikét fogadja el; a /v1/music/plan megköveteli a prompt
mezőt, és opcionálisan elfogadja a source_composition_plan mezőt. A natív sémák megőrzik a további
szolgáltatói mezőket, így a kompozíciós terv verziói és a finomhangolási beállítások eljutnak az ElevenLabshez.
Az egységes /v1/music/generations végpont az elevenlabs/music_v1,
elevenlabs/music_v2 és elevenlabs/music_v2_5 modelleket is elfogadja. Aktív ElevenLabs-kapcsolat
esetén ezek a modellek megjelennek a zenei katalógusban. Ez a végpont a következőt adja vissza:
{"created":...,"data":[{"b64_json":"...","format":"mp3"}]}. A duration mező értéke
másodpercben van megadva, és a music_length_ms mezőre képeződik le; a kifejezetten megadott
music_length_ms elsőbbséget élvez. Az instrumental a force_instrumental mezőre képeződik le,
a natív mező pedig elsőbbséget élvez. Folyamatos átvitelhez használja a natív streaming-végpontokat,
és kizárólag kompozíciós terv által vezérelt kérésekhez a natív kompozíciós végpontot.
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}'
A végpont-, modell-, költségkeret- és kapcsolatkorlátozások még a felsőbb szintű szolgáltatóhoz intézett
hívás előtt érvényesülnek. A natív útvonalak változatlanul adják vissza a felsőbb szintű szolgáltató
HTTP-állapotkódjait és hibatörzseit, beleértve a 402 kódot tervkorlátozás, a 429 kódot pedig kvótakorlát
esetén. A character-cost, song-id, request-id és retry-after fejlécek jelenlétük esetén megmaradnak.
Az ingyenes kreditegyenleg nem garantál hozzáférést minden zenei modellhez, kimeneti formátumhoz vagy
API-funkcióhoz: az ElevenLabs minden kérésnél maga dönti el a jogosultságot.
Az egységes végpont megőrzi a hibák állapotkódjait az OmniRoute normalizált hiba burkában.
Felsőbb szintű szolgáltatói szerződések: hangeffektusok, zenei kompozíció és folyamatos zenei részletek.
Kompatibilitási végpontok
| Metódus | Útvonal | Formátum |
|---|---|---|
| POST | /v1/chat/completions |
OpenAI |
| POST | /v1/messages |
Anthropic |
| POST | /v1/responses |
OpenAI Responses |
| POST | /v1/embeddings |
OpenAI |
| POST | /v1/images/generations |
OpenAI Images |
| POST | /v1/images/edits |
OpenAI Images (szerkesztés/inpaint) |
| POST | /v1/videos/generations |
OpenAI-stílusú videógenerálás |
| POST | /v1/music/generations |
OpenAI-stílusú zenegenerálás |
| POST | /v1/audio/transcriptions |
OpenAI Audio (STT) |
| POST | /v1/audio/speech |
OpenAI TTS (hangtörzset ad vissza) |
| POST | /v1/rerank |
Cohere/Voyage-stílusú újrarangsorolás |
| POST | /v1/classify |
Jina classify (api.jina.ai) |
| POST | /v1/segment |
Jina szegmentáló (segment.jina.ai) |
| POST | /v1/moderations |
OpenAI Moderations |
| GET | /v1/models |
OpenAI |
| POST | /v1/models/query |
Szűrt modellrövidlista |
| 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}/ |
OpenAI-katalógus-alias |
| GET | /api/v1/vscode/{token}/models |
OpenAI-modellek-alias |
| POST | /api/v1/vscode/{token}/chat/completions |
Tokenizált OpenAI-alias |
| POST | /api/v1/vscode/{token}/responses |
Tokenizált OpenAI Responses-alias |
| POST | /api/v1/vscode/{token}/api/chat |
Tokenizált Ollama-alias |
| GET | /api/v1/vscode/{token}/api/tags |
Tokenizált Ollama-címke-alias |
Minden POST-útvonal ugyanazt a struktúrát követi: Bearer your-api-key + Zod által validált JSON-törzs (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema stb.; lásd: src/shared/validation/schemas.ts). Sikertelen sémaellenőrzés esetén 4xx-es válasz érkezik.
Azoknál a klienseknél, amelyek nem tudnak Authorization: Bearer ... fejlécet csatolni, az OmniRoute URL-ben is elfogad API-kulcsokat a lekérdezési karakterlánccal való kompatibilitás (?token=..., ?apiKey=..., ?api_key=..., ?key=...) vagy az alább dokumentált dedikált /api/v1/vscode/{token}/... végpontok használatával.
# Újrarangsorolás (felhőbeli registry-szolgáltató vagy OpenAI-kompatibilis szolgáltatói csomópont "<prefix>/<model>" formában)
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Jina classify (Foundation API hitelesítő adatok)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Jina szegmentáló
POST /v1/segment { "content": "...", "return_chunks": true }
# Jina search (s.jina.ai; szolgáltatói aliasok: jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Moderálás
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — audio/mpeg (vagy a kért formátumú) törzset ad vissza
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# A Soniox TTS-hez nyelv és hang szükséges: a `language` alapértelmezett értéke "en"; hiányzó
# `voice` esetén, illetve OpenAI-alapértelmezett hangnév (alloy, nova, …) megadásakor az érték "Adrian" lesz
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }
# Képszerkesztés (multipart)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# Videó-/zenegenerálás (szolgáltató-előtaggal ellátott modellazonosító)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "kie/suno-v4.0", "prompt": "..." }
Rerank-szolgáltatói csomópontok: A
POST /v1/rerankOpenAI-kompatibilis szolgáltatói csomópontokhoz is továbbítja a kérést (oMLX, vLLM, Infinity, átjáró mögötti TEI, …), amelyek címe<node-prefix>/<model>. A loopback- csomópontok (localhost,127.0.0.1,172.16.0.0/12) mindig használhatók, csakúgy, mint az üzemeltető által azOMNIROUTE_LOCAL_PROVIDER_NODE_HOSTSváltozóban felsorolt állomásnevek (például egy Docker/Compose-szolgáltatás neve, mint ahttp://reranker:8080/v1; ezeket közvetlenül hívja, soha nem aHTTP(S)_PROXYváltozón vagy egy kapcsolat rögzített proxyján keresztül). Bármely más állomáson — például egy LAN-gépen vagy Tailscale-partneren — található csomópontok csak akkor használhatók, ha az üzemeltető engedélyezi aRERANK_REMOTE_PROVIDER_NODESfunkciójelzőt, és a csomópont alap-URL-je megfelel a szolgáltatói kimenő URL-szabályzatnak (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS/OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS). A memóriaengine rerank-lépése loopbacken keresztül hívja ezt az útvonalat, ezért ugyanez a szabály vonatkozik a Memória beállításaiban megadottrerankProviderModelértékre is.Helyi kiszolgálóformák: A csomópontot a rendszer a
<base>/v1/rerankcímen, 404 esetén pedig a<base>/rerankcímen hívja (Infinity, TEI). A felfelé irányuló kérés törzse a Cohere/OpenAI-féle (documents,return_documents) és a TEI-féle (texts,return_text) elnevezéseket is tartalmazza, a felfelé irányuló válasz pedig a Cohere-burkolatra normalizálódik: a TEI csupasz[{index, score, text}]válasza, a vékony átjáróktól érkező{results: [{index, score}]}, valamint a Voyage-féle{data: [...]}mind{results: [{index, relevance_score, document?}]}formában érkezik vissza az ügyfélhez, pontszám szerint rendezve éstop_nértékre korlátozva.
Szolgáltatói csomópontok felderítése: Az OpenAI-kompatibilis szolgáltatói csomóponton található modellek a
GET /v1/modelsválaszában jelennek meg a csomópont-előtag alatt. Azok a sorok, amelyek nem tartalmaznak végpont-metaadatokat (ez jellemző a helyi/v1/modelslistákra), öröklik a csomópontapiTypeértékét, ezért egyembeddingscsomópont modelljeitype: "embedding", egyrerankcsomópont modelljei pedigtype: "rerank"típusúak lesznek, ahelyett hogy alapértelmezés szerint chatként jelennének meg; a szinkronizált vagy manuálisan hozzáadott sorokon szereplő explicitsupportedEndpointstovábbra is elsőbbséget élvez.
Dedikált szolgáltatói útvonalak
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
A szolgáltatói előtag automatikusan hozzáadódik, ha hiányzik. Az eltérő modellek 400 választ adnak.
Fájlok API
OpenAI-kompatibilis fájlvégpont kötegelt bemenetekhez/kimenetekhez és fájlcélú feltöltésekhez.
| Method | Path | Description |
|---|---|---|
| POST | /v1/files |
Fájl feltöltése (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — legfeljebb 512 MiB |
| GET | /v1/files |
A hitelesített API-kulcshoz tartozó fájlok listázása |
| GET | /v1/files/[id] |
Egy fájl metaadatainak lekérése |
| DELETE | /v1/files/[id] |
Fájl törlése |
| GET | /v1/files/[id]/content |
A nyers fájltörzs streamelése vissza |
Hitelesítés: Bearer API-kulcs — a fájlok API-kulcsonként vannak elkülönítve a getApiKeyRequestScope használatával. Egy kulcs csak a saját fájljait látja, tölti le és törli; a kulcs nélküli irányítópult-munkamenet a teljes példányt olvassa; a tulajdonossal nem rendelkező fájlokhoz (névtelen vagy irányítópult-munkamenet által feltöltött fájlokhoz) minden nem munkamenet-alapú hívó számára megtagadott a hozzáférés. A GET /v1/files egy névtelen hívó — valamint egy olyan megadott kulcs esetén, amely nem oldható fel — 401 hibával utasítja el a kérést még akkor is, ha a REQUIRE_API_KEY=false, ahelyett, hogy felsorolná minden bérlő fájljait (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).
Kötegek API-ja
OpenAI-kompatibilis kötegelt feldolgozás.
| Method | Path | Description |
|---|---|---|
| POST | /v1/batches |
Köteg létrehozása — a törzs validálását a v1BatchCreateSchema végzi (input_file_id, endpoint, completion_window) |
| GET | /v1/batches |
Kötegek listázása |
| GET | /v1/batches/[id] |
A köteg állapotának és a request_counts értéknek a lekérése |
| DELETE | /v1/batches/[id] |
Befejezett vagy sikertelen köteg törlése |
| POST | /v1/batches/[id]/cancel |
Folyamatban lévő köteg megszakítása |
Hitelesítés: Bearer API-kulcs. A kötegek API-kulcsonként vannak elkülönítve, a fájlokkal azonos háromirányú szabály szerint: csak a saját kulcs, a teljes példányra kiterjedő irányítópult-munkamenet, a tulajdonossal nem rendelkező rekordokhoz pedig minden nem munkamenet-alapú hívó számára megtagadott a hozzáférés (lekérés, törlés, megszakítás és a létrehozáskor végzett input_file_id-ellenőrzés esetén). A GET /v1/batches egy névtelen hívó kérését 401 hibával utasítja el még akkor is, ha a REQUIRE_API_KEY=false.
Keresés API
Web/search szolgáltató absztrakció (Tavily, Brave, Exa, Serper stb.).
| Módszer | Útvonal | Leírás |
|---|---|---|
| GET | /v1/search |
Sorolja fel a konfigurált keresési szolgáltatók + képességeit |
| POST | /v1/search |
v1SearchSchema le caching/coalescing keresési — |
| GET | /v1/search/analytics |
Szolgáltatónkénti hit/latency/cache statisztika |
Auth: Tartó API kulcs (extractApiKey + isValidApiKey). A keresési szabályzat enforceApiKeyPolicy keresztül érvényesítve.
Automatikus kiválasztás: provider nélkül a legolcsóbb, konfigurált kapcsolattal rendelkező szolgáltató fut először, és a következő legolcsóbb a feladatátvétel. Az ingyenes utolsó szolgáltatók (duckduckgo-free) csak akkor használatosak, ha semmi más nincs beállítva. A saját üzemeltetésű SearXNG konfiguráltnak számít, ha a kapcsolata valódi baseUrl (nem a katalógus alapértelmezett http://localhost:8888/search baseUrl ) tárolja: ezután 0 dolláros szolgáltatóként szerepel a kulcsos szolgáltatók előtt, a legolcsóbb kulcsos szolgáltató pedig feladatátvételként, beleértve azt is, ha SearXNG 400, 401, 403 vagy 404 URL válaszol. http(s) -metaadat cím nem számít. A tokent tároló SearXNG kapcsolat csak https:// vagy loopback http:// felett rangsorolható. A távoli sima http:// en soha nem jelent feladatátvételt, és csak az utolsó lehetőség marad, csak akkor használják, ha nincs más szolgáltató konfigurálva, vagy ha név szerint kérik, tehát ebben a két esetben egyértelmű szöveggel küldi el a tokent.
Exa és Tavily provider_options
Az Exa és a Tavily beolvassa a szolgáltató-specifikus mezőket egy névteres táskából: provider_options.exa (vagy provider_options["exa-search"]) és provider_options.tavily (vagy provider_options["tavily-search"]). Csak az alábbi kulcsok kerülnek továbbításra. Mindegyiket ellenőrzik a saját Zod sémájával open-sse/handlers/search/providerOptionsPassthrough.ts ben, és egy nem megfelelő típusú kulcs kerül kidobásra. Minden más kulcs figyelmen kívül marad, beleértve az auth, base URL, stream és outputSchema. A más szolgáltatók által használt lapos billentyűk (cx, depth, ...) a korábbiak szerint működnek.
| Szolgáltató | Legfelső szintű mezők | Beágyazott |
|---|---|---|
| Exa | type, category, userLocation, moderation, additionalQueries, objective, systemPrompt, compliance (lapos primitívek), startPublishedDate, endPublishedDate |
contents.{text, highlights, summary, extras, livecrawlTimeout, maxAgeHours} egyesült az alapértelmezett { text: true, highlights: true } vel |
| 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 |
— |
Mindig az általános mezők nyernek: query, max_results, filters (domains), country és a search_type ből származó téma. Az Exa-n a search_type: "news" megtartja category: "news". Tavily search_type: "finance" (topic: "finance") is elfogadja.
A Firecrawl keresési költsége 10 visszaadott eredmény elindított blokkjára vonatkozik, blokkonként 0,002 USD (2 kredit) és hívásonként legalább egy blokk ( Firecrawl-számlázás ): 11 találat 0,004 USD-ba kerül.
Az általános time_range mostantól mindkét szolgáltatót eléri: Exa startPublishedDate (ISO timestamp), Tavily pedig start_date (YYYY-MM-DD) kap. Az explicit dátum provider_options ben felülírja a leképezett dátumot.
Az Exa eredmények id, highlights (minden kiemelés, nem csak az első snippet), highlight_scores, summary, subpages, entities és extras provider_raw-ben marad. A Tavily eredmények images és favicon maradnak.
A linkup keresési költsége 0,005 USD depth fast és standard, és 0,05 USD deep ( Linkup pricing ) esetében, függetlenül attól, hogy depth provider_options ből vagy a kapcsolat beállításaiból származik.
Az Exa type: "lite" (Exa 3.0) kisebb mezőket fogad el, és elutasítja a teljes kérést, ha bármely más mező be van állítva. Lite esetén additionalQueries, systemPrompt és text és highlights kivételével minden contents billentyű eldobásra kerül a hívás előtt. Az elavult subpages, subpageTarget, highlights.numSentences és highlights.highlightsPerUrl továbbítása már nem történik meg.
A költségelszámolás a costPerQuery lapos nyilvántartás, kivéve az Exa esetében, amely az Exa saját árait követi: 0,007 USD hívásonként auto (és az örökölt fast) esetében vagy 0,004 USD lite (és az örökölt instant) esetében, amely 10 eredményt takar; 0,001 USD minden további eredményért; és 0,001 USD visszaadott eredményenként, ha contents.summary be van állítva. A Tavily 1 kreditet (0,008 USD) search_depth basic, fast és ultra-fast esetében, és 2 kreditet ($ 0,016) advanced esetében ( Tavily API kredit ). A auto_parameters: true folytatott hívást, amelyet Tavily haladó szintre frissít, továbbra is 1 kredittel rögzítenek.
Web Fetch API
Tartalom kinyerése egy URL-ből konfigurált web-fetch-szolgáltatón keresztül (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract).
A Parallel Extract (parallel-search, ugyanazt az API-kulcsot használja, mint a Parallel Search) csak Markdown formátumot ad vissza — bármely más format érték 400 hibát eredményez —, és a tartalmat 100 000 karakterben korlátozza. Ha magát a céloldalt nem lehet kinyerni, a upstream szolgáltatás ezt HTTP 200-as válaszon belül jelenti; az OmniRoute ezt 422 válaszként, rögzített üzenettel továbbítja.
| Metódus | Útvonal | Leírás |
|---|---|---|
| POST | /v1/web/fetch |
URL lekérése/kaparása — a törzset a v1WebFetchSchema ellenőrzi |
Hitelesítés: Bearer API-kulcs (extractApiKey + isValidApiKey). A házirendet az enforceApiKeyPolicy érvényesíti.
Kvótatudatos tartalékmegoldás (#8297): amikor nincs explicit provider megadva, a készlet
(firecrawl → jina-reader → tavily-search → tinyfish → nimble-search →
parallel-search) rögzített
prioritási sorrendben (fill-first)
kerül bejárásra — a sebességkorlátozott, de konfigurált szolgáltató átugrásra kerül
ahelyett, hogy a kérés azonnal hibával leállna, továbbá egy újrapróbálható/kvótával kapcsolatos upstream-hiba
(mindig a HTTP 429; a 402/403 a Firecrawl/Tavily/TinyFish kvótajellegű ingyenes csomagjainál —
a Jina Reader esetében nem, és egyszerű, hibás kérés miatti 400 esetén soha) kérésenként továbblép
a következő, még nem próbált, hitelesítő adatokkal rendelkező szolgáltatóra. Ha a készlet minden szolgáltatója kimerült, a végpont egyetlen 429 választ ad (Retry-After
fejléc mellett) a korábbi általános 400 helyett. Explicit provider kérésekor nincs
csendes tartalékmegoldás — a sebességkorlátozott vagy hibázó explicit szolgáltató a saját hibáját adja vissza (429, ha sebességkorlátozás történt, egyébként az upstream állapotkódját).
WebSocket-streamelés
GET /v1/ws?handshake=1
Ellenőrzi a WebSocket-frissítési kézfogást, és visszaadja a vezetékprotokoll példaként szolgáló üzeneteit (request, cancel). A tényleges WS-kereteket a beépített WS-szerver kezeli a Next.js útvonaltábláján kívül.
Hitelesítés: Bearer API-kulcs a kézfogás során.
Responses API WebSocketen keresztül (csak codex)
# Ugyanaz a host:port, mint a HTTP API esetében (alapértelmezés: 20128); a kapcsolat frissítése:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (vagy: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
# Az első keretnek KÖTELEZŐEN response.create típusúnak kell lennie:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
A Responses-API-WebSocket-proxy kizárólag a codex szolgáltatáshoz van bekötve (ChatGPT-backend). Az API-val/irányítópulttal azonos porton figyel a /v1/responses,
/responses és /api/v1/responses útvonalakon. Az első response.create keret beérkezésekor
a belső codex-responses-ws hídon keresztül hitelesít és előkészít, kiválaszt egy
codex OAuth-kapcsolatot, majd a wreq-js átvitellel továbbítja a kérést a wss://chatgpt.com/backend-api/codex/responses
címre. A nem codex modellek elutasításra kerülnek (codex_ws_provider_required).
Kvótamegosztásos útválasztáshoz használja a model: "qtSd/<group>/codex/<model>" értéket. A megvalósítás helyei:
app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.
Hitelesítés: Bearer API-kulcs a kézfogás során. A beépített HTTP-szervernek (server-ws.mjs)
az aktív belépési pontnak kell lennie (alapértelmezés szerint az, amikor az app/server-ws.mjs létezik).
Modellazonosító: használja a csupasz ChatGPT-azonosítót (a codex/ előtag nélkül)
Az OpenAI Codex CLI kliensoldalon ellenőrzi a modell nevét, amikor
a supports_websockets = true, és elutasítja a szolgáltató-előtaggal ellátott azonosítókat,
például a codex/gpt-5.5 értéket (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Küldje a csupasz azonosítót (például gpt-5.5). Az OmniRoute hídja csak codexhez használható, ezért a továbbítás előtt codex-modellként oldja fel újra a csupasz azonosítót
(resolveCodexWsModelInfo) — még akkor is, ha a csupasz gpt-5.5 HTTP-n keresztül egyébként egy másik szolgáltatóhoz lenne irányítva.
Az OpenAI Codex CLI konfigurálása
Irányítsa a Codex CLI-t az OmniRoute-ra WebSocket-támogatással rendelkező egyéni szolgáltató hozzáadásával a ~/.codex/config.toml fájlhoz (használjon külön CODEX_HOME értéket egy meglévő konfiguráció módosításának elkerüléséhez):
model = "gpt-5.5" # csupasz azonosító — NEM "codex/gpt-5.5"
model_provider = "omniroute"
[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1" # nincs záró perjel; a WS URL ebből származik (éles környezetben használjon https/wss protokollt)
wire_api = "responses" # 2026 februárja óta az egyetlen támogatott érték
supports_websockets = true # engedélyezi a Responses-WS átvitelt
env_key = "OMNIROUTE_API_KEY" # az OmniRoute API-kulcsot tartalmazza (Bearer)
export OMNIROUTE_API_KEY=sk-... # egy OmniRoute API-kulcs (bármely kulcs, ha REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
A CLI a base_url + /responses címet WebSocketté alakítja, az OmniRoute pedig továbbítja azt a kiválasztott codex OAuth-kapcsolathoz. A működést végponttól végpontig ellenőrizték a helyi szerverrel: a ChatGPT visszaadja a codex.rate_limits + response.created eseményeket, és streameli a kiegészítést.
Kvóták és problémák jelentése
| Metódus | Elérési út | Leírás |
|---|---|---|
| GET | /v1/quotas/check |
Kvóta előzetes ellenőrzése egy provider + accountId pároshoz regisztrált kulcs kiadása előtt |
| POST | /v1/issues/report |
Kvóta- vagy kulcskibocsátási hiba jelentése a GitHub felé (a GITHUB_ISSUES_REPO + token szükséges) |
Hitelesítés: Bearer API-kulcs (isAuthenticated).
Kvótamunkamenet helyreállítása (opt-in)
Egy nem streamelt POST /v1/chat/completions vagy POST /v1/responses kérés, amely
terminális kvótahibával (402/429/503, amelynek törzse szerint a kvóta vagy a kreditek kimerültek)
sikertelen, eltárolható és később újrajátszható ahelyett, hogy a hiba visszaadásra kerülne. A hívó
kérésenként, három fejléc használatával engedélyezheti ezt:
| Fejléc | Érték |
|---|---|
x-omniroute-quota-recovery |
auto |
x-omniroute-session |
munkamenet-azonosító, [A-Za-z0-9._:-]{1,128} |
x-omniroute-recovery-turn |
a munkameneten belül egyedi fordulóazonosító (ugyanez a szabály) |
Csak a stream: false beállítású, eszközök, eszközelőzmények vagy previous_response_id nélküli,
valamint x-omniroute-connection-pin nélküli fordulók jogosultak erre, továbbá a
STORAGE_ENCRYPTION_KEY változónak beállítva kell lennie (a kérés legfeljebb 24 órán át titkosítva
kerül tárolásra). A válasz ekkor 202, és tartalmazza a recovery.poll értéket; a lekérdezéshez
használd a GET /v1/quota-recoveries/{id} végpontot (202, amíg függőben van, 200 a
helyreállított törzzsel, amikor elkészült), vagy töröld a kérést a DELETE használatával. A jegyeket
csak az őket létrehozó API-kulcs láthatja. Ha egy újrajátszás kimenetele bizonytalan, az
needs_confirmation állapotban zárul, ahelyett hogy a kérés kétszer kerülne elküldésre.
Forrás: src/lib/quota/quotaSessionRecovery.ts.
Önkiszolgáló használat (/api/usage/om-usage)
Bármelyik API billentyű képes olvasni** a sajátja** használat és kvóták — nincs kezelési hitelesítés. Ez az a végpont, amelyet az ügyfél (CLI, a OmniCopilot panel) használ a kulcstulajdonosnak a költéseinek megjelenítésére.
# 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"
A kulcsnak meg kell lennie**allowUsageCommand** engedélyezve (alapértelmezés szerint kikapcsolva — az irányítópult API-kulcskezelője kulcsonként kapcsolja át). Enélkül a végpont 403 választ ad.
?format=json megkülönböztetett alakzatot ad vissza, így a hívó soha nem olvas le egy adatmezőt az elutasításról. A sikerről:
{
"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" /* … */ },
],
}
Visszautasításkor (401 rossz kulcs / 403 nem engedélyezett) ugyanaz az útvonal { "allowed": false, "error": { "message": "…" } } — adja vissza, a jelenlévő, de üres personal/provider (kulcs engedélyezett, még nem tanultunk semmit) különbözik az elutasítástól, és csak a JSON alak különbözteti meg őket.
Auth: a hívó saját Bearer API kulcsa, isValidApiKey — -vel érvényesítve ez nem a kezelőfelület (/api/keys/…), amely requireManagementAuth mögött marad.
Nyers vs. Cutoff-Adjusted kvótaszázalékok
/api/usage/om-usage fogyasztása során a hívóknak figyelniük kell a százalékok közötti különbségre** egyszerű szöveges kimenet** és a strukturáltJSON kimenet :
| Vonatkozás | Egyszerű szöveges formátum (/api/usage/om-usage / @@om-usage) |
JSON formátum (?format=json) |
|---|---|---|
| Kimeneti mező | NN% left (pl. 20% left) |
provider.quotas / providers[].quotas |
| Mérés | Levágással korrigált felhasználható pótlék : fennmaradó kapacitás a küszöbérték felett | Nyers upstream kvóta : korrigálatlan szolgáltatói mérés |
| Levágási méretezés | effectiveRemainingPercent() keresztül skálázva, így a védett tartalék 0% left ként jelenik meg |
Nincs (a szolgáltató által jelentett nyers pillanatkép értékek) |
| Küszöb adatok | Beépítve a megjelenített százalékba | Kapcsolatonként quotaWindowThresholds -ban tárolva (vagy a szerver alapértelmezett beállításaiban) |
| Elsődleges fogyasztó | Interaktív CLIs, terminál promptok, emberi operátorok | Automatikus integrációk, irányítópultok, elemzések, számlázási nyomkövetők |
A határérték beállítási képlete
OmniRoute támogatja a proaktív kvóta-lezárásokat, hogy megakadályozza az upstream kimerülést ( quotaWindowThresholds kapcsolaton, a szolgáltatói alapértelmezéseken vagy a globális rugalmassági beállításokon keresztül konfigurálva). Ha egy küszöbérték (pl. cutoff = 25%) aktív egy kvótaablakban, a szövegmegjelenítő a következőképpen számítja ki a fennmaradó ráhagyást:
- Ha
remaining <= cutoff:0%t adja vissza. - Ha
remaining > cutoff:((remaining - cutoff) / (100 - cutoff)) * 100t adja vissza.
A formázott szövegkimenet ezt a legközelebbi egész számra kerekíti (Math.round(...)).
Szemléltető példa
Fontolja meg a szolgáltatói ablakot** 60% nyers felhasználás** (ezért** 40% nyers maradék kvóta** ) és egy konfigurált** 25%-os maradék kvóta-lezárás** küszöb:
| Képviselet | Számítás | Többi | Impulzív használt |
|---|---|---|---|
Nyers JSON (?format=json) |
Felfelé irányuló pillanatkép (quotas[window]) |
40% | 60% |
Szövegformátum (NN% left) |
((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100 |
20% | 80% (ha 100 - remaining t számolunk) |
- Miért jelenik meg a szövegben a 20% maradt: A számlán maradt 40%-os fizikai kvótából 25%-ot a lezárási politika lefoglal. A hívó félnek csak 15%-a marad a 75%-ból, mielőtt az útválasztó leállítja az útválasztást ehhez a kapcsolathoz. A méretezés biztosítja, hogy a kapcsolati jelek kimerülése (
0% left) pontosan akkor történjen, amikor az útválasztás leáll. - Miért őrzi meg JSON a nyers értékeket: A JSON hasznos adata a pontos szolgáltatói pillanatképet (
UsageSnapshot) adja vissza, így a külső eszközök hozzáférhetnek az alapszintű upstream hasznosításhoz és a kapcsolatszintűquotaWindowThresholdsszerveroldali veszteséges skálázás nélkül.
Fogyasztói migrációs útmutató
Ha egy külső integráció (például egy szerkesztő beépülő modul vagy ügynökbővítmény) korábban lekaparta a szövegvégpontot (NN% left), és a használt százalékot 100 - NN ként számította ki, ?format=json re való átállás a következőket jelenti:
- A nyers JSON értékek olvasása tükrözni fogja** tényleges upstream fogyasztás** (a fenti példában használt 60%).
- Ha az integráció meg akarja őrizni a szövegvégpont felhasználható engedményes szemantikáját, ki tudja értékelni a hatékony fennmaradó képletet ügyféloldalon
quotaWindowThresholdshasználatával a kapcsolatszintű felülírásokhoz.
Szemantikus gyorsítótár
# Gyorsítótár-statisztikák lekérése
GET /api/cache/stats
# Minden gyorsítótár törlése
DELETE /api/cache/stats
Válaszpélda:
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
Késleltetésre gyakorolt hatás
A szemantikus gyorsítótár találata (HIT) a választ gyorsítótárból szolgálja ki upstream
hívás nélkül, ezért a jelentett X-OmniRoute-Response-Latency értéke közel nulla
(az eredeti upstream késleltetéstől függetlenül). A késleltetésre érzékeny klienseknek
(benchmarkok, p50/p99-monitorozás) ellenőrizniük kell az
X-OmniRoute-Cache-Latency válaszfejlécet:
| Érték | Jelentés |
|---|---|
synthetic |
A választ a gyorsítótár szolgáltatta ki; a késleltetés nem a tényleges upstream idő |
| (absent) | A válasz valódi upstream-hívásból származik |
Gyorsítótár megkerülése kulcsonként
Az API-kulcsok a cacheDefaultMode használatával letilthatják a szemantikus gyorsítótár olvasását:
| Érték | Működés |
|---|---|
legacy |
Normál gyorsítótár-viselkedés (alapértelmezett) |
bypass |
A gyorsítótár-keresés teljes kihagyása; mindig az upstream elérése |
Beállítás kulcs létrehozásakor (POST /api/keys) vagy frissítésekor (PATCH /api/keys/[id]):
{ "cacheDefaultMode": "bypass" }
Gyorsítótár megkerülése kérésenként
Bármely kérés megkerülheti a gyorsítótárat a kulcsbeállításoktól függetlenül:
X-OmniRoute-No-Cache: true
CLIProxyAPI-kezelési kompatibilitás
Az OmniRoute megválaszolja azt a három CLIProxyAPI
kezelési végpontot, amelyeket a használati irányítópultok a Claude- és Codex-előfizetések korlátainak
lekérdezésére hívnak (például a T3 Code cliproxy használatikorlát-forrása). Irányítsd a kliens
alap URL-címét az OmniRoute-ra, és használj manage hatókörrel rendelkező API-kulcsot kezelési kulcsként.
Az útvonalak a /v0/management/* és az /api/v0/management/* alatt érhetők el.
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /v0/management/auth-files |
Claude- és Codex-OAuth-kapcsolatok mint { files: [{ id, auth_index, provider, email, disabled, id_token }] }. Tokenek nélkül |
| POST | /v0/management/api-call |
Törzs: { auth_index, method, url, header?, data? }. Egy engedélyezőlistán szereplő kérést küld a fiók tokenjével, és { status_code, body } formátumban adja vissza |
| POST | /v0/management/reset-quota |
Törzs: { auth_index }. Törli egy fiók kapcsolatának várakozási idejét, modellzárolásait és a Codex hatókörönkénti várakozási időit |
- Az
auth_indexaz OmniRoute-kapcsolat azonosítója. Aproviderértékeclaudevagycodex(csak OAuth-kapcsolatok; azanthropicAPI-kulcs-szolgáltató nem szerepel a listában). A Codex esetében azid_token.chatgpt_account_ida tárolt munkaterület-azonosító, aplan_typepedig a tárolt csomag. - Az
api-callnem általános proxy. Csak a ClaudeGET https://api.anthropic.com/api/oauth/usageés a CodexGET https://chatgpt.com/backend-api/wham/usage,GET .../wham/rate-limit-reset-credits, valamintPOST .../wham/rate-limit-reset-credits/consumekéréseit fogadja el, és mindegyiket csak a megfelelő szolgáltatóhoz tartozó fiók esetében. Minden egyéb kérés403választ ad anélkül, hogy kapcsolatba lépne az upstreammel. A hívóAuthorizationfejléce (beleértve a$TOKEN$helyőrzőt) figyelmen kívül marad: az OmniRoute a kapcsolat hozzáférési tokenjét illeszti be, szükség esetén előtte frissítve azt, és csak az engedélyezőlistán szereplő fejléceket továbbítja (anthropic-beta;OpenAI-Beta,Originator,Chatgpt-Account-Id;Accept,Content-Type). A hiányzóChatgpt-Account-Idalapértelmezés szerint a tárolt munkaterület-azonosítót kapja. A kérések időkorlátja 15 másodperc, és a kapcsolat proxyját használják. - A
reset-quotaérintetlenül hagyja a végleges állapotokat (banned,expired,credits_exhausted). Az ismeretlenauth_index404választ ad.
Hitelesítés: irányítópult-munkamenet vagy manage hatókörrel rendelkező API-kulcs szükséges,
akkor is, ha a bejelentkezés le van tiltva (az útvonalak az ALWAYS_PROTECTED_API_PATHS részét képezik).
A csak következtetésre használható kulcsok 403 választ kapnak. Forrás:
src/lib/cliproxyCompat/managementApi.ts.
Irányítópult és kezelés
A kezelési útvonalak (/api/* kivéve a nyilvános auth/login) vannak** nem** közönséges következtetési API billentyűk által engedélyezett. Hitelesítőadat-családok, hatókörök és curl-példák: Kezelői hitelesítés.
Hitelesítés
| Végpont | Módszer | Leírás |
|---|---|---|
/api/auth/login |
POST | Bejelentkezés |
/api/auth/logout |
POST | Kijelentkezés |
/api/settings/require-login |
GET/POST | Bejelentkezési állapot (GET, nyilvános). POST beállítja a jelszót / átkapcsolja a bejelentkezést: operátor csak akkor, ha már létezik jelszó (műszerfali munkamenet, helyi CLI vagy bejelentkezés tiltva — API kulcsok és oma_ tokenek get 403); a műszerfali munkamenet currentPassword küld a jelszó lecserélésére |
Szolgáltató menedzsment
| Végpont | Módszer | Leírás |
|---|---|---|
/api/providers |
GET/POST | Szolgáltatók listázása / létrehozása |
/api/providers/[id] |
GET/PUT/DELETE | Szolgáltató kezelése |
/api/providers/[id]/test |
POST | Tesztelje a szolgáltatói kapcsolatot |
/api/providers/[id]/models |
GET | Sorolja fel a szolgáltatói modelleket |
/api/providers/validate |
POST | A szolgáltató konfigurációjának ellenőrzése |
/api/providers/bulk |
POST | API kulcsok tömeges hozzáadása ONE szolgáltatóhoz |
/api/providers/import |
POST | Heterogén szolgáltató LIST importálása elemzett CSV/JSON fájlból (#6836); soronkénti részhibás eredmények |
/api/provider-nodes* |
Különféle | Szolgáltatói csomópontok kezelése |
/api/provider-models |
GET/POST/PUT/PATCH/DELETE | Egyéni modellek és modellenkénti felülírások (hozzáadás, frissítés, hide/show, törlés) |
/api/provider-models/validate-and-add |
POST | Menedzsment által hitelesített, opt-in szigorú kapcsolati érvényesítés és atomi egyedi modell regisztráció; lásd a modell érvényesítése |
synced/imported modelleknél PUT /api/provider-models elfogadja provider, modelId és maxOutputTokenOverride: a pozitív egész szám beállítja a kézi kimeneti token korlátot, null pedig törli az alapértelmezett érték visszaállításához. GET /api/provider-models?provider=<provider> ezeket az értékeket adja vissza modelOutputOverrides-ban, beleértve az egyéni modellsor nélküli modelleket is. A felülírás a futásidejű max_output_tokens képességet használja, és túléli a modell-újraszinkronizálást. Az OpenAI-kompatibilis szolgáltatói oldal ugyanazokat a edit/clear vezérlőket kínálja, és megjelöli az explicit látástámogatással rendelkező modelleket.
Egy kompatibilis szolgáltatói csomóponton az írási útvonalak (POST, PUT, PATCH, DELETE és /api/provider-models/validate-and-add) a modellazonosítót csupasz upstream azonosítóként tárolják: egy előtaggal ellátott listából beillesztett azonosító esetén a csomópont saját előtagjának bármely vezető verem összeomlott, és a válaszok a tárolt azonosítót visszhangozzák. A kanonikus szolgáltatók vágott azonosítóit (pl. nvidia/nemotron-…) a rendszer szó szerint tárolja. /v1/models soha nem ad ki halmozott <prefix>/<prefix>/<model> azonosítót.
Az egyéni csevegés befejezési csomópontjai az explicit indoklási leiratkozásokat igazítják az upstream háttérrendszerhez. A sikeres kapcsolódási teszt automatikusan kiválasztja a chat-sablon vezérlőket minden olyan pontos ID modellhez, amelynek /models bejegyzése felismert owned_by értéket igazol: vllm, sglang vagy llamacpp. Az átlátszó OpenAI-kompatibilis burkolók megőrizhetik az eredeti modellbejegyzést egy beágyazott openai objektumon belül; az észlelés legfeljebb három ilyen borítékot követ. A hiányzó, ismeretlen vagy ütköző tulajdonjoggal rendelkező modellek megtartják a szokásos OpenAI viselkedést. Az észlelés újra felhasználja a meglévő katalóguskérelmet, nem hoz létre befejezési jogkivonatokat, és érvénytelenítésre kerül, ha a kapcsolat végpontja megváltozik.
Egy olyan háttérrendszer viselkedésének rögzítéséhez, amely nem teszi közzé ezeket a metaadatokat, használja a meglévő API részleges szolgáltatói frissítést:
{
"providerSpecificData": {
"reasoningControl": "chat-template"
}
}
Küldd el azt a testet PUT /api/providers/<connection-id> val. Ezen a kapcsolaton a none explicit gondolkodási erőfeszítése chat_template_kwargs.thinking=false és chat_template_kwargs.enable_thinking=false néven kerül elküldésre. Az explicit natív sablonértékek mérvadóak maradnak, hacsak egy szerveroldali érvelési szabály nem kényszerít rá. A beállítás csak akkor érvényes, ha egy egyéni OpenAI-kompatibilis kapcsolat küldi el a Chat Completions törzset; A válaszkérések és a normál szolgáltatók megtartják natív kérésformájukat. Állítsa reasoningControl openai -re a normál OpenAI reasoning_effort áthárítás kényszerítéséhez, vagy hagyja ki it/set null -re az automatikus észlelés használatához.
Claude kód automatikus módú osztályozója az alapértelmezett natív gondolkodás letiltását kéri, ha nem tartalmaznak kifejezett érvelési vezérlőket. Az észlelés az osztályozó rendszerjelölőjét használja a Claude-formátumú kérésekben, nem pedig a modellneveket vagy a befejezési korlátokat. Az explicit törzsvezérlők, a támogatott effort/thinking fejlécek, az útválasztási szabályok és a megoldott modell-erőfeszítések megtartják meglévő prioritásukat. Mindkét osztályozó szakasz megtartja a promptokat, a befejezési korlátokat, a leállítási szekvenciákat és a valós upstream engedélyezési ítéleteket; a második szakasz még közönséges szövegként tudja előállítani a kért látható érvelését.
OAuth Flows
| Végpont | Módszer | Leírás |
|---|---|---|
/api/oauth/[provider]/[action] |
Különféle | Szolgáltató-specifikus OAuth |
Routing & Config
| Végpont | Módszer | Leírás |
|---|---|---|
/api/models |
GET/PUT | Modelllista / alias frissítése |
/api/models/alias |
GET/POST | Modellálnevek |
/api/models/catalog |
GET | Minden modell szolgáltató szerint + típus |
/api/combos* |
Különféle | Kombinált menedzsment |
/api/keys* |
Különféle | API kulcskezelés |
/api/pricing |
GET | Modell árképzés |
Modell határ eredet
GET /api/models?withLimits=1 (szintén true; 0/false, vagy kihagyásával az alapértelmezett hasznos terhelés változatlan marad) minden modellsorhoz hozzáadja contextWindow, maxInputTokens, maxOutputTokens és egy capsSource objektumot. capsSource megnevezi az egyes limiteket biztosító szabályt, így egy meglepő határérték (például 128k egy 1M modellen) eredetére vezethető vissza. A feloldott értékek ugyanazok, amelyeket az útválasztás használ; a zászló csak mezőket ad hozzá, és soha nem változtat értéket. Minden más withLimits értéket a 400 visszautasít.
capsSource érték |
Származás |
|---|---|
override:context |
Tartós környezet-ablak felülírás (model_context_overrides) |
override:max_input / override:max_output |
Folyamatos max_input_tokens / max_output_tokens képesség felülírása |
static-authoritative:<provider>/<model> |
Statikus mérvadó környezeti ablaktábla |
synced:<provider>/<model> |
models.dev szinkronizált képességek sora |
registry:<provider>/<model> |
Szolgáltató nyilvántartási bejegyzése |
spec:<model> |
Statikus modell specifikáció |
effort-base: előtag |
A sor egy erőfeszítés-utótagú változat alapmodelljéből kölcsönzött |
none |
Egyetlen forrás sem deklarálja a határértéket (az érték null) |
Megvalósítás: getResolvedModelCapabilitiesWithLimitSources() src/lib/modelCapabilities.ts -ben és a precedencialáncok src/lib/modelCapabilityLimits.ts ben.
Használat és elemzések
| Végpont | Módszer | Leírás |
|---|---|---|
/api/usage/history |
GET | Használati előzmények |
/api/usage/logs |
GET | Használati naplók |
/api/usage/request-logs |
GET | Kérelem szintű naplók |
/api/usage/[connectionId] |
GET | Csatlakozásonkénti használat |
/api/usage/token-limits |
GET/POST/DELETE | API-kulcsonkénti token-limit költségkeretek |
/api/usage/model-latency-stats |
GET | Gördülő per-provider/model késleltetési aggregátum (avg/p50/p95/p99, sikerességi arány); szűrők: windowHours/minSamples/maxRows/provider/model (#6873) |
/api/usage/cache-health |
GET | A gyorsítótár állapotának összefoglalója call_logs — write/read arány, p50/p90/p99 írási méret eloszlás, a nehéz írási koncentráció, a modellenkénti felosztás és a healthy/degraded/thrash/no-data ítélet alapján; params range (1h| 24h| 7d| 30d, alapértelmezett 24h) és opcionális model (#8827) lekérdezése |
API kulcsengedélyek
PATCH /api/keys/{id} frissíti a meglévő kulcsok engedélyeit. Mint minden /api/keys* útvonalnak, ehhez felügyeleti jogosultságra van szüksége (lásd: Kezelői hitelesítés ), nem pedig következtetési kulcsra. Csak a módosítani kívánt mezőket küldje el; az egyik kérést sem utasítja el No valid fields to update. Az elfogadott mezőket updateKeyPermissionsSchema határozza meg src/shared/validation/schemas/keys.ts-ben.
| Mező | Írja be | Megjegyzések |
|---|---|---|
name |
karakterlánc, 1-200 karakter | |
isActive |
logikai érték | |
isBanned |
logikai érték | |
expiresAt |
ISO 8601 datetime vagy null |
null törli a lejáratot |
modelAccessMode |
all | restricted |
allowedModels üresnek kell lennie, ha a mód all |
allowedModels, blockedModels |
karakterláncok tömbje, 1000-ig | |
allowedCombos |
karakterláncok tömbje, legfeljebb 500 | Kapuk, amelyek kombinációit a kulcs hívhatja; a közvetlen modelleket a modelAccessMode / allowedModels szabályozza |
connectionAccessMode |
all | restricted |
allowedConnections nem lehet üres, ha restricted és üres, ha all |
allowedConnections |
UUIDs tömb, 100-ig | |
allowAutoCombos |
logikai érték | false ezzel a kulccsal elutasítja auto/* modellekre vonatkozó kéréseket; olyan kulcsok engedélyezettek, amelyek soha nem állítják be |
catalogScope |
all | combos | models |
Mit jelenít meg GET /v1/models ehhez a kulcshoz (csak kombók, csak modellek vagy mindkettő); ez nem változtat azon, hogy a kulcs mit hívhat |
forcedModel |
legfeljebb 300 karakter hosszúságú karakterlánc vagy null |
A csevegési kéréseket erre model/combo irányítja X-Route-Model és body.model felett; a kulcs korlátai továbbra is érvényesek |
noLog, autoResolve |
logikai érték | |
throttleDelayMs |
egész szám, 0-300000 | |
maxSessions |
egész szám, 0-10000 | |
rateLimits |
{ limit, window } (pozitív egész számok, legfeljebb 50) vagy null tömbje |
null tisztázza a határokat |
accessSchedule |
ütemezési objektum vagy null |
null törli a menetrendet |
scopes |
karakterláncok tömbje, legfeljebb 32 | |
allowedEndpoints |
karakterláncok tömbje, legfeljebb 20 | |
streamDefaultMode |
legacy | json |
|
cacheDefaultMode |
legacy | bypass |
Lásd: Kulcsonkénti gyorsítótár megkerülése |
compressionEnabled |
logikai érték | |
codexServiceMode |
az egyik Codex szolgáltatási mód | |
disableNonPublicModels |
logikai érték | |
allowUsageCommand |
logikai érték | |
usageLimitEnabled |
logikai érték | |
dailyUsageLimitUsd, weeklyUsageLimitUsd |
szám >= 0 vagy null |
|
fiveHourUsageLimitUsd |
szám >= 0 vagy null |
Gördülő 5 órás USD költségvetés, a napi és heti limitekhez hasonlóan (usageLimitEnabled, UNPRICED_USAGE_BUDGET_POLICY) érvényesítve. retry-after az az idő, amikor a legrégebbi költés az ablakban lejár, ami miatt a korlátot jóval meghaladó kulcs továbbra is blokkolva maradhat. |
chaosModeEnabled |
logikai érték |
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
-H "Authorization: Bearer <management-credential>" \
-H "Content-Type: application/json" \
-d '{ "allowAutoCombos": false, "catalogScope": "combos" }'
Beállítások elemre
| Végpont | Módszer | Leírás |
|---|---|---|
/api/settings |
GET/PUT/PATCH | Általános beállítások. A biztonsági kulcsokhoz (requireLogin, newPassword, oidc*, corsOrigins, bruteForceProtection) currentPassword és operátori hitelesítő adatok szükségesek — API kulcsok és oma_ tokenek 403; minden mutációnak szüksége van a admin hozzáférési token hatókörére |
/api/settings/proxy |
GET/PUT | Hálózati proxy konfig |
/api/settings/proxy/test |
POST | Proxy kapcsolat tesztelése |
/api/settings/ip-filter |
GET/PUT | IP allowlist/blocklist |
/api/settings/thinking-budget |
GET/PUT | Thinking/reasoning** kér** átírási mód (passthrough / auto-strip / custom / adaptive). Független a tömörítéstől. Lásd THINKING_BUDGET.md fájlt. |
/api/settings/system-prompt |
GET/PUT | Globális rendszerkérdés |
/api/settings/compression |
GET/PUT | Globális tömörítési konfiguráció |
/api/settings/purge-request-history |
POST | Törölje a kérésnapló-sorokat és a helyi hívásnapló-műtermékeket |
Kontextus és tömörítés
| Végpont | Módszer | Leírás |
|---|---|---|
/api/compression/preview |
POST | off/lite/standard/aggressive/ultra/RTK/stacked tömörítés előnézete |
/api/compression/language-packs |
GET | Sorolja fel az elérhető Caveman nyelvi csomagokat |
/api/compression/rules |
GET | Sorolja fel a Caveman-szabály metaadatait |
/api/context/caveman/config |
GET/PUT | Caveman-specifikus beállítások álnév |
/api/context/rtk/config |
GET/PUT | RTK-specifikus beállítások, beleértve az egyéni szűrőket és a nyers kimenet megőrzését |
/api/context/rtk/filters |
GET | RTK szűrőkatalógus és egyedi szűrődiagnosztika |
/api/context/rtk/test |
POST | Futtassa RTK preview/test egy szöveges rakomány ellen |
/api/context/rtk/raw-output/[id] |
GET | A megőrzött szerkesztett nyers kimenet beolvasása mutatóazonosítóval |
/api/context/combos |
GET/POST | Kompressziós kombó list/create |
/api/context/combos/[id] |
GET/PUT/DELETE | Kompressziós kombó detail/update/delete |
/api/context/combos/[id]/assignments |
GET/PUT | Tömörítési kombókat rendelhet az útválasztási kombókhoz |
/api/context/analytics |
GET | Tömörítési elemzési álnév |
Monitoring
| Végpont | Módszer | Leírás |
|---|---|---|
/api/sessions |
GET | Aktív munkamenet-követés |
/api/rate-limits |
GET | Számlánkénti kamatkorlátok |
/api/monitoring/health |
GET | Az állapotfelmérés + szolgáltató összefoglalója (catalogCount, configuredCount, activeCount, monitoredCount). A kezelési nézet tartalmazza credentialHealth: probe-cache skalárokat, failedConnections amikor failed>0 és staleDbNonOkCount (SQLite ragadós test_status, nem a mérőeszköz ). Lásd MONITORING_GUIDE.md fájlt. |
/api/cache/stats |
GET/DELETE | Gyorsítótár statisztika / törlés |
/api/modality-bridge/stats |
GET | Memórián belüli attempts, sikerek/bridged, meghibásodások, gyorsítótár találatai, totalLatencyMs, latencySamples, mintaalapú averageLatencyMs és utolsó használat ideje (reset újraindításkor; kezelési hitelesítés) |
/api/modality-bridge/video/runtime |
GET | Szigorú megbízható visszacsatolási ellenőrzés a menedzsment előtt auth/probe; fertőtlenített FFmpeg/ffprobe elérhetőség és verziók (bolt nélkül) |
/api/modality-bridge/video/extract |
POST | Belső hitelesített, megbízható visszacsatolású bájtközvetítő; 50 MiB bemenet, korlátos queue/32 MiB kimenet, 503 kapacitás, 499 leválasztás, 504 határidő; nem nyilvános feltöltés API |
Videó képkocka lefúrása
GET /api/v1/video-bridge/drilldown beolvas egy bérlőhöz kötött átlátszatlan leírót, amely x-omniroute-video-drilldown ben kapott vissza egy kifejezetten jóváhagyott Video Bridge kérés után. Mind az olvasáshoz, mind DELETE mindig érvényes API kulcsra és az operátor független modalityBridgeVideoDrilldownRemoteEnabled engedélyére van szükség. A termelés megtartásához emellett modalityBridgeVideoDrilldownEnabled és szigorú alkatrészenkénti drilldown: true is szükséges. Ha a kulcsnak nincs üres végpont-engedélyezőlistája, akkor video is tartalmaznia kell GET és DELETE esetében, függetlenül attól, hogy a hívó /v1 vagy /api/v1 használja.
GET lekérdezés: kötelező handle; opcionális variant (preview, standard, detail), limit (1–8; az örökölt frames elfogadott, de nem kombinálható limit vel), nulla alapú page és start/end másodperc. Ha mindkét fókuszhatár meg van adva, end nagyobbnak kell lennie, mint start. Duplicate/unknown lekérdezési kulcsok elutasítva. A sikeres válaszok a következőket tartalmazzák: derivation, durationSeconds, frames, hasMore, page, variant és opcionális focusWindow; A no-store JSON 32 MiB felső határa, beleértve a Base64-et is. Túlméretezett kimenet 413; kérjen kevesebb képkockát.
DELETE /api/v1/video-bridge/drilldown?handle=... { "removed": 0|1 } adja vissza. Az ismeretlen, lejárt és keresztkulcsos GETs válaszok megkülönböztethetetlenek; keresztbillentyűs DELETE nem tudja eltávolítani a tulajdonos bejegyzését. A letiltott hozzáférés 403-at, missing/invalid hitelesítést 401, az érvénytelen lekérdezéseket 400, a törlést 499 és az 503-as ideiglenes hibákat adja vissza. A fogantyúk folyamat-helyiek, tíz perc után lejárnak, és nem élik túl az újraindítást. Az új leírók v1. és egy 32 bájtos véletlenszerű Base64URL tokent használják; csak a token hashek maradnak meg. A régi 64 hexadecimális tokenek szintaktikailag olvashatóak maradnak a kompatibilitás érdekében. Tekintse meg a Video Bridge védőkorlátjait a beleegyezés, a kvóták és a változatok származtatásának részleteiért.
Biztonsági mentés és Export/Import
| Végpont | Módszer | Leírás |
|---|---|---|
/api/db-backups |
GET | Sorolja fel az elérhető biztonsági másolatokat |
/api/db-backups |
PUT | Készítsen manuális biztonsági mentést |
/api/db-backups |
POST | Visszaállítás egy adott biztonsági másolatból |
/api/db-backups |
PATCH | Biztonsági mentés megőrzési beállításainak mentése (csak kezelő számára) |
/api/db-backups |
DELETE | A tárolt biztonsági másolatok visszavágása a megőrzési beállításokra (csak kezelő) |
/api/db-backups/export |
GET | Adatbázis letöltése .sqlite fájlként |
/api/db-backups/import |
POST | Töltsön fel .sqlite fájlt az adatbázis lecseréléséhez (csak ?dryRun=true érvényesítése) |
/api/db-backups/exportAll |
GET | Töltse le a teljes biztonsági másolatot .tar.gz archívumként |
/api/db-backups/export, /api/db-backups/exportAll és /api/settings/export-json minden tárolt hitelesítő adatot kiosztanak, ezért szükség van a műszerfali munkamenetre vagy a helyi CLI (vagy letiltva a bejelentkezést). A tetszőleges hatókörű API kulcsok és oma_ hozzáférési tokenek 403 kapnak. A visszaállítások ugyanazt a határt követik: POST /api/db-backups/import (beleértve dryRun=true ), POST /api/db-backups (helyreállítás azonosító alapján) és POST /api/settings/import-json lecseréli az élő adatbázist vagy a beállításokat, így a gép hitelesítő adatai is megkapják 403 ; omniroute sync import elküldi a helyi CLI hitelesítő adatokat. Így tesz DELETE /api/db-backups (mentett biztonsági másolatok metszése) és PATCH /api/db-backups (megőrzési beállítások: a megmaradt értékek hajtják végre az automatikus metszést minden mentés után). A listázás (GET) és a kézi biztonsági mentés (PUT) létrehozása megőrzi a szokásos felügyeleti hitelesítést.
Cloud Sync
| Végpont | Módszer | Leírás |
|---|---|---|
/api/sync/cloud |
Különféle | Felhő szinkronizálási műveletek |
/api/sync/initialize |
POST | Szinkronizálás inicializálása |
/api/cloud/* |
Különféle | Felhőkezelés |
Alagutak
| Végpont | Módszer | Leírás |
|---|---|---|
/api/tunnels/cloudflared |
GET | Olvassa el Cloudflare Quick Tunnel install/runtime állapotát az irányítópulthoz |
/api/tunnels/cloudflared |
POST | A Cloudflare Quick Tunnel (action=enable/disable) engedélyezése vagy letiltása |
/api/tunnels/ngrok |
GET | Olvassa el ngrok Tunnel futásidejű állapotát az irányítópulthoz |
/api/tunnels/ngrok |
POST | A ngrok alagút (action=enable/disable) engedélyezése vagy letiltása |
CLI Tools
| Végpont | Módszer | Leírás |
|---|---|---|
/api/cli-tools/claude-settings |
GET | Claude CLI állapot |
/api/cli-tools/codex-settings |
GET | Codex CLI állapot |
/api/cli-tools/droid-settings |
GET | Droid CLI állapot |
/api/cli-tools/openclaw-settings |
GET | OpenClaw CLI állapot |
/api/cli-tools/runtime/[toolId] |
GET | Általános CLI futási idő |
CLI válaszok a következők: installed, runnable, command, commandPath, runtimeMode, reason.
ACP ügynökök
| Végpont | Módszer | Leírás |
|---|---|---|
/api/acp/agents |
GET | Sorolja fel az összes észlelt ügynököt (beépített + custom) állapottal |
/api/acp/agents |
POST | Egyéni ügynök hozzáadása vagy észlelési gyorsítótár frissítése |
/api/acp/agents |
DELETE | Egyéni ügynök eltávolítása id lekérdezési paraméterrel |
GET válasz tartalmazza agents[] (azonosító, név, bináris, verzió, telepített, protokoll, isCustom) és summary (teljes, telepített, notFound, builtIn, egyéni).
Rugalmassági és sebességhatárok
| Végpont | Módszer | Leírás |
|---|---|---|
/api/resilience |
GET/PATCH | Get/update kérési sor, kapcsolat lehűlés, szolgáltató megszakító és várakozási beállítások |
/api/resilience/reset |
POST | Állítsa vissza a szolgáltató megszakítóit |
/api/resilience/model-cooldowns |
GET | Listázza az aktív (szolgáltatónkénti, kapcsolati, modellenkénti) kizárásokat, hátralévő idő szerint rendezve |
/api/resilience/model-cooldowns |
DELETE | Törölje le a modellzár — test {provider, model} vagy {all: true} mindent törölni |
/api/rate-limits |
GET/POST | Fiókonkénti kamatkorlát állapot (GET) vagy kapcsolja be a rátakorlát védelmét egy kapcsolathoz (POST {connectionId, enabled}). Támogatott írási útvonal rateLimitProtection számára (soha nem módosítva PUT /api/providers/[id] segítségével). Megjegyzés: enabled: false letiltja az explicit védelmet, de nem választja ki az aktív API-kulcsos kapcsolatot a globális automatikus engedélyezési biztonsági hálóból (autoEnableApiKeyProviders). |
/api/rate-limit |
GET | Globális díjkorlát konfiguráció (elavult; álneve /api/rate-limits) |
Mind a négy
/api/resilience/*útvonal megköveteli** menedzsment hitelesítés** (requireManagementAuth). A rugalmasság (kiterjesztett) című témakörben a szolgáltatói megszakítás és a kapcsolat lehűlése és a modellzárás teljes lebontása található.
Evals
| Végpont | Módszer | Leírás |
|---|---|---|
/api/evals |
GET/POST | Eval suites listázás / kiértékelés futtatása |
Irányelvek
| Végpont | Módszer | Leírás |
|---|---|---|
/api/policies |
GET/POST/DELETE | Útválasztási házirendek kezelése |
Megfelelés
| Végpont | Módszer | Leírás |
|---|---|---|
/api/compliance/audit-log |
GET | Megfelelőségi ellenőrzési napló (utolsó N) |
v1beta (Gemini-kompatibilis)
| Végpont | Módszer | Leírás |
|---|---|---|
/v1beta/models |
GET | Sorolja fel a modelleket Gemini formátumban |
/v1beta/models/{...path} |
POST | Gemini generateContent végpont |
Ezek a végpontok GeminiAPI formátumát tükrözik azon ügyfelek számára, akik natív Gemini SDK kompatibilitást várnak el.
Belső / Rendszer APIs
| Végpont | Módszer | Leírás |
|---|---|---|
/api/init |
GET | Háttér szinkronizálási szolgáltatások indítása (felügyeleti hitelesítés) |
/api/tags |
GET | Ollama-kompatibilis modellcímkék ( Ollama ügyfelek számára) |
/api/restart |
POST | Indítsa el a kecses szerver újraindítást |
/api/shutdown |
POST | Indítsa el a kecses szerverleállást |
/api/system/env/repair |
POST | Javítsa meg OAuth szolgáltató környezeti változóit |
/api/system/version |
GET | Current/latest verzió, frissítés állapota, kiadási csatorna |
/api/system/version |
POST | Indítson el egy üzembe helyezés-tudatos frissítést a legújabb verzióra |
Jegyzet: Ezeket a végpontokat a rendszer belsőleg vagy Ollama -kliens-kompatibilitás érdekében használja. Általában nem hívják a végfelhasználók.
OAuth környezet javítása (v3.6.1 +)
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
Kijavítja a hiányzó vagy sérült OAuth környezeti változókat egy adott szolgáltatónál. Visszaküldés:
{
"success": true,
"repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
"backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}
Verzió és kiadási csatorna
GET /api/system/version
Csak visszahurkolt felügyeleti útvonal (admin auth). Visszaadja a futó verziót, a legújabb közzétett verziót és az automatikus frissítés állapotát. releaseChannel és channels additív mezők (3.8.54-es sín); channel megtartja jelentését — az irányítópult-frissítő által használt központi telepítési mód (npm, source vagy 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" }
}
- A futó build
releaseChannel— npm csatornája:nightly-nightly.*verziókhoz,nexta többi előzetes kiadáshoz (-rc.*,-beta.*,-alpha.*),ltschannels.latest-nál régebbi fő stabil verziójához, egyébkéntlatest. Ugyanazok a szabályok, mintscripts/release/dist-tag.mjsesetében, amely a közzétételkor választja ki az npm dist-címkét. channels— közzétette az egyes dist-címkék fejrészétnpm view omniroute dist-tagsből (regiszter HTTP tartalék), ugyanazzal a 10 perces TTL gyorsítótárban, mintlatest.latestmindig jelen van (visszaesik alatestmezőbe, majd"unavailable");next,nightlyésltscsak akkor jelennek meg, ha a dist-tag létezik. ACache-Control: no-cachekérés mindkét keresést frissíti.
A csatornamodellt (latest = v3 a 4.0 GA ig, next = rc, nightly = develop buildek, lts = v3 javítások a 4.0 GA után) docs/ops/RELEASE_STRATEGY.md írja le.
Hangátirat készítése
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
Hangfájlok átírása bármely konfigurált STT-szolgáltató használatával. Az első útvonalszegmens a natív szolgáltatót választja ki (openai/…, deepgram/…). Azok az átjárók, amelyek egy másik gyártó modelljét teszik elérhetővé, minősített azonosítót használnak
(openrouter/deepgram/nova-3).
Kérés:
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "file=@recording.mp3" \
-F "model=openai/whisper-1"
Válasz:
{
"text": "Hello, this is the transcribed audio content.",
"task": "transcribe",
"language": "en",
"duration": 12.5
}
Példa modellazonosítók: openai/whisper-1 (OpenAI-kulcs szükséges),
openrouter/deepgram/nova-3 (OpenRouter-kulcs szükséges),
deepgram/nova-3 (natív Deepgram-kulcs szükséges). Egy önálló
deepgram/nova-3 kérés nem használja az OpenRoutert.
Támogatott formátumok: mp3, wav, m4a, flac, ogg, webm.
Gemini Live (gemini/gemini-3.5-transcribe-live): fájlalapú átírás a Gemini Live
WebSocketen keresztül (Gemini API-kulcs szükséges). A feltöltött fájl ffmpeg használatával 16 kHz-es monó PCM-re lesz átalakítva
(PATH-on elérhetőnek kell lennie, kivéve, ha a fájl már eleve 16 kHz-es monó PCM WAV), majd a munkamenetbe kerül továbbításra, és
a véglegesített szöveg { "text": "..." } formátumban kerül visszaadásra. Az opcionális language és prompt űrlapmezők továbbításra kerülnek. Korlátok: a 25 MiB-nál nagyobb feltöltések, illetve a 10 percnél hosszabb dekódolt hanganyagok esetén a válasz
413; a 60 másodpercnél tovább futó átalakítás leállításra kerül, és a válasz
504. Az API-kulcs csak az x-goog-api-key fejlécben kerül elküldésre, a WebSocket URL-jében soha.
Ollama-kompatibilitás
Az Ollama API-formátumát használó kliensekhez:
# Chat-végpont (Ollama-formátum)
POST /v1/api/chat
# Modellek listázása (Ollama-formátum)
GET /api/tags
A kérések automatikusan átalakulnak az Ollama és a belső formátumok között.
Tokenizált VS Code- és fejléc nélküli aliasok
Ezeket az aliasokat akkor használja, ha egy integráció nem tud Authorization fejlécet
beilleszteni, és az API-kulcsot az alap URL-be kell ágyaznia.
# OpenAI-stílusú katalógusalias
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# OpenAI-stílusú csevegési aliasok
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Ollama-stílusú aliasok
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
Példa:
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"}]}'
Megjegyzések:
- A tokenizált aliasok ugyanazokat a kezelőket használják, mint a
/v1/*és az/api/tags; a válaszok struktúrája változatlan marad. - Amikor a kliens támogatja az egyéni fejléceket, részesítse előnyben az
Authorization: Bearer ...használatát. - Az URL-alapú tokenek megjelenhetnek a fordított proxyk naplóiban, a böngészési előzményekben és az OmniRoute-on kívüli telemetriában. Ezeket kompatibilitási lehetőségként kezelje, ne alapértelmezett hitelesítési módként.
Telemetria
# Késleltetési telemetria összesítése (p50/p95/p99 szolgáltatónként)
GET /api/telemetry/summary
Válasz:
{
"providers": {
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
}
}
Költségkeret
# Költségkeret állapotának lekérése az összes API-kulcshoz
GET /api/usage/budget
# Költségkeret beállítása vagy frissítése
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"
}
Sémamegjegyzések (
setBudgetSchema): azapiKeyIdkötelező; adailyLimitUsd,weeklyLimitUsdvagymonthlyLimitUsdmezők közül legalább egyiknek nullánál nagyobbnak kell lennie. Opcionális mezők:warningThreshold(0–1),resetInterval(daily|weekly|monthly),resetTime(HH:MM). A régi{keyId, limit, period}struktúra400 Bad Requestválaszt ad.
Tokenkorlátok
API-kulcsonkénti token-keretek (elkülönülnek a fent ismertetett, USD-alapú kerettől). A kérési útvonalon közvetlenül érvényesülnek: amikor egy kulcs aktuális időablakbeli használata eléri a korlátját, a kéréseket a rendszer 429 Too Many Requests hibával elutasítja. A korlátok egy adott model-hez vagy provider-hez rendelhetők, illetve a kulcs egészére, global módon alkalmazhatók; ha egy kérésre több korlát is illeszkedik, a legszigorúbb érvényesül.
# Egy kulcs tokenkorlátjainak listázása (az aktuális időablakbeli használatot is tartalmazza)
GET /api/usage/token-limits?apiKeyId=key-123
# Tokenkorlát létrehozása vagy frissítése
POST /api/usage/token-limits
Content-Type: application/json
{
"apiKeyId": "key-123",
"scopeType": "model",
"scopeValue": "openai/gpt-4o",
"tokenLimit": 1000000,
"resetInterval": "monthly",
"enabled": true
}
# Tokenkorlát törlése azonosító alapján
DELETE /api/usage/token-limits?id=tl-abc
Sémamegjegyzések (
setTokenLimitSchema): AzapiKeyIdés ascopeType(model|provider|global) kötelező. AscopeValuekötelező, kivéve, ha ascopeTypeértékeglobal(például modellazonosítómodelhatókör, szolgáltatóazonosító pedigproviderhatókör esetén). AtokenLimitértékének pozitív egész számnak kell lennie (szövegből átalakítva). Opcionális mezők:id(létrehozáskor hagyja ki, frissítéskor adja meg),resetInterval(daily|weekly|monthly, alapértelmezés:monthly),resetTime(HH:MM),enabled(alapértelmezés:true). AGETválaszai minden korlátot kiegészítenek a következőkkel:tokensUsed,remaining,windowStart,periodStartAtésnextResetAt. Ez kezelési osztályú végpont (a hitelesítést központilag az authz-folyamat kényszeríti ki).
Kérésfeldolgozás
- Az ügyfél kérést küld a
/v1/*címre - Az útvonalkezelő meghívja a
handleChat,handleEmbedding,handleAudioTranscriptionvagyhandleImageGenerationfüggvényt - A rendszer feloldja a modellt (közvetlen szolgáltató/modell vagy alias/kombináció alapján)
- A hitelesítő adatokat a helyi adatbázisból választja ki, a fiók elérhetősége szerinti szűréssel
- Csevegés esetén a
handleChatCoreellenőrzi a szemantikai/aláírás-alapú gyorsítótárat, és feloldja a kombináció tömörítési beállításait - Ha engedélyezve van, a proaktív tömörítés a szolgáltatóra történő fordítás előtt fut le (
lite, Caveman, RTK vagy egymásra építve) - A szolgáltatói végrehajtó elküldi a kérést a felsőbb szintű szolgáltatónak
- A válasz vissza lesz fordítva az ügyfél formátumára (csevegés esetén), vagy változatlanul kerül visszaadásra (beágyazások/képek/hang esetén)
- A rendszer rögzíti a használatot, a tömörítési elemzéseket és a kérési naplókat
- Hiba esetén a tartalékmechanizmus a kombinációs szabályok szerint lép működésbe
Teljes architektúra-hivatkozás: ARCHITECTURE.md
Kombinációk kezelése
A magasabb szintű útválasztási kombinációk (amelyekről az /api/combos* alatt már készült összefoglaló) modellazonosító-minta alapján 1:1-ben is leképezhetők, így egy OpenAI-stílusú modellazonosító átlátható módon átirányítható egy kombinációra.
| Method | Path | Description |
|---|---|---|
| GET | /api/model-combo-mappings |
Az összes modell→kombináció-leképezés listázása |
| POST | /api/model-combo-mappings |
Leképezés létrehozása — törzs: {pattern, comboId, priority?, enabled?, description?} |
| GET | /api/model-combo-mappings/[id] |
Egyetlen leképezés lekérése |
| PUT | /api/model-combo-mappings/[id] |
Egy meglévő leképezés mezőinek frissítése |
| DELETE | /api/model-combo-mappings/[id] |
Egy leképezés eltávolítása |
Hitelesítés: kezelési munkamenet/API-kulcs (requireManagementAuth).
Webhookok
Kimenő webhook-előfizetések az OmniRoute eseményeihez (kérés befejezése, kvóta kimerülése, kulcsrotáció stb.).
| Method | Path | Description |
|---|---|---|
| GET | /api/webhooks |
Webhookok listázása (a titkos kulcsok maszkolva jelennek meg: <prefix>...) |
| POST | /api/webhooks |
Webhook létrehozása — törzs: {url, events?: ["*"], secret?, description?} |
| GET | /api/webhooks/[id] |
Webhook lekérése |
| PUT | /api/webhooks/[id] |
Az url/events/secret/description frissítése |
| DELETE | /api/webhooks/[id] |
Webhook eltávolítása |
| POST | /api/webhooks/[id]/test |
Tesztadatküldés a webhook URL-jére, majd a kézbesítés állapotának visszaadása |
Hitelesítés: kezelési munkamenet/API-kulcs (requireManagementAuth).
Regisztrált kulcsok (automatikus kezelés)
Az automatikus kulcskezelő alrendszer használja API-kulcsok kibocsátására és rotálására egy háttérszolgáltató/-fiók ellenében, napi/óránkénti kvótákkal.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/registered-keys |
Regisztrált kulcsok listázása (csak a maszkolt előtag) |
| POST | /api/v1/registered-keys |
Új regisztrált kulcs kibocsátása — törzs: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. A nyers kulcsot egyszer adja vissza. Kvótaelutasítás esetén 429 értéket ad vissza. |
| GET | /api/v1/registered-keys/[id] |
Egy regisztrált kulcs metaadatainak lekérése (nyers kulcsanyag nélkül) |
| DELETE | /api/v1/registered-keys/[id] |
Regisztrált kulcs visszavonása |
| POST | /api/v1/registered-keys/[id]/revoke |
Explicit visszavonási végpont (ugyanaz a hatása, mint a DELETE-nek) |
Hitelesítés: kezelési munkamenet/API-kulcs (requireManagementAuth) — ugyanaz az ellenőrzés, mint a /api/keys esetében: dashboard-munkamenet, helyi CLI-token vagy manage/admin hatókörrel rendelkező API-kulcs; csak következtetésre használható API-kulcsok 403 hibát kapnak. Lásd még: /v1/quotas/check és /v1/issues/report.
Ügynökprotokoll
Távolról, az OmniRoute felhasználói nevében végrehajtott felhőügynök-feladatok (Claude Code, Codex Cloud, OpenHands stb.).
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/agents/tasks |
Feladatok listázása — opcionális ?provider=, ?status=, ?limit= (1–500, alapértelmezés: 50) |
| POST | /api/v1/agents/tasks |
Feladat létrehozása — a törzs validálása a CreateCloudAgentTaskSchema alapján történik (providerId, prompt, source, options?). 201 választ ad feladattárolóval |
| DELETE | /api/v1/agents/tasks?id=... |
Feladat törlése |
| GET | /api/v1/agents/tasks/[id] |
Feladat beolvasása — szinkron módon frissíti az állapotot a felsőbb szintű felhőügynöktől, ha az external_id be van állítva |
| POST | /api/v1/agents/tasks/[id] |
Megkülönböztetett művelet: {action: "approve"}, {action: "message", message} vagy {action: "cancel"} |
| DELETE | /api/v1/agents/tasks/[id] |
Egy adott feladat törlése azonosító alapján |
Hitelesítés: minden metódushoz kezelési hitelesítés szükséges (
requireCloudAgentManagementAuth). A v3.8.0 előtt ezek nem igényeltek hitelesítést — lásd a588a0333commitot a visszamenőleges inkompatibilis változásért.
# Claude Code felhőfeladat létrehozása
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":"..."}}'
Kezelési proxyk
Kimenő HTTP(S)/SOCKS-proxyk, amelyek hozzárendelhetők szolgáltatókhoz, fiókokhoz vagy globálisan.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/management/proxies |
Proxyk listázása (az ?id= egyet ad vissza; az ?id=&where_used=1 a hozzárendelési gráfot adja vissza) |
| POST | /api/v1/management/proxies |
Proxy létrehozása — a törzs validálása a createProxyRegistrySchema alapján történik |
| PATCH | /api/v1/management/proxies |
Proxy frissítése — a törzs validálása az updateProxyRegistrySchema alapján történik (az id kötelező) |
| DELETE | /api/v1/management/proxies?id=...&force=1 |
Proxy törlése (a hozzárendelések leválasztásához használd a force=1 paramétert) |
| GET | /api/v1/management/proxies/assignments |
Hozzárendelések listázása — szűrhető proxy_id, scope, scope_id alapján; az aktív proxy kapcsolat szerinti feloldásához add meg a resolve_connection_id=<id> paramétert |
| PUT | /api/v1/management/proxies/assignments |
Hozzárendelés — a törzs validálása a proxyAssignmentSchema alapján történik ({scope, scopeId?, proxyId?}). Törli a diszpécser gyorsítótárát |
| PUT | /api/v1/management/proxies/bulk-assign |
Tömeges hozzárendelés — a törzs validálása a bulkProxyAssignmentSchema alapján történik ({scope, scopeIds[], proxyId?}) |
| GET | /api/v1/management/proxies/health?hours=24 |
Összesített proxyállapot (sikeres/sikertelen kérések száma, késleltetés) egy időablakra vetítve |
Hitelesítés: minden útvonalon kezelési munkamenet/API-kulcs szükséges (requireManagementAuth).
A feladatleírásban szereplő
POST /api/v1/management/proxies/[id]/assignmentsésPOST /api/v1/management/proxies/[id]/healthkéréseket a fent bemutatott lapos/assignmentsés/healthútvonalak szolgálják ki — a kódbázisban nincsenek azonosítónkénti alútvonalak.
Reziliencia (kibővítve)
Az OmniRoute három egymástól független, ideiglenes hibakezelési mechanizmust tesz elérhetővé; az alábbi kezelési végpontok lehetővé teszik az üzemeltetők számára ezek állapotának lekérdezését és felülbírálását:
| Hatókör | Állapottárolás | Lekérdezés | Visszaállítás / törlés |
|---|---|---|---|
| Szolgáltatói megszakító | domain_circuit_breakers + memóriában |
/api/monitoring/health |
POST /api/resilience/reset |
| Kapcsolati várakozási idő | rateLimitedUntil a szolgáltatói kapcsolatokon |
/api/rate-limits, /api/providers/[id] |
(lustán engedélyezi újra; törlés szolgáltatói PUT segítségével) |
| Modellzárolás | Memóriabeli modell-elérhetőségi nyilvántartás | GET /api/resilience/model-cooldowns |
DELETE /api/resilience/model-cooldowns |
A PATCH /api/resilience a szolgáltatói megszakító felülbírálásait a providerBreaker.oauth és providerBreaker.apikey alatt fogadja. Minden profil támogatja a degradationThreshold, failureThreshold és resetTimeoutMs mezőket; ugyanezek a mezők a Dashboard → Settings → Resilience területen is elérhetők.
# Egyetlen modellzárolás törlése
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"}'
# Minden zárolás törlése
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
A teljes fogalmi referenciát és a megszakító alapértelmezéseit lásd a CLAUDE.md → „Resilience Runtime State” és a docs/architecture/RESILIENCE_GUIDE.md dokumentumban.
Sebességkorlátozási várólista és automatikus engedélyezési biztonsági háló
- Támogatott írási útvonal: a
POST /api/rate-limitsa{"connectionId": "<id>", "enabled": true|false}törzzsel a támogatott kezelési végpont a sebességkorlátozás elleni védelem kapcsolatonkénti be- vagy kikapcsolására. APUT /api/providers/[id]szándékosan nem módosítja és nem kapcsolja át arateLimitProtectionértékét (#11278). - Az
enabled: falsejelentése: azenabled: falsebeállítása eltávolítja a kapcsolat explicit védelmét, de nem zárja ki az aktív API-kulcsos kapcsolatot a globális automatikus engedélyezési biztonsági hálóból (autoEnableApiKeyProviders = true). AreconcileEnabledConnectionsfüggvényben (open-sse/services/rateLimitManager.ts) afalseés azundefinedegyenértékű; az explicit védelemmel nem rendelkező aktív API-kulcsos kapcsolatok az automatikus engedélyezési biztonsági háló alatt továbbra is védettek maradnak. - Globális kikapcsolás: ha API-kulcsos kapcsolatokat szeretne sebességkorlátozási várólisták nélkül futtatni, globálisan tiltsa le a biztonsági hálót a
RATE_LIMIT_AUTO_ENABLE=false(környezeti változó) vagy aresilienceSettings.requestQueue.autoEnableApiKeyProviders = false(Settings → Resilience /PATCH /api/resilience) beállításával.
Készségek
Készségkeretrendszer az OmniRoute egyéni végrehajtható kezelőkkel való bővítéséhez, valamint piactéri integrációkhoz.
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /api/skills |
Telepített készségek listázása — szűrhető a következőkkel: ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, lapozható |
| GET | /api/skills/[id] |
Egy készség lekérése |
| PUT | /api/skills/[id] |
Készség frissítése (név, leírás, mód, séma, kezelő, címkék) |
| DELETE | /api/skills/[id] |
Készség eltávolítása |
| POST | /api/skills/install |
Készség telepítése nyers manifestből — törzs: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?} |
| GET | /api/skills/executions |
Legutóbbi készség-végrehajtások listázása (bemeneteket, kimeneteket és időtartamot tartalmazó auditnapló) |
| GET | /api/skills/marketplace?q=... |
Keresés és népszerűségi lista a SkillsMP piacteréről (a skillsmpApiKey beállítás szükséges) |
| POST | /api/skills/marketplace/install |
Készség telepítése azonosító alapján a SkillsMP-ből |
| GET | /api/skills/skillssh?q=&limit= |
Keresés a skills.sh nyilvántartásában |
| POST | /api/skills/skillssh/install |
Készség telepítése azonosító alapján a skills.sh szolgáltatásból |
Hitelesítés: kezelési munkamenet/API-kulcs. A piactéri keresési útvonalak kezelési hitelesítést vagy Bearer API-kulcsot fogadnak el (isAuthenticated).
Memória
Tartós beszélgetési/tényalapú memóriatároló, API-kulcsonként / munkamenetenként korlátozva.
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /api/memory |
Memóriák listázása — ?apiKeyId=, ?type=, ?sessionId=, ?q=, offset/limit vagy page/limit lapozással |
| POST | /api/memory |
Memória létrehozása — a törzs validálása Zod segítségével történik: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?} |
| GET | /api/memory/[id] |
Egy memória lekérése |
| DELETE | /api/memory/[id] |
Egy memória törlése |
| GET | /api/memory/health |
A memória-alrendszer állapota (adatbázis-kapcsolat, embedding-háttérrendszer, vektorindex állapota) |
Hitelesítés: kezelési munkamenet/API-kulcs (requireManagementAuth). type felsorolás: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (lásd a MemoryType típust itt: src/lib/memory/types.ts).
MCP-kiszolgáló
Az OmniRoute beágyazott Model Context Protocol-kiszolgálót biztosít 3 átviteli móddal (stdio, SSE, streamable-http) és korlátozott hatókörű eszközökkel. Az alábbi irányítópult-végpontok állapot- és auditadatokat olvasnak, valamint proxyt biztosítanak a HTTP-átvitelekhez.
| Metódus | Útvonal | Leírás | |
|---|---|---|---|
| GET | /api/mcp/status |
Életjel, átviteli mód, online állapot, utolsó hívás, leggyakrabban használt eszközök, 24 órás sikerességi arány | |
| GET | /api/mcp/tools |
MCP-eszközök listája name, description, scopes, phase, auditLevel, sourceEndpoints mezőkkel |
|
| GET | /api/mcp/sse |
SSE-stream megnyitása az SSE-átvitelhez (503 értéket ad vissza, ha az MCP le van tiltva, vagy az átviteli mód nem egyezik) |
|
| POST | /api/mcp/sse |
JSON-RPC-keret küldése az SSE-átvitelen | |
| GET | /api/mcp/stream |
Az SSE-oldal megnyitása a Streamable HTTP-átvitelhez (a kiszolgáló által kezdeményezett üzenetekhez) | |
| POST | /api/mcp/stream |
JSON-RPC-keret küldése a Streamable HTTP-átvitelen | |
| DELETE | /api/mcp/stream |
Streamable HTTP-munkamenet befejezése | |
| GET | /api/mcp/audit |
Auditnapló lekérdezése — ?limit=, ?offset=, ?tool=, `?success=true |
false, ?apiKeyId=` |
| GET | /api/mcp/audit/stats |
Összesített auditstatisztikák (összesítés, sikerességi arány, átlagos időtartam, leggyakrabban használt eszközök) |
Hitelesítés: az sse/stream átviteli módok az MCP-specifikus hitelesítési felületet használják (Bearer API-kulcs mcp hatókörrel); a status/tools/audit* útvonalak az irányítópultról olvashatók (az irányítópult gazdagépének elérésén túl nincs szükség további hitelesítésre).
Mindkét HTTP-átviteli módot a
settings.mcpEnabledés asettings.mcpTransportszabályozza — az átviteli mód eltérése400értéket ad vissza, letiltott MCP-állapot esetén pedig503értéket.
A2A-kiszolgáló
Az OmniRoute egy A2A (Agent-to-Agent) JSON-RPC 2.0 végpontot, valamint egy REST-wrappert biztosít az ellenőrzéshez és a műszerfal használatához.
JSON-RPC
POST /a2a
Authorization: Bearer your-api-key # opcionális, kivéve ha az OMNIROUTE_API_KEY be van állítva
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "message/send",
"params": {
"skill": "smart-routing",
"messages": [{"role": "user", "content": "Route this coding task"}]
}
}
Támogatott metódusok (mindegyik a settings.a2aEnabled beállítástól függ):
| Metódus | Leírás |
|---|---|
message/send |
Szinkron skill-végrehajtás; {task, artifacts, metadata} értéket ad vissza |
message/stream |
A skillkészlet azonos végrehajtása SSE-streameléssel |
tasks/get |
Feladat lekérése a taskId alapján |
tasks/cancel |
Feladat megszakítása a taskId alapján |
Beépített skillek: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.
Agent Card
GET /.well-known/agent.json
A nyilvános A2A-agentkártyát adja vissza (név, leírás, képességek, skillkatalógus, hitelesítési séma) — 1 órára nyilvánosan gyorsítótárazva. Hitelesítés nem szükséges.
REST-segédek
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /api/a2a/status |
Az A2A engedélyezettsége + feladatstatisztikák + a gyorsítótárazott agentkártya összefoglalója |
| GET | /api/a2a/tasks |
Feladatok listázása — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset= |
| POST | /api/a2a/tasks |
(REST-segédként nincs implementálva — létrehozás JSON-RPC message/send használatával) |
| GET | /api/a2a/tasks/[id] |
Egy feladat lekérése |
| POST | /api/a2a/tasks/[id]/cancel |
Feladat megszakítása |
Hitelesítés: a REST-segédek felügyeleti hitelesítés nélkül futnak (a műszerfal számára olvashatók); a JSON-RPC /a2a útvonal konfigurálás esetén Bearer OMNIROUTE_API_KEY használatával működik.
Felhő, értékelések és felmérés
| Metódus | Útvonal | Leírás | ||
|---|---|---|---|---|
| POST | /api/cloud/auth |
Bearer-kulcs ellenőrzése, valamint maszkolt szolgáltatói kapcsolatok és modellaliasok visszaadása a felhőszinkronizáló kliensek számára | ||
| POST | /api/cloud/credentials/update |
Titkosított hitelesítő adatok frissítése egy felhővel szinkronizált szolgáltatóhoz | ||
| POST | /api/cloud/model/resolve |
Egy logikai modellazonosító feloldása konkrét szolgáltatóra/modellre a helyi útválasztási tábla használatával | ||
| GET | /api/cloud/models/alias |
A felhőszinkronizálás számára elérhető modellaliasok listázása | ||
| GET | /api/assess |
A legutóbbi felmérési kategorizálások beolvasása (szolgáltatónként/modellenként) | ||
| POST | /api/assess |
Felmérés futtatása — törzs: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | /api/evals |
A beépített értékelési csomagok és a legutóbbi futtatások listázása | ||
| POST | /api/evals |
Értékelés futtatásának elindítása | ||
| POST | /api/evals/suites |
Egyéni értékelési csomag létrehozása — a törzset az evalSuiteSaveSchema ellenőrzi |
||
| GET | /api/evals/suites/[id] |
Egyéni értékelési csomag lekérése |
Hitelesítés: a /api/cloud/auth közvetlenül ellenőriz egy Bearer-kulcsot, és az egyes kapcsolatok maszkolt kulcsát és projectId értékét csak manage / admin hatókörrel rendelkező kulcs esetén adja vissza; a többi /api/cloud/*, /api/evals/* és /api/assess útvonal felügyeleti munkamenetet/API-kulcsot igényel. A /api/assess POST a validateBody használatával ellenőrzi a diszkriminált uniót alkalmazó hatókörsémát.
ACP (Agent Client Protocol) kezelése
gyermekfolyamatokként. Ezek a végpontok az ACP-ügynökök észlelését, valamint az egyéni ügynökök regisztrációját kezelik.
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /api/acp/agents |
Az összes ismert CLI-ügynök listázása (beépített + egyéni), telepítési állapottal, verzióval és bináris fájllal |
| POST | /api/acp/agents |
Egyéni ACP-ügynök regisztrálása vagy a gyorsítótár frissítése — törzs: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} vagy {action: "refresh"} |
| DELETE | /api/acp/agents |
Egyéni ACP-ügynök eltávolítása — lekérdezési paraméter: ?id=<agentId> |
Válaszpélda (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
}
Hitelesítés: Kezelési munkamenet szükséges (a dashboard auth_token cookie-ja) vagy kezelési hatókörű API-kulcs.
A teljes részletekért lásd az ACP-keretrendszert.
Analitika és megfigyelhetőség
Valós idejű analitikai végpontok az útválasztás, a tömörítés és a szolgáltatói diverzitás monitorozásához. Ezek szolgálják a /dashboard/analytics/* oldalakat.
Automatikus útválasztási analitika
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /api/analytics/auto-routing |
Az automatikus útválasztás összesített statisztikái: hívások száma, stratégiák megoszlása, szintek megoszlása, leggyakoribb szolgáltatók |
| GET | /api/analytics/auto-routing?days=7 |
Időablakra vonatkozó statisztikák (alapértelmezés: 24 óra) |
Válaszpélda:
{
"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 }
]
}
Tömörítési analitika
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /api/analytics/compression |
A tömörítés összesített statisztikái: megtakarított tokenek, megtakarítási %, módok megoszlása, motorhasználat |
Válaszpélda:
{
"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
}
}
A szolgáltatói diverzitás nyomon követése
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /api/analytics/diversity |
Shannon-entrópián alapuló diverzitáskövetés: a szolgáltatók eloszlásának mérésével megakadályozza az egyetlen hibapont kialakulását |
Válaszpélda:
{
"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"]
}
Hitelesítés: Kezelési munkamenet vagy kezelési hatókörű API-kulcs szükséges.
Adminisztrátori műveletek
Csak adminisztrátorok számára elérhető végpontok az üzemeltetés kezeléséhez.
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /api/admin/concurrency |
Aktuális konkurencialimitok lekérése (globális + szolgáltatónkénti) |
| POST | /api/admin/concurrency |
Konkurencialimitok frissítése — törzs: {global?: number, perProvider?: Record<string, number>} |
Hitelesítés: Adminisztrátori hatókörrel rendelkező kezelési munkamenet szükséges.
CLI-eszközök kezelése
Az OmniRoute-tal integrálódó CLI-eszközök kezelése (antigravity, commandCode, devin-cli stb.). A teljes listát lásd a szolgáltató-referenciában.
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /api/cli-tools/all-statuses |
Az összes CLI-eszköz állapota (telepítve, verzió, utolsó észlelés) |
| GET | /api/cli-tools/status |
Egy CLI-eszköz részletes állapota (?tool= lekérdezés) |
| POST | /api/cli-tools/apply |
Egy eszköz létrehozott konfigurációjának írása (a dryRun előnézetet jelenít meg; konténeres környezetben 422 + containerEphemeralTarget; a migration egy örökölt Codex YAML-re hivatkozik) |
| GET | /api/cli-tools/backups |
CLI-eszközök konfigurációs biztonsági mentéseinek listázása |
| POST | /api/cli-tools/backups |
Az összes CLI-eszköz konfigurációjának biztonsági mentése |
| POST | /api/cli-tools/backups |
Visszaállítás: ugyanaz a végpont a törzsben található {tool, backupId} használatával visszaállítja az adott biztonsági mentést |
| GET | /api/cli-tools/antigravity-mitm |
Az Antigravity MITM-proxy állapota (az „antigravity-mitm” CLI-eszköz) |
| POST | /api/cli-tools/antigravity-mitm/alias |
Az antigravity-mitm aliasainak konfigurálása |
Hitelesítés: Kezelési munkamenet szükséges.
Ügynökképességek
AI-ügynökök képességeinek kezelése (hasonlóan az OpenAI egyéni GPT-ihez, de ügynökök számára).
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /api/agent-skills |
Az összes ügynökképesség listázása (beépített + egyéni) |
| GET | /api/agent-skills/[id] |
Egy adott ügynökképesség lekérése |
| POST | /api/agent-skills |
Egyéni ügynökképesség létrehozása — törzs: {name, description, prompt, model?, temperature?} |
| PUT | /api/agent-skills/[id] |
Egyéni ügynökképesség frissítése |
| DELETE | /api/agent-skills/[id] |
Egyéni ügynökképesség törlése |
| GET | /api/agent-skills/[id]/raw |
Nyers prompt és metaadatok lekérése (végrehajtás nélkül) |
| POST | /api/agent-skills/generate |
Új képesség generálása természetes nyelvű leírás alapján AI segítségével |
Hitelesítés: Kezelési munkamenet vagy kezelési hatókörű API-kulcs szükséges.
Gyorsítótár kezelése
A szemantikai gyorsítótár és a következtetési gyorsítótár kezelése.
| Method | Path | Description |
|---|---|---|
| GET | /api/cache |
A gyorsítótár áttekintése: bejegyzések teljes száma, találati arány, lemezen elfoglalt méret |
| GET | /api/cache/entries |
Gyorsítótárazott bejegyzések listázása (lapozással) |
| DELETE | /api/cache/entries |
Gyorsítótár-bejegyzések törlése (lekérdezési paraméterek szerinti szűréssel) |
| GET | /api/cache/stats |
Részletes gyorsítótár-statisztikák (szolgáltatónként, modellenként) |
| GET | /api/cache/reasoning |
A következtetési gyorsítótár állapota (a következtetés visszajátszásához) |
| DELETE | /api/cache/reasoning |
A következtetési gyorsítótár törlése — lekérdezési paraméterek: ?toolCallId=<id> (egyetlen), vagy ?provider=<p>, illetve paraméterek nélkül (mind) |
Hitelesítés: Kezelői munkamenet szükséges.
Memóriarendszer
Perzisztens memória kezelése (FTS5 + vektoros beágyazások).
| Method | Path | Description |
|---|---|---|
| GET | /api/memory |
Memóriabejegyzések listázása (hatókör, típus és keresési lekérdezés szerinti szűréssel) |
| POST | /api/memory |
Új memóriabejegyzés létrehozása — törzs: {scope, type, content, metadata?} |
| GET | /api/memory/[id] |
Egy adott memóriabejegyzés lekérése |
| PUT | /api/memory/[id] |
Memóriabejegyzés frissítése |
| DELETE | /api/memory/[id] |
Memóriabejegyzés törlése |
| GET | /api/memory?q= |
Memóriakeresés (FTS5 + vektoros keresés) — a statisztikák ugyanabban a válaszban szerepelnek |
Hitelesítés: Kezelői munkamenet vagy kezelési hatókörű API-kulcs szükséges.
Webhookok
Eseményekhez tartozó webhook-előfizetések kezelése.
| Method | Path | Description |
|---|---|---|
| GET | /api/webhooks |
Az összes webhook-előfizetés listázása |
| POST | /api/webhooks |
Webhook-előfizetés létrehozása — törzs: {url, events[], secret?, active?} |
| GET | /api/webhooks/[id] |
Egy adott webhook-előfizetés lekérése |
| PUT | /api/webhooks/[id] |
Webhook-előfizetés frissítése |
| DELETE | /api/webhooks/[id] |
Webhook-előfizetés törlése |
| GET | /api/webhooks/[id]/deliveries |
Egy webhook kézbesítési előzményeinek listázása (sikeres/sikertelen napló) |
| POST | /api/webhooks/[id]/test |
Tesztesemény küldése egy webhooknak |
Hitelesítés: Kezelői munkamenet szükséges.
A teljes eseménytípus-listát lásd a Webhookok keretrendszere oldalon.
Képességkeretrendszer
Képességek kezelése (az agentikus bővítmények keretrendszere).
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /api/skills |
Az összes telepített képesség listázása (beépített + egyéni) |
| POST | /api/skills/install |
Képesség telepítése helyi útvonalról vagy URL-ről |
| DELETE | /api/skills/[id] |
Képesség eltávolítása |
| PUT | /api/skills/[id] |
Képesség engedélyezése vagy letiltása — törzs: {enabled?: boolean, mode?: "on" | "off" | "auto"} |
| POST | /api/skills/executions |
Képesség végrehajtása — törzs: {skillName, apiKeyId, input?, sessionId?} |
| GET | /api/skills/executions |
Az összes képesség végrehajtási előzményeinek listázása (szűrés ?apiKeyId= alapján) |
Hitelesítés: Kezelési munkamenetet vagy kezelési hatókörű API-kulcsot igényel.
A teljes részletekért lásd: Képességkeretrendszer.
Bővítmények
Az OmniRoute bővítményeinek (harmadik féltől származó kiegészítések) kezelése.
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /api/plugins |
A telepített bővítmények listázása |
| POST | /api/plugins/marketplace/install |
Bővítmény telepítése a piactérről |
| DELETE | /api/plugins/[name] |
Bővítmény eltávolítása |
| POST | /api/plugins/[name]/activate |
Bővítmény aktiválása |
| POST | /api/plugins/[name]/deactivate |
Bővítmény deaktiválása |
| GET | /api/plugins/[name]/config |
Bővítménykonfiguráció lekérése |
| PUT | /api/plugins/[name]/config |
Bővítménykonfiguráció frissítése |
Hitelesítés: Kezelési munkamenetet igényel.
A teljes részletekért lásd: Bővítménykeretrendszer.
Árnyékútválasztás
A szolgáltatók árnyékos / A-B összehasonlítása nem önálló REST-felület — a kombinált útválasztáson keresztül konfigurálható (lásd: Automatikus kombináció). A kombinációnkénti összehasonlítási metrikákat a GET /api/combos/metrics szolgáltatja.
Védelmi korlátok
A futásidejű védelmi korlátok vizsgálata (PII-felismerés, promptinjektálás-felismerés, vizuális összekapcsolás). A védelmi korlátok minden kérésnél lefutnak; a hívásonkénti kihagyás az x-omniroute-disabled-guardrails kérésfejlécen keresztül történik — nincs tartós engedélyezési/letiltási felület.
| Metódus | Útvonal | Leírás |
|---|---|---|
| GET | /api/guardrails |
A regisztrált védelmi korlátok és állapotuk listázása (név / engedélyezve / prioritás) |
| POST | /api/guardrails/test |
A hívás előtti folyamat próbaüzemű futtatása egy minta-bemeneten — törzs: {input, disabledGuardrails?} |
Hitelesítés: Kezelési munkamenetet igényel.
A teljes részletekért lásd: Biztonság > Védelmi korlátok.
Hitelesítés
A négy hitelesítési adatcsaládról (dashboard-munkamenet, helyi CLI-token, oma_live_… hozzáférési token, manage-hatókörű API-kulcs), valamint az inferenciakulcsoktól való eltérésükről lásd a Management Authentication útmutatót.
- A dashboard útvonalai (
/dashboard/*) azauth_tokencookie-t használják - A bejelentkezés a mentett jelszóhash-t használja; tartalékként az
INITIAL_PASSWORDszolgál - A
requireLogina/api/settings/require-loginútvonalon kapcsolható - A
/v1/*útvonalak opcionálisan Bearer API-kulcsot igényelnek, ha aREQUIRE_API_KEY=true - A jelen hivatkozásban a „management token” / „management-scoped API key” az útmutatóban szereplő hitelesítési adatcsaládok egyikét jelenti — nem egy nem definiált, további titkos adattípust
Kompatibilitástörő változás (v3.8.0) — Az
/api/v1/agents/tasks/*és a cooldown kezelésére szolgáló végpontok mostantól management hitelesítést (dashboardauth_tokencookie-t vagy manage-hatókörű API-kulcsot) igényelnek. Azok a kliensek, amelyek korábban hitelesítés nélkül hívták ezeket az útvonalakat,401 Unauthorizedválaszt kapnak. Lásd a588a0333commitot (fix(auth): require management auth for agent and cooldown APIs).