# API Reference (Čeština) 🌐 **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) · 🇩🇰 [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) · 🇸🇰 [sk](../../../sk/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) | 🇨🇿 [Č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í dokumentace k API OmniRoute. Popisuje veřejné rozhraní `/v1` a nejpoužívanější koncové body pro správu; úplnými zdroji jsou strojově čitelný soubor [`docs/openapi.yaml`](../openapi.yaml) a strom tras v `src/app/api/`. --- ## Obsah - [Dokončování chatu](#chat-completions) - [Výhradní pronájmy spravovaných relací](#exclusive-managed-session-leases) - [Vektorové reprezentace](#embeddings) - [Generování obrázků](#image-generation) - [OCR dokumentů](#document-ocr) - [Seznam modelů](#list-models) - [Manifest pluginu poskytovatele](#provider-plugin-manifest) - [Koncové body kompatibility](#compatibility-endpoints) - [API souborů](#files-api) - [API dávek](#batches-api) - [API vyhledávání](#search-api) - [Streamování přes WebSocket](#websocket-streaming) - [Kvóty a hlášení problémů](#quotas--issues-reporting) - [Sémantická mezipaměť](#semantic-cache) - [Řídicí panel a správa](#dashboard--management) - [Správa kombinací](#combo-management) - [Webhooky](#webhooks) - [Registrované klíče (automatická správa)](#registered-keys-auto-management) - [Protokol agentů](#agents-protocol) - [Proxy servery pro správu](#management-proxies) - [Odolnost (rozšířená)](#resilience-extended) - [Dovednosti](#skills) - [Paměť](#memory) - [Server MCP](#mcp-server) - [Server A2A](#a2a-server) - [Cloud, vyhodnocování a posuzování](#cloud-evals--assess) - [Zpracování požadavků](#request-processing) - [Ověřování](#authentication) --- ## Dokončování 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 | Směr | Popis | | ------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-OmniRoute-No-Cache` | Požadavek | Nastavením na `true` obejdete mezipaměť | | `x-omniroute-no-memory` | Požadavek | Nastavením na `true` přeskočíte pro tento požadavek vkládání paměti a dovedností (obdobně jako bez mezipaměti; zabrání režii tokenů a nákladů na jednotlivá volání) | | `X-OmniRoute-Progress` | Požadavek | Nastavením na `true` povolíte události průběhu | | `X-Session-Id` | Požadavek | Klíč připnuté relace pro externí afinitu relací | | `x_session_id` | Požadavek | Přijímána je také varianta s podtržítkem (přímé HTTP) | | `X-OmniRoute-Session-Id` | Požadavek | Značka relace/konverzace zadaná volajícím (používá ji také paměť). Pokud je uvedena, uloží se beze změny do `call_logs.session_tag` pro přiřazení nákladů jednotlivým relacím (#8249) — pokud chybí, nikdy se nevytváří | | `Idempotency-Key` | Požadavek | Klíč pro odstranění duplicit (časové okno 5 s) | | `X-Request-Id` | Požadavek | Alternativní klíč pro odstranění duplicit | | `X-OmniRoute-Cache` | Odpověď | `HIT` nebo `MISS` (bez streamování) | | `X-OmniRoute-Idempotent` | Odpověď | `true`, pokud byly odstraněny duplicity | | `X-OmniRoute-Progress` | Odpověď | `enabled`, pokud je zapnuto sledování průběhu | | `X-OmniRoute-Session-Id` | Odpověď | Efektivní ID relace používané službou OmniRoute | | `X-OmniRoute-Request-Id` | Odpověď | ID pro korelaci požadavku (pokud je známo) | | `X-OmniRoute-Version` | Odpověď | Verze sestavení OmniRoute (vždy uvedena) | | `X-OmniRoute-Cost-Saved` | Odpověď | Částka v USD, kterou mezipaměť ušetřila při výsledku HIT (pouze při nalezení v mezipaměti) | | `X-OmniRoute-Decision` | Odpověď | Trasování směrování: `strategy=; provider=; latency_ms=` (`` je strategie kombinace, nebo `single` u požadavku bez kombinace) — vždy uvedeno v odpovědích po dokončení | > Poznámka k Nginx: pokud spoléháte na hlavičky s podtržítky (například `x_session_id`), povolte `underscores_in_headers on;`. > **Hlavičky telemetrie nákladů:** úspěšné odpovědi bez streamování obsahují také sadu telemetrie nákladů `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, pevně 10 desetinných míst; `0.0000000000` pro bezplatné položky nebo položky bez stanovené 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` (pouze pokud > 0) spolu s `X-OmniRoute-Request-Id` a `X-OmniRoute-Version`. Tyto hlavičky vracejí dokončení chatu, `/v1/responses`, `/v1/messages` **i koncové body pro média** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` a `/v1/moderations` (náklady jsou vždy `0`). Náklady na média se počítají podle modality (za obrázek, za sekundu, za znak, za vyhledávací jednotku), pokud jsou k dispozici cenové údaje; jinak jsou `0` (při chybě se pokračuje). > **Sémantika nákladů při zásahu do mezipaměti:** při ZÁSAHU do sémantické mezipaměti (`X-OmniRoute-Cache-Hit: true`) není provedeno žádné volání upstreamu, takže `X-OmniRoute-Response-Cost` je `0.0000000000` (**přírůstkové** náklady na obsloužení zásahu). Původní/předpokládané náklady jsou vykázány samostatně v `X-OmniRoute-Cost-Saved`. Systémy zpracovávající fakturační údaje by měly sčítat `X-OmniRoute-Response-Cost` (zásahy nic nestojí); analytické systémy mezipaměti mohou agregovat `X-OmniRoute-Cost-Saved`. ## Výhradní spravované pronájmy relací Výhradní pronájem spravovaných relací je volitelná, na klientovi nezávislá směrovací smlouva: jeden aktivní vlastník drží jedno způsobilé připojení OmniRoute. Nepronajímá model, nevyžaduje OAuth, neidentifikuje konkrétního klienta ani nevyžaduje konkrétního poskytovatele. Ověřovaný API klíč musí mít oprávnění `lease:exclusive` a explicitní neprázdný seznam `allowedConnections`. Hranice databázových mutací vynucuje obě pole společně při vytvoření klíče i při částečných aktualizací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"} ``` Úspěšné odpovědi na získání, obnovení a uvolnění zpřístupňují časová razítka, `state` a přesnou kladnou hodnotu `generation`, nikdy však vybrané připojení ani přihlašovací údaje. Obnovení a uvolnění předávají generaci v těle JSON: ```json { "action": "renew", "generation": 1 } ``` ```json { "action": "release", "generation": 1, "reason": "OWNER_EXIT" } ``` Aktivní vlastník pronájmu si může explicitně vyžádat metadata vhodná k bezpečnému zobrazení pro svou aktuální vazbu: ```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" } } ``` Tato volitelná akce stavu je v rámci jedné databázové transakce ohraničena neprůhledným vlastníkem, ověřeným spravovaným API klíčem a přesnou aktivní generací. `displayName` je pouze oříznutý nakonfigurovaný název připojení; pokud žádný bezpečný nakonfigurovaný název neexistuje, má hodnotu `null`. OmniRoute nikdy nenahrazuje tento název e-mailem ani vygenerovanou identitou účtu. Hodnota poskytovatele je necitlivý popisek pro zobrazení a nikdy nejde o vygenerovaný identifikátor kompatibilního poskytovatele. Přihlašovací údaje, tokeny, soubory cookie, nezpracované identifikátory připojení nebo API klíčů, otisky vlastníků, tajné hodnoty pro ohraničení a interní směrovací data jsou vyloučeny. Vyhledání s nesprávným klíčem, nesprávným vlastníkem, zastaralou generací nebo vyhledání chybějícího, prošlého, uvolněného či zneplatněného pronájmu vždy vrátí stejnou chybu `409 LEASE_FENCE_STALE` bez metadat připojení. Klient, který obdržel odpověď o čekání na kapacitu, nemá žádnou aktivní vazbu, kterou by mohl zkontrolovat. Když směrování převede aktivní pronájem, zůstává platná stejná generace a stav atomicky vrátí novou vazbu, nikdy ne tu starou. Stávající klienti zůstávají beze změny, protože odpovědi na získání, obnovení, uvolnění a čekání si zachovávají své předchozí struktury. Tato serverová smlouva nemění standardní `/status` OpenAI Codex. Standardní Codex aktuálně hlásí svého poskytovatele modelu a vestavěný stav ověření/účtu, ale nezobrazuje libovolná metadata účtů vlastních poskytovatelů; budoucí integrace klienta musí zavolat tuto akci a rozhodnout, jak zobrazit `connection.displayName`. Každý spravovaný inferenční požadavek poté předává obě řídicí hlavičky: ```http X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> X-OmniRoute-Lease-Generation: 1 ``` Přesný vlastník, generace, aktivní připojení a ověřený API klíč jsou ohraničeny bezprostředně před každým podporovaným pokusem o přístup k nadřazené službě. Opakované použití vlastníka a generace s jiným klíčem selže, i když tento klíč povoluje stejné připojení. Nezpracované hodnoty vlastníků se neukládají, nezaznamenávají do protokolů, neuchovávají ve snímku požadavku ani nepředávají nadřazené službě. Dočasná kolize vrátí 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 } ``` Tato odpověď pouze znamená, že běžná množina způsobilých připojení nebyla prázdná a každý volný kandidát byl držen cizím aktivním pronájmem. Nepodporované modely/poskytovatelé, neshoda zásad, doba zklidnění, kvóta, stav služby a další běžná selhání způsobilosti si zachovávají své stávající odpovědi OmniRoute. ### `x-omniroute-compression` Přepsání plánu komprese pro jednotlivý požadavek. Má nejvyšší prioritu — přebíjí přepsání směrovací kombinace, aktivní profil, automatické spuštění i výchozí nastavení panelu. Hodnoty: | Hodnota | Účinek | | ------------- | ----------------------------------------------------------------------------------------------------- | | `off` | Pro tento požadavek se nepoužije žádná komprese. | | `default` | Výchozí profil odvozený z panelu (ignoruje aktivní profil). | | `engine:` | Jeden modul, pokud je povolen, např. `engine:rtk`. | | `` | Pojmenovaná kombinace, nejprve porovnaná podle názvu (bez rozlišení velikosti písmen), poté podle id. | Poznámky: - Neznámé hodnoty jsou ignorovány (požadavek není nikdy odmítnut); vyhodnocení pokračuje podle běžného pořadí priorit operátorů. - Pokud má více kombinací stejný název, předejte **id** kombinace, aby bylo nalezení jednoznačné. - Kombinaci s názvem `off` nebo `default` nelze vybrat podle názvu (tato klíčová slova jsou interpretována jako první); na takovou kombinaci odkazujte pomocí jejího id. - Hlavní přepínač komprese je nepřekročitelná podmínka: pokud je komprese globálně zakázána, tato hlavička ji nemůže povolit. Použitý plán se vrací v hlavičce odpovědi: ``` X-OmniRoute-Compression: ; source= ``` kde `` je jedna z hodnot `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` nebo `off`. --- ## Embeddingy ```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í poskytovatelé: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI. Identifikátory katalogu mají tvar `provider/model` (příklad: `jina-ai/jina-embeddings-v5-omni-small`). Samostatné identifikátory modelů Jina uvedené v registru (například `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) se také správně rozpoznají. Operace embed/rerank/classify/segment od Jina používají přednostně přihlašovací údaje `jina-ai` z řídicího panelu; `JINA_AI_API_KEY` slouží pouze jako záložní možnost, pokud v řídicím panelu žádný klíč neexistuje. Karta `jina-reader` je určena pouze pro Reader / `r.jina.ai` (`POST /v1/web/fetch`) a nikdy neposkytuje embeddingy ani reranking. Modely v registru, které deklarují podporu multimodality, přijímají také až 32 strukturovaných položek nezávislých na poskytovateli. Typy multimediálních položek jsou `text`, `image`, `audio`, `video` a `document`. Jejich multimediální `source` je buď `{"type":"url","url":"https://..."}`, nebo `{"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) přijímá také nativní dokumenty EmbeddingsV5Request od Jina a **předává je beze změny** 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,..." }] } ] } ``` Nativní hodnoty `{ image | audio | video | pdf }` mohou být veřejná adresa URL používající HTTPS, identifikátor URI `data:` nebo nezpracovaný base64. OmniRoute tyto objekty nepřevádí na řetězce ani nestahuje nativní adresy URL obrázků — veřejná média načítá sama Jina. Dodatečná pole Jina (`task`, `normalized`, `truncate`, `embedding_type`) se předávají dále. Textové SKU Jina nadále odmítají netextové dokumenty. Bezpečnostní a přenosová omezení: - Vzdálené adresy URL médií musí být veřejné a používat HTTPS. Kanonické položky `{type,source:url}` se načítají na straně serveru (opakované ověření přesměrování, časový limit, omezení velikosti, veřejné DNS, připnutí připojení) a před voláním poskytovatele se vloží přímo do požadavku. Nativní položky Jina `{image:"https://..."}` se předávají beze změny po stejné kontrole veřejného HTTPS; adresu URL načte Jina. - Multimédia vložená jako base64 jsou omezena na 8 MiB dekódovaných dat na položku a 16 MiB dekódovaných dat v rámci celého požadavku. Převod pro poskytovatele (kanonické položky se nikdy nepředávají beze změny): - Multimodální modely Jina: každá položka nejvyšší úrovně se převede na jeden objekt s klíčem modality (`text` / `image` / `audio` / `video` / `pdf`), přičemž pro vložená média se použijí identifikátory URI typu data; jeden vektor na každou položku nejvyšší úrovně. - Rodina Gemini Embedding 2: jedno pole nejvyšší úrovně se převede na jediný nativní požadavek `models/{model}:embedContent` s `content.parts` (`text` nebo `inline_data`). - Neznámé/dynamické modely bez explicitních metadat modality odmítnou strukturovaný vstup s 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é kombinace modelu a modality vrátí HTTP 400 namísto převodu položky. Rozšiřující pole mimo vstup se u starších požadavků s řetězci/tokeny nadále předávají beze změny. ```bash # Vypsat všechny embeddingové modely GET /v1/embeddings ``` --- ## Generování obrázků ```bash POST /v1/images/generations Authorization: Bearer your-api-key Content-Type: application/json { "model": "openai/gpt-image-2", "prompt": "Krásný západ slunce nad horami", "size": "1024x1024" } ``` Dostupní poskytovatelé: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (lokální), ComfyUI (lokální). ```bash # Vypsat všechny modely pro generování obrázků GET /v1/images/generations ``` --- ## OCR dokumentů ```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` vybírá poskytovatele OCR pomocí prefixu `provider/model`; samotné ID modelu (např. `mistral-ocr-latest`) se přeloží na jeho registrovaného poskytovatele a při vynechání `model` se jako výchozí použije Mistral (`mistral-ocr-latest`). Registrovaní poskytovatelé (`open-sse/config/ocrRegistry.ts`): | ID poskytovatele | ID modelu | Hodnota `model` | Poznámky | | ----------------------------- | -------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (nebo samotné `mistral-ocr-latest`) | Synchronní — odpověď je vrácena přímo z jediného volání nadřazené služby. | | `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Asynchronní nadřazená služba (`analyze` + dotazování) — viz níže. | | `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Synchronní, prostřednictvím partnerského koncového bodu `openapi/chat/completions` služby Vertex AI — podrobnosti o ověřování a URL viz níže. | Všichni tři poskytovatelé odpovídají ve stejném formátu těla jako Mistral: ```json { "pages": [{ "index": 0, "markdown": "# Extrahovaný text..." }], "model": "mistral-ocr-latest", "usage_info": { "pages_processed": 1 } } ``` ### Průběh dotazování služby Azure Document Intelligence API `analyze` služby Azure Document Intelligence je asynchronní: počáteční požadavek vrací namísto těla hlavičku `Operation-Location` a na výsledek je nutné se opakovaně dotazovat. Obslužná rutina (`open-sse/handlers/ocr.ts`) se na danou URL dotazuje každou sekundu, maximálně však 30krát; při odpovědi na dotazování, která není `ok`, nebo při stavu `"failed"` okamžitě skončí s chybou (v dotazování nepokračuje) a vrátí `504`, pokud operace běží i po vyčerpání povoleného počtu pokusů. Konečná odpověď Azure je před vrácením volajícímu normalizována do stejného formátu `pages`/`markdown`, jaký používá Mistral, takže klientský kód nemusí poskytovatele řešit jako zvláštní případ. ### Ověřování a určení koncového bodu pro Vertex AI DeepSeek OCR `vertex-deepseek-ocr` znovu používá stejné ověřování Vertex AI, které již OmniRoute podporuje pro provoz chatu a obrázků (`open-sse/executors/vertex.ts`): klíčem API připojení je buď přihlašovací údaj Service Account ve formátu JSON (vyměněný za krátkodobý přístupový token OAuth prostřednictvím toku JWT bearer), nebo již vydaný přístupový token OAuth použitý beze změny. URL nadřazeného koncového bodu je obecný partnerský koncový bod Vertex `openapi/chat/completions`, sestavený z projektu a oblasti připojení — explicitní `providerSpecificData.project`/`providerSpecificData.region` má vždy přednost; jinak je projekt odvozen z `project_id` v JSON Service Account a jako výchozí oblast se použije `us-central1`. Obě hodnoty se určují v `open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`) a jsou použity v `src/app/api/v1/ocr/route.ts` před předáním do `handleOcr`. --- ## Výpis modelů ```bash GET /v1/models Authorization: Bearer your-api-key → Vrátí všechny chatovací, embeddingové a obrazové modely + kombinace ve formátu OpenAI ``` ### Prefixy ID modelů (`?prefix=`) Většina modelů je zveřejňována pod **prefixem poskytovatele**. Použitý prefix je řízen příznakem funkce `MODELS_CATALOG_PREFIX_MODE` a lze jej přepsat **pro každý požadavek** pomocí parametru dotazu — což je užitečné pro klienta, který chce přehledný seznam, aniž by měnil nastavení serveru pro všechny ostatní: ```bash GET /v1/models?prefix=alias # jedno ID na model — krátký alias prefixu GET /v1/models?prefix=dual # obě podoby (výchozí nastavení serveru) GET /v1/models?prefix=canonical # pouze úplný prefix ID poskytovatele ``` | Režim | Vrací | Poznámky | | ----------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dual` | `cc/claude-sonnet-4-6` **a** `claude/claude-sonnet-4-6` | **Výchozí.** Obě ID směrují na stejný model; tato možnost je zachována, aby nadále fungovaly konfigurace klientů, které napevno používají jednu z těchto podob. Přibližně zdvojnásobuje velikost katalogu. | | `alias` | `cc/claude-sonnet-4-6` | Jedna položka na model. Poskytovatelé bez samostatného aliasu svou položku přesto vracejí, takže se nic neztratí. | | `canonical` | `claude/claude-sonnet-4-6` | Jedna položka na model pod úplným prefixem ID poskytovatele. Poskytovatelé bez samostatného aliasu (např. `antigravity/…`, `agy/…`) zde také vracejí své jediné ID, takže se nic neztratí. | Zrcadlenou položku v režimu `dual` lze rozpoznat také bez parametru dotazu: obsahuje pole `parent` odkazující na primární ID. Klienti zobrazující výběr modelu by měli používat `?prefix=alias` — takto postupuje [rozšíření OmniCopilot pro VS Code](../guides/VSCODE-COPILOT.md). ### Varianty modelů bez přemýšlení Pro modely Claude podporující přemýšlení zveřejňuje `/v1/models` také variantu **bez přemýšlení**, jejíž ID má prefix `claude-3-omniroute-no-thinking/`: ``` claude-3-omniroute-no-thinking// ``` Výběr tohoto ID (např. v konfiguraci Claude Code, která vždy připojuje blok `thinking`) se přeloží zpět na skutečný model `/` s potlačeným uvažováním — pomocí `thinking:{type:"disabled"}` na cestě `/v1/messages`, nebo odstraněním polí `reasoning`/`reasoning_effort` na cestě `/v1/chat/completions`. Tato varianta je uvedena pouze pro modely rodiny Claude, které podporují přemýšlení **a zároveň** respektují hodnotu `disabled` (takže jsou například vyloučeny modely podporující pouze adaptivní režim, které hodnotu `disabled` odmítají). Provozovatelé mohou tuto variantu pro jednotlivé modely vynutit nebo zakázat prostřednictvím `ModelSpec.noThinkingAlias`. --- ## Manifest pluginů poskytovatelů ```bash GET /api/v1/provider-plugin-manifest ``` Vrací manifest pluginů poskytovatelů kompatibilní s JSON, který používají Bifrost, CLIProxyAPI a budoucí postranní směrovače. Odpověď se generuje z registru poskytovatelů v TypeScriptu a záměrně nezahrnuje klientská tajemství OAuth, řešení běhového prostředí, spouštěcí funkce, hlavičky požadavků ani údaje účtů. Tento koncový bod použijte, když postranní proces běží mimo hlavní proces a nemůže přímo importovat `open-sse/config/providerPluginManifestRegistry.ts`. --- ## Koncové body kompatibility | Metoda | 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 (úpravy/inpainting) | | POST | `/v1/videos/generations` | Generování videa ve stylu OpenAI | | POST | `/v1/music/generations` | Generování hudby ve stylu OpenAI | | POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) | | POST | `/v1/audio/speech` | OpenAI TTS (vrací tělo se zvukem) | | POST | `/v1/rerank` | Přeřazení ve stylu Cohere/Voyage | | POST | `/v1/classify` | Klasifikace Jina (`api.jina.ai`) | | POST | `/v1/segment` | Segmentátor Jina (`segment.jina.ai`) | | POST | `/v1/moderations` | OpenAI Moderations | | GET | `/v1/models` | OpenAI | | 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 katalogu OpenAI | | GET | `/api/v1/vscode/{token}/models` | Alias modelů 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ček Ollama | Všechny trasy POST mají stejnou strukturu: `Bearer your-api-key` + tělo JSON ověřené pomocí Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` atd., viz `src/shared/validation/schemas.ts`). Při selhání ověření schématu se vrátí stav 4xx. Klientům, kteří nemohou připojit `Authorization: Bearer ...`, umožňuje OmniRoute předat klíče API také v URL, a to buď prostřednictvím kompatibilních parametrů řetězce dotazu (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`), nebo pomocí vyhrazených koncových bodů `/api/v1/vscode/{token}/...` popsaných níže. ```bash # Přeřazení POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] } # Klasifikace Jina (přihlašovací ú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 } # Vyhledávání Jina (s.jina.ai; aliasy poskytovatele: jina-search, jina-ai, jina) POST /v1/search { "query": "...", "provider": "jina-search" } # Moderování POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." } # TTS — vrací tělo audio/mpeg (nebo tělo v požadovaném formátu) POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } # Úprava obrázku (multipart) POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png # Generování videa / hudby (ID modelu s prefixem poskytovatele) POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." } POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." } ``` ### Vyhrazené trasy poskytovatelů ```bash POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` Pokud prefix poskytovatele chybí, přidá se automaticky. Při neshodě modelů se vrátí `400`. --- ## Files API Endpoint kompatibilní s OpenAI pro dávkový vstup/výstup a nahrávání souborů s určeným účelem. | Metoda | Cesta | Popis | | ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/files` | Nahraje soubor (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — maximálně 512 MiB | | GET | `/v1/files` | Vypíše soubory pro ověřený API klíč | | GET | `/v1/files/[id]` | Načte metadata souboru | | DELETE | `/v1/files/[id]` | Smaže soubor | | GET | `/v1/files/[id]/content` | Odešle zpět nezpracovaný obsah souboru jako stream | **Ověření:** API klíč typu Bearer — rozsah souborů je omezen na jednotlivé API klíče prostřednictvím `getApiKeyRequestScope`. Klíč může zobrazit, stáhnout a smazat pouze vlastní soubory; relace ovládacího panelu bez klíče má přístup k celé instanci; přístup k souboru bez vlastníka (anonymně nahranému nebo nahranému prostřednictvím relace ovládacího panelu) je odepřen všem volajícím bez relace. `GET /v1/files` odmítne anonymního volajícího — stejně jako poskytnutý klíč, který nelze přeložit — s kódem `401`, i když je `REQUIRE_API_KEY=false`, namísto vypsání souborů všech klientů (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523). --- ## Batches API Dávkové zpracování kompatibilní s OpenAI. | Metoda | Cesta | Popis | | ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------ | | POST | `/v1/batches` | Vytvoří dávku — tělo ověřené pomocí `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) | | GET | `/v1/batches` | Vypíše dávky | | GET | `/v1/batches/[id]` | Načte stav dávky a `request_counts` | | DELETE | `/v1/batches/[id]` | Smaže dokončenou nebo neúspěšnou dávku | | POST | `/v1/batches/[id]/cancel` | Zruší probíhající dávku | **Ověření:** API klíč typu Bearer. Rozsah dávek je omezen na jednotlivé API klíče podle stejného trojstranného pravidla jako u souborů: pouze vlastní klíč, relace ovládacího panelu v rámci celé instance, záznamy s vlastníkem null jsou odepřeny všem volajícím bez relace (načtení, smazání, zrušení a kontrola `input_file_id` při vytváření). `GET /v1/batches` odmítne anonymního volajícího s kódem `401`, i když je `REQUIRE_API_KEY=false`. --- ## Vyhledávací API Abstrakce poskytovatelů webového vyhledávání (Tavily, Brave, Exa, Serper atd.). | Metoda | Cesta | Popis | | ------ | ---------------------- | ---------------------------------------------------------------------------------------------------- | | GET | `/v1/search` | Vypíše nakonfigurované poskytovatele vyhledávání a jejich možnosti | | POST | `/v1/search` | Spustí vyhledávací dotaz — tělo ověřuje `v1SearchSchema`, podporuje ukládání do mezipaměti/slučování | | GET | `/v1/search/analytics` | Statistiky zásahů, latence a mezipaměti pro jednotlivé poskytovatele | **Ověření:** API klíč typu Bearer (`extractApiKey` + `isValidApiKey`). Zásady vyhledávání jsou vynucovány prostřednictvím `enforceApiKeyPolicy`. --- ## API pro načítání webu Extrahuje obsah z URL prostřednictvím nakonfigurovaného poskytovatele načítání webu (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract). | Metoda | Cesta | Popis | | ------ | --------------- | ----------------------------------------------------- | | POST | `/v1/web/fetch` | Načte/extrahuje URL — tělo ověřuje `v1WebFetchSchema` | **Ověření:** API klíč typu Bearer (`extractApiKey` + `isValidApiKey`). Zásady jsou vynucovány prostřednictvím `enforceApiKeyPolicy`. **Záložní přepínání zohledňující kvóty (#8297):** pokud není zadán explicitní `provider`, fond (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) je procházen v pevném pořadí priorit (fill-first) — nakonfigurovaný poskytovatel s omezenou četností požadavků je přeskočen, místo aby požadavek okamžitě ukončil, a opakovatelná chyba upstreamu nebo chyba kvóty (HTTP 429 vždy; 402/403 pro bezplatné úrovně Firecrawl/Tavily/TinyFish se stylem kvót — nikoli pro Jina Reader a nikdy pro běžný chybný požadavek 400) způsobí za běhu požadavku přechod k dalšímu dosud nevyzkoušenému poskytovateli s přihlašovacími údaji. Když jsou vyčerpáni všichni poskytovatelé ve fondu, koncový bod vrátí jedinou odpověď `429` (s hlavičkou `Retry-After`) namísto dřívější obecné odpovědi `400`. Pokud je vyžádán explicitní `provider`, k žádnému tichému záložnímu přepnutí **nedojde** — explicitní poskytovatel s omezenou četností požadavků nebo s chybou vrátí svou vlastní chybu (`429` při omezení četnosti požadavků, jinak stav upstreamu). --- ## Streamování přes WebSocket ```bash GET /v1/ws?handshake=1 ``` Ověří handshake pro upgrade na WebSocket a vrátí ukázkové zprávy přenosového protokolu (`request`, `cancel`). Skutečné rámce WS zpracovává přibalený server WS mimo tabulku tras Next.js. **Ověření:** API klíč typu Bearer během handshaku. ### Responses API přes WebSocket (pouze codex) ```bash # Stejný hostitel:port jako HTTP API (výchozí 20128); upgradujte připojení: wscat -c "ws://localhost:20128/v1/responses?api_key=" # (nebo: -H "Authorization: Bearer ") # První rámec MUSÍ být response.create: { "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] } ``` Proxy Responses API přes WebSocket je propojena **výhradně s `codex`** (backend ChatGPT). Naslouchá na stejném portu jako API/řídicí panel na cestách `/v1/responses`, `/responses` a `/api/v1/responses`. Při prvním rámci `response.create` provede ověření a přípravu prostřednictvím interního mostu `codex-responses-ws`, vybere připojení codex OAuth a tuneluje do `wss://chatgpt.com/backend-api/codex/responses` prostřednictvím transportu `wreq-js`. **Modely jiné než codex jsou odmítnuty** (`codex_ws_provider_required`). Pro směrování podle sdílené kvóty použijte `model: "qtSd//codex/"`. Implementováno v `app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`. **Ověření:** API klíč typu Bearer během handshaku. Přibalený HTTP server (`server-ws.mjs`) musí být aktivním vstupním bodem (což ve výchozím nastavení je, pokud existuje `app/server-ws.mjs`). #### ID modelu: použijte holé ID ChatGPT (bez prefixu `codex/`) OpenAI **Codex CLI** ověřuje název modelu na straně klienta, pokud `supports_websockets = true`, a **odmítá ID s prefixem poskytovatele**, například `codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`). Odešlete **holé** ID (např. `gpt-5.5`). Most OmniRoute je určen pouze pro codex, takže před tunelováním do upstreamu znovu vyhodnotí holé ID jako model codex (`resolveCodexWsModelInfo`) — i když by jinak bylo holé `gpt-5.5` přes HTTP směrováno k jinému poskytovateli. #### Konfigurace OpenAI Codex CLI Nasměrujte Codex CLI na OmniRoute přidáním vlastního poskytovatele s podporou WebSocket do `~/.codex/config.toml` (použijte samostatný `CODEX_HOME`, abyste nezasáhli do existující konfigurace): ```toml model = "gpt-5.5" # holé ID — NE „codex/gpt-5.5“ model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute (WS)" base_url = "http://localhost:20128/v1" # bez koncového lomítka; URL WS se odvodí (v produkci použijte https/wss) wire_api = "responses" # jediná podporovaná hodnota od února 2026 supports_websockets = true # povolí transport Responses přes WS env_key = "OMNIROUTE_API_KEY" # obsahuje API klíč OmniRoute (Bearer) ``` ```bash export OMNIROUTE_API_KEY=sk-... # API klíč OmniRoute (libovolný klíč, pokud REQUIRE_API_KEY=false) codex exec "Responda apenas: PONG" ``` CLI upgraduje `base_url + /responses` na WebSocket a OmniRoute jej tuneluje do vybraného připojení codex OAuth. Ověřeno kompletně od začátku do konce vůči místnímu serveru: ChatGPT vrací `codex.rate_limits` + `response.created` a streamuje dokončení. --- ## Kvóty a hlášení problémů | Metoda | Cesta | Popis | | ------ | ------------------- | ------------------------------------------------------------------------------------------- | | GET | `/v1/quotas/check` | Předběžné ověření kvóty pro `provider` + `accountId` před vydáním registrovaného klíče | | POST | `/v1/issues/report` | Nahlášení selhání kvóty nebo vydání klíče na GitHub (vyžaduje `GITHUB_ISSUES_REPO` + token) | **Ověření:** Bearer API klíč (`isAuthenticated`). --- ## Samoobslužné zobrazení využití (`/api/usage/om-usage`) Libovolný API klíč může načíst **své vlastní** využití a kvóty — bez ověření pro správu. Toto je koncový bod, který klient (CLI, panel OmniCopilot) používá k zobrazení útraty držitele klíče. ```bash # Textová podoba (historický kontrakt — prostý text pro terminál) curl -H "Authorization: Bearer " \ http://localhost:20128/api/usage/om-usage # Strukturovaná podoba — používá ji uživatelské rozhraní curl -H "Authorization: Bearer " \ "http://localhost:20128/api/usage/om-usage?format=json" ``` Klíč musí mít povolenou možnost **`allowUsageCommand`** (ve výchozím nastavení je vypnutá — správce API klíčů na řídicím panelu ji přepíná pro každý klíč zvlášť). Bez ní koncový bod odpoví stavem `403`. `?format=json` vrací rozlišitelnou strukturu, takže volající nikdy nečte datové pole z odpovědi o zamítnutí. Při úspěchu: ```jsonc { "allowed": true, // přítomno pouze tehdy, když má klíč aktivované limity využití pro jednotlivý klíč (denní/týdenní v USD): "personal": { "dailySpentUsd": 1.25, "dailyLimitUsd": 5, "dailyResetAtIso": "…", "weeklySpentUsd": 8, "weeklyLimitUsd": 20, "weeklyResetAtIso": "…" /* … */, }, // snímek kvóty vybraného poskytovatele, nebo null, pokud zatím není nic v mezipaměti: "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */}, }, // snímek každého připojení, aby uživatelské rozhraní mohlo zobrazit několik poskytovatelů vedle sebe: "providers": [ { "connectionId": "…", "provider": "claude" /* … */ }, { "provider": "codex" /* … */ }, ], } ``` Při zamítnutí (`401` neplatný klíč / `403` nepovoleno) stejná trasa vrátí `{ "allowed": false, "error": { "message": "…" } }` — přítomné, ale prázdné `personal`/`provider` (klíč je povolen, ale zatím nebyla získána žádná data) představuje jiný stav než zamítnutí a rozlišuje je pouze podoba JSON. **Ověření:** vlastní Bearer API klíč volajícího, ověřený pomocí `isValidApiKey` — toto _není_ rozhraní pro správu (`/api/keys/…`), které zůstává chráněné pomocí `requireManagementAuth`. --- ## Sémantická mezipaměť ```bash # Získání statistik mezipaměti GET /api/cache/stats # Vymazání všech mezipamětí DELETE /api/cache/stats ``` Příklad odpovědi: ```json { "semanticCache": { "memorySize": 42, "memoryMaxSize": 500, "dbSize": 128, "hitRate": 0.65 }, "idempotency": { "activeKeys": 3, "windowMs": 5000 } } ``` ### Dopad na latenci ZÁSAH do sémantické mezipaměti poskytne odpověď z mezipaměti **bez volání nadřazené služby**, takže hlášená hodnota `X-OmniRoute-Response-Latency` je téměř nulová (bez ohledu na původní latenci nadřazené služby). Klienti citliví na latenci (benchmarking, monitorování p50/p99) by měli kontrolovat hlavičku odpovědi `X-OmniRoute-Cache-Latency`: | Hodnota | Význam | | ----------- | -------------------------------------------------------------------- | | `synthetic` | Odpověď poskytnutá z mezipaměti; latence není skutečný čas upstreamu | | _(chybí)_ | Odpověď ze skutečného volání upstreamu | ### Obejití mezipaměti pro jednotlivé klíče API klíče mohou pomocí `cacheDefaultMode` vypnout čtení ze sémantické mezipaměti: | Hodnota | Chování | | -------- | ------------------------------------------------------------- | | `legacy` | Běžné chování mezipaměti (výchozí) | | `bypass` | Zcela přeskočit vyhledávání v mezipaměti; vždy volat upstream | Nastavte při vytvoření klíče (`POST /api/keys`) nebo aktualizaci (`PATCH /api/keys/[id]`): ```json { "cacheDefaultMode": "bypass" } ``` ### Obejití pro jednotlivý požadavek Libovolný požadavek může obejít mezipaměť bez ohledu na nastavení klíče: ``` X-OmniRoute-No-Cache: true ``` --- ## Řídicí panel a správa Trasy pro správu (`/api/*` kromě veřejného ověřování/přihlášení) **nejsou** autorizovány běžnými API klíči pro inferenci. Rodiny přihlašovacích údajů, rozsahy oprávnění a příklady použití curl: [Ověřování pro správu](../guides/MANAGEMENT-AUTH.md). ### Ověřování | Koncový bod | Metoda | Popis | | ----------------------------- | ------- | ----------------------------- | | `/api/auth/login` | POST | Přihlášení | | `/api/auth/logout` | POST | Odhlášení | | `/api/settings/require-login` | GET/PUT | Přepnutí povinného přihlášení | ### Správa poskytovatelů | Koncový bod | Metoda | Popis | | ---------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `/api/providers` | GET/POST | Výpis / vytvoření poskytovatelů | | `/api/providers/[id]` | GET/PUT/DELETE | Správa poskytovatele | | `/api/providers/[id]/test` | POST | Otestování připojení k poskytovateli | | `/api/providers/[id]/models` | GET | Výpis modelů poskytovatele | | `/api/providers/validate` | POST | Ověření konfigurace poskytovatele | | `/api/providers/bulk` | POST | Hromadné přidání API klíčů pro JEDNOHO poskytovatele | | `/api/providers/import` | POST | Import heterogenního SEZNAMU poskytovatelů z analyzovaného souboru CSV/JSON (#6836); výsledky částečných selhání po řádcích | | `/api/provider-nodes*` | Různé | Správa uzlů poskytovatelů | | `/api/provider-models` | GET/POST/PATCH/DELETE | Vlastní modely (přidání, aktualizace, skrytí/zobrazení, odstranění) | ### Toky OAuth | Koncový bod | Metoda | Popis specifický pro poskytovatele | | -------------------------------- | ------ | ---------------------------------- | | `/api/oauth/[provider]/[action]` | Různé | OAuth specifický pro poskytovatele | ### Směrování a konfigurace | Koncový bod | Metoda | Popis | | --------------------- | -------- | ----------------------------------------- | | `/api/models/alias` | GET/POST | Aliasy modelů | | `/api/models/catalog` | GET | Všechny modely podle poskytovatele + typu | | `/api/combos*` | Různé | Správa kombinací | | `/api/keys*` | Různé | Správa API klíčů | | `/api/pricing` | GET | Ceny modelů | ### Využití a analytika | Endpoint | Metoda | Popis | | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/api/usage/history` | GET | Historie využití | | `/api/usage/logs` | GET | Protokoly využití | | `/api/usage/request-logs` | GET | Protokoly na úrovni požadavků | | `/api/usage/[connectionId]` | GET | Využití podle připojení | | `/api/usage/token-limits` | GET/POST/DELETE | Rozpočty limitů tokenů podle klíče API | | `/api/usage/model-latency-stats` | GET | Průběžné agregované statistiky latence podle poskytovatele/modelu (průměr/p50/p95/p99, míra úspěšnosti); filtry: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) | | `/api/usage/cache-health` | GET | Souhrn stavu mezipaměti promptů nad `call_logs` — poměr zápisů/čtení, rozdělení velikosti zápisů p50/p90/p99, koncentrace intenzivních zápisů, rozdělení podle modelu a výsledek `healthy`/`degraded`/`thrash`/`no-data`; parametry dotazu `range` (`1h`\|`24h`\|`7d`\|`30d`, výchozí `24h`) a volitelný `model` (#8827) | ### Nastavení | Endpoint | Metoda | Popis | | ------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/settings` | GET/PUT/PATCH | Obecná nastavení | | `/api/settings/proxy` | GET/PUT | Konfigurace síťového proxy serveru | | `/api/settings/proxy/test` | POST | Otestování připojení přes proxy server | | `/api/settings/ip-filter` | GET/PUT | Seznam povolených/blokovaných IP adres | | `/api/settings/thinking-budget` | GET/PUT | Režim přepisu **požadavku** na rozpočet přemýšlení/uvažování (beze změny / automatické odstranění / vlastní / adaptivní). Nezávislý na kompresi. Viz [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). | | `/api/settings/system-prompt` | GET/PUT | Globální systémový prompt | | `/api/settings/compression` | GET/PUT | Globální konfigurace komprese | | `/api/settings/purge-request-history` | POST | Vymazání řádků protokolu požadavků a místních artefaktů protokolu volání | ### Kontext a komprese | Endpoint | Metoda | Popis | | -------------------------------------- | -------------- | ----------------------------------------------------------------------------------------- | | `/api/compression/preview` | POST | Náhled komprese off/lite/standard/aggressive/ultra/RTK/stacked | | `/api/compression/language-packs` | GET | Seznam dostupných jazykových balíčků Caveman | | `/api/compression/rules` | GET | Seznam metadat pravidel Caveman | | `/api/context/caveman/config` | GET/PUT | Alias pro nastavení specifická pro Caveman | | `/api/context/rtk/config` | GET/PUT | Nastavení specifická pro RTK, včetně vlastních filtrů a uchovávání nezpracovaného výstupu | | `/api/context/rtk/filters` | GET | Katalog filtrů RTK a diagnostika vlastních filtrů | | `/api/context/rtk/test` | POST | Spuštění náhledu/testu RTK nad textovou datovou částí | | `/api/context/rtk/raw-output/[id]` | GET | Načtení uchovaného anonymizovaného nezpracovaného výstupu podle ID ukazatele | | `/api/context/combos` | GET/POST | Seznam/vytvoření kombinací komprese | | `/api/context/combos/[id]` | GET/PUT/DELETE | Podrobnosti/aktualizace/odstranění kombinace komprese | | `/api/context/combos/[id]/assignments` | GET/PUT | Přiřazení kombinací komprese ke kombinacím směrování | | `/api/context/analytics` | GET | Alias analytiky komprese | ### Monitorování | Endpoint | Metoda | Popis | | ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/sessions` | GET | Sledování aktivních relací | | `/api/rate-limits` | GET | Limity požadavků pro jednotlivé účty | | `/api/monitoring/health` | GET | Kontrola stavu + souhrn poskytovatelů (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Zobrazení pro správu zahrnuje `credentialHealth`: skalární hodnoty mezipaměti sond, `failedConnections`, když `failed>0`, a `staleDbNonOkCount` (trvalá hodnota `test_status` v SQLite, nikoli ukazatel). Viz [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). | | `/api/cache/stats` | GET/DELETE | Statistiky mezipaměti / vymazání | | `/api/modality-bridge/stats` | GET | Hodnoty `attempts`, úspěšné pokusy/`bridged`, selhání, zásahy mezipaměti, `totalLatencyMs`, `latencySamples`, hodnota `averageLatencyMs` vypočtená podle počtu vzorků a čas posledního použití uložené v paměti (resetují se při restartu; ověření pro správu) | | `/api/modality-bridge/video/runtime` | GET | Striktní kontrola důvěryhodného místního rozhraní před ověřením/sondou pro správu; sanitizované informace o dostupnosti a verzích FFmpeg/ffprobe (no-store) | | `/api/modality-bridge/video/extract` | POST | Interní ověřovaný zprostředkovatel bajtů přes důvěryhodné místní rozhraní; vstup 50 MiB, omezená fronta/výstup 32 MiB, kapacita `503`, odpojení `499`, překročení časového limitu `504`; nejde o veřejné API pro nahrávání souborů | ### Zálohování a export/import | Endpoint | Metoda | Popis | | --------------------------- | ------ | ------------------------------------------ | | `/api/db-backups` | GET | Vypsat dostupné zálohy | | `/api/db-backups` | PUT | Vytvořit ruční zálohu | | `/api/db-backups` | POST | Obnovit z konkrétní zálohy | | `/api/db-backups/export` | GET | Stáhnout databázi jako soubor .sqlite | | `/api/db-backups/import` | POST | Nahrát soubor .sqlite a nahradit databázi | | `/api/db-backups/exportAll` | GET | Stáhnout úplnou zálohu jako archiv .tar.gz | ### Cloudová synchronizace | Endpoint | Metoda | Popis | | ---------------------- | ------ | ------------------------------ | | `/api/sync/cloud` | Různé | Operace cloudové synchronizace | | `/api/sync/initialize` | POST | Inicializovat synchronizaci | | `/api/cloud/*` | Různé | Správa cloudu | ### Tunely | Endpoint | Metoda | Popis | | -------------------------- | ------ | ---------------------------------------------------------------------- | | `/api/tunnels/cloudflared` | GET | Načíst stav instalace a běhu Cloudflare Quick Tunnel pro řídicí panel | | `/api/tunnels/cloudflared` | POST | Povolit nebo zakázat Cloudflare Quick Tunnel (`action=enable/disable`) | | `/api/tunnels/ngrok` | GET | Načíst stav běhu ngrok Tunnel pro řídicí panel | | `/api/tunnels/ngrok` | POST | Povolit nebo zakázat ngrok Tunnel (`action=enable/disable`) | ### Nástroje CLI | Endpoint | Metoda | Popis | | ---------------------------------- | ------ | -------------------- | | `/api/cli-tools/claude-settings` | GET | Stav Claude CLI | | `/api/cli-tools/codex-settings` | GET | Stav Codex CLI | | `/api/cli-tools/droid-settings` | GET | Stav Droid CLI | | `/api/cli-tools/openclaw-settings` | GET | Stav OpenClaw CLI | | `/api/cli-tools/runtime/[toolId]` | GET | Obecné prostředí CLI | Odpovědi CLI zahrnují: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. ### Agenti ACP | Endpoint | Metoda | Popis | | ----------------- | ------ | ----------------------------------------------------------------- | | `/api/acp/agents` | GET | Vypsat všechny zjištěné agenty (vestavěné + vlastní) včetně stavu | | `/api/acp/agents` | POST | Přidat vlastního agenta nebo aktualizovat mezipaměť detekce | | `/api/acp/agents` | DELETE | Odebrat vlastního agenta podle parametru dotazu `id` | Odpověď GET zahrnuje `agents[]` (id, name, binary, version, installed, protocol, isCustom) a `summary` (total, installed, notFound, builtIn, custom). ### Odolnost a limity požadavků | Endpoint | Metoda | Popis | | --------------------------------- | --------- | ------------------------------------------------------------------------------------------------- | | `/api/resilience` | GET/PATCH | Získat/aktualizovat frontu požadavků, prodlevu připojení, jistič poskytovatele a nastavení čekání | | `/api/resilience/reset` | POST | Resetovat jističe okruhů poskytovatelů | | `/api/resilience/model-cooldowns` | GET | Vypsat aktivní blokace podle (poskytovatele, připojení, modelu), seřazené podle zbývajícího času | | `/api/resilience/model-cooldowns` | DELETE | Zrušit blokaci modelu — tělo `{provider, model}` nebo `{all: true}` pro vymazání všech | | `/api/rate-limits` | GET | Stav limitu požadavků pro jednotlivé účty | | `/api/rate-limit` | GET | Globální konfigurace limitu požadavků | > Všechny čtyři trasy `/api/resilience/*` vyžadují **ověření pro správu** (`requireManagementAuth`). Úplný rozbor jističe poskytovatele, prodlevy připojení a blokace modelu najdete v části [Odolnost (rozšířené)](#resilience-extended). ### Vyhodnocení | Endpoint | Metoda | Popis | | ------------ | -------- | --------------------------------------------- | | `/api/evals` | GET/POST | Vypsat sady vyhodnocení / spustit vyhodnocení | ### Zásady | Endpoint | Metoda | Popis | | --------------- | --------------- | -------------------------- | | `/api/policies` | GET/POST/DELETE | Spravovat zásady směrování | ### Soulad s předpisy | Endpoint | Metoda | Popis | | --------------------------- | ------ | -------------------------------------- | | `/api/compliance/audit-log` | GET | Protokol auditu souladu (posledních N) | ### v1beta (kompatibilní s Gemini) | Endpoint | Metoda | Popis | | -------------------------- | ------ | --------------------------------- | | `/v1beta/models` | GET | Vypsat modely ve formátu Gemini | | `/v1beta/models/{...path}` | POST | Endpoint Gemini `generateContent` | Tyto endpointy kopírují formát API Gemini pro klienty, kteří očekávají nativní kompatibilitu se sadou Gemini SDK. ### Interní / systémová API | Koncový bod | Metoda | Popis | | ------------------------ | ------ | --------------------------------------------------------------- | | `/api/init` | GET | Kontrola inicializace aplikace (používá se při prvním spuštění) | | `/api/tags` | GET | Značky modelů kompatibilní s Ollama (pro klienty Ollama) | | `/api/restart` | POST | Spustí korektní restart serveru | | `/api/shutdown` | POST | Spustí korektní vypnutí serveru | | `/api/system/env/repair` | POST | Opraví proměnné prostředí poskytovatele OAuth | > **Poznámka:** Tyto koncové body používá interně systém nebo slouží ke kompatibilitě s klienty Ollama. Koncoví uživatelé je obvykle nevolají. ### Oprava prostředí OAuth _(v3.6.1+)_ ```bash POST /api/system/env/repair Content-Type: application/json { "provider": "claude-code" } ``` Opraví chybějící nebo poškozené proměnné prostředí OAuth pro konkrétního poskytovatele. Vrací: ```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" } ``` --- ## Přepis zvuku ```bash POST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` Přepisujte zvukové soubory pomocí libovolného nakonfigurovaného poskytovatele STT. První segment cesty vybírá nativního poskytovatele (`openai/…`, `deepgram/…`). Brány, které znovu zpřístupňují model jiného poskytovatele, používají kvalifikovaný identifikátor (`openrouter/deepgram/nova-3`). **Požadavek:** ```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" ``` **Odpověď:** ```json { "text": "Hello, this is the transcribed audio content.", "task": "transcribe", "language": "en", "duration": 12.5 } ``` **Příklady identifikátorů modelů:** `openai/whisper-1` (vyžaduje klíč OpenAI), `openrouter/deepgram/nova-3` (vyžaduje klíč OpenRouter), `deepgram/nova-3` (vyžaduje nativní klíč Deepgram). Požadavek se samotným `deepgram/nova-3` **nepoužívá** OpenRouter. **Podporované formáty:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- ## Kompatibilita s Ollama Pro klienty, kteří používají formát API služby Ollama: ```bash # Koncový bod chatu (formát Ollama) POST /v1/api/chat # Výpis modelů (formát Ollama) GET /api/tags ``` Požadavky jsou automaticky převáděny mezi formátem Ollama a interními formáty. ## Tokenizované aliasy pro VS Code / aliasy bez hlaviček Tyto aliasy použijte, pokud integrace nemůže vložit hlavičku `Authorization` a potřebuje mít klíč API vložený do základní adresy URL. ```bash # Alias katalogu ve stylu OpenAI GET /api/v1/vscode/{token}/ GET /api/v1/vscode/{token}/models # Aliasy chatu ve stylu OpenAI POST /api/v1/vscode/{token}/chat/completions POST /api/v1/vscode/{token}/responses # Aliasy ve stylu Ollama POST /api/v1/vscode/{token}/api/chat GET /api/v1/vscode/{token}/api/tags ``` Pří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: - Tokenizované aliasy používají stejné obslužné rutiny jako `/v1/*` a `/api/tags`; struktura odpovědí zůstává identická. - Pokud klient podporuje vlastní hlavičky, upřednostněte `Authorization: Bearer ...`. - Tokeny v adrese URL se mohou objevit v protokolech reverzního proxy serveru, historii prohlížeče a telemetrii mimo OmniRoute. Považujte je za možnost zajišťující kompatibilitu, nikoli za výchozí režim ověřování. --- ## Telemetrie ```bash # Získání souhrnu telemetrie latence (p50/p95/p99 pro každého poskytovatele) GET /api/telemetry/summary ``` **Odpověď:** ```json { "providers": { "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } } } ``` --- ## Rozpočet ```bash # Získání stavu rozpočtu pro všechny klíče API GET /api/usage/budget # Nastavení nebo aktualizace rozpočtu 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 ke schématu** (`setBudgetSchema`): `apiKeyId` je povinné; alespoň jedna z hodnot `dailyLimitUsd`, `weeklyLimitUsd` nebo `monthlyLimitUsd` musí být větší než nula. Volitelná pole: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Zastaralá struktura `{keyId, limit, period}` vrací `400 Bad Request`. ## Limity tokenů Rozpočty **tokenů** pro jednotlivé klíče API (odlišné od výše uvedeného rozpočtu založeného na USD). Vynucují se přímo během zpracování požadavku: jakmile využití klíče v aktuálním časovém okně dosáhne stanoveného limitu, požadavky jsou odmítnuty s chybou `429 Too Many Requests`. Limity lze omezit na konkrétní `model`, `provider` nebo je použít globálně (`global`) pro celý klíč; pokud požadavku odpovídá více limitů, použije se ten nejpřísnější. ```bash # Výpis limitů tokenů klíče (včetně aktuálního využití časového okna) GET /api/usage/token-limits?apiKeyId=key-123 # Vytvoření nebo aktualizace limitu tokenů POST /api/usage/token-limits Content-Type: application/json { "apiKeyId": "key-123", "scopeType": "model", "scopeValue": "openai/gpt-4o", "tokenLimit": 1000000, "resetInterval": "monthly", "enabled": true } # Odstranění limitu tokenů podle id DELETE /api/usage/token-limits?id=tl-abc ``` > **Poznámky ke schématu** (`setTokenLimitSchema`): `apiKeyId` a `scopeType` (`model` | `provider` | `global`) jsou povinné. `scopeValue` je povinné, pokud `scopeType` není `global` (např. id modelu pro rozsah `model`, id poskytovatele pro rozsah `provider`). `tokenLimit` musí být kladné celé číslo (převedené z řetězce). Volitelné: `id` (vynechte při vytváření, zadejte při aktualizaci), `resetInterval` (`daily` | `weekly` | `monthly`, výchozí hodnota `monthly`), `resetTime` (`HH:MM`), `enabled` (výchozí hodnota `true`). Odpovědi `GET` rozšiřují každý limit o `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` a `nextResetAt`. Jde o koncový bod třídy pro správu (ověřování se centrálně vynucuje prostřednictvím autorizačního kanálu). ## Zpracování požadavků 1. Klient odešle požadavek na `/v1/*` 2. Obslužná rutina trasy zavolá `handleChat`, `handleEmbedding`, `handleAudioTranscription` nebo `handleImageGeneration` 3. Model je vyhodnocen (přímý poskytovatel/model nebo alias/kombinace) 4. Přihlašovací údaje jsou vybrány z místní databáze s filtrováním podle dostupnosti účtu 5. Pro chat: `handleChatCore` zkontroluje mezipaměť sémantických shod/podpisů a vyhodnotí nastavení komprese kombinace 6. Pokud je povolena, před překladem pro poskytovatele se spustí proaktivní komprese (`lite`, Caveman, RTK nebo jejich vrstvená kombinace) 7. Vykonavatel poskytovatele odešle požadavek nadřazené službě 8. Odpověď je převedena zpět do formátu klienta (chat) nebo vrácena beze změny (vektorové reprezentace/obrázky/zvuk) 9. Zaznamená se využití, analytika komprese a protokoly požadavků 10. Při chybách se podle pravidel kombinace použije záložní varianta Úplný popis architektury: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md) --- ## Správa kombinací Kombinace směrování vyšší úrovně (již shrnuté v části `/api/combos*`) lze také mapovat v poměru 1:1 ze vzoru id modelu, což umožňuje transparentní přesměrování id modelu ve stylu OpenAI na kombinaci. | Metoda | Cesta | Popis | | ------ | -------------------------------- | ---------------------------------------------------------------------------------- | | GET | `/api/model-combo-mappings` | Výpis všech mapování model→kombinace | | POST | `/api/model-combo-mappings` | Vytvoření mapování — tělo: `{pattern, comboId, priority?, enabled?, description?}` | | GET | `/api/model-combo-mappings/[id]` | Načtení jednoho mapování | | PUT | `/api/model-combo-mappings/[id]` | Aktualizace polí existujícího mapování | | DELETE | `/api/model-combo-mappings/[id]` | Odstranění mapování | **Ověření:** relace pro správu / klíč API (`requireManagementAuth`). --- ## Webhooky Odběry odchozích webhooků pro události OmniRoute (dokončení požadavku, vyčerpání kvóty, rotace klíče atd.). | Metoda | Cesta | Popis | | ------ | ------------------------- | ---------------------------------------------------------------------- | | GET | `/api/webhooks` | Vypíše webhooky (tajné klíče jsou maskovány jako `...`) | | POST | `/api/webhooks` | Vytvoří webhook — tělo: `{url, events?: ["*"], secret?, description?}` | | GET | `/api/webhooks/[id]` | Načte webhook | | PUT | `/api/webhooks/[id]` | Aktualizuje url/events/secret/description | | DELETE | `/api/webhooks/[id]` | Odstraní webhook | | POST | `/api/webhooks/[id]/test` | Odešle testovací datovou část na URL webhooku a vrátí stav doručení | **Ověření:** relace správy / API klíč (`requireManagementAuth`). --- ## Registrované klíče (automatická správa) Podsystém automatické správy klíčů je používá k vydávání a rotaci API klíčů u poskytovatele nebo účtu na pozadí s denními a hodinovými kvótami. | Metoda | Cesta | Popis | | ------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/registered-keys` | Vypíše registrované klíče (pouze maskovaná předpona) | | POST | `/api/v1/registered-keys` | Vydá nový registrovaný klíč — tělo: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Nezpracovaný klíč vrátí **pouze jednou**. Při odmítnutí kvůli kvótě vrátí `429`. | | GET | `/api/v1/registered-keys/[id]` | Načte metadata registrovaného klíče (bez nezpracovaného klíče) | | DELETE | `/api/v1/registered-keys/[id]` | Zneplatní registrovaný klíč | | POST | `/api/v1/registered-keys/[id]/revoke` | Explicitní koncový bod pro zneplatnění (stejný účinek jako DELETE) | **Ověření:** API klíč Bearer (`isAuthenticated`). Viz také `/v1/quotas/check` a `/v1/issues/report`. --- ## Protokol agentů Úlohy cloudových agentů (Claude Code, Codex Cloud, OpenHands atd.) spouštěné vzdáleně jménem uživatelů OmniRoute. | Metoda | Cesta | Popis | | ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/v1/agents/tasks` | Seznam úloh — volitelné `?provider=`, `?status=`, `?limit=` (1–500, výchozí hodnota 50) | | POST | `/api/v1/agents/tasks` | Vytvoření úlohy — tělo ověřované pomocí `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Vrací `201` s obálkou úlohy | | DELETE | `/api/v1/agents/tasks?id=...` | Odstranění úlohy | | GET | `/api/v1/agents/tasks/[id]` | Načtení úlohy — synchronně aktualizuje stav z nadřazeného cloudového agenta, pokud je nastaveno `external_id` | | POST | `/api/v1/agents/tasks/[id]` | Rozlišená akce: `{action: "approve"}`, `{action: "message", message}` nebo `{action: "cancel"}` | | DELETE | `/api/v1/agents/tasks/[id]` | Odstranění konkrétní úlohy podle ID | > **Ověření:** U každé metody je vyžadováno ověření pro správu (`requireCloudAgentManagementAuth`). Před verzí v3.8.0 nebyly tyto metody ověřovány — změnu narušující zpětnou kompatibilitu naleznete v commitu `588a0333`. ```bash # Vytvoření cloudové ú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 pro správu Odchozí proxy servery HTTP(S)/SOCKS, které lze přiřadit poskytovatelům, účtům nebo globálně. | Metoda | Cesta | Popis | | ------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/management/proxies` | Seznam proxy serverů (s `?id=` vrátí jeden; s `?id=&where_used=1` vrátí graf přiřazení) | | POST | `/api/v1/management/proxies` | Vytvoření proxy serveru — tělo ověřované pomocí `createProxyRegistrySchema` | | PATCH | `/api/v1/management/proxies` | Aktualizace proxy serveru — tělo ověřované pomocí `updateProxyRegistrySchema` (vyžaduje `id`) | | DELETE | `/api/v1/management/proxies?id=...&force=1` | Odstranění proxy serveru (pro odpojení přiřazení použijte `force=1`) | | GET | `/api/v1/management/proxies/assignments` | Seznam přiřazení — lze filtrovat podle `proxy_id`, `scope`, `scope_id`; předáním `resolve_connection_id=` zjistíte aktivní proxy server pro dané připojení | | PUT | `/api/v1/management/proxies/assignments` | Přiřazení — tělo ověřované pomocí `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Vymaže mezipaměť dispečera | | PUT | `/api/v1/management/proxies/bulk-assign` | Hromadné přiřazení — tělo ověřované pomocí `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) | | GET | `/api/v1/management/proxies/health?hours=24` | Agregovaný stav proxy serverů (počty úspěchů/neúspěchů, latence) za časové období | **Ověření:** Na každé trase je vyžadována relace pro správu nebo klíč API (`requireManagementAuth`). > Trasy `POST /api/v1/management/proxies/[id]/assignments` a `POST /api/v1/management/proxies/[id]/health` z popisu úlohy jsou obsluhovány výše uvedenými plochými trasami `/assignments` a `/health` — v kódové základně neexistují žádné dílčí trasy podle ID. --- ## Odolnost (rozšířená) OmniRoute poskytuje tři nezávislé mechanismy pro dočasná selhání; níže uvedené koncové body pro správu umožňují operátorům číst a přepisovat jejich stav: | Rozsah | Úložiště stavu | Čtení | Resetování / vymazání | | -------------------- | -------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------- | | Jistič poskytovatele | `domain_circuit_breakers` + v paměti | `/api/monitoring/health` | `POST /api/resilience/reset` | | Prodleva připojení | `rateLimitedUntil` u připojení poskytovatele | `/api/rate-limits`, `/api/providers/[id]` | (znovu se aktivuje až při použití; vymazání přes PUT poskytovatele) | | Uzamčení modelu | Registr dostupnosti modelů v paměti | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` | `PATCH /api/resilience` přijímá přepsání jističe poskytovatele v `providerBreaker.oauth` a `providerBreaker.apikey`. Každý profil podporuje `degradationThreshold`, `failureThreshold` a `resetTimeoutMs`; stejná pole jsou dostupná v Řídicí panel → Nastavení → Odolnost. ```bash # Vymazání uzamčení jednoho 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"}' # Vymazání všech uzamčení curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ -H "Cookie: auth_token=..." \ -d '{"all":true}' ``` Úplný koncepční přehled a výchozí nastavení jističů: viz [`CLAUDE.md`](../../CLAUDE.md) → „Stav běhu odolnosti“. --- ## Dovednosti Framework dovedností pro rozšíření OmniRoute o vlastní spustitelné obslužné rutiny a integrace s tržišti. | Metoda | Cesta | Popis | | ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Výpis nainstalovaných dovedností — lze filtrovat pomocí `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, stránkováno | | GET | `/api/skills/[id]` | Načtení jedné dovednosti | | PUT | `/api/skills/[id]` | Aktualizace dovednosti (název, popis, režim, schéma, obslužná rutina, značky) | | DELETE | `/api/skills/[id]` | Odinstalování dovednosti | | POST | `/api/skills/install` | Instalace dovednosti z nezpracovaného manifestu — tělo: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` | | GET | `/api/skills/executions` | Výpis nedávných spuštění dovedností (auditní stopa se vstupy, výstupy a dobou trvání) | | GET | `/api/skills/marketplace?q=...` | Vyhledávání / seznam oblíbených položek z tržiště SkillsMP (vyžaduje nastavení `skillsmpApiKey`) | | POST | `/api/skills/marketplace/install` | Instalace dovednosti podle ID ze SkillsMP | | GET | `/api/skills/skillssh?q=&limit=` | Vyhledávání v registru skills.sh | | POST | `/api/skills/skillssh/install` | Instalace dovednosti podle ID ze skills.sh | **Ověření:** relace správy / klíč API. Trasy vyhledávání na tržišti přijímají ověření správy nebo klíč API typu Bearer (`isAuthenticated`). --- ## Paměť Trvalé úložiště konverzační/faktické paměti s rozsahem omezeným na klíč API / relaci. | Metoda | Cesta | Popis | | ------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------- | | GET | `/api/memory` | Výpis vzpomínek — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, se stránkováním pomocí `offset/limit` nebo `page/limit` | | POST | `/api/memory` | Vytvoření vzpomínky — tělo validované pomocí Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` | | GET | `/api/memory/[id]` | Načtení jedné vzpomínky | | DELETE | `/api/memory/[id]` | Odstranění vzpomínky | | GET | `/api/memory/health` | Stav paměťového subsystému (připojení k DB, backend vektorových reprezentací, stav vektorového indexu) | **Ověřování:** relace pro správu / klíč API (`requireManagementAuth`). Výčet `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (viz `MemoryType` v `src/lib/memory/types.ts`). --- ## Server MCP OmniRoute obsahuje vestavěný server protokolu Model Context Protocol se 3 transporty (stdio, SSE, streamable-http) a nástroji s omezeným rozsahem oprávnění. Níže uvedené endpointy řídicího panelu načítají údaje o stavu/auditu a zprostředkovávají HTTP transporty. | Metoda | Cesta | Popis | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | `/api/mcp/status` | Prezenční signál, transport, stav připojení, poslední volání, nejpoužívanější nástroje, míra úspěšnosti za 24 hodin | | GET | `/api/mcp/tools` | Seznam nástrojů MCP s poli `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` | | GET | `/api/mcp/sse` | Otevření streamu SSE pro transport SSE (vrací `503`, pokud je MCP zakázáno nebo transport neodpovídá) | | POST | `/api/mcp/sse` | Odeslání rámce JSON-RPC prostřednictvím transportu SSE | | GET | `/api/mcp/stream` | Otevření strany SSE transportu Streamable HTTP (zprávy iniciované serverem) | | POST | `/api/mcp/stream` | Odeslání rámce JSON-RPC prostřednictvím transportu Streamable HTTP | | DELETE | `/api/mcp/stream` | Ukončení relace Streamable HTTP | | GET | `/api/mcp/audit` | Dotaz na protokol auditu — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` | | GET | `/api/mcp/audit/stats` | Agregované statistiky auditu (celkové počty, míra úspěšnosti, průměrná doba trvání, nejpoužívanější nástroje) | **Ověřování:** transporty `sse`/`stream` respektují ověřování specifické pro MCP (klíč API typu Bearer s rozsahem `mcp`); trasy `status`/`tools`/`audit*` jsou čitelné z řídicího panelu (kromě přístupu k hostiteli řídicího panelu není vyžadováno žádné další ověření). > Oba HTTP transporty jsou řízeny nastaveními `settings.mcpEnabled` a `settings.mcpTransport` — neshoda transportu vrací `400`, zakázaný stav MCP vrací `503`. --- ## Server A2A OmniRoute zpřístupňuje koncový bod A2A (Agent-to-Agent) JSON-RPC 2.0 a také REST obálku pro účely kontroly a řídicího panelu. ### JSON-RPC ```bash POST /a2a Authorization: Bearer your-api-key # volitelné, pokud není nastavena proměnná 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é metody (všechny jsou podmíněny nastavením `settings.a2aEnabled`): | Metoda | Popis | | ---------------- | ------------------------------------------------------------------- | | `message/send` | Synchronní spuštění dovednosti; vrací `{task, artifacts, metadata}` | | `message/stream` | Streamované spuštění stejné sady dovedností pomocí SSE | | `tasks/get` | Načtení úlohy podle `taskId` | | `tasks/cancel` | Zrušení úlohy podle `taskId` | Vestavěné dovednosti: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`. ### Karta agenta ```bash GET /.well-known/agent.json ``` Vrací veřejnou kartu agenta A2A (název, popis, schopnosti, katalog dovedností, schéma ověřování) — je veřejně ukládána do mezipaměti na 1 hodinu. Ověření není vyžadováno. ### Pomocné koncové body REST | Metoda | Cesta | Popis | | ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------- | | GET | `/api/a2a/status` | Stav povolení A2A + statistiky úloh + souhrn karty agenta uložené v mezipaměti | | GET | `/api/a2a/tasks` | Výpis úloh — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` | | POST | `/api/a2a/tasks` | (Není implementováno jako pomocný koncový bod REST — vytvořte prostřednictvím JSON-RPC `message/send`) | | GET | `/api/a2a/tasks/[id]` | Načtení jedné úlohy | | POST | `/api/a2a/tasks/[id]/cancel` | Zrušení úlohy | **Ověřování:** pomocné koncové body REST fungují bez ověření pro správu (jsou čitelné z řídicího panelu); trasa JSON-RPC `/a2a` používá Bearer `OMNIROUTE_API_KEY`, pokud je nakonfigurován. --- ## Cloud, vyhodnocení a posouzení | Metoda | Cesta | Popis | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | `/api/cloud/auth` | Ověří klíč Bearer a vrátí maskovaná připojení poskytovatelů + aliasy modelů pro klienty cloudové synchronizace | | POST | `/api/cloud/credentials/update` | Aktualizuje šifrované přihlašovací údaje poskytovatele synchronizovaného s cloudem | | POST | `/api/cloud/model/resolve` | Převede logické ID modelu na konkrétního poskytovatele/model pomocí místní směrovací tabulky | | GET | `/api/cloud/models/alias` | Vypíše aliasy modelů zpřístupněné cloudové synchronizaci | | GET | `/api/assess` | Načte nejnovější kategorizace posouzení (podle poskytovatele/modelu) | | POST | `/api/assess` | Spustí posouzení — tělo: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` | | GET | `/api/evals` | Vypíše vestavěné sady vyhodnocení + nejnovější běhy | | POST | `/api/evals` | Spustí běh vyhodnocení | | POST | `/api/evals/suites` | Vytvoří vlastní sadu vyhodnocení — tělo ověřuje `evalSuiteSaveSchema` | | GET | `/api/evals/suites/[id]` | Načte vlastní sadu vyhodnocení | **Ověřování:** `/api/cloud/auth` ověřuje klíč Bearer přímo; ostatní trasy `/api/cloud/*`, `/api/evals/*` a `/api/assess` vyžadují relaci pro správu nebo klíč API. Požadavek POST na `/api/assess` používá `validateBody` se schématem rozsahu typu discriminated union. --- ## Správa ACP (Agent Client Protocol) jako podřízené procesy. Tyto koncové body spravují detekci agentů ACP a registraci vlastních agentů. | Metoda | Cesta | Popis | | ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/acp/agents` | Vypíše všechny známé agenty CLI (vestavěné i vlastní) se stavem instalace, verzí a binárním souborem | | POST | `/api/acp/agents` | Zaregistruje vlastního agenta ACP nebo aktualizuje mezipaměť — tělo: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` nebo `{action: "refresh"}` | | DELETE | `/api/acp/agents` | Odebere vlastního agenta ACP — parametr dotazu: `?id=` | **Příklad odpovědi** (`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 } ``` **Autorizace:** Vyžaduje relaci pro správu (soubor cookie `auth_token` řídicího panelu) nebo klíč API s rozsahem oprávnění pro správu. Úplné podrobnosti najdete v dokumentu [Framework ACP](../frameworks/ACP.md). --- ## Analytika a pozorovatelnost Koncové body analytiky v reálném čase pro monitorování směrování, komprese a diverzity poskytovatelů. Tyto koncové body zajišťují data pro stránky `/dashboard/analytics/*`. ### Analytika automatického směrování | Metoda | Cesta | Popis | | ------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/auto-routing` | Agregované statistiky automatického směrování: celkový počet volání, rozdělení strategií, úrovní a hlavní poskytovatelé | | GET | `/api/analytics/auto-routing?days=7` | Statistiky za časové období (výchozí hodnota je 24 h) | **Příklad odpovědi**: ```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 komprese | Metoda | Cesta | Popis | | ------ | ---------------------------- | -------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/compression` | Agregované statistiky komprese: ušetřené tokeny, procento úspory, rozdělení režimů, využití enginů | **Příklad odpovědi**: ```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 } } ``` ### Sledování diverzity poskytovatelů | Metoda | Cesta | Popis | | ------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/diversity` | Sledování diverzity založené na Shannonově entropii: měřením rozložení poskytovatelů předchází jediným bodům selhání | **Příklad odpovědi**: ```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 zajišťuje 40 % provozu — zvažte větší diverzifikaci"] } ``` **Autorizace:** Vyžaduje relaci pro správu nebo klíč API s rozsahem oprávnění pro správu. --- ## Operace správce Koncové body určené pouze pro správce k provozní správě. | Metoda | Cesta | Popis | | ------ | ------------------------ | ------------------------------------------------------------------------------------------------ | | GET | `/api/admin/concurrency` | Načtení aktuálních limitů souběžnosti (globálních + pro jednotlivé poskytovatele) | | POST | `/api/admin/concurrency` | Aktualizace limitů souběžnosti — tělo: `{global?: number, perProvider?: Record}` | **Ověření:** Vyžaduje relaci pro správu s oprávněním správce. --- ## Správa nástrojů CLI Správa nástrojů CLI, které se integrují s OmniRoute (antigravity, chipotle, commandCode, devin-cli atd.). Úplný seznam naleznete v [referenční příručce poskytovatelů](./PROVIDER_REFERENCE.md). | Metoda | Cesta | Popis | | ------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cli-tools/all-statuses` | Stav všech nástrojů CLI (instalace, verze, poslední zaznamenané použití) | | GET | `/api/cli-tools/status` | Podrobnosti o stavu jednoho nástroje CLI (dotaz `?tool=`) | | POST | `/api/cli-tools/apply` | Zápis vygenerované konfigurace nástroje (`dryRun` zobrazí náhled; při běhu v kontejneru vrátí `422` + `containerEphemeralTarget`; `migration` upozorní na starší YAML konfiguraci Codex) | | GET | `/api/cli-tools/backups` | Výpis záloh konfigurace nástrojů CLI | | POST | `/api/cli-tools/backups` | Vytvoření zálohy konfigurací všech nástrojů CLI | | POST | `/api/cli-tools/backups` | Obnovení: stejný koncový bod s `{tool, backupId}` v těle obnoví danou zálohu | | GET | `/api/cli-tools/antigravity-mitm` | Stav proxy MITM Antigravity (nástroj CLI „antigravity-mitm“) | | POST | `/api/cli-tools/antigravity-mitm/alias` | Konfigurace aliasů antigravity-mitm | **Ověření:** Vyžaduje relaci pro správu. --- ## Dovednosti agentů Správa dovedností agentů AI (podobných vlastním GPT od OpenAI, ale určených pro agenty). | Metoda | Cesta | Popis | | ------ | ---------------------------- | ----------------------------------------------------------------------------------------------- | | GET | `/api/agent-skills` | Výpis všech dovedností agentů (vestavěných + vlastních) | | GET | `/api/agent-skills/[id]` | Načtení konkrétní dovednosti agenta | | POST | `/api/agent-skills` | Vytvoření vlastní dovednosti agenta — tělo: `{name, description, prompt, model?, temperature?}` | | PUT | `/api/agent-skills/[id]` | Aktualizace vlastní dovednosti agenta | | DELETE | `/api/agent-skills/[id]` | Odstranění vlastní dovednosti agenta | | GET | `/api/agent-skills/[id]/raw` | Načtení nezpracovaného promptu + metadat (bez spuštění) | | POST | `/api/agent-skills/generate` | Vygenerování nové dovednosti pomocí AI z popisu v přirozeném jazyce | **Ověření:** Vyžaduje relaci pro správu nebo klíč API s oprávněním pro správu. --- ## Správa mezipaměti Správa sémantické mezipaměti a mezipaměti uvažování. | Metoda | Cesta | Popis | | ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------- | | GET | `/api/cache` | Přehled mezipaměti: celkový počet záznamů, míra zásahů, velikost na disku | | GET | `/api/cache/entries` | Seznam záznamů v mezipaměti (se stránkováním) | | DELETE | `/api/cache/entries` | Odstranění záznamů z mezipaměti (filtrování podle parametrů dotazu) | | GET | `/api/cache/stats` | Podrobné statistiky mezipaměti (podle poskytovatele a modelu) | | GET | `/api/cache/reasoning` | Stav mezipaměti uvažování (pro opakované přehrání uvažování) | | DELETE | `/api/cache/reasoning` | Vymazání mezipaměti uvažování — parametry dotazu: `?toolCallId=` (jeden), `?provider=

` nebo žádné (vše) | **Ověření:** Vyžaduje relaci pro správu. --- ## Systém paměti Správa trvalé paměti (FTS5 + vektorová vnoření). | Metoda | Cesta | Popis | | ------ | ------------------ | -------------------------------------------------------------------------------- | | GET | `/api/memory` | Seznam záznamů v paměti (filtrování podle rozsahu, typu a vyhledávacího dotazu) | | POST | `/api/memory` | Vytvoření nového záznamu v paměti — tělo: `{scope, type, content, metadata?}` | | GET | `/api/memory/[id]` | Získání konkrétního záznamu v paměti | | PUT | `/api/memory/[id]` | Aktualizace záznamu v paměti | | DELETE | `/api/memory/[id]` | Odstranění záznamu z paměti | | GET | `/api/memory?q=` | Vyhledávání v paměti (FTS5 + vektory) — statistiky jsou součástí stejné odpovědi | **Ověření:** Vyžaduje relaci pro správu nebo klíč API s rozsahem pro správu. --- ## Webhooky Správa odběrů událostí prostřednictvím webhooků. | Metoda | Cesta | Popis | | ------ | ------------------------------- | --------------------------------------------------------------------------- | | GET | `/api/webhooks` | Seznam všech odběrů webhooků | | POST | `/api/webhooks` | Vytvoření odběru webhooku — tělo: `{url, events[], secret?, active?}` | | GET | `/api/webhooks/[id]` | Získání konkrétního odběru webhooku | | PUT | `/api/webhooks/[id]` | Aktualizace odběru webhooku | | DELETE | `/api/webhooks/[id]` | Odstranění odběru webhooku | | GET | `/api/webhooks/[id]/deliveries` | Seznam historie doručení webhooku (protokol úspěšných/neúspěšných doručení) | | POST | `/api/webhooks/[id]/test` | Odeslání testovací události webhooku | **Ověření:** Vyžaduje relaci pro správu. Úplný seznam typů událostí naleznete v dokumentu [Framework webhooků](../frameworks/WEBHOOKS.md). --- ## Framework dovedností Správa dovedností (frameworku agentních rozšíření). | Metoda | Cesta | Popis | | ------ | ------------------------ | ------------------------------------------------------------------------------------------ | | GET | `/api/skills` | Vypíše všechny nainstalované dovednosti (vestavěné i vlastní) | | POST | `/api/skills/install` | Nainstaluje dovednost z místní cesty nebo URL | | DELETE | `/api/skills/[id]` | Odinstaluje dovednost | | PUT | `/api/skills/[id]` | Povolí nebo zakáže dovednost — tělo: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` | | POST | `/api/skills/executions` | Spustí dovednost — tělo: `{skillName, apiKeyId, input?, sessionId?}` | | GET | `/api/skills/executions` | Vypíše historii spuštění všech dovedností (filtrování pomocí `?apiKeyId=`) | **Ověření:** Vyžaduje relaci pro správu nebo klíč API s oprávněními pro správu. Úplné podrobnosti naleznete v dokumentaci [Framework dovedností](../frameworks/SKILLS.md). --- ## Pluginy Správa pluginů OmniRoute (rozšíření třetích stran). | Metoda | Cesta | Popis | | ------ | ---------------------------------- | ------------------------------- | | GET | `/api/plugins` | Vypíše nainstalované pluginy | | POST | `/api/plugins/marketplace/install` | Nainstaluje plugin z tržiště | | DELETE | `/api/plugins/[name]` | Odinstaluje plugin | | POST | `/api/plugins/[name]/activate` | Aktivuje plugin | | POST | `/api/plugins/[name]/deactivate` | Deaktivuje plugin | | GET | `/api/plugins/[name]/config` | Získá konfiguraci pluginu | | PUT | `/api/plugins/[name]/config` | Aktualizuje konfiguraci pluginu | **Ověření:** Vyžaduje relaci pro správu. Úplné podrobnosti naleznete v dokumentaci [Framework pluginů](../frameworks/PLUGIN_SDK.md). --- ## Stínové směrování Stínové porovnávání poskytovatelů / porovnávání A-B **není samostatné rozhraní REST** — konfiguruje se prostřednictvím kombinovaného směrování (viz [Automatická kombinace](../routing/AUTO-COMBO.md)). Metriky porovnání pro jednotlivé kombinace poskytuje `GET /api/combos/metrics`. --- ## Ochranná opatření Kontrola běhových ochranných opatření (detekce osobních údajů, detekce vložení instrukcí, přemostění obrazového vstupu). Ochranná opatření se spouštějí při každém požadavku; jejich vynechání pro jednotlivá volání se provádí prostřednictvím hlavičky požadavku `x-omniroute-disabled-guardrails` — trvalé rozhraní pro jejich povolení či zakázání neexistuje. | Metoda | Cesta | Popis | | ------ | ---------------------- | ---------------------------------------------------------------------------------------------------- | | GET | `/api/guardrails` | Vypíše registrovaná ochranná opatření a jejich stav (název / povoleno / priorita) | | POST | `/api/guardrails/test` | Provede zkušební běh předvolacího kanálu nad vzorovým vstupem — tělo: `{input, disabledGuardrails?}` | **Ověření:** Vyžaduje relaci pro správu. Úplné podrobnosti naleznete v dokumentaci [Zabezpečení > Ochranná opatření](../security/GUARDRAILS.md). --- --- ## Autentizace Informace o čtyřech typech přihlašovacích údajů (relace řídicího panelu, místní token CLI, přístupový token `oma_live_…`, klíč API s oprávněním ke správě) a o tom, jak se liší od klíčů pro inferenci, najdete v dokumentu [Autentizace správy](../guides/MANAGEMENT-AUTH.md). - Trasy řídicího panelu (`/dashboard/*`) používají soubor cookie `auth_token` - Přihlášení používá uložený hash hesla; jako záložní možnost používá `INITIAL_PASSWORD` - Nastavení `requireLogin` lze přepínat prostřednictvím `/api/settings/require-login` - Trasy `/v1/*` mohou volitelně vyžadovat klíč API typu Bearer, pokud platí `REQUIRE_API_KEY=true` - Pojmy „token pro správu“ / „klíč API s oprávněním ke správě“ v této referenční příručce označují jeden z typů uvedených v daném průvodci — nikoli další nedefinovaný typ tajného údaje > **Zpětně nekompatibilní změna (v3.8.0)** — `/api/v1/agents/tasks/*` a koncové body pro správu intervalů cooldown nyní vyžadují **autentizaci správy** (soubor cookie `auth_token` řídicího panelu nebo klíč API s oprávněním ke správě). Klienti, kteří dříve volali tyto trasy bez autentizace, obdrží odpověď `401 Unauthorized`. Viz commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).