# API Reference (Slovenčina) 🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇧🇦 [bs](../../../bs/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md) --- 🌐 **Jazyky:** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇧🇦 [Bosanski](../i18n/bs/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md) Základná referenčná príručka k API OmniRoute. Zahŕňa verejné rozhranie `/v1` a najpoužívanejšie koncové body správy; vyčerpávajúcimi zdrojmi sú strojovo čitateľný súbor [`docs/openapi.yaml`](../openapi.yaml) a strom trás v `src/app/api/`. Podrobný protokol kompatibilný s OpenAI a maticu možností poskytovateľov nájdete v dokumente [`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md). --- ## Obsah - [Dokončenia chatu](#chat-completions) - [Výhradné prenájmy spravovaných relácií](#exclusive-managed-session-leases) - [Vektorové reprezentácie](#embeddings) - [Generovanie obrázkov](#image-generation) - [OCR dokumentov](#document-ocr) - [Zoznam modelov](#list-models) - [Manifest doplnku poskytovateľa](#provider-plugin-manifest) - [Koncové body kompatibility](#compatibility-endpoints) - [API súborov](#files-api) - [API dávok](#batches-api) - [API vyhľadávania](#search-api) - [Streamovanie cez WebSocket](#websocket-streaming) - [Kvóty a hlásenie problémov](#quotas--issues-reporting) - [Sémantická vyrovnávacia pamäť](#semantic-cache) - [Ovládací panel a správa](#dashboard--management) - [Správa kombinácií](#combo-management) - [Webhooky](#webhooks) - [Registrované kľúče (automatická správa)](#registered-keys-auto-management) - [Protokol agentov](#agents-protocol) - [Proxy servery na správu](#management-proxies) - [Odolnosť (rozšírená)](#resilience-extended) - [Zručnosti](#skills) - [Pamäť](#memory) - [Server MCP](#mcp-server) - [Server A2A](#a2a-server) - [Cloud, vyhodnotenia a posudzovanie](#cloud-evals--assess) - [Spracovanie požiadaviek](#request-processing) - [Autentifikácia](#authentication) --- ## Dokončenia chatu ```bash 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 } ``` ### Vlastné hlavičky | Hlavička | Smer | Popis | | ------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-OmniRoute-No-Cache` | Požiadavka | Nastavte na `true`, ak chcete obísť vyrovnávaciu pamäť | | `x-omniroute-no-memory` | Požiadavka | Nastavte na `true`, ak chcete pre túto požiadavku vynechať vkladanie pamäte a zručností (funguje podobne ako vypnutie vyrovnávacej pamäte; zabraňuje réžii tokenov a nákladov pri každom volaní) | | `X-OmniRoute-Progress` | Požiadavka | Nastavte na `true`, ak chcete prijímať udalosti priebehu | | `X-Session-Id` | Požiadavka | Kľúč stabilnej relácie pre externú afinitu relácie | | `x_session_id` | Požiadavka | Akceptuje sa aj variant s podčiarkovníkom (priame HTTP) | | `X-OmniRoute-Session-Id` | Požiadavka | Značka relácie/konverzácie zadaná volajúcim (používa sa aj pre pamäť). Ak je prítomná, uloží sa bez zmien do `call_logs.session_tag` na priradenie nákladov jednotlivým reláciám (#8249) — ak chýba, nikdy sa nevytvára | | `Idempotency-Key` | Požiadavka | Kľúč na deduplikáciu (5-sekundové okno) | | `X-Request-Id` | Požiadavka | Alternatívny kľúč na deduplikáciu | | `x-omniroute-connection` | Požiadavka | Pripne požiadavku na jeden model k jednému pripojeniu poskytovateľa (účtu) podľa jeho ID — pozrite si [Pripnutie účtu pre jednotlivé požiadavky](#account-pinning-per-request) | | `X-OmniRoute-Cache` | Odpoveď | `HIT` alebo `MISS` (bez streamovania) | | `X-OmniRoute-Idempotent` | Odpoveď | `true`, ak bola požiadavka deduplikovaná | | `X-OmniRoute-Progress` | Odpoveď | `enabled`, ak je zapnuté sledovanie priebehu | | `X-OmniRoute-Session-Id` | Odpoveď | Efektívne ID relácie používané službou OmniRoute | | `X-OmniRoute-Request-Id` | Odpoveď | Korelačné ID požiadavky (ak je známe) | | `X-OmniRoute-Version` | Odpoveď | Verzia zostavy OmniRoute (vždy prítomná) | | `X-OmniRoute-Cost-Saved` | Odpoveď | Suma v USD ušetrená vďaka vyrovnávacej pamäti pri výsledku HIT (iba pri zásahoch vyrovnávacej pamäte) | | `X-OmniRoute-Decision` | Odpoveď | Záznam smerovania: `strategy=; provider=; latency_ms=` (`` je stratégia kombinácie alebo `single` pri požiadavke bez kombinácie) — vždy je prítomný v odpovediach po dokončení | > Poznámka k Nginx: ak používate hlavičky s podčiarkovníkmi (napríklad `x_session_id`), povoľte `underscores_in_headers on;`. #### Pripnutie účtu pre jednotlivé požiadavky Keď má poskytovateľ viacero pripojení (účtov alebo kľúčov), OmniRoute zvyčajne jedno z nich vyberie pomocou svojej stratégie výberu účtu. Požiadavka však môže pripnúť konkrétne pripojenie pomocou hlavičky `x-omniroute-connection`: ```bash curl http://localhost:20128/v1/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "x-omniroute-connection: " \ -d '{"model": "codex/gpt-5.5", "messages": [{"role": "user", "content": "hi"}]}' ``` - **Kde nájsť id.** Otvorte stránku poskytovateľa v ovládacom paneli (**Ovládací panel → Poskytovatelia → **) a kliknite na štítok id `xxxxxxxx…` v riadku pripojenia — tým sa skopíruje celé id pripojenia. - **Ktoré požiadavky ho rešpektujú.** Požiadavky s jedným modelom (`provider/model`) na `/v1/chat/completions`, `/v1/messages` a `/v1/responses`. Kombinácie túto hlavičku ignorujú: účet pre každý krok kombinácie pripnite prostredníctvom vlastného pripojenia daného kroku. - **Pripnutie je striktné, nejde len o preferenciu.** Pripnuté pripojenie sa používa výhradne. Zlyhanie v rámci požiadavky zaznamená obdobie čakania účtu, ale **neprepne** na iný účet toho istého poskytovateľa. - **Obdobie čakania a kvóta pripnutie uvoľnia.** Kým je pripnuté pripojenie v období čakania, má vyčerpanú kvótu alebo je zablokované pravidlami kvóty, neskoršie požiadavky prejdú na ostatné pripojenia poskytovateľa presne tak ako nepripnutá prevádzka. - **Neznáme alebo zakázané id spôsobia zlyhanie.** Ak id nie je v aktívnom fonde poskytovateľa (bolo odstránené, deaktivované alebo patrí inému poskytovateľovi), nezostane žiadny vhodný účet, takže požiadavka zlyhá namiesto toho, aby bola bez upozornenia smerovaná inam. Claude Code odosiela vlastné hlavičky prostredníctvom `ANTHROPIC_CUSTOM_HEADERS`. Vložte ho do bloku `env` v súbore `~/.claude/settings.json` alebo do projektového súboru `.claude/settings.json`, ak chcete pre každý projekt pripnúť iný účet: ```jsonc { "env": { "ANTHROPIC_BASE_URL": "http://:20128", "ANTHROPIC_AUTH_TOKEN": "", "ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: ", }, } ``` Zdroj: `src/sse/handlers/chat.ts` (čítanie hlavičky), `src/sse/services/auth.ts` a `src/sse/services/sessionAffinityPin.ts` (uvoľnenie pripnutia a kontrola neprítomnosti vo fonde). > **Hlavičky telemetrie nákladov:** úspešné odpovede bez streamovania obsahujú aj súpravu telemetrie nákladov `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, presne 10 desatinných miest; `0.0000000000` pre bezplatné položky alebo položky bez stanovenej ceny), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit` a `X-OmniRoute-Fallback-Attempts` (iba keď > 0), ako aj `X-OmniRoute-Request-Id` a `X-OmniRoute-Version`. Generujú ich dokončenia chatu, `/v1/responses`, `/v1/messages` **aj koncové body médií** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` a `/v1/moderations` (náklady vždy `0`). Náklady na médiá sa počítajú podľa modality (za obrázok, za sekundu, za znak, za vyhľadávaciu jednotku), ak sú dostupné cenové údaje; v opačnom prípade sú `0` (prístup fail-open). > **Sémantika nákladov pri zásahu do vyrovnávacej pamäte:** pri zásahu do sémantickej vyrovnávacej pamäte (`X-OmniRoute-Cache-Hit: true`) sa nevykoná žiadne volanie nadradenej služby, takže `X-OmniRoute-Response-Cost` je `0.0000000000` (**prírastkové** náklady na obslúženie zásahu). Pôvodné/predpokladané náklady sa vykazujú samostatne v `X-OmniRoute-Cost-Saved`. Systémy spracúvajúce fakturáciu by mali sčítavať `X-OmniRoute-Response-Cost` (zásahy nič nestoja); analytické systémy vyrovnávacej pamäte môžu agregovať `X-OmniRoute-Cost-Saved`. ## Exkluzívne spravované prenájmy relácií Exkluzívny spravovaný prenájom relácie je voliteľná smerovacia zmluva nezávislá od klienta: jeden aktívny vlastník drží jedno oprávnené pripojenie OmniRoute. Neprenajíma model, nevyžaduje OAuth, neidentifikuje konkrétneho klienta ani nevyžaduje konkrétneho poskytovateľa. Overujúci API kľúč musí mať rozsah oprávnenia `lease:exclusive` a explicitný neprázdny zoznam `allowedConnections`. Hranica databázových mutácií vynucuje obe polia spoločne pri vytváraní kľúča aj pri čiastočných aktualizáciách. ```http POST /api/v1/session-leases Authorization: Bearer Content-Type: application/json X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> {"action":"acquire","model":"glm/glm-4.6"} ``` Úspešné odpovede na získanie, obnovenie a uvoľnenie uvádzajú časové pečiatky, `state` a presnú kladnú hodnotu `generation`, nikdy však vybrané pripojenie ani prihlasovacie údaje. Pri obnovení a uvoľnení sa generácia uvádza v tele JSON: ```json { "action": "renew", "generation": 1 } ``` ```json { "action": "release", "generation": 1, "reason": "OWNER_EXIT" } ``` Vlastník aktívneho prenájmu si môže explicitne vyžiadať zobrazované metadáta chrániace súkromie pre svoju aktuálnu väzbu: ```json { "action": "status", "generation": 1 } ``` ```json { "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" } } ``` Táto voliteľná akcia stavu je v rámci jednej databázovej transakcie ohraničená nepriehľadným vlastníkom, overeným spravovaným API kľúčom a presnou aktívnou generáciou. `displayName` obsahuje iba nakonfigurovaný názov pripojenia bez okolitých medzier; ak neexistuje žiadny bezpečný nakonfigurovaný názov, má hodnotu `null`. OmniRoute ho nikdy nenahrádza e-mailom ani vygenerovanou identitou účtu. Hodnota poskytovateľa je necitlivý zobrazovaný názov a nikdy nejde o vygenerovaný identifikátor kompatibilného poskytovateľa. Prihlasovacie údaje, tokeny, súbory cookie, nespracované ID pripojení alebo API kľúčov, haše vlastníkov, tajné údaje ohraničenia a interné smerovacie údaje sú vylúčené. Vyhľadania s nesprávnym kľúčom, nesprávnym vlastníkom, zastaranou generáciou, ako aj chýbajúce, exspirované, uvoľnené a zneplatnené vyhľadania vracajú rovnakú chybu `409 LEASE_FENCE_STALE` bez metadát pripojenia. Klient, ktorý dostal odpoveď o čakaní na kapacitu, nemá žiadnu aktívnu väzbu, ktorú by bolo možné preskúmať. Keď smerovanie prepne aktívny prenájom, rovnaká generácia zostáva platná a stav atomicky vráti novú väzbu, nikdy nie starú. Existujúci klienti zostávajú nezmenení, pretože odpovede na získanie, obnovenie, uvoľnenie a čakanie si zachovávajú svoje predchádzajúce formáty. Táto zmluva servera nemení štandardný príkaz OpenAI Codex `/status`. Štandardný Codex momentálne uvádza svojho poskytovateľa modelu a vstavaný stav overenia/účtu, ale nezobrazuje ľubovoľné vlastné metadáta účtu poskytovateľa; budúca integrácia klienta musí zavolať túto akciu a rozhodnúť, ako zobraziť `connection.displayName`. Každá spravovaná požiadavka na inferenciu potom uvádza obe riadiace hlavičky: ```http X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> X-OmniRoute-Lease-Generation: 1 ``` Presný vlastník, generácia, aktívne pripojenie a overený API kľúč sa ohraničia bezprostredne pred každým podporovaným pokusom smerom k nadradenej službe. Opätovné použitie vlastníka a generácie s iným kľúčom zlyhá aj vtedy, keď tento kľúč povoľuje rovnaké pripojenie. Nespracované hodnoty vlastníkov sa neukladajú, nezaznamenávajú do protokolov, neuchovávajú v snímke požiadavky ani neposielajú nadradenej službe. Dočasný konflikt vracia HTTP `429` s `Retry-After` a: ```json { "state": "WAITING_FOR_CAPACITY", "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" }, "reason": "NO_FREE_ELIGIBLE_CONNECTION", "retryAfter": 30 } ``` Táto odpoveď znamená iba to, že bežná množina oprávnených pripojení nebola prázdna a každý voľný kandidát bol držaný cudzím aktívnym prenájmom. Nepodporované modely/poskytovatelia, nesúlad so zásadami, čakacia lehota, kvóta, stav služby a ďalšie bežné zlyhania oprávnenosti si zachovávajú svoje existujúce odpovede OmniRoute. ### `x-omniroute-compression` Prepísanie plánu kompresie pre konkrétnu požiadavku. Má najvyššiu prioritu — prevažuje nad prepísaním kombinácie smerovania, aktívnym profilom, automatickým spustením aj predvoleným nastavením panela. Hodnoty: | Hodnota | Účinok | | ------------- | --------------------------------------------------------------------------------------------------------------- | | `off` | Bez kompresie pre túto požiadavku. | | `default` | Predvolený profil odvodený od panela (ignoruje aktívny profil). Stratové mechanizmy zostávajú vypnuté. | | `safe` | Iba deduplikácia a zlučovanie bielych znakov. | | `allow-lossy` | Zachová plán operátora pre túto požiadavku vrátane súhrnov a prepisovania štýlu. | | `engine:` | Jeden mechanizmus, ak je povolený, napr. `engine:rtk`. Voliteľná aktivácia tohto mechanizmu pre požiadavku. | | `` | Pomenovaná kombinácia, ktorá sa najprv porovná podľa názvu (bez rozlišovania veľkosti písmen) a potom podľa ID. | Poznámky: - Neznáme hodnoty sa ignorujú (požiadavka sa nikdy neodmietne); vyhodnocovanie pokračuje podľa bežného poradia priorít operátora. - Ak má viacero kombinácií rovnaký názov, na jednoznačné priradenie odovzdajte **id** kombinácie. - Kombináciu s názvom `off` alebo `default` nemožno vybrať podľa názvu (tieto kľúčové slová sa interpretujú ako prvé); na takúto kombináciu odkazujte pomocou jej ID. - Hlavný prepínač kompresie predstavuje neprekročiteľnú podmienku: keď je kompresia globálne zakázaná, táto hlavička ju nemôže povoliť. Použitý plán sa zopakuje v hlavičke odpovede: ``` X-OmniRoute-Compression: ; source= ``` kde `` je jedna z hodnôt `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` alebo `off`. --- ## Vektorové reprezentácie ```bash POST /v1/embeddings Authorization: Bearer your-api-key Content-Type: application/json { "model": "nebius/Qwen/Qwen3-Embedding-8B", "input": "The food was delicious" } ``` Dostupní poskytovatelia: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI. Identifikátory katalógu majú formát `provider/model` (príklad: `jina-ai/jina-embeddings-v5-omni-small`). Samostatné identifikátory modelov Jina, ktoré sa nachádzajú v registri (napríklad `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`), sa tiež rozpoznajú. Operácie embed/rerank/classify/segment služby Jina najprv používajú prihlasovacie údaje `jina-ai` z ovládacieho panela; `JINA_AI_API_KEY` sa použije ako záložná možnosť iba vtedy, keď v ovládacom paneli neexistuje žiadny kľúč. Karta `jina-reader` je určená iba pre Reader / `r.jina.ai` (`POST /v1/web/fetch`) a nikdy neposkytuje vektorové reprezentácie ani zmenu poradia. Modely v registri, ktoré deklarujú podporu multimodality, prijímajú aj najviac 32 štruktúrovaných položiek nezávislých od poskytovateľa. Typy multimediálnych položiek sú `text`, `image`, `audio`, `video` a `document`. Ich multimediálny `source` má buď podobu `{"type":"url","url":"https://..."}`, alebo `{"type":"base64","data":"...","media_type":"..."}`. Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano` a alias rodiny `jina-ai/jina-embeddings-v5-omni` → omni-small) prijíma aj natívne dokumenty EmbeddingsV5Request služby Jina a **bez zmeny ich preposiela** na `https://api.jina.ai/v1/embeddings`: ```json { "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,..." }] } ] } ``` Natívne hodnoty `{ image | audio | video | pdf }` môžu byť verejná adresa URL HTTPS, URI `data:` alebo nespracované dáta base64. OmniRoute tieto objekty neprevádza na reťazce ani nenačítava natívne adresy URL obrázkov — verejné médiá načíta samotná služba Jina. Dodatočné polia Jina (`task`, `normalized`, `truncate`, `embedding_type`) sa preposielajú. SKU Jina určené iba pre text naďalej odmietajú netextové dokumenty. Bezpečnostné a prenosové obmedzenia: - Vzdialené adresy URL médií musia byť verejné adresy HTTPS. Kanonické položky `{type,source:url}` sa načítavajú na strane servera (opätovné overenie presmerovaní, časový limit, obmedzenia veľkosti, verejný DNS, pripnutie pripojenia) a pred volaním poskytovateľa sa vložia priamo do požiadavky. Natívne položky Jina `{image:"https://..."}` sa preposielajú bez zmien po rovnakej kontrole verejnej adresy HTTPS; adresu URL načíta služba Jina. - Multimédiá base64 vložené priamo v požiadavke sú obmedzené na 8 MiB dekódovaných dát na položku a 16 MiB dekódovaných dát v rámci celej požiadavky. Prevod pre poskytovateľov (kanonické položky sa nikdy nepreposielajú bez zmien): - Multimodálne modely Jina: každá položka najvyššej úrovne sa zmení na jeden objekt s kľúčom modality (`text` / `image` / `audio` / `video` / `pdf`), pričom pre médiá vložené priamo v požiadavke sa použijú URI dát; pre každú položku najvyššej úrovne sa vytvorí jeden vektor. - Rodina Gemini Embedding 2: jedno pole najvyššej úrovne sa zmení na jednu natívnu požiadavku `models/{model}:embedContent` s `content.parts` (`text` alebo `inline_data`). - llama.cpp (`llama-cpp/`, ľubovoľný model načítaný lokálnym serverom): kanonické položky `text` sa zmenia na obyčajné reťazce a položky `image` / `audio` / `video` sa zmenia každá na jeden objekt `{"content": [part]}`, pričom sa použijú časti konverzačného obsahu llama-server (`image_url`, `input_audio` s formátom `wav` / `mp3` / `flac`, `input_video`) s priamo vloženými dátami; pre každú položku najvyššej úrovne sa vytvorí jeden vektor. Server musí byť spustený s `--embedding --mmproj …`; bez projektora sám odmietne médiá. Typ `document` nie je podporovaný. - Neznáme/dynamické modely bez explicitných metadát modality odmietnu štruktúrovaný vstup s kódom HTTP 400. ```json { "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" } ``` Nepodporované kombinácie modelov a modalít vrátia HTTP 400 namiesto konverzie položky. Rozširujúce polia mimo vstupu v starších požiadavkách s reťazcami/tokenmi sa naďalej preposielajú bez zmien. ```bash # Zobrazenie všetkých modelov vektorových reprezentácií GET /v1/embeddings ``` --- ## Generovanie obrázkov ```bash 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" } ``` Medzi dostupných poskytovateľov patria OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, **ZenMux**, SD WebUI (lokálny) a ComfyUI (lokálny). `n` vráti `n` obrázkov v `data[]`. Pri poskytovateľoch, ktorých nadradené API vracia jeden obrázok na volanie (Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI), sa vykoná `n` samostatných nadradených volaní, pričom súčasne môžu prebiehať najviac 4. Pevná hodnota `seed` sa posunie o index volania (`seed`, `seed + 1`, …), takže obrázky sa líšia, ale zostávajú reprodukovateľné. Hodnota `n` je obmedzená na 10. Ak zlyhá ktorékoľvek volanie, zlyhá celá požiadavka. Zoznam formátov s rozdelením na viacero volaní je `SINGLE_IMAGE_FANOUT_FORMATS` v súbore `open-sse/handlers/imageGeneration/fanOut.ts`. ZenMux opätovne používa existujúce pripojenie s kľúčom API a prijíma predpony `zenmux/` alebo `zm/`: - `zenmux/openai/gpt-image-2` používa OpenAI Images API od ZenMux. Medzi možnosti patria `size`, `quality`, `n`, `output_format`, `output_compression`, `background` a `response_format`. - Ostatní vydavatelia, napríklad `zm/meta/muse-image-1.0`, používajú koncový bod Vertex AI `:predict` od ZenMux. `n` sa mapuje na `sampleCount`, `aspect_ratio` na `aspectRatio` a `image_size` (`1K`, `2K`, `4K`) na `sampleImageSize`. Hodnota `size` v pixeloch určuje iba pomer strán, nie zaručené rozmery v pixeloch. Podporované pomery strán, rozlíšenia a počty sa líšia podľa modelu. - `zm/inclusionai/ming-image-0.1-design` si vyberá vlastné rozmery. Vynechajte `size`, `aspect_ratio` a `image_size`; explicitné hodnoty vrátia HTTP 400. Formáty PNG, JPEG a WebP možno vyžiadať pomocou `output_format`. Táto integrácia podporuje generovanie obrázkov z textu, nie úpravu referenčných obrázkov. Výstup Vertex sa normalizuje do `data[].b64_json`; `response_format: "url"` vráti nadradenú adresu URL HTTPS alebo dátovú adresu URL base64, ak sú k dispozícii iba bajty obrázka. Prázdne alebo odfiltrované výstupy vrátia chybu namiesto prázdnej úspešnej odpovede. Prístup k modelom závisí od účtu ZenMux. Pozrite si [Vertex API od ZenMux](https://docs.zenmux.ai/api/vertexai/generate-images) a [OpenAI Images API](https://docs.zenmux.ai/api/openai/generate-an-image). ```bash # Zobrazenie všetkých obrazových modelov GET /v1/images/generations ``` --- ## OCR dokumentov ```bash POST /v1/ocr Authorization: Bearer your-api-key Content-Type: application/json { "model": "mistral/mistral-ocr-latest", "document": { "type": "document_url", "document_url": "https://example.com/invoice.pdf" } } ``` `model` vyberá poskytovateľa OCR pomocou predpony `provider/model`; samotný identifikátor modelu (napr. `mistral-ocr-latest`) sa priradí k jeho registrovanému poskytovateľovi a pri vynechaní `model` sa predvolene použije Mistral (`mistral-ocr-latest`). Registrovaní poskytovatelia (`open-sse/config/ocrRegistry.ts`): | ID poskytovateľa | ID modelu | Hodnota `model` | Poznámky | | ----------------------------- | -------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (alebo samotné `mistral-ocr-latest`) | Synchrónne — odpoveď sa vráti priamo z jediného nadradeného volania. | | `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Asynchrónne nadradené rozhranie (`analyze` + dopytovanie) — pozrite nižšie. | | `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Synchrónne, prostredníctvom partnerského koncového bodu Vertex AI `openapi/chat/completions` — informácie o overovaní a adrese URL nájdete nižšie. | Všetci traja poskytovatelia odpovedajú rovnakým telom v tvare Mistral: ```json { "pages": [{ "index": 0, "markdown": "# Extracted text..." }], "model": "mistral-ocr-latest", "usage_info": { "pages_processed": 1 } } ``` ### Priebeh dopytovania Azure Document Intelligence API `analyze` služby Azure Document Intelligence je asynchrónne: počiatočná požiadavka vráti hlavičku `Operation-Location` namiesto tela a výsledok sa musí získavať opakovaným dopytovaním. Obslužný program (`open-sse/handlers/ocr.ts`) sa na túto adresu URL dopytuje každú sekundu, najviac však 30-krát; okamžite zlyhá (nepokračuje v dopytovaní) pri odpovedi na dopyt, ktorá nie je `ok`, alebo pri stave `"failed"`, a vráti `504`, ak operácia stále prebieha po vyčerpaní limitu pokusov. Konečná odpoveď Azure sa pred vrátením volajúcemu normalizuje do rovnakého tvaru `pages`/`markdown`, aký používa Mistral, takže klientsky kód nemusí poskytovateľa spracovávať osobitne. ### Overovanie a rozpoznanie koncového bodu Vertex AI DeepSeek OCR `vertex-deepseek-ocr` opätovne používa rovnaké overovanie Vertex AI, ktoré OmniRoute už podporuje pre chatovú a obrazovú komunikáciu (`open-sse/executors/vertex.ts`): kľúč API pripojenia je buď poverenie Service Account JSON (vymenené za krátkodobý prístupový token OAuth prostredníctvom toku JWT bearer), alebo už vydaný prístupový token OAuth použitý bez zmeny. Nadradená adresa URL koncového bodu je všeobecný partnerský koncový bod Vertex `openapi/chat/completions`, zostavený z projektu a regiónu pripojenia — explicitná hodnota `providerSpecificData.project`/`providerSpecificData.region` má vždy prednosť; inak sa projekt odvodí z `project_id` v Service Account JSON a ako predvolený región sa použije `us-central1`. Obe rozpoznania prebiehajú v `open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`) a používa ich `src/app/api/v1/ocr/route.ts` pred odoslaním do `handleOcr`. --- ## Zoznam modelov ```bash GET /v1/models Authorization: Bearer your-api-key → Vráti všetky četové, embeddingové a obrazové modely + kombinácie vo formáte OpenAI ``` ### Ceny modelov (`pricing`) Položka obsahuje objekt `pricing`, keď OmniRoute pozná cenu modelu. Cena pochádza z cenovej tabuľky používanej na účtovanie nákladov: vstavané predvolené hodnoty, synchronizované ceny a prepísania nastavené prostredníctvom `/api/pricing`. Ide o cenníkové ceny, takže poskytovatelia predplatného tiež zobrazujú cenu za token. ```json "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 } ``` | Polia | Jednotka | Poznámky | | --------------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `prompt`, `completion`, `input_cache_read`, `input_cache_write` | USD za token, desatinný reťazec | Kompatibilné s OpenRouter, nikdy nie v exponenciálnom zápise. Dve polia vyrovnávacej pamäte sa zobrazia iba vtedy, keď existuje cena vyrovnávacej pamäte. | | `input`, `output`, `cached`, `cache_creation` | USD za 1 mil. tokenov, číslo | Polia zo starších verzií katalógu, zachované pre existujúcich klientov. `reasoning` a `long_context` sa tiež zobrazia, keď ich cenový riadok obsahuje. | - **Kombinácie** obsahujú cenu svojho prvého viditeľného cieľa. Vstavané kombinácie `auto/*` vyberajú cieľ v čase požiadavky, takže nemajú `pricing`. - **Bezplatné modely** zobrazujú `"0"` (a `0`), keď je ich cena nulová. Model bez cenového riadka tiež zobrazuje `"0"`, keď ho katalóg označuje ako bezplatný (`free: true`) alebo keď sa nachádza vo vstavanom katalógu bezplatných modelov. - **Neznáma cena:** položka nemá kľúč `pricing`. - **Poskytovatelia účtujúci kredity** (napríklad Kiro) účtujú za požiadavku, nie za token. Ich položky si zachovávajú číselné polia ceny za 1 milión tokenov, ktoré mali predtým, a neobsahujú reťazcové polia ceny za token. - **Varianty** (id intenzity uvažovania, aliasy bez uvažovania, vyhľadávacie a bránové zrkadlá) kopírujú cenu modelu, na ktorý smerujú. - Polia obsahujú iba základné sadzby. Úrovne pre dlhý kontext (číselné pole `long_context`) a násobitele úrovne služby (napríklad Codex fast alebo flex) nemenia `prompt` ani `completion`. - Objekt je rovnaký pre každý spôsob autentifikácie vrátane požiadavky v štýle Anthropic s `x-api-key` a `anthropic-version` (odpoveď zostáva `{ "object": "list", "data": [...] }`). Implementácia: `src/app/api/v1/models/catalogPricing.ts`. ### Predpony id modelov (`?prefix=`) Väčšina modelov sa zobrazuje pod **predponou poskytovateľa**. To, ktorú predponu dostanete, riadi príznak funkcie `MODELS_CATALOG_PREFIX_MODE` a možno ho prepísať **pre každú požiadavku** pomocou parametra dopytu — je to užitočné pre klienta, ktorý chce prehľadný zoznam bez zmeny celoserverového nastavenia pre všetkých ostatných: ```bash GET /v1/models?prefix=alias # jedno id na model — krátka predpona aliasu GET /v1/models?prefix=dual # obe formy (predvolené nastavenie servera) GET /v1/models?prefix=canonical # iba úplná predpona id poskytovateľa ``` | Režim | Poskytuje | Poznámky | | ----------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dual` | `cc/claude-sonnet-4-6` **a** `claude/claude-sonnet-4-6` | **Predvolené.** Obe id smerujú na rovnaký model; zachované, aby konfigurácie klientov, ktoré majú napevno nastavenú ktorúkoľvek formu, naďalej fungovali. Približne zdvojnásobuje katalóg. | | `alias` | `cc/claude-sonnet-4-6` | Jedna položka na model. Poskytovatelia bez samostatného aliasu stále poskytujú svoju položku, takže sa nič nestratí. | | `canonical` | `claude/claude-sonnet-4-6` | Jedna položka na model pod úplnou predponou id poskytovateľa. Poskytovatelia bez samostatného aliasu (napr. `antigravity/…`, `agy/…`) tu tiež poskytujú svoje jediné id, takže sa nič nestratí. | Zrkadlo režimu `dual` možno rozpoznať aj bez parametra dopytu: obsahuje pole `parent` odkazujúce na primárne id. Klienti, ktorí zobrazujú výber modelu, by mali požadovať `?prefix=alias` — takto to robí [rozšírenie OmniCopilot pre VS Code](../guides/VSCODE-COPILOT.md). ### Filtre vyhľadávania (`?capability=`, `?min_context=`, `?kind=`, `?q=`) `GET /v1/models` podporuje voliteľné filtre vyhľadávania. Bez ktoréhokoľvek z nich zostáva odpoveď nezmenená. Zužujú katalóg, ktorý už volajúci vidí (najskôr sa uplatnia oprávnenia kľúča API), a spúšťajú sa pred stránkovaním v štýle OpenAI pomocou `limit` / `after`: ```bash GET /v1/models?capability=vision&capability=tool_calling # každá uvedená schopnosť musí byť pravdivá GET /v1/models?capability=vision,reasoning&min_context=200000 GET /v1/models?kind=embedding # katalógové `type`; riadky bez neho sú `chat` GET /v1/models?q=sonnet&limit=10 # zhoda bez rozlišovania veľkosti písmen v id alebo názve ``` | Parameter | Hodnoty | | ------------- | --------------------------------------------------------------------------------------------------- | | `capability` | `attachment`, `reasoning`, `structured_output`, `temperature`, `thinking`, `tool_calling`, `vision` | | `min_context` | nezáporné celé číslo porovnávané s `context_length` | | `kind` | `chat`, `audio`, `embedding`, `image`, `moderation`, `music`, `rerank`, `video` | | `q` | 1–200 znakov | Neznáma hodnota alebo `min_context`, ktorý nie je nezáporným celým číslom (napríklad `1.5`), vráti HTTP `400` a správa uvedie platné hodnoty. Implementácia: `src/app/api/v1/models/catalogFilters.ts`. ### Užší výber modelov (`POST /v1/models/query`) `POST /v1/models/query` vráti krátky, deterministický zoznam z rovnakého katalógu s rovnakým overovaním a viditeľnosťou pre jednotlivé kľúče ako `GET /v1/models`: ```bash 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 ] } ``` Každé pole je voliteľné. `capabilities` a `exclude` prijímajú pole alebo reťazec s hodnotami oddelenými čiarkami; `max_output` sa porovnáva s `max_output_tokens`. Výsledky sú zoradené podľa `owned_by` a následne podľa `id`. Predvolená hodnota `limit` je `20` a hodnoty nad `100` sú obmedzené na `100`. Neplatný JSON, neznáme pole alebo neplatná hodnota vrátia HTTP `400`. ### Individuálne skryté četové modely Model označený na stránke svojho poskytovateľa ako **Skrytý** je vylúčený z katalógu a pri explicitnom vyžiadaní odmietnutý s HTTP `404` / `model_not_found`. Kontrola používa určeného poskytovateľa a model vrátane aliasov poskytovateľov, prefixov uzlov kompatibilných poskytovateľov a predvolených nastavení pripojenia. Kombinácia preskočí skryté ciele a môže použiť viditeľný súvisiaci model; ak nezostane žiadny spustiteľný cieľ, vráti rovnaký chybový kód. Zrušenie skrytia sa prejaví pri nasledujúcej požiadavke. Nastavenia viditeľnosti iba pre obrázky neskryjú četový model s rovnakým ID. Toto individuálne nastavenie modelu je oddelené od [zoznamov povolených a zakázaných modelov](../routing/MODEL_EXPOSURE_LIST.md), ktoré filtrujú zverejnenie v katalógu a kandidátov na automatické smerovanie, pričom zachovávajú explicitné odoslanie. Oprávnenia modelov pre API kľúče sa naďalej uplatňujú nezávisle. Predvolený režim prefixov katalógu zostáva `dual`. ### Varianty modelov bez premýšľania Pre modely Claude podporujúce premýšľanie `/v1/models` propaguje aj variant **bez premýšľania**, ktorého ID má prefix `claude-3-omniroute-no-thinking/`: ``` claude-3-omniroute-no-thinking// ``` Výber tohto ID (napr. v konfigurácii Claude Code, ktorá vždy pripája blok `thinking`) sa preloží späť na skutočný `/` s potlačeným uvažovaním — `thinking:{type:"disabled"}` na ceste `/v1/messages` alebo s vynechanými poľami `reasoning`/`reasoning_effort` na ceste `/v1/chat/completions`. Variant sa uvádza iba pre modely z rodiny Claude, ktoré podporujú premýšľanie **a zároveň** rešpektujú `disabled` (takže napr. modely výhradne s adaptívnym režimom, ktoré odmietajú `disabled`, sú vylúčené). Prevádzkovatelia môžu variant pre jednotlivé modely vynútene zapnúť alebo vypnúť pomocou `ModelSpec.noThinkingAlias`. --- ## Manifest doplnku poskytovateľa ```bash GET /api/v1/provider-plugin-manifest ``` Vracia manifest doplnkov poskytovateľov bezpečný pre JSON, ktorý používajú Bifrost, CLIProxyAPI a budúce smerovače typu sidecar. Odpoveď sa generuje z registra poskytovateľov v jazyku TypeScript a zámerne nezahŕňa klientske tajomstvá OAuth, riešenie prostredia za behu, vykonávacie funkcie, hlavičky požiadaviek ani údaje účtov. Tento koncový bod použite, keď sidecar beží mimo procesu a nemôže priamo importovať `open-sse/config/providerPluginManifestRegistry.ts`. --- ## Generovanie zvuku pomocou ElevenLabs Nakonfigurujte v OmniRoute pripojenie poskytovateľa `elevenlabs` pomocou svojho kľúča API ElevenLabs. Klienti sa autentifikujú pomocou svojho kľúča **OmniRoute** (`Authorization: Bearer $OMNIROUTE_API_KEY`); brána poskytne uložený kľúč poskytovateľa ako `xi-api-key`. Nikdy neposielajte kľúč ElevenLabs ako bearer token brány. | Metóda | Cesta | Odpoveď | Kategória koncového bodu kľúča API | | ------ | --------------------------- | ---------------------------------------- | ---------------------------------- | | POST | `/v1/sound-generation` | Natívne zvukové bajty | `elevenlabs` | | POST | `/v1/music` | Natívne zvukové bajty | `music` | | POST | `/v1/music/stream` | Streamované zvukové bajty | `music` | | POST | `/v1/music/detailed` | Natívny multipart zvuk a plán kompozície | `music` | | POST | `/v1/music/detailed/stream` | Natívne metadáta SSE a zvukové bloky | `music` | | POST | `/v1/music/plan` | Plán kompozície vo formáte JSON | `music` | Tieto koncové body dopĺňajú existujúce trasy `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/voices`, `/v1/text-to-speech/{voiceId}` a `/v1/speech-to-text`. Natívne polia JSON a parametre dopytu, ako napríklad `output_format` a `enable_logging`, sa zachovávajú. Odpovede `/v1/music/detailed` si zachovávajú svoje multipart hranice; spracujte ich ako multipart. `/v1/music/detailed/stream` vracia `text/event-stream` s metadátami kompozície a zvukovými blokmi base64 v udalostiach SSE. Všetkých šesť trás podporuje predbežné požiadavky CORS. ```bash export OMNIROUTE_BASE_URL="http://localhost:20128" export OMNIROUTE_API_KEY="your-omniroute-api-key" # Krátky zvukový efekt. Trvanie: 0,5 až 30 sekúnd. 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 # Trvanie hudby sa vyjadruje v milisekundách: 3000 až 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 ``` Na postupné doručovanie zvuku použite `/v1/music/stream` s rovnakým telom JSON. Kompozícia prijíma presne jedno z `prompt` alebo `composition_plan`; `/v1/music/plan` vyžaduje `prompt` a voliteľne prijíma `source_composition_plan`. Natívne schémy zachovávajú ďalšie polia poskytovateľa, takže verzie plánu kompozície a možnosti dolaďovania sa prenesú do ElevenLabs. Zjednotený koncový bod `/v1/music/generations` tiež prijíma `elevenlabs/music_v1`, `elevenlabs/music_v2` a `elevenlabs/music_v2_5`. Pri aktívnom pripojení ElevenLabs sú tieto modely dostupné v hudobnom katalógu. Tento koncový bod vracia `{"created":...,"data":[{"b64_json":"...","format":"mp3"}]}`. Jeho pole `duration` je uvedené v sekundách a mapuje sa na `music_length_ms`; explicitné `music_length_ms` má prednosť. `instrumental` sa mapuje na `force_instrumental`, pričom natívne pole má prednosť. Na streamovanie používajte natívne streamovacie koncové body a na požiadavky riadené iba plánom kompozície použite natívny koncový bod kompozície. ```bash 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}' ``` Pred volaním nadradenej služby sa uplatnia obmedzenia koncového bodu, modelu, rozpočtu a pripojenia. Natívne trasy vracajú stavové kódy a telá chýb nadradenej služby bez zmien vrátane `402` pri obmedzení plánu a `429` pri prekročení kvóty. Hlavičky `character-cost`, `song-id`, `request-id` a `retry-after` sa zachovajú, ak sú prítomné. Bezplatný zostatok kreditu nezaručuje prístup ku každému hudobnému modelu, výstupnému formátu ani funkcii API: o oprávnení pre každú požiadavku rozhoduje ElevenLabs. Zjednotený koncový bod zachováva stavové kódy chýb v normalizovanej chybovej obálke OmniRoute. Zmluvy nadradenej služby: [zvukové efekty](https://elevenlabs.io/docs/api-reference/text-to-sound-effects/convert), [kompozícia hudby](https://elevenlabs.io/docs/api-reference/music/compose) a [podrobnosti streamovania hudby](https://elevenlabs.io/docs/api-reference/music/compose-detailed-stream). --- ## Kompatibilné koncové body | Metóda | Cesta | Formát | | ------ | ----------------------------------------- | ------------------------------------- | | 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 (úprava/dokresľovanie) | | POST | `/v1/videos/generations` | Generovanie videa v štýle OpenAI | | POST | `/v1/music/generations` | Generovanie hudby v štýle OpenAI | | POST | `/v1/audio/transcriptions` | OpenAI Audio (prevod reči na text) | | POST | `/v1/audio/speech` | OpenAI TTS (vracia telo so zvukom) | | POST | `/v1/rerank` | Preusporiadanie v štýle Cohere/Voyage | | POST | `/v1/classify` | Klasifikácia Jina (`api.jina.ai`) | | POST | `/v1/segment` | Segmentátor Jina (`segment.jina.ai`) | | POST | `/v1/moderations` | OpenAI Moderations | | GET | `/v1/models` | OpenAI | | POST | `/v1/models/query` | Filtrovaný užší výber modelov | | POST | `/v1/messages/count_tokens` | Anthropic | | GET | `/v1beta/models` | Gemini | | POST | `/v1beta/models/{...path}` | Gemini generateContent | | POST | `/v1/api/chat` | Ollama | | GET | `/api/v1/vscode/{token}/` | Alias katalógu OpenAI | | GET | `/api/v1/vscode/{token}/models` | Alias modelov OpenAI | | POST | `/api/v1/vscode/{token}/chat/completions` | Tokenizovaný alias OpenAI | | POST | `/api/v1/vscode/{token}/responses` | Tokenizovaný alias OpenAI Responses | | POST | `/api/v1/vscode/{token}/api/chat` | Tokenizovaný alias Ollama | | GET | `/api/v1/vscode/{token}/api/tags` | Tokenizovaný alias značiek Ollama | Všetky trasy POST majú rovnakú štruktúru: `Bearer your-api-key` + telo JSON overené pomocou Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` atď.; pozrite si `src/shared/validation/schemas.ts`). Pri zlyhaní overenia schémy sa vráti stavový kód 4xx. Klientom, ktoré nedokážu pripojiť `Authorization: Bearer ...`, umožňuje OmniRoute odovzdať kľúče API aj v adrese URL, a to buď prostredníctvom kompatibilných parametrov reťazca dopytu (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`), alebo cez vyhradené koncové body `/api/v1/vscode/{token}/...` zdokumentované nižšie. ```bash # Preusporiadanie výsledkov (poskytovateľ z cloudového registra alebo uzol poskytovateľa kompatibilného s OpenAI vo forme "/") POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] } # Klasifikácia Jina (prihlasovacie údaje Foundation API) POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] } # Segmentátor Jina POST /v1/segment { "content": "...", "return_chunks": true } # Vyhľadávanie Jina (s.jina.ai; aliasy poskytovateľa: jina-search, jina-ai, jina) POST /v1/search { "query": "...", "provider": "jina-search" } # Moderovanie POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." } # TTS — vracia telo vo formáte audio/mpeg (alebo v požadovanom formáte) POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } # Soniox TTS vyžaduje jazyk a hlas: predvolená hodnota `language` je "en"; chýbajúci # hlas alebo názov štandardného hlasu OpenAI (alloy, nova, …) sa zmení na "Adrian" POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" } # Úprava obrázka (multipart) POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png # Generovanie videa/hudby (ID modelu s predponou poskytovateľa) POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." } POST /v1/music/generations { "model": "kie/suno-v4.0", "prompt": "..." } ``` > **Uzly poskytovateľov pre preradenie:** `POST /v1/rerank` smeruje požiadavky aj na uzly poskytovateľov kompatibilné s OpenAI > (oMLX, vLLM, Infinity, TEI za bránou, …), ktoré sú adresované ako `/`. Uzly spätnej slučky > (`localhost`, `127.0.0.1`, `172.16.0.0/12`) sú vždy oprávnené, rovnako ako názvy hostiteľov, ktoré > operátor uvedie v `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` (napr. názov služby Docker/Compose, ako > `http://reranker:8080/v1`; tieto sa volajú priamo, nikdy nie cez `HTTP(S)_PROXY` ani pripnutý proxy server > pripojenia). Uzly na akomkoľvek inom > hostiteľovi — zariadenie v sieti LAN alebo partnerské zariadenie Tailscale — sú oprávnené iba vtedy, keď operátor povolí > príznak funkcie `RERANK_REMOTE_PROVIDER_NODES` **a zároveň** základná URL adresa uzla spĺňa pravidlá > odchádzajúcich URL adries poskytovateľa (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`). > Krok preradenia pamäťového mechanizmu volá túto trasu cez > spätnú slučku, takže rovnaké pravidlo sa vzťahuje na `rerankProviderModel` v nastaveniach pamäte. > > **Podoby lokálnych serverov:** uzol sa volá na adrese `/v1/rerank` a pri odpovedi 404 na adrese `/rerank` > (Infinity, TEI). Telo požiadavky upstreamu obsahuje pravopis variantu Cohere/OpenAI (`documents`, > `return_documents`) aj variantu TEI (`texts`, `return_text`) a odpoveď upstreamu sa > normalizuje do obálky Cohere: holé pole TEI `[{index, score, text}]`, `{results: [{index, score}]}` > z jednoduchých brán aj formát Voyage `{data: [...]}` sa klientovi vrátia ako > `{results: [{index, relevance_score, document?}]}`, zoradené podľa skóre a obmedzené hodnotou `top_n`. > **Vyhľadávanie uzlov poskytovateľov:** modely na uzle poskytovateľa kompatibilnom s OpenAI sa zobrazujú v `GET /v1/models` > pod prefixom uzla. Riadky, ktoré neobsahujú metadáta koncového bodu (typické pre lokálne výpisy `/v1/models`), > dedia `apiType` uzla, takže modely uzla `embeddings` majú `type: "embedding"` a modely > uzla `rerank` majú `type: "rerank"` namiesto predvoleného nastavenia na chat; explicitná hodnota > `supportedEndpoints` v synchronizovanom alebo manuálne pridanom riadku má naďalej prednosť. ### Vyhradené trasy poskytovateľov ```bash POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` Ak prefix poskytovateľa chýba, pridá sa automaticky. Nezhodujúce sa modely vrátia `400`. --- ## Files API Koncový bod súborov kompatibilný s OpenAI na dávkový vstup/výstup a nahrávanie súborov podľa účelu. | Metóda | Cesta | Popis | | ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | | POST | `/v1/files` | Nahranie súboru (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — max. 512 MiB | | GET | `/v1/files` | Zoznam súborov pre overený kľúč API | | GET | `/v1/files/[id]` | Získanie metadát súboru | | DELETE | `/v1/files/[id]` | Odstránenie súboru | | GET | `/v1/files/[id]/content` | Odoslanie nespracovaného obsahu súboru späť formou streamu | **Autorizácia:** Kľúč API typu Bearer — rozsah súborov je obmedzený podľa kľúča API prostredníctvom `getApiKeyRequestScope`. Kľúč vidí, sťahuje a odstraňuje iba vlastné súbory; relácia ovládacieho panela bez kľúča má prístup na čítanie v rámci celej inštancie; prístup k súboru bez vlastníka (anonymné nahranie alebo nahranie prostredníctvom relácie ovládacieho panela) je zamietnutý každému volajúcemu bez relácie. `GET /v1/files` odmietne anonymného volajúceho — aj poskytnutý kľúč, ktorý sa nepodarí rozpoznať — s kódom `401`, a to aj vtedy, keď `REQUIRE_API_KEY=false`, namiesto zobrazenia zoznamu súborov všetkých nájomníkov (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523). --- ## Batches API Dávkové spracovanie kompatibilné s OpenAI. | Metóda | Cesta | Popis | | ------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------- | | POST | `/v1/batches` | Vytvorenie dávky — telo overené pomocou `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) | | GET | `/v1/batches` | Zoznam dávok | | GET | `/v1/batches/[id]` | Získanie stavu dávky a `request_counts` | | DELETE | `/v1/batches/[id]` | Odstránenie dokončenej/neúspešnej dávky | | POST | `/v1/batches/[id]/cancel` | Zrušenie prebiehajúcej dávky | **Autorizácia:** Kľúč API typu Bearer. Rozsah dávok je obmedzený podľa kľúča API na základe rovnakého trojitého pravidla ako pri súboroch: iba vlastný kľúč, relácia ovládacieho panela v rámci celej inštancie, záznamy bez vlastníka sú zamietnuté každému volajúcemu bez relácie (získanie, odstránenie, zrušenie a kontrola `input_file_id` pri vytváraní). `GET /v1/batches` odmietne anonymného volajúceho s kódom `401`, a to aj vtedy, keď `REQUIRE_API_KEY=false`. --- ## API vyhľadávania Abstrakcia poskytovateľov webového vyhľadávania (Tavily, Brave, Exa, Serper atď.). | Metóda | Cesta | Popis | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | | GET | `/v1/search` | Zoznam nakonfigurovaných poskytovateľov vyhľadávania a ich možností | | POST | `/v1/search` | Spustenie vyhľadávacieho dopytu — telo overuje `v1SearchSchema`, podporuje ukladanie do vyrovnávacej pamäte a zlučovanie | | GET | `/v1/search/analytics` | Štatistiky úspešnosti, latencie a vyrovnávacej pamäte pre jednotlivých poskytovateľov | **Autentifikácia:** API kľúč typu Bearer (`extractApiKey` + `isValidApiKey`). Pravidlá vyhľadávania sa vynucujú prostredníctvom `enforceApiKeyPolicy`. ### `provider_options` pre Exa a Tavily Exa a Tavily čítajú polia špecifické pre poskytovateľa z menného priestoru: `provider_options.exa` (alebo `provider_options["exa-search"]`) a `provider_options.tavily` (alebo `provider_options["tavily-search"]`). Odosielajú sa iba kľúče uvedené nižšie. Každý z nich sa kontroluje podľa vlastnej schémy Zod v súbore `open-sse/handlers/search/providerOptionsPassthrough.ts` a kľúč s nesprávnym typom sa zahodí. Všetky ostatné kľúče sa ignorujú vrátane autentifikácie, základnej URL, `stream` a `outputSchema`. Ploché kľúče používané inými poskytovateľmi (`cx`, `depth`, ...) fungujú rovnako ako predtým. | Poskytovateľ | Polia najvyššej úrovne | Vnorené | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Exa | `type`, `category`, `userLocation`, `moderation`, `additionalQueries`, `objective`, `systemPrompt`, `compliance` (ploché primitívne hodnoty), `startPublishedDate`, `endPublishedDate` | `contents.{text, highlights, summary, extras, subpages, subpageTarget, livecrawlTimeout, maxAgeHours}` zlúčené s predvolenou hodnotou `{ text: true, highlights: true }` | | Tavily | `search_depth`, `chunks_per_source`, `time_range`, `start_date`, `end_date`, `include_published_date`, `filter_by_published_date`, `include_answer`, `include_raw_content`, `include_images`, `include_image_descriptions`, `include_favicon`, `include_domains_mode`, `language`, `filter_by_language`, `auto_parameters`, `exact_match`, `include_usage`, `safe_search` | — | Všeobecné polia majú vždy prednosť: `query`, `max_results`, `filters` (domény), `country` a téma odvodená z `search_type`. V Exa hodnota `search_type: "news"` zachová `category: "news"`. Tavily akceptuje aj `search_type: "finance"` (`topic: "finance"`). Všeobecné pole `time_range` sa teraz prenáša k obom poskytovateľom: Exa dostane `startPublishedDate` (časová pečiatka ISO) a Tavily dostane `start_date` (`YYYY-MM-DD`). Explicitný dátum v `provider_options` má prednosť pred mapovanou hodnotou. Výsledky Exa zachovávajú `id`, `highlight_scores`, `summary`, `subpages`, `entities` a `extras` v `provider_raw`. Výsledky Tavily zachovávajú `images` a `favicon`. Účtovanie nákladov naďalej používa plochý register `costPerQuery`. Tavily účtuje za `search_depth: "advanced"` viac kreditov na jedno volanie a tento rozdiel sa neodráža v `usage.search_cost_usd`. --- ## API Web Fetch Extrahuje obsah z URL prostredníctvom nakonfigurovaného poskytovateľa webového načítania (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract). Parallel Extract (`parallel-search`, rovnaký kľúč API ako Parallel Search) vracia iba Markdown — akýkoľvek iný `format` vedie k odpovedi `400` — a obmedzuje obsah na 100 000 znakov. Keď samotnú cieľovú stránku nemožno extrahovať, nadradená služba to oznámi v rámci HTTP 200; OmniRoute to sprístupní ako `422` s pevne stanovenou správou. | Metóda | Cesta | Opis | | ------ | --------------- | -------------------------------------------------------------- | | POST | `/v1/web/fetch` | Načíta/extrahuje URL — telo overené pomocou `v1WebFetchSchema` | **Autentifikácia:** Kľúč API typu Bearer (`extractApiKey` + `isValidApiKey`). Zásady sa vynucujú prostredníctvom `enforceApiKeyPolicy`. **Záložný mechanizmus zohľadňujúci kvóty (#8297):** keď nie je uvedený explicitný `provider`, fond (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search` → `parallel-search`) sa prechádza v pevnom poradí priorít (najprv sa naplní prvý) — nakonfigurovaný poskytovateľ s obmedzenou frekvenciou požiadaviek sa preskočí namiesto okamžitého ukončenia požiadavky a opakovateľné zlyhanie nadradenej služby alebo zlyhanie pre vyčerpanú kvótu (HTTP 429 vždy; 402/403 pre bezplatné úrovne služieb Firecrawl/Tavily/TinyFish s kvótami — nie pre Jina Reader a nikdy nie pre obyčajnú chybnú požiadavku 400) spôsobí počas spracovania požiadavky prechod na ďalšieho doteraz nevyskúšaného poskytovateľa s nakonfigurovanými prihlasovacími údajmi. Keď sú všetci poskytovatelia vo fonde vyčerpaní, koncový bod vráti jednu odpoveď `429` (s hlavičkou `Retry-After`) namiesto predchádzajúcej všeobecnej odpovede `400`. Keď sa požaduje explicitný `provider`, **nepoužije sa žiadny** tichý záložný mechanizmus — explicitný poskytovateľ s obmedzenou frekvenciou požiadaviek alebo so zlyhaním sprístupní svoju vlastnú chybu (`429`, ak je obmedzená frekvencia požiadaviek, inak stav nadradenej služby). --- ## Streamovanie cez WebSocket ```bash GET /v1/ws?handshake=1 ``` Overí inicializačnú požiadavku na prechod na WebSocket a vráti vzorové správy drôtového protokolu (`request`, `cancel`). Skutočné rámce WS spracúva pribalený server WS mimo tabuľky trás Next.js. **Autentifikácia:** Kľúč API typu Bearer počas inicializácie spojenia. ### Responses API cez WebSocket (iba codex) ```bash # Rovnaký hostiteľ a port ako API HTTP (predvolene 20128); prepnite pripojenie: wscat -c "ws://localhost:20128/v1/responses?api_key=" # (alebo: -H "Authorization: Bearer ") # Prvým rámcom MUSÍ byť response.create: { "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] } ``` Proxy Responses API cez WebSocket je napojené **výhradne na `codex`** (backend ChatGPT). Počúva na rovnakom porte ako API/ovládací panel na cestách `/v1/responses`, `/responses` a `/api/v1/responses`. Pri prvom rámci `response.create` vykoná autentifikáciu a prípravu prostredníctvom interného mosta `codex-responses-ws`, vyberie pripojenie codex OAuth a vytvorí tunel k `wss://chatgpt.com/backend-api/codex/responses` prostredníctvom transportu `wreq-js`. **Modely iné ako codex sa odmietnu** (`codex_ws_provider_required`). Na smerovanie s podielom kvóty použite `model: "qtSd//codex/"`. Implementované v `app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`. **Autentifikácia:** Kľúč API typu Bearer počas inicializácie spojenia. Pribalený server HTTP (`server-ws.mjs`) musí byť aktívnym vstupným bodom (predvolene ním je, keď existuje `app/server-ws.mjs`). #### ID modelu: použite základné ID ChatGPT (bez predpony `codex/`) OpenAI **Codex CLI** overuje názov modelu na strane klienta, keď je `supports_websockets = true`, a **odmieta ID s predponou poskytovateľa**, ako je `codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`). Odošlite **základné** ID (napr. `gpt-5.5`). Most OmniRoute je určený iba pre codex, preto pred vytvorením tunela k nadradenej službe znova vyhodnotí základné ID ako model codex (`resolveCodexWsModelInfo`) — aj keď by sa základné `gpt-5.5` cez HTTP inak smerovalo k inému poskytovateľovi. #### Konfigurácia OpenAI Codex CLI Nasmerujte Codex CLI na OmniRoute pridaním vlastného poskytovateľa s podporou WebSocket do `~/.codex/config.toml` (použite samostatný `CODEX_HOME`, aby ste neovplyvnili existujúcu konfiguráciu): ```toml model = "gpt-5.5" # základné ID — NIE „codex/gpt-5.5“ model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute (WS)" base_url = "http://localhost:20128/v1" # bez koncovej lomky; URL WS sa odvodí (v produkcii použite https/wss) wire_api = "responses" # jediná podporovaná hodnota od februára 2026 supports_websockets = true # povoľuje transport Responses cez WS env_key = "OMNIROUTE_API_KEY" # obsahuje kľúč API OmniRoute (Bearer) ``` ```bash export OMNIROUTE_API_KEY=sk-... # kľúč API OmniRoute (ľubovoľný kľúč, ak REQUIRE_API_KEY=false) codex exec "Responda apenas: PONG" ``` CLI prepne `base_url + /responses` na WebSocket a OmniRoute ho tuneluje k vybranému pripojeniu codex OAuth. Overené komplexne voči lokálnemu serveru: ChatGPT vráti `codex.rate_limits` + `response.created` a streamuje dokončenie. --- ## Kvóty a hlásenie problémov | Metóda | Cesta | Popis | | ------ | ------------------- | ----------------------------------------------------------------------------------------------- | | GET | `/v1/quotas/check` | Predbežné overenie kvóty pre `provider` + `accountId` pred vydaním registrovaného kľúča | | POST | `/v1/issues/report` | Nahlásenie zlyhania kvóty alebo vydania kľúča na GitHub (vyžaduje `GITHUB_ISSUES_REPO` + token) | **Autentifikácia:** Bearer API kľúč (`isAuthenticated`). --- ## Samoobslužné používanie (`/api/usage/om-usage`) Ľubovoľný API kľúč môže čítať **svoje vlastné** využitie a kvóty — bez autentifikácie na správu. Toto je koncový bod, ktorý klient (CLI, panel OmniCopilot) používa na zobrazenie výdavkov držiteľovi kľúča. ```bash # Textová forma (historický kontrakt — obyčajný text pre terminál) curl -H "Authorization: Bearer " \ http://localhost:20128/api/usage/om-usage # Štruktúrovaná forma — používaná používateľským rozhraním curl -H "Authorization: Bearer " \ "http://localhost:20128/api/usage/om-usage?format=json" ``` Kľúč musí mať povolené **`allowUsageCommand`** (predvolene je vypnuté — správca API kľúčov na ovládacom paneli ho prepína pre každý kľúč samostatne). Bez tohto povolenia koncový bod odpovie stavom `403`. `?format=json` vracia rozlíšiteľnú štruktúru, takže volajúci nikdy nečíta dátové pole z odmietnutej odpovede. Pri úspechu: ```jsonc { "allowed": true, // prítomné iba vtedy, keď má kľúč zapnuté limity využitia pre konkrétny kľúč (denné/týždenné v USD): "personal": { "dailySpentUsd": 1.25, "dailyLimitUsd": 5, "dailyResetAtIso": "…", "weeklySpentUsd": 8, "weeklyLimitUsd": 20, "weeklyResetAtIso": "…" /* … */, }, // snímka kvóty vybraného poskytovateľa alebo null, ak zatiaľ nie je nič vo vyrovnávacej pamäti: "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */} }, // snímka každého pripojenia, aby používateľské rozhranie mohlo vykresliť viacero poskytovateľov vedľa seba: "providers": [ { "connectionId": "…", "provider": "claude" /* … */ }, { "provider": "codex" /* … */ }, ], } ``` Pri odmietnutí (`401` neplatný kľúč / `403` nepovolené) tá istá trasa vráti `{ "allowed": false, "error": { "message": "…" } }` — prítomné, ale prázdne `personal`/`provider` (kľúč je povolený, ale zatiaľ neboli získané žiadne údaje) predstavuje iný stav než odmietnutie a rozlišuje ich iba forma JSON. **Autentifikácia:** vlastný Bearer API kľúč volajúceho, overený pomocou `isValidApiKey` — toto _nie je_ rozhranie na správu (`/api/keys/…`), ktoré zostáva chránené pomocou `requireManagementAuth`. ### Nespracované percentá kvót verzus percentá upravené podľa hraničnej hodnoty Pri používaní `/api/usage/om-usage` by volajúci mali brať do úvahy rozdiel medzi percentami uvádzanými vo **výstupe obyčajného textu** a štruktúrovanom **výstupe JSON**: | Aspekt | Formát obyčajného textu (`/api/usage/om-usage` / `@@om-usage`) | Formát JSON (`?format=json`) | | :--------------------- | :------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------- | | **Výstupné pole** | `NN% left` (napr. `20% left`) | `provider.quotas` / `providers[].quotas` | | **Meranie** | **Použiteľná kapacita upravená podľa hraničnej hodnoty**: zostávajúca kapacita nad prahom | **Nespracovaná upstreamová kvóta**: neupravené meranie poskytovateľa | | **Úprava podľa prahu** | Upravené pomocou `effectiveRemainingPercent()`, takže chránená rezerva sa zobrazuje ako `0% left` | Žiadna (nespracované hodnoty snímky nahlásené poskytovateľom) | | **Údaje o prahu** | Zahrnuté do zobrazeného percenta | Uložené v `quotaWindowThresholds` pre každé pripojenie (alebo predvolené hodnoty servera) | | **Hlavný používateľ** | Interaktívne CLI, terminálové výzvy, ľudskí operátori | Programové integrácie, ovládacie panely, analytika, nástroje na sledovanie fakturácie | #### Vzorec úpravy podľa hraničnej hodnoty OmniRoute podporuje proaktívne hraničné hodnoty kvót, ktoré zabraňujú vyčerpaniu upstreamových zdrojov (konfigurované prostredníctvom `quotaWindowThresholds` pripojenia, predvolených hodnôt poskytovateľa alebo globálnych nastavení odolnosti). Keď je v intervale kvóty aktívny hraničný prah (napr. `cutoff = 25%`), textový renderer vypočíta zostávajúcu kapacitu takto: - Ak `remaining <= cutoff`: vráti `0%`. - Ak `remaining > cutoff`: vráti `((remaining - cutoff) / (100 - cutoff)) * 100`. Formátovaný textový výstup túto hodnotu zaokrúhli na najbližšie celé číslo (`Math.round(...)`). #### Ilustračný príklad Predstavte si interval poskytovateľa so **60 % nespracovaného využitia** (teda **40 % nespracovanej zostávajúcej kvóty**) a nakonfigurovaným prahom **25 % zostávajúcej kvóty**: | Reprezentácia | Výpočet | Zostáva | Odvodené využitie | | :------------------------------------- | :------------------------------------------------- | :------: | :--------------------------------------: | | **Nespracovaný JSON (`?format=json`)** | Upstreamová snímka (`quotas[window]`) | **40 %** | **60 %** | | **Textový formát (`NN% left`)** | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **20 %** | **80 %** (pri výpočte `100 - remaining`) | - **Prečo text zobrazuje 20 % zostávajúcej kapacity:** Z 40 % fyzickej kvóty zostávajúcej na účte je 25 % rezervovaných zásadou hraničnej hodnoty. Volajúcemu zostáva len 15 % zo 75 % použiteľnej rezervy predtým, ako smerovač prestane smerovať požiadavky na toto pripojenie. Úprava zabezpečuje, že pripojenie signalizuje vyčerpanie (`0% left`) presne vtedy, keď sa smerovanie ukončí. - **Prečo JSON zachováva nespracované hodnoty:** Obsah JSON vracia presnú snímku poskytovateľa (`UsageSnapshot`), takže externé nástroje majú prístup k skutočnému upstreamovému využitiu a hodnotám `quotaWindowThresholds` na úrovni pripojenia bez stratovej úpravy na strane servera. #### Pokyny na migráciu používateľov Ak externá integrácia (napríklad doplnok editora alebo rozšírenie agenta) predtým získavala údaje z textového koncového bodu (`NN% left`) a vypočítavala použité percento ako `100 - NN`, prechod na `?format=json` znamená: - Čítanie nespracovaných hodnôt JSON bude odrážať **skutočnú spotrebu v nadradenom systéme** (v príklade vyššie je použitých 60 %). - Ak chce integrácia zachovať sémantiku použiteľného zostávajúceho limitu textového koncového bodu, môže vzorec efektívneho zostávajúceho limitu vyhodnotiť na strane klienta pomocou `quotaWindowThresholds` pre prepísania na úrovni pripojenia. --- ## Sémantická vyrovnávacia pamäť ```bash # Získanie štatistík vyrovnávacej pamäte GET /api/cache/stats # Vymazanie všetkých vyrovnávacích pamätí DELETE /api/cache/stats ``` Príklad odpovede: ```json { "semanticCache": { "memorySize": 42, "memoryMaxSize": 500, "dbSize": 128, "hitRate": 0.65 }, "idempotency": { "activeKeys": 3, "windowMs": 5000 } } ``` ### Vplyv na latenciu Pri ZÁSAHU do sémantickej vyrovnávacej pamäte sa odpoveď poskytne z vyrovnávacej pamäte **bez volania nadradenej služby**, takže hlásená hodnota `X-OmniRoute-Response-Latency` je takmer nulová (bez ohľadu na pôvodnú latenciu nadradenej služby). Klienti citliví na latenciu (porovnávacie testovanie, monitorovanie p50/p99) by mali kontrolovať hlavičku odpovede `X-OmniRoute-Cache-Latency`: | Hodnota | Význam | | ----------- | ------------------------------------------------------------------------------------------- | | `synthetic` | Odpoveď poskytnutá z vyrovnávacej pamäte; latencia nie je skutočným časom nadradenej služby | | _(chýba)_ | Odpoveď zo skutočného volania nadradenej služby | ### Obídenie vyrovnávacej pamäte pre jednotlivé kľúče Kľúče API môžu zrušiť používanie čítania zo sémantickej vyrovnávacej pamäte prostredníctvom `cacheDefaultMode`: | Hodnota | Správanie | | -------- | --------------------------------------------------------------------------------------- | | `legacy` | Bežné správanie vyrovnávacej pamäte (predvolené) | | `bypass` | Úplné preskočenie vyhľadávania vo vyrovnávacej pamäti; vždy sa použije nadradená služba | Nastavte pri vytváraní kľúča (`POST /api/keys`) alebo aktualizácii (`PATCH /api/keys/[id]`): ```json { "cacheDefaultMode": "bypass" } ``` ### Obídenie pre jednotlivé požiadavky Ľubovoľná požiadavka môže obísť vyrovnávaciu pamäť bez ohľadu na nastavenia kľúča: ``` X-OmniRoute-No-Cache: true ``` --- ## Ovládací panel a správa Trasy správy (`/api/*` okrem verejného overovania/prihlásenia) **nie sú** autorizované bežnými kľúčmi API na inferenciu. Skupiny prihlasovacích údajov, rozsahy a príklady použitia curl: [Overovanie pre správu](../guides/MANAGEMENT-AUTH.md). ### Overovanie | Koncový bod | Metóda | Popis | | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/auth/login` | POST | Prihlásenie | | `/api/auth/logout` | POST | Odhlásenie | | `/api/settings/require-login` | GET/POST | Stav prihlásenia (GET, verejné). POST nastaví heslo/prepne požiadavku na prihlásenie: po vytvorení hesla je k dispozícii iba operátorovi (relácia ovládacieho panela, lokálne CLI alebo vypnuté prihlasovanie — kľúče API a tokeny `oma_` dostanú `403`); relácia ovládacieho panela odošle `currentPassword` na nahradenie hesla | ### Správa poskytovateľov | Koncový bod | Metóda | Popis | | --------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/providers` | GET/POST | Zobrazenie zoznamu / vytvorenie poskytovateľov | | `/api/providers/[id]` | GET/PUT/DELETE | Správa poskytovateľa | | `/api/providers/[id]/test` | POST | Test pripojenia k poskytovateľovi | | `/api/providers/[id]/models` | GET | Zobrazenie zoznamu modelov poskytovateľa | | `/api/providers/validate` | POST | Overenie konfigurácie poskytovateľa | | `/api/providers/bulk` | POST | Hromadné pridanie kľúčov API pre JEDNÉHO poskytovateľa | | `/api/providers/import` | POST | Import heterogénneho ZOZNAMU poskytovateľov zo spracovaného súboru CSV/JSON (#6836); výsledky čiastočných zlyhaní pre jednotlivé riadky | | `/api/provider-nodes*` | Rôzne | Správa uzlov poskytovateľov | | `/api/provider-models` | GET/POST/PUT/PATCH/DELETE | Vlastné modely a prepísania pre jednotlivé modely (pridanie, aktualizácia, skrytie/zobrazenie, odstránenie) | | `/api/provider-models/validate-and-add` | POST | Voliteľné striktné overenie pripojenia s overeným správcovským prístupom a atómová registrácia vlastného modelu; pozrite si [Overenie modelu](../guides/MODEL-VALIDATION.md) | Pre synchronizované/importované modely prijíma `PUT /api/provider-models` hodnoty `provider`, `modelId` a `maxOutputTokenOverride`: kladné celé číslo nastaví manuálny limit výstupných tokenov a hodnota `null` ho zruší, čím sa obnoví predvolené nastavenie. `GET /api/provider-models?provider=` vracia tieto hodnoty v `modelOutputOverrides` vrátane modelov bez riadka vlastného modelu. Prepísanie používa runtime schopnosť `max_output_tokens` a zachová sa aj po opätovnej synchronizácii modelu. Stránka poskytovateľa kompatibilného s OpenAI ponúka rovnaké ovládacie prvky na úpravu/zrušenie a označuje modely s explicitnou podporou obrazu. Vlastné uzly Chat Completions prispôsobujú explicitné vypnutie uvažovania nadradenému backendu. Úspešný test pripojenia automaticky vyberie ovládacie prvky šablóny chatu pre každé presné ID modelu, ktorého položka `/models` preukazuje rozpoznanú hodnotu `owned_by`: `vllm`, `sglang` alebo `llamacpp`. Transparentné obalové vrstvy kompatibilné s OpenAI môžu zachovať pôvodnú položku modelu vo vnorenom objekte `openai`; detekcia prechádza až tromi takýmito obálkami. Modely s chýbajúcim, neznámym alebo konfliktným vlastníctvom si zachovajú bežné správanie OpenAI. Detekcia opätovne využíva existujúcu požiadavku na katalóg, negeneruje žiadne tokeny dokončenia a zneplatní sa pri zmene koncového bodu pripojenia. Ak chcete toto správanie pevne nastaviť pre backend, ktorý tieto metadáta neposkytuje, použite existujúce rozhranie API na čiastočnú aktualizáciu poskytovateľa: ```json { "providerSpecificData": { "reasoningControl": "chat-template" } } ``` Toto telo odošlite pomocou `PUT /api/providers/`. Pri danom pripojení sa explicitná intenzita uvažovania `none` odošle ako `chat_template_kwargs.thinking=false` a `chat_template_kwargs.enable_thinking=false`. Explicitné hodnoty natívnej šablóny zostávajú rozhodujúce, pokiaľ pravidlo uvažovania na strane servera nevynúti určitú intenzitu. Nastavenie sa uplatňuje iba vtedy, keď vlastné pripojenie kompatibilné s OpenAI odosiela telo Chat Completions; požiadavky Responses a bežní poskytovatelia si zachovávajú svoj natívny tvar požiadavky. Nastavte `reasoningControl` na `openai`, ak chcete vynútiť bežné odovzdanie `reasoning_effort` do OpenAI, alebo ho vynechajte/nastavte na `null`, ak chcete použiť automatickú detekciu. Požiadavky klasifikátora automatického režimu Claude Code predvolene nastavujú natívne premýšľanie ako vypnuté, ak neobsahujú žiadne explicitné ovládacie prvky uvažovania. Detekcia používa systémovú značku klasifikátora v požiadavkách vo formáte Claude, nie názvy modelov ani limity dokončenia. Explicitné ovládacie prvky tela, podporované hlavičky intenzity/premýšľania, pravidlá smerovania a vyriešená intenzita modelu si zachovávajú svoju existujúcu prioritu. Obe fázy klasifikátora si zachovávajú svoje prompty, limity dokončenia, sekvencie zastavenia a skutočné rozhodnutia nadradeného systému o oprávneniach; druhá fáza môže naďalej vytvárať požadované viditeľné uvažovanie ako bežný text. ### Toky OAuth | Koncový bod | Metóda | Popis špecifický pre poskytovateľa | | -------------------------------- | ------ | ---------------------------------- | | `/api/oauth/[provider]/[action]` | Rôzne | OAuth špecifické pre poskytovateľa | ### Smerovanie a konfigurácia | Koncový bod | Metóda | Popis | | --------------------- | -------- | ---------------------------------------- | | `/api/models/alias` | GET/POST | Aliasy modelov | | `/api/models/catalog` | GET | Všetky modely podľa poskytovateľa a typu | | `/api/combos*` | Rôzne | Správa kombinácií | | `/api/keys*` | Rôzne | Správa API kľúčov | | `/api/pricing` | GET | Ceny modelov | ### Používanie a analytika | Koncový bod | Metóda | Popis | | -------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/usage/history` | GET | História používania | | `/api/usage/logs` | GET | Záznamy o používaní | | `/api/usage/request-logs` | GET | Záznamy na úrovni požiadaviek | | `/api/usage/[connectionId]` | GET | Používanie podľa jednotlivých pripojení | | `/api/usage/token-limits` | GET/POST/DELETE | Rozpočty limitov tokenov pre jednotlivé API kľúče | | `/api/usage/model-latency-stats` | GET | Priebežné agregované štatistiky latencie podľa poskytovateľa/modelu (priemer/p50/p95/p99, miera úspešnosti); filtre: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) | | `/api/usage/cache-health` | GET | Súhrn stavu vyrovnávacej pamäte promptov na základe `call_logs` — pomer zápisov/čítaní, rozdelenie veľkosti zápisov p50/p90/p99, koncentrácia veľkých zápisov, členenie podľa modelov a verdikt `healthy`/`degraded`/`thrash`/`no-data`; parametre dotazu `range` (`1h`\|`24h`\|`7d`\|`30d`, predvolene `24h`) a voliteľný parameter `model` (#8827) | ### Oprávnenia API kľúčov `PATCH /api/keys/{id}` aktualizuje oprávnenia existujúceho kľúča. Rovnako ako každá trasa `/api/keys*` vyžaduje autorizáciu na správu (pozrite si [Autentifikáciu správy](../guides/MANAGEMENT-AUTH.md)), nie inferenčný kľúč. Odošlite iba polia, ktoré chcete zmeniť; požiadavka bez ktoréhokoľvek z nich bude zamietnutá s hlásením `No valid fields to update`. Akceptované polia definuje `updateKeyPermissionsSchema` v súbore `src/shared/validation/schemas/keys.ts`. | Pole | Typ | Poznámky | | ------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | `name` | reťazec, 1 – 200 znakov | | | `isActive` | logická hodnota | | | `isBanned` | logická hodnota | | | `expiresAt` | dátum a čas podľa ISO 8601 alebo `null` | `null` zruší platnosť času vypršania | | `modelAccessMode` | `all` \| `restricted` | `allowedModels` musí byť prázdne, keď je režim nastavený na `all` | | `allowedModels`, `blockedModels` | pole reťazcov, najviac 1000 | | | `allowedCombos` | pole reťazcov, najviac 500 | Určuje, ktoré kombinácie môže kľúč volať; priame modely sa riadia nastaveniami `modelAccessMode` / `allowedModels` | | `connectionAccessMode` | `all` \| `restricted` | `allowedConnections` nesmie byť prázdne pri nastavení `restricted` a musí byť prázdne pri nastavení `all` | | `allowedConnections` | pole UUID, najviac 100 | | | `allowAutoCombos` | logická hodnota | `false` odmietne požiadavky na modely `auto/*` s týmto kľúčom; kľúče, ktoré túto hodnotu nikdy nenastavili, sú povolené | | `catalogScope` | `all` \| `combos` \| `models` | Určuje, čo `GET /v1/models` vypíše pre tento kľúč (iba kombinácie, iba modely alebo oboje); nemení, čo môže kľúč volať | | `forcedModel` | reťazec s najviac 300 znakmi alebo `null` | Smeruje chatové požiadavky na tento model/kombináciu s prednosťou pred `X-Route-Model` a `body.model`; obmedzenia kľúča naďalej platia | | `noLog`, `autoResolve` | logická hodnota | | | `throttleDelayMs` | celé číslo, 0 – 300000 | | | `maxSessions` | celé číslo, 0 – 10000 | | | `rateLimits` | pole objektov `{ limit, window }` (kladné celé čísla, najviac 50) alebo `null` | `null` zruší obmedzenia | | `accessSchedule` | objekt harmonogramu alebo `null` | `null` zruší harmonogram | | `scopes` | pole reťazcov, najviac 32 | | | `allowedEndpoints` | pole reťazcov, najviac 20 | | | `streamDefaultMode` | `legacy` \| `json` | | | `cacheDefaultMode` | `legacy` \| `bypass` | Pozrite si [Obídenie vyrovnávacej pamäte pre jednotlivé kľúče](#per-key-cache-bypass) | | `compressionEnabled` | logická hodnota | | | `codexServiceMode` | jeden z režimov služby Codex | | | `disableNonPublicModels` | boolean | | | `allowUsageCommand` | boolean | | | `usageLimitEnabled` | boolean | | | `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | číslo >= 0 alebo `null` | | | `chaosModeEnabled` | boolean | | ```bash curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "allowAutoCombos": false, "catalogScope": "combos" }' ``` ### Nastavenia | Koncový bod | Metóda | Popis | | ------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/settings` | GET/PUT/PATCH | Všeobecné nastavenia. Kľúče bezpečnostných zásad (`requireLogin`, `newPassword`, `oidc*`, `corsOrigins`, `bruteForceProtection`) vyžadujú `currentPassword` a prihlasovací údaj operátora — API kľúče a tokeny `oma_` dostanú `403`; každá zmena vyžaduje rozsah prístupového tokenu `admin` | | `/api/settings/proxy` | GET/PUT | Konfigurácia sieťového proxy servera | | `/api/settings/proxy/test` | POST | Otestovanie pripojenia cez proxy server | | `/api/settings/ip-filter` | GET/PUT | Zoznam povolených/blokovaných IP adries | | `/api/settings/thinking-budget` | GET/PUT | Režim prepisovania **požiadaviek** na premýšľanie/uvažovanie (bez zmeny / automatické odstránenie / vlastný / adaptívny). Nezávisí od kompresie. Pozrite si [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). | | `/api/settings/system-prompt` | GET/PUT | Globálna systémová výzva | | `/api/settings/compression` | GET/PUT | Globálna konfigurácia kompresie | | `/api/settings/purge-request-history` | POST | Vymazanie riadkov denníka požiadaviek a lokálnych artefaktov denníka volaní | ### Kontext a kompresia | Endpoint | Metóda | Popis | | -------------------------------------- | -------------- | -------------------------------------------------------------------------------------------- | | `/api/compression/preview` | POST | Náhľad kompresie off/lite/standard/aggressive/ultra/RTK/stacked | | `/api/compression/language-packs` | GET | Zoznam dostupných jazykových balíkov Caveman | | `/api/compression/rules` | GET | Zoznam metadát pravidiel Caveman | | `/api/context/caveman/config` | GET/PUT | Alias nastavení špecifických pre Caveman | | `/api/context/rtk/config` | GET/PUT | Nastavenia špecifické pre RTK vrátane vlastných filtrov a uchovávania nespracovaného výstupu | | `/api/context/rtk/filters` | GET | Katalóg filtrov RTK a diagnostika vlastných filtrov | | `/api/context/rtk/test` | POST | Spustenie náhľadu/testu RTK nad textovým dátovým obsahom | | `/api/context/rtk/raw-output/[id]` | GET | Načítanie uchovaného redigovaného nespracovaného výstupu podľa ID ukazovateľa | | `/api/context/combos` | GET/POST | Zoznam/vytvorenie kombinácií kompresie | | `/api/context/combos/[id]` | GET/PUT/DELETE | Podrobnosti/aktualizácia/odstránenie kombinácie kompresie | | `/api/context/combos/[id]/assignments` | GET/PUT | Priradenie kombinácií kompresie ku kombináciám smerovania | | `/api/context/analytics` | GET | Alias analytiky kompresie | ### Monitorovanie | Endpoint | Metóda | Popis | | ------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/sessions` | GET | Sledovanie aktívnych relácií | | `/api/rate-limits` | GET | Limity požiadaviek pre jednotlivé účty | | `/api/monitoring/health` | GET | Kontrola stavu + súhrn poskytovateľov (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Zobrazenie správy zahŕňa `credentialHealth`: skalárne hodnoty vyrovnávacej pamäte sond, `failedConnections`, keď `failed>0`, a `staleDbNonOkCount` (trvalý `test_status` databázy SQLite, nie ukazovateľ). Pozrite si [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). | | `/api/cache/stats` | GET/DELETE | Štatistiky vyrovnávacej pamäte / vymazanie | | `/api/modality-bridge/stats` | GET | Hodnoty `attempts` v pamäti, úspechy/`bridged`, zlyhania, zásahy vyrovnávacej pamäte, `totalLatencyMs`, `latencySamples`, hodnota `averageLatencyMs` vypočítaná podľa počtu vzoriek a čas posledného použitia (obnoví sa pri reštarte; vyžaduje overenie správy) | | `/api/modality-bridge/video/runtime` | GET | Striktná kontrola dôveryhodného lokálneho rozhrania pred overením správcu/sondou; sanitizované údaje o dostupnosti a verziách FFmpeg/ffprobe (bez ukladania) | | `/api/modality-bridge/video/extract` | POST | Interný autentifikovaný sprostredkovateľ bajtov cez dôveryhodné lokálne rozhranie; vstup 50 MiB, ohraničený front/výstup 32 MiB, `503` pri nedostatočnej kapacite, `499` pri odpojení, `504` pri prekročení časového limitu; nejde o verejné API na nahrávanie súborov | ### Zálohovanie a export/import | Endpoint | Metóda | Popis | | --------------------------- | ------ | ------------------------------------------------------------------------ | | `/api/db-backups` | GET | Zobraziť dostupné zálohy | | `/api/db-backups` | PUT | Vytvoriť manuálnu zálohu | | `/api/db-backups` | POST | Obnoviť z konkrétnej zálohy | | `/api/db-backups` | PATCH | Uložiť nastavenia uchovávania záloh (len pre operátora) | | `/api/db-backups` | DELETE | Odstrániť uložené zálohy podľa nastavení uchovávania (len pre operátora) | | `/api/db-backups/export` | GET | Stiahnuť databázu ako súbor .sqlite | | `/api/db-backups/import` | POST | Nahrať súbor .sqlite a nahradiť databázu (`?dryRun=true` iba overuje) | | `/api/db-backups/exportAll` | GET | Stiahnuť úplnú zálohu ako archív .tar.gz | `/api/db-backups/export`, `/api/db-backups/exportAll` a `/api/settings/export-json` poskytujú všetky uložené prihlasovacie údaje, preto vyžadujú reláciu ovládacieho panela alebo lokálne CLI (prípadne vypnuté prihlasovanie). Kľúče API s ľubovoľným rozsahom a prístupové tokeny `oma_` dostanú odpoveď `403`. Na obnovenia sa vzťahuje rovnaké obmedzenie: `POST /api/db-backups/import` (vrátane `dryRun=true`), `POST /api/db-backups` (obnovenie podľa id) a `POST /api/settings/import-json` nahrádzajú aktívnu databázu alebo nastavenia, takže prihlasovacie údaje stroja dostanú odpoveď `403` aj v týchto prípadoch; `omniroute sync import` odosiela prihlasovacie údaje lokálneho CLI. To isté platí pre `DELETE /api/db-backups` (odstránenie uložených záloh) a `PATCH /api/db-backups` (nastavenia uchovávania: uložené hodnoty riadia automatické odstraňovanie po každej zálohe). Výpis (`GET`) a vytvorenie manuálnej zálohy (`PUT`) naďalej používajú bežné overovanie pre správu. ### Synchronizácia s cloudom | Endpoint | Metóda | Popis | | ---------------------- | ------ | --------------------------------- | | `/api/sync/cloud` | Rôzne | Operácie synchronizácie s cloudom | | `/api/sync/initialize` | POST | Inicializovať synchronizáciu | | `/api/cloud/*` | Rôzne | Správa cloudu | ### Tunely | Endpoint | Metóda | Popis | | -------------------------- | ------ | ------------------------------------------------------------------------- | | `/api/tunnels/cloudflared` | GET | Načítať pre ovládací panel stav inštalácie a behu Cloudflare Quick Tunnel | | `/api/tunnels/cloudflared` | POST | Povoliť alebo zakázať Cloudflare Quick Tunnel (`action=enable/disable`) | | `/api/tunnels/ngrok` | GET | Načítať pre ovládací panel stav behu tunela ngrok | | `/api/tunnels/ngrok` | POST | Povoliť alebo zakázať tunel ngrok (`action=enable/disable`) | ### Nástroje CLI | Endpoint | Metóda | Popis | | ---------------------------------- | ------ | ------------------------------- | | `/api/cli-tools/claude-settings` | GET | Stav CLI Claude | | `/api/cli-tools/codex-settings` | GET | Stav CLI Codex | | `/api/cli-tools/droid-settings` | GET | Stav CLI Droid | | `/api/cli-tools/openclaw-settings` | GET | Stav CLI OpenClaw | | `/api/cli-tools/runtime/[toolId]` | GET | Všeobecné behové prostredie CLI | Odpovede CLI obsahujú: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. ### Agenti ACP | Endpoint | Metóda | Popis | | ----------------- | ------ | ----------------------------------------------------------------------- | | `/api/acp/agents` | GET | Zobraziť všetkých zistených agentov (vstavaných aj vlastných) so stavom | | `/api/acp/agents` | POST | Pridať vlastného agenta alebo obnoviť vyrovnávaciu pamäť zisťovania | | `/api/acp/agents` | DELETE | Odstrániť vlastného agenta podľa parametra dopytu `id` | Odpoveď GET obsahuje `agents[]` (id, name, binary, version, installed, protocol, isCustom) a `summary` (total, installed, notFound, builtIn, custom). ### Odolnosť a limity požiadaviek | Koncový bod | Metóda | Popis | | --------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/resilience` | GET/PATCH | Získanie/aktualizácia frontu požiadaviek, času čakania pripojenia, ističa poskytovateľa a nastavení čakania | | `/api/resilience/reset` | POST | Resetovanie ističov poskytovateľov | | `/api/resilience/model-cooldowns` | GET | Zoznam aktívnych blokovaní pre jednotlivé kombinácie (poskytovateľ, pripojenie, model), zoradený podľa zostávajúceho času | | `/api/resilience/model-cooldowns` | DELETE | Zrušenie blokovania modelu — telo `{provider, model}` alebo `{all: true}` na vymazanie všetkých blokovaní | | `/api/rate-limits` | GET/POST | Stav limitu požiadaviek pre jednotlivé účty (GET) alebo prepnutie ochrany pred prekročením limitu pre pripojenie (POST `{connectionId, enabled}`). Podporovaný spôsob zápisu pre `rateLimitProtection` (nikdy sa neupravuje prostredníctvom `PUT /api/providers/[id]`). Poznámka: `enabled: false` vypne explicitnú ochranu, ale nevyradí aktívne pripojenie s kľúčom API z globálnej automatickej ochrany (`autoEnableApiKeyProviders`). | | `/api/rate-limit` | GET | Globálna konfigurácia limitu požiadaviek (zastarané; alias pre `/api/rate-limits`) | > Všetky štyri trasy `/api/resilience/*` vyžadujú **overenie správy** (`requireManagementAuth`). Úplný rozpis rozdielov medzi ističom poskytovateľa, časom čakania pripojenia a blokovaním modelu nájdete v časti [Odolnosť (rozšírené)](#resilience-extended). ### Vyhodnotenia | Koncový bod | Metóda | Popis | | ------------ | -------- | ----------------------------------------------- | | `/api/evals` | GET/POST | Zoznam sád vyhodnotení / spustenie vyhodnotenia | ### Zásady | Koncový bod | Metóda | Popis | | --------------- | --------------- | ----------------------- | | `/api/policies` | GET/POST/DELETE | Správa zásad smerovania | ### Súlad s predpismi | Koncový bod | Metóda | Popis | | --------------------------- | ------ | ---------------------------------------------- | | `/api/compliance/audit-log` | GET | Protokol auditu súladu (posledných N záznamov) | ### v1beta (kompatibilné s Gemini) | Koncový bod | Metóda | Popis | | -------------------------- | ------ | ------------------------------------ | | `/v1beta/models` | GET | Zoznam modelov vo formáte Gemini | | `/v1beta/models/{...path}` | POST | Koncový bod Gemini `generateContent` | Tieto koncové body kopírujú formát API služby Gemini pre klientov, ktorí očakávajú natívnu kompatibilitu so súpravou Gemini SDK. ### Interné/systémové API | Koncový bod | Metóda | Popis | | ------------------------ | ------ | ----------------------------------------------------------------- | | `/api/init` | GET | Kontrola inicializácie aplikácie (používa sa pri prvom spustení) | | `/api/tags` | GET | Značky modelov kompatibilné s Ollama (pre klientov Ollama) | | `/api/restart` | POST | Spustenie riadeného reštartu servera | | `/api/shutdown` | POST | Spustenie riadeného vypnutia servera | | `/api/system/env/repair` | POST | Oprava premenných prostredia poskytovateľa OAuth | | `/api/system/version` | GET | Aktuálna/najnovšia verzia, stav aktualizácie a kanál vydania | | `/api/system/version` | POST | Spustenie aktualizácie na najnovšiu verziu s ohľadom na nasadenie | > **Poznámka:** Tieto koncové body používa interne systém alebo slúžia na kompatibilitu s klientmi Ollama. Koncoví používatelia ich zvyčajne nevolajú. ### Oprava prostredia OAuth _(v3.6.1+)_ ```bash POST /api/system/env/repair Content-Type: application/json { "provider": "claude-code" } ``` Opraví chýbajúce alebo poškodené premenné prostredia OAuth pre konkrétneho poskytovateľa. Vráti: ```json { "success": true, "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"], "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak" } ``` ### Verzia a kanál vydania ```bash GET /api/system/version ``` Trasa na správu dostupná iba cez loopback (overenie správcu). Vráti spustenú verziu, najnovšiu publikovanú verziu a stav automatických aktualizácií. `releaseChannel` a `channels` sú pridané polia (vetva 3.8.54); `channel` si zachováva svoj význam — režim nasadenia, ktorý používa nástroj na aktualizáciu ovládacieho panela (`npm`, `source` alebo `docker-compose`). ```json { "current": "3.8.52", "latest": "3.8.52", "updateAvailable": false, "channel": "npm", "autoUpdateSupported": true, "autoUpdateError": null, "news": null, "releaseChannel": "latest", "channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" } } ``` - `releaseChannel` — npm kanál spustenej zostavy: `nightly` pre verzie `-nightly.*`, `next` pre ostatné predbežné vydania (`-rc.*`, `-beta.*`, `-alpha.*`), `lts` pre stabilnú verziu staršej hlavnej verzie než `channels.latest`, inak `latest`. Rovnaké pravidlá ako v `scripts/release/dist-tag.mjs`, ktorý pri publikovaní vyberá npm dist-tag. - `channels` — najnovšia publikovaná verzia každého dist-tagu získaná pomocou `npm view omniroute dist-tags` (s použitím registra HTTP ako záložnej možnosti), uložená vo vyrovnávacej pamäti s rovnakou 10-minútovou dobou platnosti ako `latest`. `latest` je vždy prítomné (ako záložná hodnota sa použije pole `latest` a následne `"unavailable"`); `next`, `nightly` a `lts` sa zobrazia iba vtedy, keď daný dist-tag existuje. Požiadavka `Cache-Control: no-cache` obnoví obe vyhľadávania. Model kanálov (`latest` = v3 až do všeobecnej dostupnosti verzie 4.0, `next` = rc, `nightly` = zostavy z vetvy `develop`, `lts` = opravy v3 po všeobecnej dostupnosti verzie 4.0) je opísaný v `docs/ops/RELEASE_STRATEGY.md`. --- ## Prepis zvuku ```bash POST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` Prepisujte zvukové súbory pomocou ľubovoľného nakonfigurovaného poskytovateľa STT. Prvý segment cesty vyberá natívneho poskytovateľa (`openai/…`, `deepgram/…`). Brány, ktoré opätovne sprístupňujú model iného poskytovateľa, používajú kvalifikovaný identifikátor (`openrouter/deepgram/nova-3`). **Požiadavka:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ -H "Authorization: Bearer your-api-key" \ -F "file=@recording.mp3" \ -F "model=openai/whisper-1" ``` **Odpoveď:** ```json { "text": "Hello, this is the transcribed audio content.", "task": "transcribe", "language": "en", "duration": 12.5 } ``` **Príklady identifikátorov modelov:** `openai/whisper-1` (vyžaduje kľúč OpenAI), `openrouter/deepgram/nova-3` (vyžaduje kľúč OpenRouter), `deepgram/nova-3` (vyžaduje natívny kľúč Deepgram). Samostatná požiadavka `deepgram/nova-3` **nepoužíva** OpenRouter. **Podporované formáty:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- ## Kompatibilita s Ollama Pre klientov, ktorí používajú formát API služby Ollama: ```bash # Koncový bod chatu (formát Ollama) POST /v1/api/chat # Výpis modelov (formát Ollama) GET /api/tags ``` Požiadavky sa automaticky prekladajú medzi formátom Ollama a internými formátmi. ## Aliasové adresy s tokenom pre VS Code / bez hlavičky Tieto aliasové adresy použite, keď integrácia nedokáže vložiť hlavičku `Authorization` a potrebuje kľúč API zahrnúť do základnej adresy URL. ```bash # Alias katalógu v štýle OpenAI GET /api/v1/vscode/{token}/ GET /api/v1/vscode/{token}/models # Aliasy chatu v štýle OpenAI POST /api/v1/vscode/{token}/chat/completions POST /api/v1/vscode/{token}/responses # Aliasy v štýle Ollama POST /api/v1/vscode/{token}/api/chat GET /api/v1/vscode/{token}/api/tags ``` Príklad: ```bash 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"}]}' ``` Poznámky: - Aliasové adresy s tokenom opätovne používajú rovnaké obslužné rutiny ako `/v1/*` a `/api/tags`; štruktúry odpovedí zostávajú identické. - Vždy, keď klient podporuje vlastné hlavičky, uprednostnite `Authorization: Bearer ...`. - Tokeny v adresách URL sa môžu objaviť v protokoloch reverzného proxy servera, histórii prehliadača a telemetrii mimo OmniRoute. Považujte ich za možnosť na zaistenie kompatibility, nie za predvolený spôsob overovania. --- ## Telemetria ```bash # Získať súhrn telemetrie latencie (p50/p95/p99 pre každého poskytovateľa) GET /api/telemetry/summary ``` **Odpoveď:** ```json { "providers": { "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } } } ``` --- ## Rozpočet ```bash # Získať stav rozpočtu pre všetky kľúče API GET /api/usage/budget # Nastaviť alebo aktualizovať rozpočet 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" } ``` > **Poznámky k schéme** (`setBudgetSchema`): `apiKeyId` je povinné; aspoň jedna z hodnôt `dailyLimitUsd`, `weeklyLimitUsd` alebo `monthlyLimitUsd` musí byť väčšia ako nula. Voliteľné polia: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Zastaraný formát `{keyId, limit, period}` vráti `400 Bad Request`. ## Limity tokenov Rozpočty **tokenov** pre jednotlivé API kľúče (odlišné od rozpočtu založeného na USD uvedeného vyššie). Vynucujú sa priamo pri spracovaní požiadavky: keď využitie kľúča v aktuálnom časovom okne dosiahne svoj limit, požiadavky sa odmietnu s chybou `429 Too Many Requests`. Limity možno obmedziť na konkrétny `model`, `provider` alebo ich použiť globálne pre celý kľúč (`global`); keď požiadavke zodpovedá viacero limitov, použije sa najprísnejší. ```bash # Zobrazenie limitov tokenov kľúča (vrátane aktuálneho využitia okna) GET /api/usage/token-limits?apiKeyId=key-123 # Vytvorenie alebo aktualizácia limitu tokenov POST /api/usage/token-limits Content-Type: application/json { "apiKeyId": "key-123", "scopeType": "model", "scopeValue": "openai/gpt-4o", "tokenLimit": 1000000, "resetInterval": "monthly", "enabled": true } # Odstránenie limitu tokenov podľa id DELETE /api/usage/token-limits?id=tl-abc ``` > **Poznámky k schéme** (`setTokenLimitSchema`): `apiKeyId` a `scopeType` (`model` | `provider` | `global`) sú povinné. `scopeValue` je povinné, pokiaľ `scopeType` nie je `global` (napr. ID modelu pre rozsah `model`, ID poskytovateľa pre rozsah `provider`). `tokenLimit` musí byť kladné celé číslo (konvertované z reťazca). Voliteľné: `id` (vynechajte pri vytváraní, zadajte pri aktualizácii), `resetInterval` (`daily` | `weekly` | `monthly`, predvolená hodnota `monthly`), `resetTime` (`HH:MM`), `enabled` (predvolená hodnota `true`). Odpovede `GET` dopĺňajú každý limit o `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` a `nextResetAt`. Ide o koncový bod triedy správy (autentifikácia sa vynucuje centrálne prostredníctvom autorizačného reťazca). ## Spracovanie požiadaviek 1. Klient odošle požiadavku na `/v1/*` 2. Obslužná rutina trasy zavolá `handleChat`, `handleEmbedding`, `handleAudioTranscription` alebo `handleImageGeneration` 3. Model sa rozpozná (priamy poskytovateľ/model alebo alias/kombinácia) 4. Z lokálnej databázy sa vyberú prihlasovacie údaje s filtrovaním podľa dostupnosti účtu 5. Pre konverzáciu: `handleChatCore` skontroluje sémantickú/signatúrnu vyrovnávaciu pamäť a určí nastavenia kompresie kombinácie 6. Ak je povolená, pred prekladom pre poskytovateľa sa spustí proaktívna kompresia (`lite`, Caveman, RTK alebo ich kombinácia) 7. Vykonávací modul poskytovateľa odošle požiadavku nadradenej službe 8. Odpoveď sa preloží späť do formátu klienta (konverzácia) alebo sa vráti bez zmien (vektorové reprezentácie/obrázky/zvuk) 9. Zaznamená sa využitie, analytika kompresie a protokoly požiadaviek 10. Pri chybách sa podľa pravidiel kombinácie použije záložné riešenie Úplný prehľad architektúry: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md) --- ## Správa kombinácií Kombinácie smerovania vyššej úrovne (už zhrnuté v časti `/api/combos*`) možno tiež mapovať v pomere 1 : 1 zo vzoru ID modelu, čo umožňuje transparentné presmerovanie ID modelu v štýle OpenAI na kombináciu. | Metóda | Cesta | Popis | | ------ | -------------------------------- | --------------------------------------------------------------------------------- | | GET | `/api/model-combo-mappings` | Zobrazí všetky mapovania model→kombinácia | | POST | `/api/model-combo-mappings` | Vytvorí mapovanie — telo: `{pattern, comboId, priority?, enabled?, description?}` | | GET | `/api/model-combo-mappings/[id]` | Načíta jedno mapovanie | | PUT | `/api/model-combo-mappings/[id]` | Aktualizuje polia existujúceho mapovania | | DELETE | `/api/model-combo-mappings/[id]` | Odstráni mapovanie | **Autentifikácia:** relácia správy/API kľúč (`requireManagementAuth`). --- ## Webhooky Odchádzajúce odbery webhookov pre udalosti OmniRoute (dokončenie požiadavky, vyčerpanie kvóty, rotácia kľúča atď.). | Metóda | Cesta | Popis | | ------ | ------------------------- | -------------------------------------------------------------------------- | | GET | `/api/webhooks` | Zoznam webhookov (tajné hodnoty sú maskované ako `...`) | | POST | `/api/webhooks` | Vytvorenie webhooku — telo: `{url, events?: ["*"], secret?, description?}` | | GET | `/api/webhooks/[id]` | Získanie webhooku | | PUT | `/api/webhooks/[id]` | Aktualizácia adresy URL/udalostí/tajnej hodnoty/p opisu | | DELETE | `/api/webhooks/[id]` | Odstránenie webhooku | | POST | `/api/webhooks/[id]/test` | Odoslanie testovacích údajov na URL webhooku a vrátenie stavu doručenia | **Autentifikácia:** relácia správy/kľúč API (`requireManagementAuth`). --- ## Registrované kľúče (automatická správa) Používa ich subsystém automatickej správy kľúčov na vydávanie a rotáciu kľúčov API u podkladového poskytovateľa alebo účtu s dennými a hodinovými kvótami. | Metóda | Cesta | Popis | | ------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/registered-keys` | Zoznam registrovaných kľúčov (iba maskovaný prefix) | | POST | `/api/v1/registered-keys` | Vydanie nového registrovaného kľúča — telo: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Nespracovaný kľúč sa vráti **iba raz**. Pri odmietnutí pre kvótu sa vráti `429`. | | GET | `/api/v1/registered-keys/[id]` | Získanie metadát registrovaného kľúča (bez nespracovanej hodnoty) | | DELETE | `/api/v1/registered-keys/[id]` | Zrušenie registrovaného kľúča | | POST | `/api/v1/registered-keys/[id]/revoke` | Explicitný koncový bod na zrušenie (rovnaký účinok ako DELETE) | **Autentifikácia:** relácia správy/kľúč API (`requireManagementAuth`) — rovnaká ochrana ako pri `/api/keys`: relácia ovládacieho panela, lokálny token CLI alebo kľúč API s rozsahom `manage`/`admin`; kľúče API určené iba na inferenciu dostanú odpoveď `403`. Pozrite si tiež `/v1/quotas/check` a `/v1/issues/report`. --- ## Protokol agentov Úlohy cloudových agentov (Claude Code, Codex Cloud, OpenHands atď.) vykonávané vzdialene v mene používateľov OmniRoute. | Metóda | Cesta | Popis | | ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/v1/agents/tasks` | Zoznam úloh — voliteľné `?provider=`, `?status=`, `?limit=` (1–500, predvolene 50) | | POST | `/api/v1/agents/tasks` | Vytvorenie úlohy — telo overené pomocou `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Vráti `201` s obálkou úlohy | | DELETE | `/api/v1/agents/tasks?id=...` | Odstránenie úlohy | | GET | `/api/v1/agents/tasks/[id]` | Načítanie úlohy — synchrónne obnoví stav z nadradeného cloudového agenta, keď je nastavené `external_id` | | POST | `/api/v1/agents/tasks/[id]` | Rozlíšená akcia: `{action: "approve"}`, `{action: "message", message}` alebo `{action: "cancel"}` | | DELETE | `/api/v1/agents/tasks/[id]` | Odstránenie konkrétnej úlohy podľa ID | > **Autentifikácia:** pri každej metóde sa vyžaduje autentifikácia správy (`requireCloudAgentManagementAuth`). Pred verziou v3.8.0 neboli tieto metódy autentifikované — zlomovú zmenu nájdete v commite `588a0333`. ```bash # Vytvorenie cloudovej úlohy Claude Code curl -X POST http://localhost:20128/api/v1/agents/tasks \ -H "Authorization: Bearer your-management-key" \ -H "Content-Type: application/json" \ -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}' ``` --- ## Proxy servery správy Odchádzajúce proxy servery HTTP(S)/SOCKS, ktoré možno priradiť poskytovateľom, účtom alebo globálne. | Metóda | Cesta | Popis | | ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/management/proxies` | Zoznam proxy serverov (s `?id=` vráti jeden; s `?id=&where_used=1` vráti graf priradení) | | POST | `/api/v1/management/proxies` | Vytvorenie proxy servera — telo overené pomocou `createProxyRegistrySchema` | | PATCH | `/api/v1/management/proxies` | Aktualizácia proxy servera — telo overené pomocou `updateProxyRegistrySchema` (vyžaduje `id`) | | DELETE | `/api/v1/management/proxies?id=...&force=1` | Odstránenie proxy servera (na zrušenie priradení použite `force=1`) | | GET | `/api/v1/management/proxies/assignments` | Zoznam priradení — možno filtrovať podľa `proxy_id`, `scope`, `scope_id`; na určenie aktívneho proxy servera pre pripojenie odovzdajte `resolve_connection_id=` | | PUT | `/api/v1/management/proxies/assignments` | Priradenie — telo overené pomocou `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Vymaže vyrovnávaciu pamäť dispečera | | PUT | `/api/v1/management/proxies/bulk-assign` | Hromadné priradenie — telo overené pomocou `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) | | GET | `/api/v1/management/proxies/health?hours=24` | Agregovaný stav proxy serverov (počty úspechov/zlyhaní, latencia) za časové obdobie | **Autentifikácia:** pri každej trase sa vyžaduje relácia správy/kľúč API (`requireManagementAuth`). > Trasy `POST /api/v1/management/proxies/[id]/assignments` a `POST /api/v1/management/proxies/[id]/health` uvedené v popise úlohy obsluhujú vyššie zobrazené ploché trasy `/assignments` a `/health` — v zdrojovom kóde neexistujú žiadne podtrasy pre jednotlivé ID. --- ## Odolnosť (rozšírené) OmniRoute poskytuje tri nezávislé mechanizmy dočasného zlyhania; nižšie uvedené koncové body správy umožňujú operátorom čítať a prepisovať ich stav: | Rozsah | Ukladanie stavu | Čítanie | Resetovanie / vymazanie | | ----------------------- | ------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------ | | Istič poskytovateľa | `domain_circuit_breakers` + v pamäti | `/api/monitoring/health` | `POST /api/resilience/reset` | | Časový limit pripojenia | `rateLimitedUntil` v pripojeniach poskytovateľov | `/api/rate-limits`, `/api/providers/[id]` | (opätovne sa povolí lenivo; vymaže sa cez PUT poskytovateľa) | | Uzamknutie modelu | Register dostupnosti modelov v pamäti | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` | `PATCH /api/resilience` prijíma prepísania ističov poskytovateľov v `providerBreaker.oauth` a `providerBreaker.apikey`. Každý profil podporuje `degradationThreshold`, `failureThreshold` a `resetTimeoutMs`; rovnaké polia sú dostupné v Ovládací panel → Nastavenia → Odolnosť. ```bash # Vymazanie uzamknutia jedného modelu 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"}' # Vymazanie všetkých uzamknutí curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ -H "Cookie: auth_token=..." \ -d '{"all":true}' ``` Úplnú koncepčnú referenciu a predvolené hodnoty ističov nájdete v [`CLAUDE.md`](../../CLAUDE.md) → „Stav modulu odolnosti počas behu“ a [`docs/architecture/RESILIENCE_GUIDE.md`](../architecture/RESILIENCE_GUIDE.md). ### Front požiadaviek s obmedzením frekvencie a poistka automatického povolenia - **Podporovaný spôsob zápisu**: `POST /api/rate-limits` s telom `{"connectionId": "", "enabled": true|false}` je podporovaný koncový bod správy na prepínanie ochrany pripojenia pred obmedzením frekvencie. `PUT /api/providers/[id]` zámerne neupravuje ani neprepína `rateLimitProtection` (#11278). - **Sémantika `enabled: false`**: Nastavenie `enabled: false` odstráni explicitnú ochranu pripojenia, ale **nevyradí** aktívne pripojenie s API kľúčom z globálnej poistky automatického povolenia (`autoEnableApiKeyProviders = true`). V `reconcileEnabledConnections` (`open-sse/services/rateLimitManager.ts`) sú hodnoty `false` a `undefined` ekvivalentné; aktívne pripojenia s API kľúčom bez explicitnej ochrany zostávajú chránené globálnou poistkou automatického povolenia. - **Globálne vypnutie**: Ak chcete používať pripojenia s API kľúčom bez frontov požiadaviek s obmedzením frekvencie, globálne vypnite túto poistku pomocou `RATE_LIMIT_AUTO_ENABLE=false` (premenná prostredia) alebo `resilienceSettings.requestQueue.autoEnableApiKeyProviders = false` (Nastavenia → Odolnosť / `PATCH /api/resilience`). --- ## Zručnosti Framework zručností na rozšírenie OmniRoute o vlastné spustiteľné obslužné programy a integrácie s trhoviskami. | Metóda | Cesta | Popis | | ------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Zoznam nainštalovaných zručností — filtrovanie podľa `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, so stránkovaním | | GET | `/api/skills/[id]` | Načítanie jednej zručnosti | | PUT | `/api/skills/[id]` | Aktualizácia zručnosti (názov, popis, režim, schéma, obslužný program, značky) | | DELETE | `/api/skills/[id]` | Odinštalovanie zručnosti | | POST | `/api/skills/install` | Inštalácia zručnosti zo surového manifestu — telo: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` | | GET | `/api/skills/executions` | Zoznam nedávnych spustení zručností (auditný záznam so vstupmi, výstupmi a trvaním) | | GET | `/api/skills/marketplace?q=...` | Vyhľadávanie/zoznam obľúbených položiek z trhoviska SkillsMP (vyžaduje nastavenie `skillsmpApiKey`) | | POST | `/api/skills/marketplace/install` | Inštalácia zručnosti podľa ID zo SkillsMP | | GET | `/api/skills/skillssh?q=&limit=` | Vyhľadávanie v registri skills.sh | | POST | `/api/skills/skillssh/install` | Inštalácia zručnosti podľa ID zo skills.sh | **Overenie totožnosti:** relácia správy/API kľúč. Trasy vyhľadávania na trhovisku akceptujú overenie totožnosti správy alebo API kľúč typu Bearer (`isAuthenticated`). --- ## Pamäť Trvalé úložisko konverzačnej/faktickej pamäte s rozsahom obmedzeným na kľúč API/reláciu. | Metóda | Cesta | Popis | | ------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------- | | GET | `/api/memory` | Zoznam pamätí — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, so stránkovaním pomocou `offset/limit` alebo `page/limit` | | POST | `/api/memory` | Vytvorenie pamäte — telo overované pomocou Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` | | GET | `/api/memory/[id]` | Načítanie jednej pamäte | | DELETE | `/api/memory/[id]` | Odstránenie pamäte | | GET | `/api/memory/health` | Stav podsystému pamäte (pripojenie k databáze, backend vnorení, stav vektorového indexu) | **Autentifikácia:** relácia správy/kľúč API (`requireManagementAuth`). Enum `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (pozrite si `MemoryType` v `src/lib/memory/types.ts`). --- ## Server MCP OmniRoute obsahuje vstavaný server Model Context Protocol s 3 transportmi (stdio, SSE, streamable-http) a nástrojmi s obmedzeným rozsahom. Nižšie uvedené koncové body ovládacieho panela načítavajú údaje o stave/audite a zastupujú transporty HTTP. | Metóda | Cesta | Popis | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | `/api/mcp/status` | Signál aktivity, transport, stav online, posledné volanie, najpoužívanejšie nástroje, 24-hodinová miera úspešnosti | | GET | `/api/mcp/tools` | Zoznam nástrojov MCP s `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` | | GET | `/api/mcp/sse` | Otvorenie prúdu SSE pre transport SSE (vráti `503`, ak je MCP deaktivovaný alebo sa transport nezhoduje) | | POST | `/api/mcp/sse` | Odoslanie rámca JSON-RPC prostredníctvom transportu SSE | | GET | `/api/mcp/stream` | Otvorenie strany SSE transportu Streamable HTTP (správy iniciované serverom) | | POST | `/api/mcp/stream` | Odoslanie rámca JSON-RPC prostredníctvom transportu Streamable HTTP | | DELETE | `/api/mcp/stream` | Ukončenie relácie Streamable HTTP | | GET | `/api/mcp/audit` | Dotazovanie denníka auditu — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` | | GET | `/api/mcp/audit/stats` | Agregované štatistiky auditu (celkové počty, miera úspešnosti, priemerné trvanie, najpoužívanejšie nástroje) | **Autentifikácia:** transporty `sse`/`stream` rešpektujú autentifikačné rozhranie špecifické pre MCP (kľúč API typu Bearer s rozsahom `mcp`); trasy `status`/`tools`/`audit*` sú čitateľné z ovládacieho panela (okrem prístupu k hostiteľovi ovládacieho panela sa nevyžaduje žiadna ďalšia autentifikácia). > Oba transporty HTTP sú riadené nastaveniami `settings.mcpEnabled` a `settings.mcpTransport` — nezhoda transportu vráti `400`, deaktivovaný stav MCP vráti `503`. --- ## Server A2A OmniRoute poskytuje koncový bod A2A (Agent-to-Agent) JSON-RPC 2.0 spolu s obalom REST na účely kontroly a použitia v ovládacom paneli. ### JSON-RPC ```bash POST /a2a Authorization: Bearer your-api-key # voliteľné, pokiaľ nie je nastavené OMNIROUTE_API_KEY Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "message/send", "params": { "skill": "smart-routing", "messages": [{"role": "user", "content": "Route this coding task"}] } } ``` Podporované metódy (všetky závisia od `settings.a2aEnabled`): | Metóda | Popis | | ---------------- | -------------------------------------------------------------------- | | `message/send` | Synchrónne vykonanie zručnosti; vracia `{task, artifacts, metadata}` | | `message/stream` | Streamované vykonanie rovnakej množiny zručností cez SSE | | `tasks/get` | Načíta úlohu podľa `taskId` | | `tasks/cancel` | Zruší úlohu podľa `taskId` | Vstavané zručnosti: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`. ### Karta agenta ```bash GET /.well-known/agent.json ``` Vracia verejnú kartu agenta A2A (názov, popis, možnosti, katalóg zručností, schéma autentifikácie) — verejne uloženú vo vyrovnávacej pamäti na 1 hodinu. Nevyžaduje sa autentifikácia. ### Pomocné rozhrania REST | Metóda | Cesta | Popis | | ------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- | | GET | `/api/a2a/status` | Stav povolenia A2A + štatistiky úloh + súhrn karty agenta z vyrovnávacej pamäte | | GET | `/api/a2a/tasks` | Zoznam úloh — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` | | POST | `/api/a2a/tasks` | (Nie je implementované ako pomocné rozhranie REST — vytvárajte prostredníctvom JSON-RPC `message/send`) | | GET | `/api/a2a/tasks/[id]` | Načíta jednu úlohu | | POST | `/api/a2a/tasks/[id]/cancel` | Zruší úlohu | **Autentifikácia:** pomocné rozhrania REST fungujú bez autentifikácie na správu (sú čitateľné ovládacím panelom); trasa JSON-RPC `/a2a` používa nosný token `OMNIROUTE_API_KEY`, ak je nakonfigurovaný. --- ## Cloud, Evals a Assess | Metóda | Cesta | Popis | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | `/api/cloud/auth` | Overí nosný kľúč a vráti maskované pripojenia poskytovateľov + aliasy modelov pre klientov cloudovej synchronizácie | | POST | `/api/cloud/credentials/update` | Aktualizuje šifrované prihlasovacie údaje poskytovateľa synchronizovaného s cloudom | | POST | `/api/cloud/model/resolve` | Preloží logické ID modelu na konkrétneho poskytovateľa/model pomocou lokálnej smerovacej tabuľky | | GET | `/api/cloud/models/alias` | Zobrazí zoznam aliasov modelov sprístupnených cloudovej synchronizácii | | GET | `/api/assess` | Načíta najnovšie kategorizácie hodnotení (podľa poskytovateľa/modelu) | | POST | `/api/assess` | Spustí hodnotenie — telo: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` | | GET | `/api/evals` | Zobrazí zoznam vstavaných sád evalov + najnovších behov | | POST | `/api/evals` | Spustí beh evalu | | POST | `/api/evals/suites` | Vytvorí vlastnú sadu evalov — telo overené pomocou `evalSuiteSaveSchema` | | GET | `/api/evals/suites/[id]` | Načíta vlastnú sadu evalov | **Autentifikácia:** `/api/cloud/auth` priamo overuje nosný kľúč a vracia maskovaný kľúč a `projectId` každého pripojenia iba pre kľúč s rozsahom `manage` / `admin`; ostatné trasy `/api/cloud/*`, `/api/evals/*` a `/api/assess` vyžadujú reláciu na správu/kľúč API. POST `/api/assess` používa `validateBody` so schémou rozsahu typu diskriminovaného zjednotenia. --- ## Správa ACP (Agent Client Protocol) ako podradené procesy. Tieto koncové body spravujú detekciu agentov ACP a registráciu vlastných agentov. | Metóda | Cesta | Popis | | ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/acp/agents` | Zobrazí všetkých známych agentov CLI (vstavaných aj vlastných) so stavom inštalácie, verziou a binárnym súborom | | POST | `/api/acp/agents` | Zaregistruje vlastného agenta ACP alebo obnoví vyrovnávaciu pamäť — telo: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` alebo `{action: "refresh"}` | | DELETE | `/api/acp/agents` | Odstráni vlastného agenta ACP — parameter dopytu: `?id=` | **Príklad odpovede** (`GET /api/acp/agents`): ```json { "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 } ``` **Autentifikácia:** Vyžaduje reláciu správy (súbor cookie `auth_token` ovládacieho panela) alebo kľúč API s rozsahom správy. Úplné podrobnosti nájdete v dokumentácii [Framework ACP](../frameworks/ACP.md). --- ## Analytika a pozorovateľnosť Koncové body analytiky v reálnom čase na monitorovanie smerovania, kompresie a diverzity poskytovateľov. Tieto koncové body zabezpečujú fungovanie stránok `/dashboard/analytics/*`. ### Analytika automatického smerovania | Metóda | Cesta | Popis | | ------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/auto-routing` | Agregované štatistiky automatického smerovania: celkový počet volaní, rozdelenie stratégií, rozdelenie úrovní, najpoužívanejší poskytovatelia | | GET | `/api/analytics/auto-routing?days=7` | Štatistiky za časové okno (predvolene 24 h) | **Príklad odpovede**: ```json { "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 } ] } ``` ### Analytika kompresie | Metóda | Cesta | Popis | | ------ | ---------------------------- | ------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/compression` | Agregované štatistiky kompresie: ušetrené tokeny, percento úspory, rozdelenie režimov, využitie enginov | **Príklad odpovede**: ```json { "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 } } ``` ### Sledovanie diverzity poskytovateľov | Metóda | Cesta | Popis | | ------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/diversity` | Sledovanie diverzity založené na Shannonovej entropii: meraním rozloženia poskytovateľov predchádza jediným bodom zlyhania | **Príklad odpovede**: ```json { "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"] } ``` **Autentifikácia:** Vyžaduje reláciu správy alebo kľúč API s rozsahom správy. --- ## Operácie správcu Koncové body určené iba správcom na prevádzkovú správu. | Metóda | Cesta | Popis | | ------ | ------------------------ | ------------------------------------------------------------------------------------------------- | | GET | `/api/admin/concurrency` | Načítanie aktuálnych limitov súbežnosti (globálnych + pre jednotlivých poskytovateľov) | | POST | `/api/admin/concurrency` | Aktualizácia limitov súbežnosti — telo: `{global?: number, perProvider?: Record}` | **Autorizácia:** Vyžaduje reláciu na správu s rozsahom oprávnení správcu. --- ## Správa nástrojov CLI Spravujte nástroje CLI, ktoré sa integrujú so službou OmniRoute (antigravity, commandCode, devin-cli atď.). Úplný zoznam nájdete v [referenčnej dokumentácii poskytovateľov](./PROVIDER_REFERENCE.md). | Metóda | Cesta | Popis | | ------ | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cli-tools/all-statuses` | Stav všetkých nástrojov CLI (inštalácia, verzia, posledné zaznamenanie) | | GET | `/api/cli-tools/status` | Podrobný stav jedného nástroja CLI (parameter dopytu `?tool=`) | | POST | `/api/cli-tools/apply` | Zápis vygenerovanej konfigurácie nástroja (`dryRun` zobrazí náhľad; `422` + `containerEphemeralTarget` pri spustení v kontajneri; `migration` upozorní na starší YAML Codexu) | | GET | `/api/cli-tools/backups` | Zoznam záloh konfigurácií nástrojov CLI | | POST | `/api/cli-tools/backups` | Vytvorenie zálohy konfigurácií všetkých nástrojov CLI | | POST | `/api/cli-tools/backups` | Obnovenie: rovnaký koncový bod s `{tool, backupId}` v tele obnoví danú zálohu | | GET | `/api/cli-tools/antigravity-mitm` | Stav proxy servera MITM Antigravity (nástroj CLI „antigravity-mitm“) | | POST | `/api/cli-tools/antigravity-mitm/alias` | Konfigurácia aliasov antigravity-mitm | **Autorizácia:** Vyžaduje reláciu na správu. --- ## Zručnosti agentov Spravujte zručnosti agentov AI (podobné vlastným GPT od OpenAI, ale určené pre agentov). | Metóda | Cesta | Popis | | ------ | ---------------------------- | ------------------------------------------------------------------------------------------------ | | GET | `/api/agent-skills` | Zoznam všetkých zručností agentov (vstavaných + vlastných) | | GET | `/api/agent-skills/[id]` | Získanie konkrétnej zručnosti agenta | | POST | `/api/agent-skills` | Vytvorenie vlastnej zručnosti agenta — telo: `{name, description, prompt, model?, temperature?}` | | PUT | `/api/agent-skills/[id]` | Aktualizácia vlastnej zručnosti agenta | | DELETE | `/api/agent-skills/[id]` | Odstránenie vlastnej zručnosti agenta | | GET | `/api/agent-skills/[id]/raw` | Získanie nespracovaného promptu + metadát (bez vykonania) | | POST | `/api/agent-skills/generate` | Vygenerovanie novej zručnosti pomocou AI z opisu v prirodzenom jazyku | **Autorizácia:** Vyžaduje reláciu na správu alebo kľúč API s rozsahom oprávnení na správu. --- ## Správa vyrovnávacej pamäte Spravujte sémantickú vyrovnávaciu pamäť a vyrovnávaciu pamäť uvažovania. | Metóda | Cesta | Popis | | ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cache` | Prehľad vyrovnávacej pamäte: celkový počet záznamov, miera zásahov, veľkosť na disku | | GET | `/api/cache/entries` | Zoznam záznamov vo vyrovnávacej pamäti (so stránkovaním) | | DELETE | `/api/cache/entries` | Odstránenie záznamov z vyrovnávacej pamäte (filtrovanie podľa parametrov dotazu) | | GET | `/api/cache/stats` | Podrobné štatistiky vyrovnávacej pamäte (podľa jednotlivých poskytovateľov a modelov) | | GET | `/api/cache/reasoning` | Stav vyrovnávacej pamäte uvažovania (na opätovné prehratie uvažovania) | | DELETE | `/api/cache/reasoning` | Vymazanie vyrovnávacej pamäte uvažovania — parametre dotazu: `?toolCallId=` (jeden), `?provider=

` alebo bez parametrov (všetky) | **Autorizácia:** Vyžaduje reláciu správy. --- ## Pamäťový systém Spravujte trvalú pamäť (FTS5 + vektorové vnorenia). | Metóda | Cesta | Popis | | ------ | ------------------ | ----------------------------------------------------------------------------------- | | GET | `/api/memory` | Zoznam záznamov v pamäti (filtrovanie podľa rozsahu, typu a vyhľadávacieho dotazu) | | POST | `/api/memory` | Vytvorenie nového záznamu v pamäti — telo: `{scope, type, content, metadata?}` | | GET | `/api/memory/[id]` | Získanie konkrétneho záznamu v pamäti | | PUT | `/api/memory/[id]` | Aktualizácia záznamu v pamäti | | DELETE | `/api/memory/[id]` | Odstránenie záznamu z pamäte | | GET | `/api/memory?q=` | Vyhľadávanie v pamäti (FTS5 + vektory) — štatistiky sú zahrnuté v rovnakej odpovedi | **Autorizácia:** Vyžaduje reláciu správy alebo kľúč API s rozsahom správy. --- ## Webhooky Spravujte odbery webhookov pre udalosti. | Metóda | Cesta | Popis | | ------ | ------------------------------- | ---------------------------------------------------------------------- | | GET | `/api/webhooks` | Zoznam všetkých odberov webhookov | | POST | `/api/webhooks` | Vytvorenie odberu webhooku — telo: `{url, events[], secret?, active?}` | | GET | `/api/webhooks/[id]` | Získanie konkrétneho odberu webhooku | | PUT | `/api/webhooks/[id]` | Aktualizácia odberu webhooku | | DELETE | `/api/webhooks/[id]` | Odstránenie odberu webhooku | | GET | `/api/webhooks/[id]/deliveries` | Zoznam histórie doručení webhooku (záznam úspechov/neúspechov) | | POST | `/api/webhooks/[id]/test` | Odoslanie testovacej udalosti webhooku | **Autorizácia:** Vyžaduje reláciu správy. Úplný zoznam typov udalostí nájdete v dokumente [Framework webhookov](../frameworks/WEBHOOKS.md). --- ## Framework Skills Spravujte Skills (framework agentických rozšírení). | Metóda | Cesta | Popis | | ------ | ------------------------ | --------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Zoznam všetkých nainštalovaných Skills (vstavaných aj vlastných) | | POST | `/api/skills/install` | Inštalácia Skill z lokálnej cesty alebo URL | | DELETE | `/api/skills/[id]` | Odinštalovanie Skill | | PUT | `/api/skills/[id]` | Povolenie alebo zakázanie Skill — telo: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` | | POST | `/api/skills/executions` | Spustenie Skill — telo: `{skillName, apiKeyId, input?, sessionId?}` | | GET | `/api/skills/executions` | Zoznam histórie spustení všetkých Skills (filtrovanie podľa `?apiKeyId=`) | **Autorizácia:** Vyžaduje reláciu správy alebo kľúč API s rozsahom správy. Úplné podrobnosti nájdete v dokumente [Framework Skills](../frameworks/SKILLS.md). --- ## Pluginy Spravujte pluginy OmniRoute (rozšírenia tretích strán). | Metóda | Cesta | Popis | | ------ | ---------------------------------- | --------------------------------- | | GET | `/api/plugins` | Zoznam nainštalovaných pluginov | | POST | `/api/plugins/marketplace/install` | Inštalácia pluginu z marketplace | | DELETE | `/api/plugins/[name]` | Odinštalovanie pluginu | | POST | `/api/plugins/[name]/activate` | Aktivácia pluginu | | POST | `/api/plugins/[name]/deactivate` | Deaktivácia pluginu | | GET | `/api/plugins/[name]/config` | Získanie konfigurácie pluginu | | PUT | `/api/plugins/[name]/config` | Aktualizácia konfigurácie pluginu | **Autorizácia:** Vyžaduje reláciu správy. Úplné podrobnosti nájdete v dokumente [Framework pluginov](../frameworks/PLUGIN_SDK.md). --- ## Tieňové smerovanie Tieňové porovnávanie poskytovateľov / porovnávanie A-B **nie je samostatným rozhraním REST** — konfiguruje sa prostredníctvom kombinovaného smerovania (pozrite si [Automatické kombinácie](../routing/AUTO-COMBO.md)). Metriky porovnávania pre jednotlivé kombinácie poskytuje `GET /api/combos/metrics`. --- ## Ochranné mechanizmy Kontrolujte ochranné mechanizmy za behu (detekcia osobných údajov, detekcia vloženia promptu, premostenie počítačového videnia). Ochranné mechanizmy sa spúšťajú pri každej požiadavke; odhlásenie pre jednotlivé volania sa vykonáva prostredníctvom hlavičky požiadavky `x-omniroute-disabled-guardrails` — neexistuje trvalé rozhranie na ich povolenie alebo zakázanie. | Metóda | Cesta | Popis | | ------ | ---------------------- | --------------------------------------------------------------------------------------------------- | | GET | `/api/guardrails` | Zoznam registrovaných ochranných mechanizmov a ich stavov (názov / povolené / priorita) | | POST | `/api/guardrails/test` | Skúšobné spustenie postupu pred volaním nad vzorovým vstupom — telo: `{input, disabledGuardrails?}` | **Autorizácia:** Vyžaduje reláciu správy. Úplné podrobnosti nájdete v dokumente [Zabezpečenie > Ochranné mechanizmy](../security/GUARDRAILS.md). --- --- ## Autentifikácia Informácie o štyroch skupinách prihlasovacích údajov (relácia ovládacieho panela, lokálny token CLI, prístupový token `oma_live_…`, kľúč API s rozsahom správy) a o tom, ako sa líšia od kľúčov na inferenciu, nájdete v časti [Autentifikácia správy](../guides/MANAGEMENT-AUTH.md). - Trasy ovládacieho panela (`/dashboard/*`) používajú súbor cookie `auth_token` - Prihlásenie používa uložený hash hesla; ako záložná možnosť sa používa `INITIAL_PASSWORD` - Nastavenie `requireLogin` možno prepínať prostredníctvom `/api/settings/require-login` - Trasy `/v1/*` môžu voliteľne vyžadovať kľúč API typu Bearer, keď je `REQUIRE_API_KEY=true` - „token správy“ / „kľúč API s rozsahom správy“ v tejto referenčnej príručke označuje jednu zo skupín uvedených v danej príručke — nejde o nedefinovaný dodatočný typ tajného údaja > **Nekompatibilná zmena (v3.8.0)** — `/api/v1/agents/tasks/*` a koncové body správy časového obmedzenia teraz vyžadujú **autentifikáciu správy** (súbor cookie `auth_token` ovládacieho panela alebo kľúč API s rozsahom správy). Klienti, ktorí predtým volali tieto trasy bez autentifikácie, dostanú odpoveď `401 Unauthorized`. Pozrite si commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).