# API Reference (Lietuvių) 🌐 **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) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇻 [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) --- 🌐 **Kalbos:** 🇺🇸 [Anglų](./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) Pagrindinis „OmniRoute“ API žinynas. Jame aprašoma viešoji `/v1` sąsaja ir dažniausiai naudojami valdymo galiniai taškai; išsamūs šaltiniai yra kompiuterio skaitomas failas [`docs/openapi.yaml`](../openapi.yaml) ir maršrutų medis kataloge `src/app/api/`. --- ## Turinys - [Pokalbių užbaigimai](#chat-completions) - [Išskirtinės valdomų sesijų nuomos](#exclusive-managed-session-leases) - [Įterpiniai](#embeddings) - [Vaizdų generavimas](#image-generation) - [Dokumentų OCR](#document-ocr) - [Modelių sąrašas](#list-models) - [Teikėjo papildinio manifestas](#provider-plugin-manifest) - [Suderinamumo galiniai taškai](#compatibility-endpoints) - [Failų API](#files-api) - [Paketinių užduočių API](#batches-api) - [Paieškos API](#search-api) - [WebSocket srautinis perdavimas](#websocket-streaming) - [Kvitų ir problemų ataskaitos](#quotas--issues-reporting) - [Semantinė podėlio atmintinė](#semantic-cache) - [Valdymo skydelis ir administravimas](#dashboard--management) - [Derinių valdymas](#combo-management) - [Žiniatinklio kabliai](#webhooks) - [Registruoti raktai (automatinis valdymas)](#registered-keys-auto-management) - [Agentų protokolas](#agents-protocol) - [Valdymo tarpiniai serveriai](#management-proxies) - [Atsparumas (išplėstinis)](#resilience-extended) - [Įgūdžiai](#skills) - [Atmintis](#memory) - [MCP serveris](#mcp-server) - [A2A serveris](#a2a-server) - [Debesija, vertinimai ir įvertinimas](#cloud-evals--assess) - [Užklausų apdorojimas](#request-processing) - [Autentifikavimas](#authentication) --- ## Pokalbių užbaigimai ```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 } ``` ### Pasirinktinės antraštės | Antraštė | Kryptis | Aprašymas | | ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-OmniRoute-No-Cache` | Užklausa | Nustatykite `true`, kad apeitumėte podėlį | | `x-omniroute-no-memory` | Užklausa | Nustatykite `true`, kad šiai užklausai nebūtų įterpiama atmintis ir įgūdžiai (atitinka podėlio išjungimą; išvengiama kiekvieno iškvietimo žetonų ir sąnaudų pridėtinės išlaidos) | | `X-OmniRoute-Progress` | Užklausa | Nustatykite `true`, kad gautumėte eigos įvykius | | `X-Session-Id` | Užklausa | Pastovus sesijos raktas išoriniam sesijos susiejimui | | `x_session_id` | Užklausa | Taip pat priimamas variantas su pabraukimo brūkšniais (tiesioginis HTTP) | | `X-OmniRoute-Session-Id` | Užklausa | Skambinančiojo pateikta sesijos / pokalbio žyma (taip pat naudojama atminčiai). Jei ji pateikta, pažodžiui išsaugoma `call_logs.session_tag`, kad būtų galima priskirti sąnaudas sesijai (#8249) — jei nepateikta, ji niekada nesugeneruojama | | `Idempotency-Key` | Užklausa | Dubliavimo šalinimo raktas (5 s intervalas) | | `X-Request-Id` | Užklausa | Alternatyvus dubliavimo šalinimo raktas | | `X-OmniRoute-Cache` | Atsakymas | `HIT` arba `MISS` (ne srautiniu režimu) | | `X-OmniRoute-Idempotent` | Atsakymas | `true`, jei dublikatas pašalintas | | `X-OmniRoute-Progress` | Atsakymas | `enabled`, jei įjungtas eigos stebėjimas | | `X-OmniRoute-Session-Id` | Atsakymas | Faktinis sesijos ID, kurį naudoja OmniRoute | | `X-OmniRoute-Request-Id` | Atsakymas | Užklausos koreliacijos ID (kai žinomas) | | `X-OmniRoute-Version` | Atsakymas | OmniRoute komponavimo versija (visada pateikiama) | | `X-OmniRoute-Cost-Saved` | Atsakymas | USD suma, kurios išvengta dėl podėlio `HIT` (tik podėlio pataikymų atveju) | | `X-OmniRoute-Decision` | Atsakymas | Maršruto parinkimo seka: `strategy=; provider=; latency_ms=` (`` yra derinio strategija arba `single`, jei užklausa nėra derinys) — visada pateikiama užbaigimo atsakymuose | > Pastaba dėl Nginx: jei naudojate antraštes su pabraukimo brūkšniais (pavyzdžiui, `x_session_id`), įjunkite `underscores_in_headers on;`. > **Sąnaudų telemetrijos antraštės:** sėkminguose ne srautiniu režimu pateikiamuose atsakymuose taip pat yra `X-OmniRoute-*` sąnaudų telemetrijos rinkinys — `X-OmniRoute-Response-Cost` (USD, fiksuota 10 dešimtainių skilčių; `0.0000000000`, jei nemokama arba neįkainota), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit` ir `X-OmniRoute-Fallback-Attempts` (tik kai > 0), taip pat `X-OmniRoute-Request-Id` ir `X-OmniRoute-Version`. Jas pateikia pokalbių užbaigimai, `/v1/responses`, `/v1/messages` **ir medijos galiniai taškai** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` ir `/v1/moderations` (sąnaudos visada `0`). Kai prieinamos kainos, medijos sąnaudos apskaičiuojamos pagal modalumą (už vaizdą, sekundę, simbolį ar paieškos vienetą), kitu atveju jos yra `0` (klaidos atveju veikimas tęsiamas). > **Podėlio pataikymo sąnaudų semantika:** semantinio podėlio `HIT` (`X-OmniRoute-Cache-Hit: true`) atveju išorinis iškvietimas neatliekamas, todėl `X-OmniRoute-Response-Cost` yra `0.0000000000` (pataikymo aptarnavimo **prieauginės** sąnaudos). Pradinės arba galėjusios susidaryti sąnaudos atskirai pateikiamos `X-OmniRoute-Cost-Saved`. Atsiskaitymo sistemų naudotojai turėtų sumuoti `X-OmniRoute-Response-Cost` (pataikymai nieko nekainuoja); podėlio analizė gali agreguoti `X-OmniRoute-Cost-Saved`. ## Išskirtinės valdomų seansų nuomos Išskirtinė valdomų seansų nuoma yra pasirenkama, nuo kliento nepriklausoma maršruto parinkimo sutartis: vienas aktyvus savininkas valdo vieną tinkamą „OmniRoute“ ryšį. Ji nenuomoja modelio, nereikalauja „OAuth“, neidentifikuoja konkretaus kliento ir nereikalauja konkretaus teikėjo. Autentifikavimui naudojamas API raktas turi turėti sritį `lease:exclusive` ir aiškiai nurodytą netuščią `allowedConnections` sąrašą. Duomenų bazės keitimo riba užtikrina, kad abu laukai būtų pateikti kartu kuriant raktą ir atliekant dalinius atnaujinimus. ```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"} ``` Sėkminguose įgijimo, atnaujinimo ir atlaisvinimo atsakymuose pateikiamos laiko žymos, `state` ir tiksli teigiama `generation`, tačiau niekada nepateikiamas pasirinktas ryšys ar prisijungimo duomenys. Atnaujinant ir atlaisvinant generacija pateikiama JSON turinyje: ```json { "action": "renew", "generation": 1 } ``` ```json { "action": "release", "generation": 1, "reason": "OWNER_EXIT" } ``` Aktyvios nuomos savininkas gali aiškiai paprašyti privatumą išsaugančių dabartinio susiejimo rodymo metaduomenų: ```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" } } ``` Šis pasirenkamas būsenos veiksmas vienoje duomenų bazės operacijoje apsaugomas neskaidriu savininko identifikatoriumi, autentifikuotu valdomu API raktu ir tikslia aktyvia generacija. `displayName` yra tik apkarpytas sukonfigūruoto ryšio pavadinimas; kai saugaus sukonfigūruoto pavadinimo nėra, jo reikšmė yra `null`. „OmniRoute“ niekada jo nepakeičia el. pašto adresu ar sugeneruota paskyros tapatybe. Teikėjo reikšmė yra nejautri rodymo žyma ir niekada nėra sugeneruotas suderinamo teikėjo identifikatorius. Prisijungimo duomenys, prieigos raktai, slapukai, neapdoroti ryšio ar API rakto identifikatoriai, savininko maišos, apsaugos paslaptys ir vidiniai maršruto parinkimo duomenys neįtraukiami. Užklausos su netinkamu raktu, netinkamu savininku, pasenusia generacija, taip pat nerastos, pasibaigusios, atlaisvintos ar panaikintos nuomos grąžina tą pačią `409 LEASE_FENCE_STALE` klaidą be ryšio metaduomenų. Klientas, gavęs laukimo dėl pajėgumo atsakymą, neturi aktyvaus susiejimo, kurį galėtų patikrinti. Kai maršruto parinkimas pakeičia aktyvios nuomos ryšį, ta pati generacija lieka galioti, o būsenos veiksmas atomiškai grąžina naują susiejimą, niekada ne senąjį. Esami klientai lieka nepakeisti, nes įgijimo, atnaujinimo, atlaisvinimo ir laukimo atsakymų ankstesnė struktūra išlieka. Ši serverio sutartis nekeičia standartinės „OpenAI Codex“ `/status` funkcijos. Šiuo metu standartinė „Codex“ pateikia savo modelio teikėją ir integruotą autentifikavimo bei paskyros būseną, tačiau neatvaizduoja pasirinktinių teikėjo paskyros metaduomenų; būsima kliento integracija turės iškviesti šį veiksmą ir nuspręsti, kaip rodyti `connection.displayName`. Tada kiekvienoje valdomoje išvedimo užklausoje pateikiamos abi valdymo antraštės: ```http X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> X-OmniRoute-Lease-Generation: 1 ``` Tikslaus savininko, generacijos, aktyvaus ryšio ir autentifikuoto API rakto atitiktis patikrinama prieš pat kiekvieną palaikomą bandymą kreiptis į aukštesnio lygio paslaugą. Pakartotinai panaudojus savininką ir generaciją su kitu raktu, užklausa nepavyksta net kai tas raktas leidžia naudoti tą patį ryšį. Neapdoroti savininko identifikatoriai nėra saugomi, registruojami žurnaluose, išlaikomi užklausos momentinėje kopijoje ar persiunčiami aukštesnio lygio paslaugai. Laikinas užimtumas grąžina HTTP `429` su `Retry-After` ir: ```json { "state": "WAITING_FOR_CAPACITY", "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" }, "reason": "NO_FREE_ELIGIBLE_CONNECTION", "retryAfter": 30 } ``` Šis atsakymas reiškia tik tai, kad įprastas tinkamų ryšių rinkinys nebuvo tuščias, o kiekvienas laisvas kandidatas buvo užimtas kitos aktyvios nuomos. Nepalaikomi modeliai ar teikėjai, strategijos neatitiktis, laukimo laikotarpis, kvota, būklė ir kitos įprastos tinkamumo klaidos išlaiko esamus „OmniRoute“ atsakymus. ### `x-omniroute-compression` Suspaudimo plano pakeitimas konkrečiai užklausai. Turi aukščiausią prioritetą — yra viršesnis už maršruto parinkimo derinio pakeitimą, aktyvų profilį, automatinį paleidiklį ir skydelio numatytąją nuostatą. Reikšmės: | Reikšmė | Poveikis | | ------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `off` | Šiai užklausai suspaudimas netaikomas. | | `default` | Iš skydelio gautas numatytasis profilis (aktyvus profilis ignoruojamas). | | `engine:` | Vienas modulis, kai jis įjungtas, pvz., `engine:rtk`. | | `` | Pavadintas derinys, pirmiausia sutapatinamas pagal pavadinimą (neatsižvelgiant į raidžių registrą), tada pagal identifikatorių. | Pastabos: - Nežinomos reikšmės ignoruojamos (užklausa niekada neatmetama); parinkimas tęsiamas pagal įprastą operatorių pirmumo tvarką. - Jei keli deriniai turi tą patį pavadinimą, deterministiniam sutapatinimui perduokite derinio **id**. - Derinio, kurio pavadinimas yra `off` arba `default`, negalima pasirinkti pagal pavadinimą (šie raktažodžiai interpretuojami pirmiausia); tokį derinį nurodykite pagal jo identifikatorių. - Pagrindinis suspaudimo jungiklis yra absoliutus apribojimas: kai suspaudimas išjungtas visuotinai, ši antraštė negali jo įjungti. Pritaikytas planas pakartojamas atsakymo antraštėje: ``` X-OmniRoute-Compression: ; source= ``` kur `` yra viena iš šių reikšmių: `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` arba `off`. --- ## Vektorinės reprezentacijos ```bash POST /v1/embeddings Authorization: Bearer your-api-key Content-Type: application/json { "model": "nebius/Qwen/Qwen3-Embedding-8B", "input": "The food was delicious" } ``` Galimi teikėjai: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI. Katalogo ID yra `provider/model` formato (pavyzdžiui, `jina-ai/jina-embeddings-v5-omni-small`). Taip pat atpažįstami registre esantys Jina modelių ID be teikėjo prefikso (pavyzdžiui, `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`). Jina vektorizavimo, perrikiavimo, klasifikavimo ir segmentavimo funkcijos pirmiausia naudoja valdymo skydelyje esančius `jina-ai` prisijungimo duomenis; `JINA_AI_API_KEY` naudojamas kaip atsarginis variantas tik tada, kai valdymo skydelyje nėra rakto. `jina-reader` kortelė skirta tik Reader / `r.jina.ai` (`POST /v1/web/fetch`) ir niekada neteikia vektorizavimo ar perrikiavimo paslaugų. Registro modeliai, kuriems nurodytas daugiarūšio turinio palaikymas, taip pat priima iki 32 nuo teikėjo nepriklausomų struktūrizuotų elementų. Medijos elementų tipai yra `text`, `image`, `audio`, `video` ir `document`. Jų medijos `source` yra arba `{"type":"url","url":"https://..."}`, arba `{"type":"base64","data":"...","media_type":"..."}`. Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano` ir šeimos alternatyvusis pavadinimas `jina-ai/jina-embeddings-v5-omni` → omni-small) taip pat priima Jina vietinio EmbeddingsV5Request formato dokumentus ir **persiunčia juos nepakeistus** į `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,..." }] } ] } ``` Vietinio formato `{ image | audio | video | pdf }` reikšmė gali būti viešas HTTPS URL, `data:` URI arba neapdorotas base64. OmniRoute nekonvertuoja šių objektų į eilutes ir neatsisiunčia vietinio formato vaizdų URL — Jina pati gauna viešai pasiekiamą mediją. Papildomi Jina laukai (`task`, `normalized`, `truncate`, `embedding_type`) yra persiunčiami. Tik tekstui skirti Jina variantai ir toliau atmeta netekstinius dokumentus. Saugumo ir perdavimo apribojimai: - Nuotolinės medijos URL turi būti vieši HTTPS adresai. Kanoninio formato `{type,source:url}` elementai atsisiunčiami serverio pusėje (pakartotinai tikrinant peradresavimus, taikant skirtąjį laiką ir dydžio ribas, naudojant viešą DNS bei fiksuojant ryšį) ir įterpiami prieš kreipiantis į teikėją. Vietinio Jina formato `{image:"https://..."}` elementai persiunčiami nepakeisti atlikus tą patį viešo HTTPS adreso patikrinimą; URL atsisiunčia Jina. - Įterptos base64 medijos iškoduotas dydis ribojamas iki 8 MiB vienam elementui ir iki 16 MiB visai užklausai. Pritaikymas teikėjui (kanoninio formato elementai niekada nepersiunčiami nepakeisti): - Jina daugiarūšiai modeliai: kiekvienas aukščiausio lygio elementas tampa vienu pagal modalumą susietu objektu (`text` / `image` / `audio` / `video` / `pdf`), įterptai medijai naudojant duomenų URI; kiekvienam aukščiausio lygio elementui pateikiamas vienas vektorius. - Gemini Embedding 2 šeima: vienas aukščiausio lygio masyvas tampa viena vietinio formato `models/{model}:embedContent` užklausa su `content.parts` (`text` arba `inline_data`). - Nežinomi arba dinaminiai modeliai be aiškių modalumo metaduomenų atmeta struktūrizuotą įvestį, grąžindami 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" } ``` Nepalaikomi modelio ir modalumo deriniai grąžina HTTP 400, užuot priverstinai konvertavę elementą. Kiti nei input senųjų eilučių ar prieigos raktų užklausų išplėtimo laukai ir toliau persiunčiami nepakeisti. ```bash # Išvardyti visus vektorizavimo modelius GET /v1/embeddings ``` --- ## Vaizdų generavimas ```bash POST /v1/images/generations Authorization: Bearer your-api-key Content-Type: application/json { "model": "openai/gpt-image-2", "prompt": "A beautiful sunset over mountains", "size": "1024x1024" } ``` Galimi teikėjai: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (vietinis), ComfyUI (vietinis). ```bash # Išvardyti visus vaizdų modelius GET /v1/images/generations ``` --- ## Dokumentų OCR ```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` parenka OCR teikėją pagal `provider/model` prefiksą; modelio ID be prefikso (pvz., `mistral-ocr-latest`) susiejamas su registruotu jo teikėju, o jei `model` nenurodytas, pagal numatytuosius nustatymus naudojamas Mistral (`mistral-ocr-latest`). Registruoti teikėjai (`open-sse/config/ocrRegistry.ts`): | Teikėjo ID | Modelio ID | `model` reikšmė | Pastabos | | ----------------------------- | -------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (arba `mistral-ocr-latest` be prefikso) | Sinchroninis — atsakymas grąžinamas tiesiogiai iš vienintelės išorinės užklausos. | | `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Asinchroninė išorinė paslauga (`analyze` + būsenos tikrinimas) — žr. toliau. | | `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Sinchroninis, naudojantis Vertex AI partnerio galiniu tašku `openapi/chat/completions` — autentifikavimas ir URL aprašyti toliau. | Visi trys teikėjai pateikia tokios pačios Mistral formos atsako turinį: ```json { "pages": [{ "index": 0, "markdown": "# Extracted text..." }], "model": "mistral-ocr-latest", "usage_info": { "pages_processed": 1 } } ``` ### Azure Document Intelligence būsenos tikrinimo eiga Azure Document Intelligence `analyze` API yra asinchroninė: pradinė užklausa vietoje atsako turinio grąžina `Operation-Location` antraštę, todėl rezultatą reikia periodiškai tikrinti. Apdorojimo programa (`open-sse/handlers/ocr.ts`) tikrina tą URL kas sekundę, atlikdama iki 30 bandymų, iškart nutraukia darbą (nebetęsia tikrinimo), jei tikrinimo atsakymas nėra `ok` arba būsena yra `"failed"`, ir grąžina `504`, jei išnaudojus visus bandymus operacija vis dar vykdoma. Prieš grąžinant klientui, galutinis Azure atsakymas normalizuojamas į tą pačią `pages`/`markdown` formą, kurią naudoja Mistral, todėl kliento kode nereikia atskirai apdoroti kiekvieno teikėjo. ### Vertex AI DeepSeek OCR autentifikavimas ir galinio taško nustatymas `vertex-deepseek-ocr` pakartotinai naudoja tą patį Vertex AI autentifikavimą, kurį OmniRoute jau palaiko pokalbių ir vaizdų srautui (`open-sse/executors/vertex.ts`): ryšio API raktas yra arba paslaugos paskyros JSON kredencialas (naudojant JWT nešėjo prieigos rakto gavimo eigą pakeičiamas į trumpalaikį OAuth prieigos raktą), arba jau išduotas OAuth prieigos raktas, naudojamas toks, koks yra. Išorinės paslaugos galinio taško URL yra bendrasis Vertex partnerio galinis taškas `openapi/chat/completions`, sudaromas pagal ryšio projektą ir regioną — aiškiai nurodyti `providerSpecificData.project`/`providerSpecificData.region` visada turi pirmenybę; kitu atveju projektas nustatomas pagal paslaugos paskyros JSON lauką `project_id`, o numatytasis regionas yra `us-central1`. Abu nustatymai atliekami faile `open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`) ir naudojami `src/app/api/v1/ocr/route.ts` prieš perduodant vykdymą funkcijai `handleOcr`. --- ## Modelių sąrašas ```bash GET /v1/models Authorization: Bearer your-api-key → Grąžina visus pokalbių, įterpinių ir vaizdų modelius bei jų derinius OpenAI formatu ``` ### Modelių ID prefiksai (`?prefix=`) Dauguma modelių pateikiami su **teikėjo prefiksu**. Naudojamą prefiksą valdo `MODELS_CATALOG_PREFIX_MODE` funkcijos vėliavėlė, kurią galima perrašyti **kiekvienai užklausai atskirai** naudojant užklausos parametrą — tai naudinga klientui, norinčiam gauti tvarkingą sąrašą nekeičiant bendro serverio nustatymo visiems kitiems: ```bash GET /v1/models?prefix=alias # po vieną ID kiekvienam modeliui — trumpasis pseudonimo prefiksas GET /v1/models?prefix=dual # abi formos (numatytoji serverio reikšmė) GET /v1/models?prefix=canonical # tik visas teikėjo ID prefiksas ``` | Režimas | Pateikia | Pastabos | | ----------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dual` | `cc/claude-sonnet-4-6` **ir** `claude/claude-sonnet-4-6` | **Numatytasis.** Abu ID nukreipiami į tą patį modelį; tai išlaikyta, kad klientų konfigūracijos, kuriose tiesiogiai įrašyta kuri nors forma, ir toliau veiktų. Katalogas tampa maždaug dvigubai didesnis. | | `alias` | `cc/claude-sonnet-4-6` | Po vieną įrašą kiekvienam modeliui. Teikėjai, neturintys atskiro pseudonimo, vis tiek pateikia savo įrašą, todėl niekas neprarandama. | | `canonical` | `claude/claude-sonnet-4-6` | Po vieną įrašą kiekvienam modeliui su visu teikėjo ID prefiksu. Teikėjai, neturintys atskiro pseudonimo (pvz., `antigravity/…`, `agy/…`), čia taip pat pateikia savo vienintelį ID, todėl niekas neprarandama. | `dual` režimo dubliuojamą įrašą galima atpažinti ir be užklausos parametro: jame yra `parent` laukas, nurodantis pagrindinį ID. Klientai, rodantys modelio pasirinkimo sąrašą, turėtų pateikti užklausą su `?prefix=alias` — būtent taip daro [OmniCopilot VS Code plėtinys](../guides/VSCODE-COPILOT.md). ### Modelių variantai be mąstymo Mąstymą palaikantiems Claude modeliams `/v1/models` taip pat pateikia **nemąstantį** variantą, kurio ID prasideda prefiksu `claude-3-omniroute-no-thinking/`: ``` claude-3-omniroute-no-thinking// ``` Pasirinkus šį ID (pvz., Claude Code konfigūracijoje, kuri visada prideda `thinking` bloką), jis nukreipiamas atgal į tikrąjį `/`, išjungus samprotavimą — `/v1/messages` kelyje naudojama `thinking:{type:"disabled"}`, o `/v1/chat/completions` kelyje pašalinami `reasoning` / `reasoning_effort` laukai. Šis variantas pateikiamas tik tiems Claude šeimos modeliams, kurie palaiko mąstymą **ir** priima `disabled` (todėl, pvz., tik adaptyvųjį režimą palaikantys modeliai, atmetantys `disabled`, neįtraukiami). Operatoriai gali priverstinai įjungti arba išjungti šį variantą kiekvienam modeliui naudodami `ModelSpec.noThinkingAlias`. --- ## Teikėjo papildinio manifestas ```bash GET /api/v1/provider-plugin-manifest ``` Grąžina JSON saugų teikėjo papildinio manifestą, naudojamą Bifrost, CLIProxyAPI ir būsimų pagalbinių maršruto parinktuvų. Atsakymas generuojamas iš TypeScript teikėjų registro ir sąmoningai neapima OAuth kliento paslapčių, vykdymo aplinkos nustatymo, vykdytojo funkcijų, užklausų antraščių ir paskyrų duomenų. Naudokite šį galinį tašką, kai pagalbinis procesas vykdomas atskirai ir negali tiesiogiai importuoti `open-sse/config/providerPluginManifestRegistry.ts`. --- ## Suderinamumo galiniai taškai | Metodas | Kelias | Formatas | | ------- | ----------------------------------------- | -------------------------------------------------------- | | 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 (redagavimas / užpildymas) | | POST | `/v1/videos/generations` | OpenAI stiliaus vaizdo įrašų generavimas | | POST | `/v1/music/generations` | OpenAI stiliaus muzikos generavimas | | POST | `/v1/audio/transcriptions` | OpenAI Audio (kalbos atpažinimas) | | POST | `/v1/audio/speech` | OpenAI TTS (grąžina garso turinį) | | POST | `/v1/rerank` | Cohere/Voyage stiliaus perrikiavimas | | POST | `/v1/classify` | Jina klasifikavimas (`api.jina.ai`) | | POST | `/v1/segment` | Jina segmentuotuvas (`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}/` | OpenAI katalogo alternatyvusis kelias | | GET | `/api/v1/vscode/{token}/models` | OpenAI modelių alternatyvusis kelias | | POST | `/api/v1/vscode/{token}/chat/completions` | OpenAI alternatyvusis kelias su prieigos raktu | | POST | `/api/v1/vscode/{token}/responses` | OpenAI Responses alternatyvusis kelias su prieigos raktu | | POST | `/api/v1/vscode/{token}/api/chat` | Ollama alternatyvusis kelias su prieigos raktu | | GET | `/api/v1/vscode/{token}/api/tags` | Ollama žymų alternatyvusis kelias su prieigos raktu | Visų POST maršrutų struktūra yra vienoda: `Bearer your-api-key` + Zod patikrintas JSON turinys (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` ir kt.; žr. `src/shared/validation/schemas.ts`). Nepavykus schemos patikrai, grąžinamas 4xx. Klientams, kurie negali pridėti `Authorization: Bearer ...`, OmniRoute taip pat priima API raktus URL adrese: naudodama užklausos eilutės suderinamumo parametrus (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) arba toliau aprašytus specialiuosius `/api/v1/vscode/{token}/...` galinius taškus. ```bash # Perrikiavimas POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] } # Jina klasifikavimas (Foundation API prisijungimo duomenys) POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] } # Jina segmentuotuvas POST /v1/segment { "content": "...", "return_chunks": true } # Jina paieška (s.jina.ai; teikėjo alternatyvūs pavadinimai: jina-search, jina-ai, jina) POST /v1/search { "query": "...", "provider": "jina-search" } # Moderavimas POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." } # TTS — grąžina audio/mpeg (arba prašomo formato) turinį POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } # Vaizdo redagavimas (multipart) POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png # Vaizdo įrašų / muzikos generavimas (modelio ID su teikėjo priešdėliu) POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." } POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." } ``` ### Specialieji teikėjų maršrutai ```bash POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` Jei teikėjo priešdėlio nėra, jis pridedamas automatiškai. Neatitinkantys modeliai grąžina `400`. --- ## Failų API Su OpenAI suderinamas failų galinis taškas, skirtas paketinei įvesčiai / išvesčiai ir failų įkėlimui pagal paskirtį. | Metodas | Kelias | Aprašymas | | ------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/files` | Įkelti failą (kelių dalių forma: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — daugiausia 512 MiB | | GET | `/v1/files` | Pateikti autentifikuotam API raktui priklausančių failų sąrašą | | GET | `/v1/files/[id]` | Gauti failo metaduomenis | | DELETE | `/v1/files/[id]` | Ištrinti failą | | GET | `/v1/files/[id]/content` | Srautiniu būdu grąžinti neapdorotą failo turinį | **Autentifikavimas:** „Bearer“ API raktas — failai susiejami su konkrečiu API raktu naudojant `getApiKeyRequestScope`. Raktas gali matyti, atsisiųsti ir ištrinti tik savo failus; valdymo skydelio sesija be rakto gali skaityti visos sistemos failus; failas be savininko (anoniminis arba įkeltas per valdymo skydelio sesiją) yra nepasiekiamas kiekvienam ne sesijos skambintojui. `GET /v1/files` anoniminio skambintojo — taip pat pateikto rakto, kurio nepavyksta atpažinti, — užklausą atmeta su `401`, net kai `REQUIRE_API_KEY=false`, užuot pateikęs visų nuomininkų failų sąrašą (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523). --- ## Paketų API Su OpenAI suderinamas paketinis apdorojimas. | Metodas | Kelias | Aprašymas | | ------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/batches` | Sukurti paketą — užklausos turinys tikrinamas pagal `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) | | GET | `/v1/batches` | Pateikti paketų sąrašą | | GET | `/v1/batches/[id]` | Gauti paketo būseną ir `request_counts` | | DELETE | `/v1/batches/[id]` | Ištrinti užbaigtą arba nepavykusį paketą | | POST | `/v1/batches/[id]/cancel` | Atšaukti vykdomą paketą | **Autentifikavimas:** „Bearer“ API raktas. Paketų prieiga ribojama pagal API raktą, taikant tą pačią trijų atvejų taisyklę kaip ir failams: galima naudoti tik savo raktą, valdymo skydelio sesija turi prieigą visame egzemplioriuje, o įrašai be savininko nepasiekiami jokiam užklausos teikėjui be sesijos (gaunant, ištrinant, atšaukiant ir atliekant `input_file_id` patikrą kūrimo metu). `GET /v1/batches` atmeta anoniminį užklausos teikėją su `401`, net kai `REQUIRE_API_KEY=false`. --- ## Paieškos API Žiniatinklio / paieškos teikėjų abstrakcija („Tavily“, „Brave“, „Exa“, „Serper“ ir kt.). | Metodas | Kelias | Aprašymas | | ------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------- | | GET | `/v1/search` | Pateikti sukonfigūruotų paieškos teikėjų ir jų galimybių sąrašą | | POST | `/v1/search` | Vykdyti paieškos užklausą — turinys tikrinamas naudojant `v1SearchSchema`, palaikomas podėlis / užklausų sujungimas | | GET | `/v1/search/analytics` | Pateikti kiekvieno teikėjo rezultatų, delsos ir podėlio statistiką | **Autentifikavimas:** API raktas su „Bearer“ schema (`extractApiKey` + `isValidApiKey`). Paieškos politika taikoma naudojant `enforceApiKeyPolicy`. --- ## Web Fetch API Gaukite turinį iš URL naudodami sukonfigūruotą žiniatinklio turinio gavimo teikėją („Firecrawl“, „Jina Reader“, „Tavily Extract“, „TinyFish Fetch“, „Nimble Extract“). | Metodas | Kelias | Aprašas | | ------- | --------------- | ------------------------------------------------------------------------------------- | | POST | `/v1/web/fetch` | Gauna / išrenka turinį iš URL — užklausos turinys tikrinamas pagal `v1WebFetchSchema` | **Autentifikavimas:** „Bearer“ API raktas (`extractApiKey` + `isValidApiKey`). Politika taikoma per `enforceApiKeyPolicy`. **Kvotas įvertinantis atsarginis perjungimas (#8297):** kai aiškus `provider` nenurodytas, telkinys (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) pereinamas fiksuota prioriteto tvarka (pirmiausia užpildant aukščiausio prioriteto teikėją) — sukonfigūruotas teikėjas, kurio užklausų dažnis apribotas, praleidžiamas, užuot iš karto nutraukus užklausą, o pakartotinai bandytina / su kvota susijusi aukštesnio lygmens paslaugos klaida (HTTP 429 visada; 402/403 „Firecrawl“ / „Tavily“ / „TinyFish“ kvotos tipo nemokamuose planuose — ne „Jina Reader“ atveju ir niekada paprastos 400 netinkamos užklausos atveju) užklausos vykdymo metu perduodama kitam dar nebandytam teikėjui, kuriam yra prisijungimo duomenys. Kai visi telkinio teikėjai išnaudoti, galinis taškas grąžina vieną `429` (su `Retry-After` antrašte), o ne ankstesnį bendrąjį `400`. Kai aiškiai nurodomas `provider`, **tylus atsarginis perjungimas nevykdomas** — teikėjo, kurio užklausų dažnis apribotas arba kuris sutriko, klaida grąžinama tiesiogiai (`429`, jei užklausų dažnis apribotas, kitu atveju — aukštesnio lygmens paslaugos būsena). --- ## Srautinis perdavimas per WebSocket ```bash GET /v1/ws?handshake=1 ``` Patikrina WebSocket protokolo pakeitimo užmezgimo užklausą ir grąžina perdavimo protokolo pavyzdinius pranešimus (`request`, `cancel`). Faktinius WS kadrus apdoroja komplekte esantis WS serveris už Next.js maršrutų lentelės ribų. **Autentifikavimas:** „Bearer“ API raktas užmezgant ryšį. ### Responses API per WebSocket (tik codex) ```bash # Tas pats pagrindinis kompiuteris ir prievadas kaip HTTP API (numatytasis 20128); pakeiskite ryšio protokolą: wscat -c "ws://localhost:20128/v1/responses?api_key=" # (arba: -H "Authorization: Bearer ") # Pirmasis kadras PRIVALO būti response.create: { "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] } ``` Responses API per WebSocket tarpinis serveris susietas **tik su `codex`** (ChatGPT vidine sistema). Jis klausosi tame pačiame prievade kaip API / valdymo skydelis, keliuose `/v1/responses`, `/responses` ir `/api/v1/responses`. Gavęs pirmąjį `response.create` kadrą, jis atlieka autentifikavimą ir paruošimą per vidinį `codex-responses-ws` tiltą, pasirenka codex OAuth ryšį ir tuneliuoja į `wss://chatgpt.com/backend-api/codex/responses` naudodamas `wreq-js` transportą. **Ne codex modeliai atmetami** (`codex_ws_provider_required`). Maršruto parinkimui pagal bendrinamą kvotą naudokite `model: "qtSd//codex/"`. Įgyvendinta `app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`. **Autentifikavimas:** „Bearer“ API raktas užmezgant ryšį. Komplekte esantis HTTP serveris (`server-ws.mjs`) turi būti aktyvus įėjimo taškas (pagal numatytuosius nustatymus taip ir yra, kai egzistuoja `app/server-ws.mjs`). #### Modelio ID: naudokite nepapildytą ChatGPT ID (be `codex/` prefikso) OpenAI **Codex CLI** tikrina modelio pavadinimą kliento pusėje, kai `supports_websockets = true`, ir **atmeta teikėjo prefiksą turinčius ID**, pvz., `codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`). Siųskite **nepapildytą** ID (pvz., `gpt-5.5`). OmniRoute tiltas skirtas tik codex, todėl prieš tuneliuojant į aukštesnio lygmens paslaugą nepapildytas ID iš naujo susiejamas su codex modeliu (`resolveCodexWsModelInfo`) — nors nepapildytas `gpt-5.5` naudojant HTTP kitu atveju būtų nukreiptas kitam teikėjui. #### OpenAI Codex CLI konfigūravimas Nukreipkite Codex CLI į OmniRoute, į `~/.codex/config.toml` pridėdami pasirinktinį teikėją, palaikantį WebSocket (naudokite atskirą `CODEX_HOME`, kad nepakeistumėte esamos konfigūracijos): ```toml model = "gpt-5.5" # nepapildytas ID — NE "codex/gpt-5.5" model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute (WS)" base_url = "http://localhost:20128/v1" # be baigiamojo pasvirojo brūkšnio; WS URL išvedamas automatiškai (gamybinėje aplinkoje naudokite https/wss) wire_api = "responses" # vienintelė palaikoma reikšmė nuo 2026 m. vasario supports_websockets = true # įjungia Responses per WS transportą env_key = "OMNIROUTE_API_KEY" # saugo OmniRoute API raktą („Bearer“) ``` ```bash export OMNIROUTE_API_KEY=sk-... # OmniRoute API raktas (bet kuris raktas, jei REQUIRE_API_KEY=false) codex exec "Responda apenas: PONG" ``` CLI pakeičia `base_url + /responses` ryšį į WebSocket, o OmniRoute tuneliuoja jį į pasirinktą codex OAuth ryšį. Visas procesas patikrintas naudojant vietinį serverį: ChatGPT grąžina `codex.rate_limits` + `response.created` ir srautiniu būdu perduoda užbaigtą atsakymą. --- ## Kvotų ir problemų pranešimai | Metodas | Kelias | Aprašymas | | ------- | ------------------- | -------------------------------------------------------------------------------------------------- | | GET | `/v1/quotas/check` | Iš anksto patikrinti `provider` + `accountId` kvotą prieš išduodant registruotą raktą | | POST | `/v1/issues/report` | Pranešti GitHub apie kvotos / rakto išdavimo klaidą (reikia `GITHUB_ISSUES_REPO` + prieigos rakto) | **Autentifikavimas:** Bearer API raktas (`isAuthenticated`). --- ## Savitarnos naudojimo duomenys (`/api/usage/om-usage`) Bet kuris API raktas gali peržiūrėti **savo paties** naudojimo duomenis ir kvotas — valdymo autentifikavimas nereikalingas. Šią galinę prieigą klientas (CLI, OmniCopilot skydelis) naudoja rakto turėtojo išlaidoms rodyti. ```bash # Tekstinė forma (istorinė sutartis — paprastasis tekstas terminalui) curl -H "Authorization: Bearer " \ http://localhost:20128/api/usage/om-usage # Struktūrizuota forma — skirta naudotojo sąsajai curl -H "Authorization: Bearer " \ "http://localhost:20128/api/usage/om-usage?format=json" ``` Raktui turi būti įjungtas **`allowUsageCommand`** (pagal numatytuosius nustatymus išjungtas — prietaisų skydelio API raktų tvarkytuvėje jis perjungiamas kiekvienam raktui atskirai). Jei jis neįjungtas, galinė prieiga atsako `403`. `?format=json` grąžina atskiriamą struktūrą, todėl kvietėjas niekada neskaito duomenų lauko iš atmetimo atsakymo. Sėkmės atveju: ```jsonc { "allowed": true, // pateikiama tik tada, kai raktui įjungti individualūs naudojimo apribojimai (dienos / savaitės USD): "personal": { "dailySpentUsd": 1.25, "dailyLimitUsd": 5, "dailyResetAtIso": "…", "weeklySpentUsd": 8, "weeklyLimitUsd": 20, "weeklyResetAtIso": "…" /* … */, }, // pasirinkto teikėjo kvotos momentinė kopija arba null, kai talpykloje dar nieko nėra: "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */}, }, // kiekvieno ryšio momentinė kopija, kad naudotojo sąsajoje būtų galima greta rodyti kelis teikėjus: "providers": [ { "connectionId": "…", "provider": "claude" /* … */ }, { "provider": "codex" /* … */ }, ], } ``` Atmetimo atveju (`401` netinkamas raktas / `403` neleidžiama) tas pats maršrutas grąžina `{ "allowed": false, "error": { "message": "…" } }` — pateiktas, bet tuščias `personal` / `provider` (raktas leidžiamas, tačiau dar nėra gauta duomenų) yra kitokia būsena nei atmetimas, ir jas atskiria tik JSON forma. **Autentifikavimas:** paties kvietėjo Bearer API raktas, patikrintas naudojant `isValidApiKey` — tai _nėra_ valdymo sąsaja (`/api/keys/…`), kuri tebėra apsaugota naudojant `requireManagementAuth`. --- ## Semantinė talpykla ```bash # Gauti talpyklos statistiką GET /api/cache/stats # Išvalyti visas talpyklas DELETE /api/cache/stats ``` Atsakymo pavyzdys: ```json { "semanticCache": { "memorySize": 42, "memoryMaxSize": 500, "dbSize": 128, "hitRate": 0.65 }, "idempotency": { "activeKeys": 3, "windowMs": 5000 } } ``` ### Poveikis delsai Semantinės talpyklos PATAIKYMO atveju atsakymas pateikiamas iš talpyklos **be iškvietimo į pirminę paslaugą**, todėl nurodyta `X-OmniRoute-Response-Latency` reikšmė yra artima nuliui (nepriklausomai nuo pradinės pirminės paslaugos delsos). Delsai jautrūs klientai (našumo testavimas, p50 / p99 stebėjimas) turėtų tikrinti `X-OmniRoute-Cache-Latency` atsakymo antraštę: | Reikšmė | Reikšmė | | ----------- | ------------------------------------------------------------------------------- | | `synthetic` | Atsakymas pateiktas iš talpyklos; delsa nėra tikrasis pirminės paslaugos laikas | | _(nėra)_ | Atsakymas gautas iš tikro iškvietimo į pirminę paslaugą | ### Talpyklos apėjimas pagal raktą API raktams galima išjungti skaitymą iš semantinės talpyklos naudojant `cacheDefaultMode`: | Reikšmė | Veikimas | | -------- | ------------------------------------------------------------------------- | | `legacy` | Įprastas talpyklos veikimas (numatytasis) | | `bypass` | Visiškai praleisti paiešką talpykloje; visada kreiptis į pirminę paslaugą | Nustatoma kuriant raktą (`POST /api/keys`) arba atnaujinant (`PATCH /api/keys/[id]`): ```json { "cacheDefaultMode": "bypass" } ``` ### Apėjimas pagal užklausą Bet kuri užklausa gali apeiti talpyklą neatsižvelgiant į rakto nustatymus: ``` X-OmniRoute-No-Cache: true ``` --- ## Valdymo skydelis ir administravimas Administravimo maršrutai (`/api/*`, išskyrus viešą autentifikavimą / prisijungimą) **nėra** autorizuojami įprastais išvadų API raktais. Kredencialų grupės, aprėptys ir curl pavyzdžiai: [Administravimo autentifikavimas](../guides/MANAGEMENT-AUTH.md). ### Autentifikavimas | Galinis taškas | Metodas | Aprašymas | | ----------------------------- | ------- | ---------------------------------------------- | | `/api/auth/login` | POST | Prisijungti | | `/api/auth/logout` | POST | Atsijungti | | `/api/settings/require-login` | GET/PUT | Įjungti arba išjungti prisijungimo reikalavimą | ### Teikėjų valdymas | Galinis taškas | Metodas | Aprašymas | | ---------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `/api/providers` | GET/POST | Išvardyti / sukurti teikėjus | | `/api/providers/[id]` | GET/PUT/DELETE | Valdyti teikėją | | `/api/providers/[id]/test` | POST | Patikrinti ryšį su teikėju | | `/api/providers/[id]/models` | GET | Išvardyti teikėjo modelius | | `/api/providers/validate` | POST | Patikrinti teikėjo konfigūraciją | | `/api/providers/bulk` | POST | Masiškai pridėti VIENO teikėjo API raktus | | `/api/providers/import` | POST | Importuoti nevienalytį teikėjų SĄRAŠĄ iš išanalizuoto CSV/JSON failo (#6836); pateikiami kiekvienos eilutės dalinio nepavykimo rezultatai | | `/api/provider-nodes*` | Įvairūs | Teikėjo mazgų valdymas | | `/api/provider-models` | GET/POST/PATCH/DELETE | Pasirinktiniai modeliai (pridėti, atnaujinti, paslėpti / rodyti, pašalinti) | ### OAuth srautai | Galinis taškas | Metodas | Aprašymas | | -------------------------------- | ------- | ----------------------- | | `/api/oauth/[provider]/[action]` | Įvairūs | Teikėjui būdingas OAuth | ### Maršrutų parinkimas ir konfigūracija | Galinis taškas | Metodas | Aprašymas | | --------------------- | -------- | ----------------------------------- | | `/api/models/alias` | GET/POST | Modelių alternatyvieji pavadinimai | | `/api/models/catalog` | GET | Visi modeliai pagal teikėją ir tipą | | `/api/combos*` | Įvairūs | Derinių valdymas | | `/api/keys*` | Įvairūs | API raktų valdymas | | `/api/pricing` | GET | Modelių kainodara | ### Naudojimas ir analizė | Galinis taškas | Metodas | Aprašymas | | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/usage/history` | GET | Naudojimo istorija | | `/api/usage/logs` | GET | Naudojimo žurnalai | | `/api/usage/request-logs` | GET | Užklausų lygmens žurnalai | | `/api/usage/[connectionId]` | GET | Kiekvieno ryšio naudojimas | | `/api/usage/token-limits` | GET/POST/DELETE | Kiekvieno API rakto žetonų limitų biudžetai | | `/api/usage/model-latency-stats` | GET | Slenkamasis kiekvieno teikėjo / modelio delsos suvestinis rodiklis (avg/p50/p95/p99, sėkmės rodiklis); filtrai: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) | | `/api/usage/cache-health` | GET | Užklausų podėlio būklės suvestinė pagal `call_logs` — rašymo / skaitymo santykis, p50/p90/p99 rašymo dydžio pasiskirstymas, intensyvaus rašymo koncentracija, išskaidymas pagal modelį ir `healthy`/`degraded`/`thrash`/`no-data` įvertis; užklausos parametrai `range` (`1h`\|`24h`\|`7d`\|`30d`, numatytoji reikšmė `24h`) ir pasirinktinis `model` (#8827) | ### Nuostatos | Galinis taškas | Metodas | Aprašymas | | ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/api/settings` | GET/PUT/PATCH | Bendrosios nuostatos | | `/api/settings/proxy` | GET/PUT | Tinklo įgaliotojo serverio konfigūracija | | `/api/settings/proxy/test` | POST | Patikrinti ryšį su įgaliotuoju serveriu | | `/api/settings/ip-filter` | GET/PUT | Leidžiamų / blokuojamų IP adresų sąrašas | | `/api/settings/thinking-budget` | GET/PUT | Mąstymo / samprotavimo **užklausos** perrašymo režimas (perduoti nepakeistą / automatiškai pašalinti / pasirinktinis / adaptyvusis). Nepriklauso nuo glaudinimo. Žr. [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). | | `/api/settings/system-prompt` | GET/PUT | Visuotinė sistemos užklausa | | `/api/settings/compression` | GET/PUT | Visuotinė glaudinimo konfigūracija | | `/api/settings/purge-request-history` | POST | Išvalyti užklausų žurnalo eilutes ir vietinius iškvietimų žurnalo artefaktus | ### Kontekstas ir glaudinimas | Galinis taškas | Metodas | Aprašymas | | -------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------- | | `/api/compression/preview` | POST | Peržiūrėti išjungto / lengvo / standartinio / agresyvaus / ultra / RTK / sudėtinio glaudinimo rezultatą | | `/api/compression/language-packs` | GET | Išvardyti pasiekiamus Caveman kalbų paketus | | `/api/compression/rules` | GET | Išvardyti Caveman taisyklių metaduomenis | | `/api/context/caveman/config` | GET/PUT | Caveman būdingų nuostatų alternatyvusis pavadinimas | | `/api/context/rtk/config` | GET/PUT | RTK būdingos nuostatos, įskaitant pasirinktinius filtrus ir neapdorotos išvesties išsaugojimą | | `/api/context/rtk/filters` | GET | RTK filtrų katalogas ir pasirinktinių filtrų diagnostika | | `/api/context/rtk/test` | POST | Paleisti RTK peržiūrą / testą naudojant tekstinę naudingąją apkrovą | | `/api/context/rtk/raw-output/[id]` | GET | Perskaityti išsaugotą nuasmenintą neapdorotą išvestį pagal rodyklės id | | `/api/context/combos` | GET/POST | Glaudinimo derinių sąrašas / kūrimas | | `/api/context/combos/[id]` | GET/PUT/DELETE | Glaudinimo derinio informacija / atnaujinimas / pašalinimas | | `/api/context/combos/[id]/assignments` | GET/PUT | Priskirti glaudinimo derinius maršrutų parinkimo deriniams | | `/api/context/analytics` | GET | Alternatyvusis glaudinimo analizės pavadinimas | ### Stebėsena | Galinis taškas | Metodas | Aprašymas | | ------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/sessions` | GET | Aktyvių seansų stebėjimas | | `/api/rate-limits` | GET | Kiekvienos paskyros spartos apribojimai | | `/api/monitoring/health` | GET | Būklės patikra ir teikėjų suvestinė (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | | `/api/cache/stats` | GET/DELETE | Podėlio statistika / išvalymas | | `/api/modality-bridge/stats` | GET | Atmintyje laikomi `attempts`, sėkmingi bandymai / `bridged`, nesėkmės, podėlio pataikymai, `totalLatencyMs`, `latencySamples`, pagal imčių skaičių apskaičiuotas `averageLatencyMs` ir paskutinio naudojimo laikas (nustatoma iš naujo paleidus; administravimo autentifikavimas) | | `/api/modality-bridge/video/runtime` | GET | Griežta patikimo grįžtamojo ryšio sąsajos patikra prieš administravimo autentifikavimą / zondavimą; išvalyta FFmpeg/ffprobe pasiekiamumo ir versijų informacija (no-store) | | `/api/modality-bridge/video/extract` | POST | Vidinis autentifikuotas patikimos grįžtamojo ryšio sąsajos baitų tarpininkas; 50 MiB įvestis, ribota eilė / 32 MiB išvestis, `503` pajėgumas, `499` atsijungimas, `504` terminas; tai nėra vieša įkėlimo API | ### Atsarginės kopijos ir eksportavimas / importavimas | Galinis taškas | Metodas | Aprašymas | | --------------------------- | ------- | ----------------------------------------------------- | | `/api/db-backups` | GET | Išvardyti pasiekiamas atsargines kopijas | | `/api/db-backups` | PUT | Sukurti rankinę atsarginę kopiją | | `/api/db-backups` | POST | Atkurti iš konkrečios atsarginės kopijos | | `/api/db-backups/export` | GET | Atsisiųsti duomenų bazę kaip .sqlite failą | | `/api/db-backups/import` | POST | Įkelti .sqlite failą duomenų bazei pakeisti | | `/api/db-backups/exportAll` | GET | Atsisiųsti visą atsarginę kopiją kaip .tar.gz archyvą | ### Sinchronizavimas su debesija | Galinis taškas | Metodas | Aprašymas | | ---------------------- | ------- | -------------------------------------- | | `/api/sync/cloud` | Įvairūs | Sinchronizavimo su debesija operacijos | | `/api/sync/initialize` | POST | Inicijuoti sinchronizavimą | | `/api/cloud/*` | Įvairūs | Debesijos valdymas | ### Tuneliai | Galinis taškas | Metodas | Aprašymas | | -------------------------- | ------- | ----------------------------------------------------------------------------- | | `/api/tunnels/cloudflared` | GET | Nuskaityti Cloudflare Quick Tunnel diegimo / vykdymo būseną valdymo skydeliui | | `/api/tunnels/cloudflared` | POST | Įjungti arba išjungti Cloudflare Quick Tunnel (`action=enable/disable`) | | `/api/tunnels/ngrok` | GET | Nuskaityti ngrok Tunnel vykdymo būseną valdymo skydeliui | | `/api/tunnels/ngrok` | POST | Įjungti arba išjungti ngrok Tunnel (`action=enable/disable`) | ### CLI įrankiai | Galinis taškas | Metodas | Aprašymas | | ---------------------------------- | ------- | ---------------------------- | | `/api/cli-tools/claude-settings` | GET | Claude CLI būsena | | `/api/cli-tools/codex-settings` | GET | Codex CLI būsena | | `/api/cli-tools/droid-settings` | GET | Droid CLI būsena | | `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI būsena | | `/api/cli-tools/runtime/[toolId]` | GET | Bendroji CLI vykdymo aplinka | CLI atsakymai apima: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. ### ACP agentai | Galinis taškas | Metodas | Aprašymas | | ----------------- | ------- | -------------------------------------------------------------------------- | | `/api/acp/agents` | GET | Išvardyti visus aptiktus agentus (integruotus ir pasirinktinius) su būsena | | `/api/acp/agents` | POST | Pridėti pasirinktinį agentą arba atnaujinti aptikimo podėlį | | `/api/acp/agents` | DELETE | Pašalinti pasirinktinį agentą pagal `id` užklausos parametrą | GET atsakymas apima `agents[]` (id, name, binary, version, installed, protocol, isCustom) ir `summary` (total, installed, notFound, builtIn, custom). ### Atsparumas ir spartos apribojimai | Galinis taškas | Metodas | Aprašymas | | --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------- | | `/api/resilience` | GET/PATCH | Gauti / atnaujinti užklausų eilės, ryšio atvėsimo, teikėjo grandinės pertraukiklio ir laukimo nuostatas | | `/api/resilience/reset` | POST | Iš naujo nustatyti teikėjo grandinės pertraukiklius | | `/api/resilience/model-cooldowns` | GET | Išvardyti aktyvius kiekvieno (teikėjo, ryšio, modelio) blokavimus, surikiuotus pagal likusį laiką | | `/api/resilience/model-cooldowns` | DELETE | Išvalyti modelio blokavimą — turinys `{provider, model}` arba `{all: true}`, kad būtų išvalyta viskas | | `/api/rate-limits` | GET | Kiekvienos paskyros spartos apribojimo būsena | | `/api/rate-limit` | GET | Visuotinė spartos apribojimo konfigūracija | > Visiems keturiems `/api/resilience/*` maršrutams būtinas **administravimo autentifikavimas** (`requireManagementAuth`). Išsamų teikėjo grandinės pertraukiklio, ryšio atvėsimo ir modelio blokavimo skirtumų aprašymą žr. [Atsparumas (išplėstinis)](#resilience-extended). ### Vertinimai | Galinis taškas | Metodas | Aprašymas | | -------------- | -------- | ------------------------------------------------- | | `/api/evals` | GET/POST | Išvardyti vertinimo rinkinius / vykdyti vertinimą | ### Politika | Galinis taškas | Metodas | Aprašymas | | --------------- | --------------- | ----------------------------------- | | `/api/policies` | GET/POST/DELETE | Valdyti maršrutų parinkimo politiką | ### Atitiktis | Galinis taškas | Metodas | Aprašymas | | --------------------------- | ------- | ------------------------------------------ | | `/api/compliance/audit-log` | GET | Atitikties audito žurnalas (paskutiniai N) | ### v1beta (suderinama su Gemini) | Galinis taškas | Metodas | Aprašymas | | -------------------------- | ------- | --------------------------------------- | | `/v1beta/models` | GET | Išvardyti modelius Gemini formatu | | `/v1beta/models/{...path}` | POST | Gemini `generateContent` galinis taškas | Šie galiniai taškai atkartoja Gemini API formatą klientams, kuriems būtinas vietinis suderinamumas su Gemini SDK. ### Vidinės / sistemos API | Galinis taškas | Metodas | Aprašymas | | ------------------------ | ------- | ----------------------------------------------------------------- | | `/api/init` | GET | Programos inicijavimo patikra (naudojama pirmą kartą paleidžiant) | | `/api/tags` | GET | Su Ollama suderinamos modelių žymos (Ollama klientams) | | `/api/restart` | POST | Inicijuoti sklandų serverio paleidimą iš naujo | | `/api/shutdown` | POST | Inicijuoti sklandų serverio išjungimą | | `/api/system/env/repair` | POST | Taisyti OAuth teikėjo aplinkos kintamuosius | > **Pastaba:** šiuos galinius taškus sistema naudoja viduje arba suderinamumui su Ollama klientais užtikrinti. Galutiniai naudotojai paprastai jų nekviečia. ### OAuth aplinkos taisymas _(v3.6.1+)_ ```bash POST /api/system/env/repair Content-Type: application/json { "provider": "claude-code" } ``` Pataiso trūkstamus arba sugadintus konkretaus teikėjo OAuth aplinkos kintamuosius. Grąžina: ```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" } ``` --- ## Garso transkripcija ```bash POST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` Transkribuokite garso failus naudodami bet kurį sukonfigūruotą STT teikėją. Pirmasis kelio segmentas parenka savąjį teikėją (`openai/…`, `deepgram/…`). Tinklų sąsajos, kurios pakartotinai eksportuoja kito tiekėjo modelį, naudoja kvalifikuotą ID (`openrouter/deepgram/nova-3`). **Užklausa:** ```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" ``` **Atsakymas:** ```json { "text": "Hello, this is the transcribed audio content.", "task": "transcribe", "language": "en", "duration": 12.5 } ``` **Modelių ID pavyzdžiai:** `openai/whisper-1` (reikalingas OpenAI raktas), `openrouter/deepgram/nova-3` (reikalingas OpenRouter raktas), `deepgram/nova-3` (reikalingas savasis Deepgram raktas). Neapibrėžta `deepgram/nova-3` užklausa **nenaudoja** OpenRouter. **Palaikomi formatai:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- ## Suderinamumas su Ollama Klientams, naudojantiems Ollama API formatą: ```bash # Pokalbių galinis taškas (Ollama formatas) POST /v1/api/chat # Modelių sąrašas (Ollama formatas) GET /api/tags ``` Užklausos automatiškai konvertuojamos tarp Ollama ir vidinių formatų. ## Žetoniniai VS Code / antraštės nereikalaujantys alternatyvūs adresai Naudokite šiuos alternatyvius adresus, kai integracija negali įterpti `Authorization` antraštės ir API raktą reikia įtraukti į bazinį URL. ```bash # OpenAI stiliaus katalogo alternatyvus adresas GET /api/v1/vscode/{token}/ GET /api/v1/vscode/{token}/models # OpenAI stiliaus pokalbių alternatyvūs adresai POST /api/v1/vscode/{token}/chat/completions POST /api/v1/vscode/{token}/responses # Ollama stiliaus alternatyvūs adresai POST /api/v1/vscode/{token}/api/chat GET /api/v1/vscode/{token}/api/tags ``` Pavyzdys: ```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"}]}' ``` Pastabos: - Žetoniniai alternatyvūs adresai pakartotinai naudoja tas pačias apdorojimo funkcijas kaip `/v1/*` ir `/api/tags`; atsakymų struktūra išlieka tokia pati. - Kai klientas palaiko pasirinktines antraštes, pirmenybę teikite `Authorization: Bearer ...`. - URL esantys žetonai gali būti matomi atvirkštinio tarpinio serverio žurnaluose, naršyklės istorijoje ir telemetrijoje už OmniRoute ribų. Laikykite juos suderinamumo parinktimi, o ne numatytuoju autentifikavimo režimu. --- ## Telemetrija ```bash # Gauti delsos telemetrijos suvestinę (kiekvieno teikėjo p50/p95/p99) GET /api/telemetry/summary ``` **Atsakymas:** ```json { "providers": { "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } } } ``` --- ## Biudžetas ```bash # Gauti visų API raktų biudžeto būseną GET /api/usage/budget # Nustatyti arba atnaujinti biudžetą POST /api/usage/budget Content-Type: application/json { "apiKeyId": "key-123", "dailyLimitUsd": 5.00, "weeklyLimitUsd": 30.00, "monthlyLimitUsd": 100.00, "warningThreshold": 0.8, "resetInterval": "monthly" } ``` > **Schemos pastabos** (`setBudgetSchema`): `apiKeyId` yra privalomas; bent viena iš `dailyLimitUsd`, `weeklyLimitUsd` arba `monthlyLimitUsd` reikšmių turi būti didesnė už nulį. Neprivalomi laukai: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Naudojant pasenusią struktūrą `{keyId, limit, period}`, grąžinamas atsakymas `400 Bad Request`. ## Žetonų limitai Kiekvienam API raktui taikomi **žetonų** biudžetai (atskiri nuo pirmiau aprašyto USD pagrįsto biudžeto). Jie tikrinami tiesiogiai užklausos apdorojimo kelyje: kai rakto naudojimas dabartiniame laikotarpyje pasiekia nustatytą limitą, užklausos atmetamos pateikiant `429 Too Many Requests`. Limitai gali būti taikomi konkrečiam `model`, `provider` arba visam raktui `global` mastu; kai užklausą atitinka keli limitai, taikomas griežčiausias. ```bash # Pateikti rakto žetonų limitų sąrašą (įskaitant dabartinio laikotarpio naudojimą) GET /api/usage/token-limits?apiKeyId=key-123 # Sukurti arba atnaujinti žetonų limitą POST /api/usage/token-limits Content-Type: application/json { "apiKeyId": "key-123", "scopeType": "model", "scopeValue": "openai/gpt-4o", "tokenLimit": 1000000, "resetInterval": "monthly", "enabled": true } # Ištrinti žetonų limitą pagal id DELETE /api/usage/token-limits?id=tl-abc ``` > **Schemos pastabos** (`setTokenLimitSchema`): `apiKeyId` ir `scopeType` (`model` | `provider` | `global`) yra privalomi. `scopeValue` yra privalomas, nebent `scopeType` yra `global` (pvz., modelio id, kai taikymo sritis yra `model`, arba teikėjo id, kai taikymo sritis yra `provider`). `tokenLimit` turi būti teigiamas sveikasis skaičius (konvertuojamas iš eilutės). Neprivalomi laukai: `id` (praleiskite kurdami, pateikite atnaujindami), `resetInterval` (`daily` | `weekly` | `monthly`, numatytoji reikšmė `monthly`), `resetTime` (`HH:MM`), `enabled` (numatytoji reikšmė `true`). `GET` atsakymai kiekvieną limitą papildo laukais `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` ir `nextResetAt`. Tai yra valdymo klasės galinis taškas (autentifikavimą centralizuotai užtikrina autorizavimo procesas). ## Užklausų apdorojimas 1. Klientas siunčia užklausą į `/v1/*` 2. Maršruto apdorojimo priemonė iškviečia `handleChat`, `handleEmbedding`, `handleAudioTranscription` arba `handleImageGeneration` 3. Nustatomas modelis (tiesioginis teikėjas / modelis arba pseudonimas / derinys) 4. Prisijungimo duomenys parenkami iš vietinės DB, atsižvelgiant į paskyros pasiekiamumo filtravimą 5. Pokalbiams: `handleChatCore` patikrina semantinę / parašo podėlį ir nustato derinio glaudinimo nuostatas 6. Kai įjungta, prieš konvertuojant į teikėjo formatą atliekamas išankstinis glaudinimas (`lite`, Caveman, RTK arba kelių metodų derinys) 7. Teikėjo vykdyklė išsiunčia užklausą aukštesnio lygio paslaugai 8. Atsakymas konvertuojamas atgal į kliento formatą (pokalbiams) arba grąžinamas nepakeistas (įterpiniams / vaizdams / garsui) 9. Įrašomi naudojimo duomenys, glaudinimo analizės duomenys ir užklausų žurnalai 10. Įvykus klaidoms, pagal derinio taisykles taikomas atsarginis variantas Išsamus architektūros aprašas: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md) --- ## Derinių valdymas Aukštesnio lygio maršruto parinkimo deriniai (jau apibendrinti skiltyje `/api/combos*`) taip pat gali būti susieti santykiu 1:1 pagal modelio id šabloną, todėl OpenAI stiliaus modelio id galima skaidriai nukreipti į derinį. | Metodas | Kelias | Aprašymas | | ------- | -------------------------------- | ------------------------------------------------------------------------------------ | | GET | `/api/model-combo-mappings` | Pateikti visų modelio→derinio susiejimų sąrašą | | POST | `/api/model-combo-mappings` | Sukurti susiejimą — turinys: `{pattern, comboId, priority?, enabled?, description?}` | | GET | `/api/model-combo-mappings/[id]` | Gauti vieną susiejimą | | PUT | `/api/model-combo-mappings/[id]` | Atnaujinti esamo susiejimo laukus | | DELETE | `/api/model-combo-mappings/[id]` | Pašalinti susiejimą | **Autentifikavimas:** valdymo seansas / API raktas (`requireManagementAuth`). --- ## Webhook’ai Siunčiamų „OmniRoute“ įvykių (užklausos užbaigimo, kvotos išnaudojimo, rakto pasukimo ir kt.) webhook prenumeratos. | Metodas | Kelias | Aprašymas | | ------- | ------------------------- | --------------------------------------------------------------------------------- | | GET | `/api/webhooks` | Pateikti webhook’ų sąrašą (paslaptys užmaskuojamos kaip `...`) | | POST | `/api/webhooks` | Sukurti webhook’ą — turinys: `{url, events?: ["*"], secret?, description?}` | | GET | `/api/webhooks/[id]` | Gauti webhook’ą | | PUT | `/api/webhooks/[id]` | Atnaujinti url/events/secret/description | | DELETE | `/api/webhooks/[id]` | Pašalinti webhook’ą | | POST | `/api/webhooks/[id]/test` | Nusiųsti bandomąją naudingąją apkrovą webhook’o URL ir grąžinti pristatymo būseną | **Autentifikavimas:** valdymo sesija / API raktas (`requireManagementAuth`). --- ## Užregistruoti raktai (automatinis valdymas) Naudojama automatinio raktų valdymo posistemėje, kad būtų išduodami ir pasukami API raktai, susieti su pagrindiniu teikėju / paskyra ir turintys dienos bei valandos kvotas. | Metodas | Kelias | Aprašymas | | ------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/v1/registered-keys` | Pateikti užregistruotų raktų sąrašą (rodomas tik užmaskuotas prefiksas) | | POST | `/api/v1/registered-keys` | Išduoti naują užregistruotą raktą — turinys: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Neužmaskuotas raktas grąžinamas **vieną kartą**. Atmetus dėl kvotos, grąžinamas `429`. | | GET | `/api/v1/registered-keys/[id]` | Gauti užregistruoto rakto metaduomenis (be neužmaskuoto rakto duomenų) | | DELETE | `/api/v1/registered-keys/[id]` | Atšaukti užregistruotą raktą | | POST | `/api/v1/registered-keys/[id]/revoke` | Aiškiai nurodyta atšaukimo galinė prieiga (poveikis toks pats kaip DELETE) | **Autentifikavimas:** „Bearer“ API raktas (`isAuthenticated`). Taip pat žr. `/v1/quotas/check` ir `/v1/issues/report`. --- ## Agentų protokolas Debesijos agentų užduotys („Claude Code“, „Codex Cloud“, „OpenHands“ ir kt.), nuotoliniu būdu vykdomos „OmniRoute“ naudotojų vardu. | Metodas | Kelias | Aprašymas | | ------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/agents/tasks` | Užduočių sąrašas — pasirenkami `?provider=`, `?status=`, `?limit=` (1–500, numatytoji reikšmė – 50) | | POST | `/api/v1/agents/tasks` | Sukurti užduotį — turinį patikrina `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Grąžina `201` su užduoties apvalkalu | | DELETE | `/api/v1/agents/tasks?id=...` | Ištrinti užduotį | | GET | `/api/v1/agents/tasks/[id]` | Gauti užduotį — sinchroniškai atnaujina būseną iš pirminio debesijos agento, kai nustatytas `external_id` | | POST | `/api/v1/agents/tasks/[id]` | Atskiriamasis veiksmas: `{action: "approve"}`, `{action: "message", message}` arba `{action: "cancel"}` | | DELETE | `/api/v1/agents/tasks/[id]` | Ištrinti konkrečią užduotį pagal id | > **Autentifikavimas:** kiekvienam metodui būtinas valdymo autentifikavimas (`requireCloudAgentManagementAuth`). Iki v3.8.0 autentifikavimas nebuvo taikomas — apie nesuderinamą pakeitimą žr. įraše `588a0333`. ```bash # Sukurti „Claude Code“ debesijos užduotį 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":"..."}}' ``` --- ## Valdymo tarpiniai serveriai Išeinantiems HTTP(S)/SOCKS ryšiams skirti tarpiniai serveriai, kuriuos galima priskirti teikėjams, paskyroms arba visuotinai. | Metodas | Kelias | Aprašymas | | ------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/management/proxies` | Tarpinių serverių sąrašas (su `?id=` grąžina vieną; su `?id=&where_used=1` grąžina priskyrimų grafą) | | POST | `/api/v1/management/proxies` | Sukurti tarpinį serverį — turinį patikrina `createProxyRegistrySchema` | | PATCH | `/api/v1/management/proxies` | Atnaujinti tarpinį serverį — turinį patikrina `updateProxyRegistrySchema` (būtinas `id`) | | DELETE | `/api/v1/management/proxies?id=...&force=1` | Ištrinti tarpinį serverį (naudokite `force=1`, kad pašalintumėte priskyrimus) | | GET | `/api/v1/management/proxies/assignments` | Priskyrimų sąrašas — galima filtruoti pagal `proxy_id`, `scope`, `scope_id`; perduokite `resolve_connection_id=`, kad nustatytumėte aktyvų ryšio tarpinį serverį | | PUT | `/api/v1/management/proxies/assignments` | Priskirti — turinį patikrina `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Išvalo dispečerio podėlį | | PUT | `/api/v1/management/proxies/bulk-assign` | Masinis priskyrimas — turinį patikrina `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) | | GET | `/api/v1/management/proxies/health?hours=24` | Suvestinė tarpinio serverio būklė per nurodytą laikotarpį (sėkmingų / nesėkmingų užklausų skaičius, delsa) | **Autentifikavimas:** kiekvienam maršrutui būtina valdymo sesija / API raktas (`requireManagementAuth`). > Užduoties apraše nurodytus `POST /api/v1/management/proxies/[id]/assignments` ir `POST /api/v1/management/proxies/[id]/health` aptarnauja pirmiau parodyti plokščios struktūros maršrutai `/assignments` ir `/health` — kodų bazėje nėra atskirų kiekvienam id skirtų antrinių maršrutų. --- ## Atsparumas (išplėstinis) „OmniRoute“ suteikia tris nepriklausomus laikinųjų trikčių valdymo mechanizmus; toliau nurodyti valdymo galiniai taškai leidžia operatoriams peržiūrėti ir pakeisti jų būseną: | Apimtis | Būsenos saugojimo vieta | Peržiūra | Nustatymas iš naujo / išvalymas | | ------------------------------- | ------------------------------------------------ | ----------------------------------------- | --------------------------------------------------- | | Teikėjo grandinės pertraukiklis | `domain_circuit_breakers` + atmintyje | `/api/monitoring/health` | `POST /api/resilience/reset` | | Ryšio laukimo laikotarpis | `rateLimitedUntil` teikėjo ryšiuose | `/api/rate-limits`, `/api/providers/[id]` | (vėl įjungiama atidėtai; išvaloma teikėjo PUT būdu) | | Modelio blokavimas | Atmintyje esantis modelių pasiekiamumo registras | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` | `PATCH /api/resilience` priima teikėjo grandinės pertraukiklio perrašymus laukuose `providerBreaker.oauth` ir `providerBreaker.apikey`. Kiekviename profilyje galima naudoti `degradationThreshold`, `failureThreshold` ir `resetTimeoutMs`; tie patys laukai pateikiami skiltyje Valdymo skydas → Nustatymai → Atsparumas. ```bash # Išvalyti vieno modelio blokavimą 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"}' # Išvalyti visus blokavimus curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ -H "Cookie: auth_token=..." \ -d '{"all":true}' ``` Išsamią koncepcinę informaciją ir numatytąsias grandinės pertraukiklio reikšmes žr. [`CLAUDE.md`](../../CLAUDE.md) → „Atsparumo vykdymo aplinkos būsena“. --- ## Įgūdžiai Sistema, skirta „OmniRoute“ plėsti pasirinktinėmis vykdomosiomis apdorojimo programomis, taip pat integracijomis su prekyvietėmis. | Metodas | Kelias | Aprašymas | | ------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Pateikia įdiegtų įgūdžių sąrašą — galima filtruoti pagal `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, palaikomas puslapiavimas | | GET | `/api/skills/[id]` | Gauna vieną įgūdį | | PUT | `/api/skills/[id]` | Atnaujina įgūdį (pavadinimą, aprašymą, režimą, schemą, apdorojimo programą, žymas) | | DELETE | `/api/skills/[id]` | Pašalina įgūdį | | POST | `/api/skills/install` | Įdiegia įgūdį iš neapdoroto manifesto — užklausos turinys: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` | | GET | `/api/skills/executions` | Pateikia naujausių įgūdžių vykdymų sąrašą (audito seka su įvestimis, išvestimis ir trukme) | | GET | `/api/skills/marketplace?q=...` | Paieškos / populiarių įgūdžių sąrašas iš „SkillsMP“ prekyvietės (reikalinga `skillsmpApiKey` nuostata) | | POST | `/api/skills/marketplace/install` | Įdiegia įgūdį pagal jo id iš „SkillsMP“ | | GET | `/api/skills/skillssh?q=&limit=` | Atlieka paiešką „skills.sh“ registre | | POST | `/api/skills/skillssh/install` | Įdiegia įgūdį pagal jo id iš „skills.sh“ | **Autentifikavimas:** valdymo seansas / API raktas. Prekyvietės paieškos maršrutai priima valdymo autentifikavimo duomenis arba „Bearer“ API raktą (`isAuthenticated`). --- ## Atmintis Nuolatinė pokalbių / faktinės atminties saugykla, kurios apimtis nustatoma pagal API raktą / seansą. | Metodas | Kelias | Aprašymas | | ------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/memory` | Atminčių sąrašas — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, su puslapių skaidymu naudojant `offset/limit` arba `page/limit` | | POST | `/api/memory` | Sukurti atmintį — užklausos turinį tikrina Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` | | GET | `/api/memory/[id]` | Gauti vieną atmintį | | DELETE | `/api/memory/[id]` | Ištrinti atmintį | | GET | `/api/memory/health` | Atminties posistemės būklė (DB ryšys, vektorinių įterpinių posistemė, vektorinio indekso būsena) | **Autentifikavimas:** valdymo seansas / API raktas (`requireManagementAuth`). `type` išvardijimas: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (žr. `MemoryType`, esantį `src/lib/memory/types.ts`). --- ## MCP serveris OmniRoute pateikiamas su integruotu Model Context Protocol serveriu, turinčiu 3 transportus (stdio, SSE, streamable-http) ir pagal apimtis apribotus įrankius. Toliau nurodyti valdymo skydelio galiniai taškai nuskaito būsenos / audito duomenis ir veikia kaip HTTP transportų tarpinis serveris. | Metodas | Kelias | Aprašymas | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | `/api/mcp/status` | Periodinis signalas, transportas, prisijungimo būsena, paskutinis iškvietimas, populiariausi įrankiai, sėkmės rodiklis per 24 val. | | GET | `/api/mcp/tools` | MCP įrankių sąrašas su `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` | | GET | `/api/mcp/sse` | Atverti SSE srautą SSE transportui (grąžina `503`, jei MCP išjungtas arba transportas neatitinka) | | POST | `/api/mcp/sse` | Siųsti JSON-RPC kadrą SSE transportu | | GET | `/api/mcp/stream` | Atverti Streamable HTTP transporto SSE pusę (serverio inicijuojami pranešimai) | | POST | `/api/mcp/stream` | Siųsti JSON-RPC kadrą Streamable HTTP transportu | | DELETE | `/api/mcp/stream` | Užbaigti Streamable HTTP seansą | | GET | `/api/mcp/audit` | Pateikti audito žurnalo užklausą — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` | | GET | `/api/mcp/audit/stats` | Suvestinė audito statistika (bendri skaičiai, sėkmės rodiklis, vidutinė trukmė, populiariausi įrankiai) | **Autentifikavimas:** `sse` / `stream` transportai naudoja MCP skirtą autentifikavimo sąsają („Bearer“ API raktą su `mcp` apimtimi); `status` / `tools` / `audit*` maršrutai pasiekiami iš valdymo skydelio (pasiekus valdymo skydelio pagrindinį kompiuterį, papildomas autentifikavimas nereikalingas). > Abu HTTP transportai valdomi naudojant `settings.mcpEnabled` ir `settings.mcpTransport` — jei transportas neatitinka, grąžinamas `400`, o jei MCP išjungtas — `503`. --- ## A2A serveris OmniRoute pateikia A2A (agentų tarpusavio sąveikos) JSON-RPC 2.0 galinį tašką ir REST sąsają, skirtą tikrinimui bei valdymo skydui. ### JSON-RPC ```bash POST /a2a Authorization: Bearer your-api-key # neprivaloma, nebent nustatytas 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"}] } } ``` Palaikomi metodai (visi priklauso nuo `settings.a2aEnabled`): | Metodas | Aprašymas | | ---------------- | --------------------------------------------------------------------- | | `message/send` | Sinchroninis gebėjimo vykdymas; grąžina `{task, artifacts, metadata}` | | `message/stream` | To paties gebėjimų rinkinio srautinis SSE vykdymas | | `tasks/get` | Gauti užduotį pagal `taskId` | | `tasks/cancel` | Atšaukti užduotį pagal `taskId` | Integruoti gebėjimai: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`. ### Agento kortelė ```bash GET /.well-known/agent.json ``` Grąžina viešą A2A agento kortelę (pavadinimą, aprašymą, galimybes, gebėjimų katalogą, autentifikavimo schemą) — ji viešai podėliuojama 1 val. Autentifikavimas nereikalingas. ### REST pagalbinės sąsajos | Metodas | Kelias | Aprašymas | | ------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- | | GET | `/api/a2a/status` | Ar A2A įjungtas + užduočių statistika + podėlyje saugoma agento kortelės santrauka | | GET | `/api/a2a/tasks` | Užduočių sąrašas — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` | | POST | `/api/a2a/tasks` | (Neįgyvendinta kaip REST pagalbinė sąsaja — sukurkite per JSON-RPC `message/send`) | | GET | `/api/a2a/tasks/[id]` | Gauti vieną užduotį | | POST | `/api/a2a/tasks/[id]/cancel` | Atšaukti užduotį | **Autentifikavimas:** REST pagalbinės sąsajos veikia be valdymo autentifikavimo (jas gali skaityti valdymo skydas); JSON-RPC maršrutas `/a2a` naudoja Bearer `OMNIROUTE_API_KEY`, jei jis sukonfigūruotas. --- ## Debesija, vertinimo testai ir vertinimas | Metodas | Kelias | Aprašymas | | ------- | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | `/api/cloud/auth` | Patikrinti Bearer raktą ir grąžinti užmaskuotus teikėjų ryšius bei modelių alternatyvius vardus debesijos sinchronizavimo klientams | | POST | `/api/cloud/credentials/update` | Atnaujinti užšifruotus debesijoje sinchronizuojamo teikėjo prisijungimo duomenis | | POST | `/api/cloud/model/resolve` | Pagal vietinę maršrutizavimo lentelę susieti loginį modelio ID su konkrečiu teikėju ir modeliu | | GET | `/api/cloud/models/alias` | Pateikti modelių alternatyvių vardų sąrašą taip, kaip jis prieinamas debesijos sinchronizavimui | | GET | `/api/assess` | Nuskaityti naujausias vertinimo kategorijas (pagal teikėją / modelį) | | POST | `/api/assess` | Vykdyti vertinimą — turinys: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` | | GET | `/api/evals` | Pateikti integruotų vertinimo testų rinkinių ir naujausių vykdymų sąrašą | | POST | `/api/evals` | Paleisti vertinimo testą | | POST | `/api/evals/suites` | Sukurti pasirinktinį vertinimo testų rinkinį — turinys tikrinamas naudojant `evalSuiteSaveSchema` | | GET | `/api/evals/suites/[id]` | Gauti pasirinktinį vertinimo testų rinkinį | **Autentifikavimas:** `/api/cloud/auth` tiesiogiai patikrina Bearer raktą; kitiems `/api/cloud/*`, `/api/evals/*` ir `/api/assess` maršrutams reikalingas valdymo seansas / API raktas. `/api/assess` POST naudoja `validateBody` su diskriminuotosios sąjungos aprėpties schema. --- ## ACP (Agent Client Protocol) valdymas kaip antrinius procesus. Šie galiniai taškai valdo ACP agentų aptikimą ir pasirinktinių agentų registravimą. | Metodas | Kelias | Aprašymas | | ------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/acp/agents` | Pateikia visus žinomus CLI agentus (integruotus ir pasirinktinius), jų įdiegimo būseną, versiją ir vykdomąjį failą | | POST | `/api/acp/agents` | Užregistruoja pasirinktinį ACP agentą arba atnaujina podėlį — turinys: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` arba `{action: "refresh"}` | | DELETE | `/api/acp/agents` | Pašalina pasirinktinį ACP agentą — užklausos parametras: `?id=` | **Atsakymo pavyzdys** (`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 } ``` **Autentifikavimas:** reikalingas valdymo seansas (valdymo skydelio `auth_token` slapukas) arba valdymo srities API raktas. Išsamią informaciją rasite [ACP sistemos](../frameworks/ACP.md) dokumentacijoje. --- ## Analitika ir stebimumas Tikrojo laiko analitikos galiniai taškai, skirti maršruto parinkimui, glaudinimui ir teikėjų įvairovei stebėti. Jie naudojami `/dashboard/analytics/*` puslapiuose. ### Automatinio maršruto parinkimo analitika | Metodas | Kelias | Aprašymas | | ------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/auto-routing` | Apibendrinta automatinio maršruto parinkimo statistika: bendras iškvietimų skaičius, strategijų ir lygių pasiskirstymas, populiariausi teikėjai | | GET | `/api/analytics/auto-routing?days=7` | Pasirinkto laikotarpio statistika (numatytoji reikšmė – 24 val.) | **Atsakymo pavyzdys**: ```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 } ] } ``` ### Glaudinimo analitika | Metodas | Kelias | Aprašymas | | ------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/analytics/compression` | Apibendrinta glaudinimo statistika: sutaupyti prieigos raktai, sutaupymo procentas, režimų pasiskirstymas, variklių naudojimas | **Atsakymo pavyzdys**: ```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 } } ``` ### Teikėjų įvairovės stebėjimas | Metodas | Kelias | Aprašymas | | ------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/diversity` | Šenono entropija pagrįstas įvairovės stebėjimas: matuojant pasiskirstymą tarp teikėjų išvengiama pavienių gedimo taškų | **Atsakymo pavyzdys**: ```json { "window": "24h", "shannonEntropy": 2.45, "maxEntropy": 3.17, "diversityRatio": 0.77, "providerUsage": { "openai": 0.4, "anthropic": 0.25, "google": 0.2, "kiro": 0.15 }, "warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"] } ``` **Autentifikavimas:** reikalingas valdymo seansas arba valdymo srities API raktas. --- ## Administratoriaus operacijos Tik administratoriams skirti operacinio valdymo galiniai taškai. | Metodas | Kelias | Aprašymas | | ------- | ------------------------ | -------------------------------------------------------------------------------------------------------- | | GET | `/api/admin/concurrency` | Gauti dabartinius lygiagretumo apribojimus (visuotinius ir kiekvieno teikėjo) | | POST | `/api/admin/concurrency` | Atnaujinti lygiagretumo apribojimus — turinys: `{global?: number, perProvider?: Record}` | **Autentifikavimas:** Reikalinga administratoriaus sritį turinti valdymo sesija. --- ## CLI įrankių valdymas Valdykite CLI įrankius, integruojamus su „OmniRoute“ (antigravity, chipotle, commandCode, devin-cli ir kt.). Visą sąrašą rasite [Teikėjų žinyne](./PROVIDER_REFERENCE.md). | Metodas | Kelias | Aprašymas | | ------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cli-tools/all-statuses` | Visų CLI įrankių būsena (įdiegimas, versija, kada paskutinį kartą aptiktas) | | GET | `/api/cli-tools/status` | Išsami vieno CLI įrankio būsena (`?tool=` užklausa) | | POST | `/api/cli-tools/apply` | Įrašyti sugeneruotą įrankio konfigūraciją (`dryRun` pateikia peržiūrą; naudojant konteinerį grąžinama `422` + `containerEphemeralTarget`; `migration` nurodo pasenusį „Codex“ YAML) | | GET | `/api/cli-tools/backups` | Pateikti CLI įrankių konfigūracijų atsarginių kopijų sąrašą | | POST | `/api/cli-tools/backups` | Sukurti visų CLI įrankių konfigūracijų atsarginę kopiją | | POST | `/api/cli-tools/backups` | Atkurti: tas pats galinis taškas atkuria atsarginę kopiją, kai užklausos turinyje pateikiama `{tool, backupId}` | | GET | `/api/cli-tools/antigravity-mitm` | „Antigravity“ MITM tarpinio serverio būsena (`antigravity-mitm` CLI įrankis) | | POST | `/api/cli-tools/antigravity-mitm/alias` | Konfigūruoti `antigravity-mitm` alternatyviuosius vardus | **Autentifikavimas:** Reikalinga valdymo sesija. --- ## Agentų įgūdžiai Valdykite DI agentų įgūdžius (panašius į „OpenAI“ pasirinktinius GPT, tačiau skirtus agentams). | Metodas | Kelias | Aprašymas | | ------- | ---------------------------- | ------------------------------------------------------------------------------------------------ | | GET | `/api/agent-skills` | Pateikti visų agentų įgūdžių sąrašą (integruotų ir pasirinktinių) | | GET | `/api/agent-skills/[id]` | Gauti konkretų agento įgūdį | | POST | `/api/agent-skills` | Sukurti pasirinktinį agento įgūdį — turinys: `{name, description, prompt, model?, temperature?}` | | PUT | `/api/agent-skills/[id]` | Atnaujinti pasirinktinį agento įgūdį | | DELETE | `/api/agent-skills/[id]` | Ištrinti pasirinktinį agento įgūdį | | GET | `/api/agent-skills/[id]/raw` | Gauti neapdorotą raginimą ir metaduomenis (nevykdant) | | POST | `/api/agent-skills/generate` | Naudojant DI sugeneruoti naują įgūdį iš natūraliosios kalbos aprašymo | **Autentifikavimas:** Reikalinga valdymo sesija arba valdymo srities API raktas. --- ## Talpyklos valdymas Valdykite semantinę ir samprotavimo talpyklas. | Metodas | Kelias | Aprašymas | | ------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/cache` | Talpyklos apžvalga: bendras įrašų skaičius, pataikymų dažnis, dydis diske | | GET | `/api/cache/entries` | Pateikti talpyklos įrašų sąrašą (su puslapiavimu) | | DELETE | `/api/cache/entries` | Ištrinti talpyklos įrašus (filtruojant pagal užklausos parametrus) | | GET | `/api/cache/stats` | Išsami talpyklos statistika (pagal teikėją ir modelį) | | GET | `/api/cache/reasoning` | Samprotavimo talpyklos būsena (samprotavimo pakartojimui) | | DELETE | `/api/cache/reasoning` | Išvalyti samprotavimo talpyklą — užklausos parametrai: `?toolCallId=` (vienas), `?provider=

` arba nėra parametrų (visi) | **Autentifikavimas:** reikalingas valdymo seansas. --- ## Atminties sistema Valdykite nuolatinę atmintį (FTS5 + vektoriniai įterpiniai). | Metodas | Kelias | Aprašymas | | ------- | ------------------ | ---------------------------------------------------------------------------------- | | GET | `/api/memory` | Pateikti atminties įrašų sąrašą (filtruojant pagal sritį, tipą, paieškos užklausą) | | POST | `/api/memory` | Sukurti naują atminties įrašą — turinys: `{scope, type, content, metadata?}` | | GET | `/api/memory/[id]` | Gauti konkretų atminties įrašą | | PUT | `/api/memory/[id]` | Atnaujinti atminties įrašą | | DELETE | `/api/memory/[id]` | Ištrinti atminties įrašą | | GET | `/api/memory?q=` | Ieškoti atmintyje (FTS5 + vektoriai) — statistika įtraukta į tą patį atsakymą | **Autentifikavimas:** reikalingas valdymo seansas arba valdymo sričiai skirtas API raktas. --- ## Saityno jungtys Valdykite įvykių saityno jungčių prenumeratas. | Metodas | Kelias | Aprašymas | | ------- | ------------------------------- | ----------------------------------------------------------------------------------- | | GET | `/api/webhooks` | Pateikti visų saityno jungčių prenumeratų sąrašą | | POST | `/api/webhooks` | Sukurti saityno jungties prenumeratą — turinys: `{url, events[], secret?, active?}` | | GET | `/api/webhooks/[id]` | Gauti konkrečią saityno jungties prenumeratą | | PUT | `/api/webhooks/[id]` | Atnaujinti saityno jungties prenumeratą | | DELETE | `/api/webhooks/[id]` | Ištrinti saityno jungties prenumeratą | | GET | `/api/webhooks/[id]/deliveries` | Pateikti saityno jungties pristatymų istoriją (sėkmių / nesėkmių žurnalą) | | POST | `/api/webhooks/[id]/test` | Išsiųsti bandomąjį įvykį saityno jungčiai | **Autentifikavimas:** reikalingas valdymo seansas. Visus įvykių tipus žr. [Saityno jungčių sistemoje](../frameworks/WEBHOOKS.md). --- ## Įgūdžių sistema Valdykite įgūdžius (agentinių plėtinių sistemą). | Metodas | Kelias | Aprašymas | | ------- | ------------------------ | -------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Pateikti visų įdiegtų įgūdžių sąrašą (integruotų ir pasirinktinių) | | POST | `/api/skills/install` | Įdiegti įgūdį iš vietinio kelio arba URL | | DELETE | `/api/skills/[id]` | Pašalinti įgūdį | | PUT | `/api/skills/[id]` | Įjungti arba išjungti įgūdį — turinys: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` | | POST | `/api/skills/executions` | Vykdyti įgūdį — turinys: `{skillName, apiKeyId, input?, sessionId?}` | | GET | `/api/skills/executions` | Pateikti visų įgūdžių vykdymo istoriją (filtruoti pagal `?apiKeyId=`) | **Autentifikavimas:** Reikalinga valdymo sesija arba valdymo apimties API raktas. Išsamią informaciją žr. [Įgūdžių sistema](../frameworks/SKILLS.md). --- ## Papildiniai Valdykite OmniRoute papildinius (trečiųjų šalių plėtinius). | Metodas | Kelias | Aprašymas | | ------- | ---------------------------------- | ----------------------------------- | | GET | `/api/plugins` | Pateikti įdiegtų papildinių sąrašą | | POST | `/api/plugins/marketplace/install` | Įdiegti papildinį iš prekyvietės | | DELETE | `/api/plugins/[name]` | Pašalinti papildinį | | POST | `/api/plugins/[name]/activate` | Aktyvinti papildinį | | POST | `/api/plugins/[name]/deactivate` | Išaktyvinti papildinį | | GET | `/api/plugins/[name]/config` | Gauti papildinio konfigūraciją | | PUT | `/api/plugins/[name]/config` | Atnaujinti papildinio konfigūraciją | **Autentifikavimas:** Reikalinga valdymo sesija. Išsamią informaciją žr. [Papildinių sistema](../frameworks/PLUGIN_SDK.md). --- ## Šešėlinis maršruto parinkimas Šešėlinis / A-B paslaugų teikėjų palyginimas **nėra atskira REST sąsaja** — jis konfigūruojamas naudojant kombinuotąjį maršruto parinkimą (žr. [Automatiniai deriniai](../routing/AUTO-COMBO.md)). Kiekvieno derinio palyginimo metrikos pateikiamos naudojant `GET /api/combos/metrics`. --- ## Apsaugos priemonės Peržiūrėkite vykdymo aplinkos apsaugos priemones (PII aptikimą, užklausų injekcijų aptikimą, vaizdinio turinio susiejimą). Apsaugos priemonės vykdomos kiekvienai užklausai; jų galima atsisakyti atskirai kiekvienam iškvietimui naudojant užklausos antraštę `x-omniroute-disabled-guardrails` — nėra išsaugomos įjungimo ar išjungimo sąsajos. | Metodas | Kelias | Aprašymas | | ------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/guardrails` | Pateikti užregistruotų apsaugos priemonių ir jų būsenų sąrašą (pavadinimas / įjungta / prioritetas) | | POST | `/api/guardrails/test` | Bandomuoju režimu vykdyti prieš iškvietimą atliekamą apdorojimo seką su pavyzdine įvestimi — turinys: `{input, disabledGuardrails?}` | **Autentifikavimas:** Reikalinga valdymo sesija. Išsamią informaciją žr. [Saugumas > Apsaugos priemonės](../security/GUARDRAILS.md). --- --- ## Autentifikavimas Informaciją apie keturias prisijungimo duomenų grupes (valdymo skydelio seansą, vietinį CLI prieigos raktą, `oma_live_…` prieigos raktą ir valdymo aprėpties API raktą) bei jų skirtumus nuo išvadų generavimo raktų rasite [Valdymo autentifikavimas](../guides/MANAGEMENT-AUTH.md). - Valdymo skydelio maršrutai (`/dashboard/*`) naudoja `auth_token` slapuką - Prisijungiant naudojama išsaugota slaptažodžio maiša; jei jos nėra, naudojamas `INITIAL_PASSWORD` - `requireLogin` galima perjungti per `/api/settings/require-login` - Kai `REQUIRE_API_KEY=true`, `/v1/*` maršrutams gali būti privalomas „Bearer“ API raktas - Šiame žinyne „valdymo prieigos raktas“ / „valdymo aprėpties API raktas“ reiškia vieną iš tame vadove aprašytų grupių, o ne neapibrėžtą papildomą slapto rakto tipą > **Nesuderinamas pakeitimas (v3.8.0)** — `/api/v1/agents/tasks/*` ir atvėsimo laikotarpio valdymo galiniai taškai dabar reikalauja **valdymo autentifikavimo** (valdymo skydelio `auth_token` slapuko arba valdymo aprėpties API rakto). Klientai, kurie anksčiau šiuos maršrutus iškviesdavo be autentifikavimo, gaus atsakymą `401 Unauthorized`. Žr. įsipareigojimą `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).