# API Reference (Polski) 🌐 **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) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇹 [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) --- 🌐 **Języki:** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md) Podstawowa dokumentacja referencyjna interfejsu API OmniRoute. Obejmuje publiczne punkty końcowe `/v1` oraz najczęściej używane punkty końcowe zarządzania; kompletnymi źródłami informacji są dokument [`docs/openapi.yaml`](../openapi.yaml) w formacie przeznaczonym do odczytu maszynowego oraz drzewo tras w katalogu `src/app/api/`. --- ## Spis treści - [Uzupełnienia czatu](#chat-completions) - [Wyłączne dzierżawy zarządzanych sesji](#exclusive-managed-session-leases) - [Osadzenia](#embeddings) - [Generowanie obrazów](#image-generation) - [OCR dokumentów](#document-ocr) - [Lista modeli](#list-models) - [Manifest wtyczki dostawcy](#provider-plugin-manifest) - [Punkty końcowe zgodności](#compatibility-endpoints) - [API plików](#files-api) - [API zadań wsadowych](#batches-api) - [API wyszukiwania](#search-api) - [Strumieniowanie WebSocket](#websocket-streaming) - [Limity i zgłaszanie problemów](#quotas--issues-reporting) - [Pamięć podręczna semantyczna](#semantic-cache) - [Panel i zarządzanie](#dashboard--management) - [Zarządzanie kombinacjami](#combo-management) - [Webhooki](#webhooks) - [Zarejestrowane klucze (automatyczne zarządzanie)](#registered-keys-auto-management) - [Protokół agentów](#agents-protocol) - [Serwery proxy zarządzania](#management-proxies) - [Odporność (rozszerzona)](#resilience-extended) - [Umiejętności](#skills) - [Pamięć](#memory) - [Serwer MCP](#mcp-server) - [Serwer A2A](#a2a-server) - [Chmura, ewaluacje i ocena](#cloud-evals--assess) - [Przetwarzanie żądań](#request-processing) - [Uwierzytelnianie](#authentication) --- ## Uzupełnienia czatu ```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 } ``` ### Nagłówki niestandardowe | Nagłówek | Kierunek | Opis | | ------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-OmniRoute-No-Cache` | Żądanie | Ustaw na `true`, aby ominąć pamięć podręczną | | `x-omniroute-no-memory` | Żądanie | Ustaw na `true`, aby pominąć wstrzykiwanie pamięci i umiejętności dla tego żądania (działa analogicznie do opcji bez pamięci podręcznej; pozwala uniknąć narzutu tokenów i kosztów dla każdego wywołania) | | `X-OmniRoute-Progress` | Żądanie | Ustaw na `true`, aby otrzymywać zdarzenia postępu | | `X-Session-Id` | Żądanie | Stały klucz sesji dla zewnętrznego przypisania sesji | | `x_session_id` | Żądanie | Akceptowany jest również wariant z podkreśleniami (bezpośredni HTTP) | | `X-OmniRoute-Session-Id` | Żądanie | Znacznik sesji/konwersacji podany przez wywołującego (przekazywany również do pamięci). Jeśli jest obecny, zostaje zapisany bez zmian w `call_logs.session_tag` na potrzeby przypisywania kosztów do sesji (#8249) — nigdy nie jest generowany, gdy go brak | | `Idempotency-Key` | Żądanie | Klucz deduplikacji (okno 5 s) | | `X-Request-Id` | Żądanie | Alternatywny klucz deduplikacji | | `X-OmniRoute-Cache` | Odpowiedź | `HIT` lub `MISS` (bez strumieniowania) | | `X-OmniRoute-Idempotent` | Odpowiedź | `true`, jeśli wykonano deduplikację | | `X-OmniRoute-Progress` | Odpowiedź | `enabled`, jeśli śledzenie postępu jest włączone | | `X-OmniRoute-Session-Id` | Odpowiedź | Efektywny identyfikator sesji używany przez OmniRoute | | `X-OmniRoute-Request-Id` | Odpowiedź | Identyfikator korelacji żądania (jeśli jest znany) | | `X-OmniRoute-Version` | Odpowiedź | Wersja kompilacji OmniRoute (zawsze obecna) | | `X-OmniRoute-Cost-Saved` | Odpowiedź | Kwota w USD zaoszczędzona dzięki pamięci podręcznej przy `HIT` (tylko trafienia w pamięci podręcznej) | | `X-OmniRoute-Decision` | Odpowiedź | Ślad routingu: `strategy=; provider=; latency_ms=` (`` to strategia kombinacji lub `single` w przypadku żądania bez kombinacji) — zawsze obecny w odpowiedziach końcowych | > Uwaga dotycząca Nginx: jeśli korzystasz z nagłówków zawierających podkreślenia (na przykład `x_session_id`), włącz `underscores_in_headers on;`. > **Nagłówki telemetrii kosztów:** odpowiedzi zakończone powodzeniem, które nie są strumieniowane, również zawierają zestaw nagłówków telemetrii kosztów `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, stała liczba 10 miejsc po przecinku; `0.0000000000` w przypadku usług bezpłatnych lub bez określonej ceny), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit` oraz `X-OmniRoute-Fallback-Attempts` (tylko gdy > 0), a także `X-OmniRoute-Request-Id` i `X-OmniRoute-Version`. Są one emitowane przez uzupełnienia czatu, `/v1/responses`, `/v1/messages`, **a także punkty końcowe multimediów** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` i `/v1/moderations` (koszt zawsze wynosi `0`). Koszt multimediów jest obliczany według modalności (za obraz, sekundę, znak lub jednostkę wyszukiwania), jeśli cennik jest dostępny; w przeciwnym razie wynosi `0` (tryb fail-open). > **Semantyka kosztów trafienia w pamięci podręcznej:** w przypadku TRAFIENIA w semantycznej pamięci podręcznej (`X-OmniRoute-Cache-Hit: true`) nie jest wykonywane żadne wywołanie do dostawcy nadrzędnego, dlatego wartość `X-OmniRoute-Response-Cost` wynosi `0.0000000000` (**przyrostowy** koszt obsłużenia trafienia). Pierwotny koszt lub koszt, który zostałby poniesiony, jest raportowany oddzielnie w nagłówku `X-OmniRoute-Cost-Saved`. Systemy rozliczeniowe powinny sumować wartości `X-OmniRoute-Response-Cost` (trafienia nic nie kosztują), natomiast systemy analityczne pamięci podręcznej mogą agregować wartości `X-OmniRoute-Cost-Saved`. ## Wyłączne dzierżawy zarządzanych sesji Wyłączne dzierżawienie zarządzanych sesji to opcjonalny, niezależny od klienta kontrakt routingu: jeden aktywny właściciel utrzymuje jedno kwalifikujące się połączenie OmniRoute. Nie obejmuje ono dzierżawy modelu, nie wymaga OAuth, nie identyfikuje konkretnego klienta ani nie wymaga konkretnego dostawcy. Uwierzytelniający klucz API musi mieć zakres `lease:exclusive` oraz jawną, niepustą listę `allowedConnections`. Granica mutacji bazy danych wymusza obecność obu pól zarówno podczas tworzenia klucza, jak i jego częściowych aktualizacji. ```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"} ``` Pomyślne odpowiedzi na uzyskanie, odnowienie i zwolnienie dzierżawy zawierają znaczniki czasu, `state` oraz dokładną dodatnią wartość `generation`, ale nigdy wybrane połączenie ani dane uwierzytelniające. W przypadku odnowienia i zwolnienia generacja jest przekazywana w treści JSON: ```json { "action": "renew", "generation": 1 } ``` ```json { "action": "release", "generation": 1, "reason": "OWNER_EXIT" } ``` Właściciel aktywnej dzierżawy może jawnie zażądać bezpiecznych pod względem prywatności metadanych wyświetlania dotyczących jego bieżącego powiązania: ```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" } } ``` Ta opcjonalna akcja sprawdzania stanu jest zabezpieczona przez nieprzejrzysty identyfikator właściciela, uwierzytelniony zarządzany klucz API oraz dokładną aktywną generację w ramach jednej transakcji bazy danych. `displayName` zawiera wyłącznie przyciętą skonfigurowaną nazwę połączenia; ma wartość `null`, gdy nie istnieje bezpieczna skonfigurowana nazwa. OmniRoute nigdy nie zastępuje jej adresem e-mail ani wygenerowaną tożsamością konta. Wartość dostawcy jest niewrażliwą etykietą wyświetlaną i nigdy nie jest wygenerowanym identyfikatorem kompatybilnego dostawcy. Dane uwierzytelniające, tokeny, pliki cookie, nieprzetworzone identyfikatory połączeń lub kluczy API, skróty właścicieli, sekrety odgradzające oraz wewnętrzne dane routingu są wykluczone. Wyszukiwania z nieprawidłowym kluczem, nieprawidłowym właścicielem, nieaktualną generacją, a także dotyczące brakujących, wygasłych, zwolnionych lub unieważnionych dzierżaw zwracają ten sam błąd `409 LEASE_FENCE_STALE` bez metadanych połączenia. Klient, który otrzymał odpowiedź nakazującą oczekiwanie na dostępność, nie ma aktywnego powiązania, które mógłby sprawdzić. Gdy routing przełącza aktywną dzierżawę, ta sama generacja pozostaje ważna, a stan niepodzielnie zwraca nowe powiązanie, nigdy stare. Istniejący klienci pozostają bez zmian, ponieważ odpowiedzi dotyczące uzyskania, odnowienia, zwolnienia i oczekiwania zachowują dotychczasowy format. Ten kontrakt serwera nie zmienia standardowego punktu `/status` w OpenAI Codex. Standardowy Codex raportuje obecnie swojego dostawcę modelu oraz wbudowany stan uwierzytelniania/konta, ale nie wyświetla dowolnych niestandardowych metadanych konta dostawcy; przyszła integracja klienta musi wywołać tę akcję i zdecydować, jak wyświetlić `connection.displayName`. Każde żądanie zarządzanego wnioskowania przekazuje następnie oba nagłówki sterujące: ```http X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> X-OmniRoute-Lease-Generation: 1 ``` Dokładny właściciel, generacja, aktywne połączenie oraz uwierzytelniony klucz API są weryfikowane bezpośrednio przed każdą obsługiwaną próbą wysłania żądania do usługi nadrzędnej. Ponowne użycie właściciela i generacji z innym kluczem kończy się niepowodzeniem, nawet gdy ten klucz zezwala na to samo połączenie. Nieprzetworzone identyfikatory właścicieli nie są utrwalane, rejestrowane, zachowywane w migawce żądania ani przekazywane do usługi nadrzędnej. Tymczasowy konflikt zasobów zwraca HTTP `429` z nagłówkiem `Retry-After` oraz: ```json { "state": "WAITING_FOR_CAPACITY", "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" }, "reason": "NO_FREE_ELIGIBLE_CONNECTION", "retryAfter": 30 } ``` Ta odpowiedź oznacza jedynie, że zwykły zbiór kwalifikujących się połączeń był niepusty, a każdy wolny kandydat był zajęty przez obcą aktywną dzierżawę. Nieobsługiwane modele/dostawcy, niezgodność z zasadami, okresy oczekiwania, limity, stan działania oraz inne zwykłe niepowodzenia kwalifikacji zachowują dotychczasowe odpowiedzi OmniRoute. ### `x-omniroute-compression` Nadpisanie planu kompresji dla pojedynczego żądania. Ma najwyższy priorytet — zastępuje nadpisanie kombinacji routingu, aktywny profil, automatyczny wyzwalacz oraz ustawienie Default panelu. Wartości: | Wartość | Efekt | | ------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `off` | Brak kompresji dla tego żądania. | | `default` | Profil Default pochodzący z panelu (ignoruje aktywny profil). | | `engine:` | Pojedynczy silnik, jeśli jest włączony, np. `engine:rtk`. | | `` | Nazwana kombinacja, dopasowywana najpierw według nazwy (bez rozróżniania wielkości liter), a następnie według identyfikatora. | Uwagi: - Nieznane wartości są ignorowane (żądanie nigdy nie jest odrzucane); rozstrzyganie przechodzi do standardowej kolejności priorytetów operatora. - Jeśli wiele kombinacji ma tę samą nazwę, przekaż **id** kombinacji, aby uzyskać deterministyczne dopasowanie. - Kombinacji o nazwie `off` lub `default` nie można wybrać według nazwy (te słowa kluczowe są interpretowane jako pierwsze); odwołuj się do takiej kombinacji za pomocą jej identyfikatora. - Główny przełącznik kompresji stanowi bezwzględną blokadę: gdy kompresja jest globalnie wyłączona, ten nagłówek nie może jej włączyć. Zastosowany plan jest zwracany w nagłówku odpowiedzi: ``` X-OmniRoute-Compression: ; source= ``` gdzie `` przyjmuje jedną z wartości `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` lub `off`. --- ## Embeddingi ```bash POST /v1/embeddings Authorization: Bearer your-api-key Content-Type: application/json { "model": "nebius/Qwen/Qwen3-Embedding-8B", "input": "The food was delicious" } ``` Dostępni dostawcy: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI. Identyfikatory katalogowe mają postać `provider/model` (przykład: `jina-ai/jina-embeddings-v5-omni-small`). Same identyfikatory modeli Jina występujące w rejestrze (na przykład `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) również są rozpoznawane. Operacje embed/rerank/classify/segment Jina używają najpierw danych uwierzytelniających `jina-ai` z panelu; `JINA_AI_API_KEY` jest używany awaryjnie tylko wtedy, gdy w panelu nie ma klucza. Karta `jina-reader` służy wyłącznie do obsługi Reader / `r.jina.ai` (`POST /v1/web/fetch`) i nigdy nie udostępnia embeddingów ani ponownego rankingowania. Modele w rejestrze deklarujące obsługę multimodalną akceptują również do 32 ustrukturyzowanych elementów niezależnych od dostawcy. Typy elementów multimedialnych to `text`, `image`, `audio`, `video` i `document`. Ich pole `source` ma postać `{"type":"url","url":"https://..."}` albo `{"type":"base64","data":"...","media_type":"..."}`. Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano` oraz alias rodziny `jina-ai/jina-embeddings-v5-omni` → omni-small) akceptuje również natywne dokumenty EmbeddingsV5Request Jina i **przekazuje je bez zmian** do `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,..." }] } ] } ``` Natywne wartości `{ image | audio | video | pdf }` mogą być publicznym adresem URL HTTPS, identyfikatorem URI `data:` albo nieprzetworzonymi danymi base64. OmniRoute nie konwertuje tych obiektów na ciągi znaków ani nie pobiera natywnych adresów URL obrazów — Jina samodzielnie pobiera publiczne multimedia. Dodatkowe pola Jina (`task`, `normalized`, `truncate`, `embedding_type`) są przekazywane dalej. Jednostki SKU Jina obsługujące wyłącznie tekst nadal odrzucają dokumenty nietekstowe. Ograniczenia bezpieczeństwa i transportu: - Zdalne adresy URL multimediów muszą być publicznymi adresami HTTPS. Kanoniczne elementy `{type,source:url}` są pobierane po stronie serwera (ponowna walidacja przekierowań, limit czasu, limity rozmiaru, publiczny DNS, przypięcie połączenia) i osadzane przed wywołaniem dostawcy. Natywne elementy Jina `{image:"https://..."}` są przekazywane bez zmian po tej samej kontroli publicznego adresu HTTPS; Jina pobiera adres URL. - Wbudowane multimedia base64 są ograniczone do 8 MiB zdekodowanych danych na element oraz 16 MiB zdekodowanych danych w całym żądaniu. Tłumaczenie formatu dostawcy (elementy kanoniczne nigdy nie są przekazywane bez zmian): - Modele multimodalne Jina: każdy element najwyższego poziomu staje się jednym obiektem z kluczem modalności (`text` / `image` / `audio` / `video` / `pdf`), używającym identyfikatorów URI danych dla wbudowanych multimediów; jeden wektor na element najwyższego poziomu. - Rodzina Gemini Embedding 2: jedna tablica najwyższego poziomu staje się pojedynczym natywnym żądaniem `models/{model}:embedContent` z `content.parts` (`text` albo `inline_data`). - Nieznane/dynamiczne modele bez jawnych metadanych modalności odrzucają ustrukturyzowane dane wejściowe z kodem 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" } ``` Nieobsługiwane kombinacje modelu i modalności zwracają kod HTTP 400 zamiast wymuszać konwersję elementu. Pola rozszerzeń niezwiązane z danymi wejściowymi w starszych żądaniach zawierających ciągi znaków/tokeny nadal są przekazywane bez zmian. ```bash # Wyświetl wszystkie modele embeddingów GET /v1/embeddings ``` --- ## Generowanie obrazów ```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" } ``` Dostępni dostawcy: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (lokalnie), ComfyUI (lokalnie). ```bash # Wyświetl wszystkie modele obrazów GET /v1/images/generations ``` --- ## OCR dokumentów ```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` wybiera dostawcę OCR za pomocą prefiksu `provider/model`; sam identyfikator modelu (np. `mistral-ocr-latest`) jest przypisywany do zarejestrowanego dostawcy, a w przypadku pominięcia `model` domyślnie używany jest Mistral (`mistral-ocr-latest`). Zarejestrowani dostawcy (`open-sse/config/ocrRegistry.ts`): | Identyfikator dostawcy | Identyfikator modelu | Wartość `model` | Uwagi | | ----------------------------- | -------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (lub samo `mistral-ocr-latest`) | Synchroniczny — odpowiedź jest zwracana bezpośrednio z pojedynczego wywołania usługi nadrzędnej. | | `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Asynchroniczna usługa nadrzędna (`analyze` + odpytywanie) — patrz poniżej. | | `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Synchroniczny, za pośrednictwem partnerskiego punktu końcowego Vertex AI `openapi/chat/completions` — informacje o uwierzytelnianiu/adresie URL znajdują się poniżej. | Wszyscy trzej dostawcy zwracają odpowiedź w tym samym formacie co Mistral: ```json { "pages": [{ "index": 0, "markdown": "# Extracted text..." }], "model": "mistral-ocr-latest", "usage_info": { "pages_processed": 1 } } ``` ### Przepływ odpytywania Azure Document Intelligence Interfejs API `analyze` usługi Azure Document Intelligence działa asynchronicznie: początkowe żądanie zwraca nagłówek `Operation-Location` zamiast treści, a następnie trzeba cyklicznie odpytywać o wynik. Procedura obsługi (`open-sse/handlers/ocr.ts`) odpytuje ten adres URL co sekundę, wykonując maksymalnie 30 prób, natychmiast kończy się błędem (bez dalszego odpytywania) w przypadku odpowiedzi odpytywania innej niż `ok` lub statusu `"failed"` oraz zwraca `504`, jeśli operacja nadal trwa po wyczerpaniu limitu prób. Końcowa odpowiedź Azure jest normalizowana do tego samego formatu `pages`/`markdown`, którego używa Mistral, zanim zostanie zwrócona wywołującemu, dzięki czemu kod klienta nie musi obsługiwać tego dostawcy w sposób specjalny. ### Uwierzytelnianie i rozpoznawanie punktu końcowego Vertex AI DeepSeek OCR `vertex-deepseek-ocr` ponownie wykorzystuje ten sam mechanizm uwierzytelniania Vertex AI, który OmniRoute obsługuje już dla ruchu czatu/obrazów (`open-sse/executors/vertex.ts`): klucz API połączenia jest albo poświadczeniem JSON konta usługi (wymienianym na krótkotrwały token dostępu OAuth za pomocą przepływu JWT bearer), albo gotowym tokenem dostępu OAuth używanym bez zmian. Adresem URL punktu końcowego usługi nadrzędnej jest ogólny partnerski punkt końcowy Vertex `openapi/chat/completions`, utworzony na podstawie projektu i regionu połączenia — jawnie określone `providerSpecificData.project`/`providerSpecificData.region` zawsze mają pierwszeństwo; w przeciwnym razie projekt jest pobierany z `project_id` w danych JSON konta usługi, a domyślnym regionem jest `us-central1`. Oba te parametry są rozpoznawane w `open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`) i używane przez `src/app/api/v1/ocr/route.ts` przed przekazaniem do `handleOcr`. --- ## Lista modeli ```bash GET /v1/models Authorization: Bearer your-api-key → Zwraca wszystkie modele czatu, osadzania i obrazów oraz ich kombinacje w formacie OpenAI ``` ### Prefiksy identyfikatorów modeli (`?prefix=`) Większość modeli jest udostępniana z **prefiksem dostawcy**. To, który prefiks otrzymasz, jest kontrolowane przez flagę funkcji `MODELS_CATALOG_PREFIX_MODE` i może zostać nadpisane **dla każdego żądania** za pomocą parametru zapytania — jest to przydatne dla klienta, który chce otrzymać uporządkowaną listę bez zmieniania ustawienia obejmującego cały serwer dla wszystkich pozostałych użytkowników: ```bash GET /v1/models?prefix=alias # jeden identyfikator na model — krótki prefiks aliasu GET /v1/models?prefix=dual # obie formy (ustawienie domyślne serwera) GET /v1/models?prefix=canonical # tylko pełny prefiks identyfikatora dostawcy ``` | Tryb | Zwraca | Uwagi | | ----------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `dual` | `cc/claude-sonnet-4-6` **oraz** `claude/claude-sonnet-4-6` | **Domyślny.** Oba identyfikatory kierują do tego samego modelu; zachowano je, aby konfiguracje klientów z zakodowaną na stałe dowolną z tych form nadal działały. W przybliżeniu podwaja rozmiar katalogu. | | `alias` | `cc/claude-sonnet-4-6` | Jeden wpis na model. Dostawcy bez odrębnego aliasu nadal zwracają swój wpis, więc nic nie zostaje pominięte. | | `canonical` | `claude/claude-sonnet-4-6` | Jeden wpis na model z pełnym prefiksem identyfikatora dostawcy. Dostawcy bez odrębnego aliasu (np. `antigravity/…`, `agy/…`) również zwracają tutaj swój pojedynczy identyfikator, więc nic nie zostaje pominięte. | Kopię lustrzaną działającą w trybie `dual` można również rozpoznać bez parametru zapytania: zawiera pole `parent` wskazujące główny identyfikator. Klienci wyświetlający selektor modeli powinni wysyłać żądanie z `?prefix=alias` — tak działa [rozszerzenie OmniCopilot dla VS Code](../guides/VSCODE-COPILOT.md). ### Warianty modeli bez rozumowania W przypadku modeli Claude obsługujących rozumowanie endpoint `/v1/models` udostępnia również wariant **bez rozumowania**, którego identyfikator jest poprzedzony prefiksem `claude-3-omniroute-no-thinking/`: ``` claude-3-omniroute-no-thinking// ``` Wybranie tego identyfikatora (np. w konfiguracji Claude Code, która zawsze dołącza blok `thinking`) powoduje ponowne wskazanie rzeczywistego modelu `/` z wyłączonym rozumowaniem — przez `thinking:{type:"disabled"}` w ścieżce `/v1/messages` albo pominięcie pól `reasoning`/`reasoning_effort` w ścieżce `/v1/chat/completions`. Wariant jest wyświetlany tylko dla modeli z rodziny Claude, które obsługują rozumowanie **i** respektują wartość `disabled` (dlatego wykluczone są np. modele działające wyłącznie w trybie adaptacyjnym, które odrzucają `disabled`). Operatorzy mogą wymusić włączenie lub wyłączenie tego wariantu dla poszczególnych modeli za pomocą `ModelSpec.noThinkingAlias`. --- ## Manifest wtyczki dostawcy ```bash GET /api/v1/provider-plugin-manifest ``` Zwraca bezpieczny dla formatu JSON manifest wtyczek dostawców używany przez Bifrost, CLIProxyAPI i przyszłe routery typu sidecar. Odpowiedź jest generowana na podstawie rejestru dostawców TypeScript i celowo nie zawiera sekretów klientów OAuth, rozwiązywania środowiska wykonawczego, funkcji wykonawczych, nagłówków żądań ani danych kont. Użyj tego punktu końcowego, gdy sidecar działa poza procesem i nie może bezpośrednio zaimportować pliku `open-sse/config/providerPluginManifestRegistry.ts`. --- ## Punkty końcowe zgodności | Metoda | Ścieżka | Format | | ------ | ----------------------------------------- | ------------------------------------------- | | 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 (edycja/uzupełnianie) | | POST | `/v1/videos/generations` | Generowanie wideo w stylu OpenAI | | POST | `/v1/music/generations` | Generowanie muzyki w stylu OpenAI | | POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) | | POST | `/v1/audio/speech` | OpenAI TTS (zwraca treść audio) | | POST | `/v1/rerank` | Ponowne rankingowanie w stylu Cohere/Voyage | | POST | `/v1/classify` | Klasyfikacja Jina (`api.jina.ai`) | | POST | `/v1/segment` | Segmentator Jina (`segment.jina.ai`) | | POST | `/v1/moderations` | OpenAI Moderations | | GET | `/v1/models` | OpenAI | | POST | `/v1/messages/count_tokens` | Anthropic | | GET | `/v1beta/models` | Gemini | | POST | `/v1beta/models/{...path}` | Gemini generateContent | | POST | `/v1/api/chat` | Ollama | | GET | `/api/v1/vscode/{token}/` | Alias katalogu OpenAI | | GET | `/api/v1/vscode/{token}/models` | Alias modeli OpenAI | | POST | `/api/v1/vscode/{token}/chat/completions` | Tokenizowany alias OpenAI | | POST | `/api/v1/vscode/{token}/responses` | Tokenizowany alias OpenAI Responses | | POST | `/api/v1/vscode/{token}/api/chat` | Tokenizowany alias Ollama | | GET | `/api/v1/vscode/{token}/api/tags` | Tokenizowany alias tagów Ollama | Wszystkie trasy POST mają taką samą strukturę: `Bearer your-api-key` + treść JSON zweryfikowana przez Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` itd.; zobacz `src/shared/validation/schemas.ts`). W przypadku niepowodzenia walidacji schematu zwracany jest kod 4xx. W przypadku klientów, które nie mogą dołączyć nagłówka `Authorization: Bearer ...`, OmniRoute akceptuje również klucze API w adresie URL — za pośrednictwem parametrów zapytania zapewniających zgodność (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) lub dedykowanych punktów końcowych `/api/v1/vscode/{token}/...` opisanych poniżej. ```bash # Ponowne rankingowanie POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] } # Klasyfikacja Jina (dane uwierzytelniające Foundation API) POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] } # Segmentator Jina POST /v1/segment { "content": "...", "return_chunks": true } # Wyszukiwanie Jina (s.jina.ai; aliasy dostawcy: jina-search, jina-ai, jina) POST /v1/search { "query": "...", "provider": "jina-search" } # Moderowanie POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." } # TTS — zwraca treść audio/mpeg (lub w żądanym formacie) POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } # Edycja obrazu (multipart) POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png # Generowanie wideo / muzyki (identyfikator modelu z prefiksem dostawcy) POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." } POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." } ``` ### Dedykowane trasy dostawców ```bash POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` Prefiks dostawcy jest dodawany automatycznie, jeśli go brakuje. Niezgodne modele powodują zwrócenie kodu `400`. --- ## API plików Endpoint plików zgodny z OpenAI, przeznaczony do wsadowych danych wejściowych/wyjściowych oraz przesyłania plików o określonym przeznaczeniu. | Metoda | Ścieżka | Opis | | ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------- | | POST | `/v1/files` | Prześlij plik (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — maks. 512 MiB | | GET | `/v1/files` | Wyświetl listę plików dla uwierzytelnionego klucza API | | GET | `/v1/files/[id]` | Pobierz metadane pliku | | DELETE | `/v1/files/[id]` | Usuń plik | | GET | `/v1/files/[id]/content` | Prześlij strumieniowo surową zawartość pliku | **Uwierzytelnianie:** klucz API typu Bearer — pliki są przypisywane do poszczególnych kluczy API za pomocą `getApiKeyRequestScope`. Klucz może wyświetlać, pobierać i usuwać wyłącznie własne pliki; sesja panelu bez klucza ma dostęp do odczytu całej instancji; dostęp do pliku bez właściciela (przesłanego anonimowo lub w ramach sesji panelu) jest odrzucany dla każdego wywołującego bez sesji. `GET /v1/files` odrzuca anonimowego wywołującego — oraz podany klucz, którego nie można rozpoznać — z kodem `401`, nawet gdy `REQUIRE_API_KEY=false`, zamiast wyświetlać pliki wszystkich dzierżawców (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523). --- ## API przetwarzania wsadowego Przetwarzanie wsadowe zgodne z OpenAI. | Metoda | Ścieżka | Opis | | ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/batches` | Utwórz zadanie wsadowe — treść weryfikowana przez `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) | | GET | `/v1/batches` | Wyświetl listę zadań wsadowych | | GET | `/v1/batches/[id]` | Pobierz stan zadania wsadowego oraz `request_counts` | | DELETE | `/v1/batches/[id]` | Usuń ukończone lub zakończone niepowodzeniem zadanie wsadowe | | POST | `/v1/batches/[id]/cancel` | Anuluj trwające zadanie wsadowe | **Uwierzytelnianie:** klucz API typu Bearer. Zadania wsadowe są przypisywane do poszczególnych kluczy API zgodnie z tą samą trójwariantową regułą co pliki: dostęp wyłącznie dla własnego klucza, dostęp do całej instancji dla sesji panelu, rekordy bez właściciela niedostępne dla każdego wywołującego bez sesji (pobieranie, usuwanie, anulowanie oraz sprawdzanie `input_file_id` podczas tworzenia). `GET /v1/batches` odrzuca anonimowego wywołującego z kodem `401`, nawet gdy `REQUIRE_API_KEY=false`. --- ## API wyszukiwania Abstrakcja dostawców wyszukiwania internetowego (Tavily, Brave, Exa, Serper itd.). | Metoda | Ścieżka | Opis | | ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------- | | GET | `/v1/search` | Wyświetla skonfigurowanych dostawców wyszukiwania i ich możliwości | | POST | `/v1/search` | Wykonuje zapytanie wyszukiwania — treść walidowana przez `v1SearchSchema`, obsługuje pamięć podręczną i koalescencję | | GET | `/v1/search/analytics` | Statystyki trafień, opóźnień i pamięci podręcznej dla poszczególnych dostawców | **Uwierzytelnianie:** Klucz API typu Bearer (`extractApiKey` + `isValidApiKey`). Zasady wyszukiwania są egzekwowane przez `enforceApiKeyPolicy`. --- ## API pobierania stron internetowych Wyodrębnia zawartość z adresu URL za pośrednictwem skonfigurowanego dostawcy pobierania stron internetowych (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract). | Metoda | Ścieżka | Opis | | ------ | --------------- | ------------------------------------------------------------------------ | | POST | `/v1/web/fetch` | Pobiera/ekstrahuje adres URL — treść walidowana przez `v1WebFetchSchema` | **Uwierzytelnianie:** Klucz API typu Bearer (`extractApiKey` + `isValidApiKey`). Zasady są egzekwowane przez `enforceApiKeyPolicy`. **Mechanizm rezerwowy uwzględniający limity (#8297):** gdy nie podano jawnie `provider`, pula (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) jest przechodzona w ustalonej kolejności priorytetów (fill-first) — skonfigurowany dostawca objęty limitem żądań jest pomijany zamiast natychmiastowego przerywania żądania, a ponawialny błąd dostawcy nadrzędnego lub przekroczenie limitu (HTTP 429 zawsze; 402/403 dla bezpłatnych planów Firecrawl/Tavily/TinyFish z limitami — nie dla Jina Reader i nigdy dla zwykłego błędnego żądania 400) powoduje przejście w czasie wykonywania żądania do następnego jeszcze niewypróbowanego dostawcy z poświadczeniami. Gdy wszyscy dostawcy w puli zostaną wyczerpani, punkt końcowy zwraca pojedynczy kod `429` (z nagłówkiem `Retry-After`) zamiast wcześniejszego ogólnego kodu `400`. Gdy jawnie zażądano określonego `provider`, **nie** następuje niejawne przełączenie awaryjne — jawnie wskazany dostawca objęty limitem lub zgłaszający błąd zwraca własny błąd (`429`, jeśli objęty limitem, w przeciwnym razie status dostawcy nadrzędnego). --- ## Strumieniowanie przez WebSocket ```bash GET /v1/ws?handshake=1 ``` Waliduje uzgadnianie aktualizacji połączenia do WebSocket i zwraca przykładowe komunikaty protokołu przewodowego (`request`, `cancel`). Rzeczywiste ramki WS są obsługiwane przez dołączony serwer WS poza tabelą tras Next.js. **Uwierzytelnianie:** Klucz API typu Bearer podczas uzgadniania połączenia. ### Responses API przez WebSocket (tylko codex) ```bash # Ten sam host:port co API HTTP (domyślnie 20128); zaktualizuj połączenie: wscat -c "ws://localhost:20128/v1/responses?api_key=" # (lub: -H "Authorization: Bearer ") # Pierwszą ramką MUSI być response.create: { "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] } ``` Serwer proxy Responses-API-over-WebSocket jest połączony **wyłącznie z `codex`** (backend ChatGPT). Nasłuchuje na tym samym porcie co API/pulpit na ścieżkach `/v1/responses`, `/responses` i `/api/v1/responses`. Po otrzymaniu pierwszej ramki `response.create` uwierzytelnia i przygotowuje połączenie za pośrednictwem wewnętrznego mostu `codex-responses-ws`, wybiera połączenie OAuth codex i tuneluje do `wss://chatgpt.com/backend-api/codex/responses` za pośrednictwem transportu `wreq-js`. **Modele inne niż codex są odrzucane** (`codex_ws_provider_required`). Do routingu udziałów limitu użyj `model: "qtSd//codex/"`. Zaimplementowano w `app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`. **Uwierzytelnianie:** Klucz API typu Bearer podczas uzgadniania połączenia. Dołączony serwer HTTP (`server-ws.mjs`) musi być aktywnym punktem wejścia (jest nim domyślnie, gdy istnieje `app/server-ws.mjs`). #### Identyfikator modelu: użyj samego identyfikatora ChatGPT (bez prefiksu `codex/`) OpenAI **Codex CLI** waliduje nazwę modelu po stronie klienta, gdy `supports_websockets = true`, i **odrzuca identyfikatory z prefiksem dostawcy**, takie jak `codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`). Wyślij **sam** identyfikator (np. `gpt-5.5`). Most OmniRoute obsługuje wyłącznie codex, dlatego przed tunelowaniem do dostawcy nadrzędnego ponownie rozpoznaje sam identyfikator jako model codex (`resolveCodexWsModelInfo`) — nawet jeśli sam identyfikator `gpt-5.5` byłby w przeciwnym razie kierowany przez HTTP do innego dostawcy. #### Konfigurowanie OpenAI Codex CLI Skieruj Codex CLI do OmniRoute, dodając niestandardowego dostawcę z obsługą WebSocket do `~/.codex/config.toml` (użyj osobnego `CODEX_HOME`, aby uniknąć modyfikowania istniejącej konfiguracji): ```toml model = "gpt-5.5" # sam identyfikator — NIE "codex/gpt-5.5" model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute (WS)" base_url = "http://localhost:20128/v1" # bez końcowego ukośnika; adres URL WS jest wyprowadzany automatycznie (w środowisku produkcyjnym użyj https/wss) wire_api = "responses" # jedyna obsługiwana wartość od lutego 2026 r. supports_websockets = true # włącza transport Responses-over-WS env_key = "OMNIROUTE_API_KEY" # zawiera klucz API OmniRoute (Bearer) ``` ```bash export OMNIROUTE_API_KEY=sk-... # klucz API OmniRoute (dowolny klucz, jeśli REQUIRE_API_KEY=false) codex exec "Responda apenas: PONG" ``` CLI aktualizuje `base_url + /responses` do połączenia WebSocket, a OmniRoute tuneluje je do wybranego połączenia OAuth codex. Zweryfikowano kompleksowo względem lokalnego serwera: ChatGPT zwraca `codex.rate_limits` + `response.created` i strumieniuje odpowiedź. --- ## Limity i zgłaszanie problemów | Metoda | Ścieżka | Opis | | ------ | ------------------- | ------------------------------------------------------------------------------------------------- | | GET | `/v1/quotas/check` | Wstępnie sprawdza limit dla `provider` + `accountId` przed wydaniem zarejestrowanego klucza | | POST | `/v1/issues/report` | Zgłasza do GitHub błąd dotyczący limitu lub wydania klucza (wymaga `GITHUB_ISSUES_REPO` + tokenu) | **Uwierzytelnianie:** klucz API typu Bearer (`isAuthenticated`). --- ## Samoobsługowe sprawdzanie użycia (`/api/usage/om-usage`) Każdy klucz API może odczytywać **własne** użycie i limity — bez uwierzytelniania administracyjnego. Jest to punkt końcowy używany przez klienta (CLI, panel OmniCopilot) do wyświetlania właścicielowi klucza jego wydatków. ```bash # Forma tekstowa (historyczny kontrakt — zwykły tekst przeznaczony dla terminala) curl -H "Authorization: Bearer " \ http://localhost:20128/api/usage/om-usage # Forma ustrukturyzowana — używana przez interfejs użytkownika curl -H "Authorization: Bearer " \ "http://localhost:20128/api/usage/om-usage?format=json" ``` Klucz musi mieć włączoną opcję **`allowUsageCommand`** (domyślnie jest wyłączona — menedżer kluczy API w panelu przełącza ją osobno dla każdego klucza). Bez niej punkt końcowy odpowiada kodem `403`. `?format=json` zwraca rozróżnialną strukturę, dzięki czemu wywołujący nigdy nie odczytuje pola danych z odpowiedzi odmownej. W przypadku powodzenia: ```jsonc { "allowed": true, // obecne tylko wtedy, gdy dla klucza włączono indywidualne limity użycia (dzienne/tygodniowe w USD): "personal": { "dailySpentUsd": 1.25, "dailyLimitUsd": 5, "dailyResetAtIso": "…", "weeklySpentUsd": 8, "weeklyLimitUsd": 20, "weeklyResetAtIso": "…" /* … */, }, // migawka limitu wybranego dostawcy lub null, jeśli nic nie znajduje się jeszcze w pamięci podręcznej: "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */}, }, // migawka każdego połączenia, aby interfejs użytkownika mógł wyświetlić kilku dostawców obok siebie: "providers": [ { "connectionId": "…", "provider": "claude" /* … */ }, { "provider": "codex" /* … */ }, ], } ``` W przypadku odmowy (`401` — nieprawidłowy klucz / `403` — brak uprawnień) ta sama trasa zwraca `{ "allowed": false, "error": { "message": "…" } }` — obecne, ale puste pole `personal`/`provider` (klucz ma uprawnienia, ale nie uzyskano jeszcze żadnych danych) oznacza inny stan niż odmowa, a rozróżnia je wyłącznie forma JSON. **Uwierzytelnianie:** własny klucz API typu Bearer wywołującego, weryfikowany za pomocą `isValidApiKey` — _nie_ jest to interfejs administracyjny (`/api/keys/…`), który pozostaje chroniony przez `requireManagementAuth`. --- ## Semantyczna pamięć podręczna ```bash # Pobierz statystyki pamięci podręcznej GET /api/cache/stats # Wyczyść wszystkie pamięci podręczne DELETE /api/cache/stats ``` Przykład odpowiedzi: ```json { "semanticCache": { "memorySize": 42, "memoryMaxSize": 500, "dbSize": 128, "hitRate": 0.65 }, "idempotency": { "activeKeys": 3, "windowMs": 5000 } } ``` ### Wpływ na opóźnienie TRAFIENIE w semantycznej pamięci podręcznej powoduje zwrócenie odpowiedzi z pamięci podręcznej **bez wywołania usługi nadrzędnej**, dlatego zgłaszana wartość `X-OmniRoute-Response-Latency` jest bliska zeru (niezależnie od pierwotnego opóźnienia usługi nadrzędnej). Klienci wrażliwi na opóźnienia (testy wydajności, monitorowanie p50/p99) powinni sprawdzać nagłówek odpowiedzi `X-OmniRoute-Cache-Latency`: | Wartość | Znaczenie | | ----------- | -------------------------------------------------------------------------------------------------- | | `synthetic` | Odpowiedź zwrócona z pamięci podręcznej; opóźnienie nie jest rzeczywistym czasem usługi nadrzędnej | | _(brak)_ | Odpowiedź z rzeczywistego wywołania usługi nadrzędnej | ### Pomijanie pamięci podręcznej dla poszczególnych kluczy Klucze API mogą zrezygnować z odczytów semantycznej pamięci podręcznej za pomocą `cacheDefaultMode`: | Wartość | Zachowanie | | -------- | ---------------------------------------------------------------------------------------- | | `legacy` | Normalne działanie pamięci podręcznej (domyślne) | | `bypass` | Całkowite pominięcie wyszukiwania w pamięci podręcznej; zawsze wywołuje usługę nadrzędną | Ustaw podczas tworzenia klucza (`POST /api/keys`) lub aktualizacji (`PATCH /api/keys/[id]`): ```json { "cacheDefaultMode": "bypass" } ``` ### Pomijanie dla poszczególnych żądań Każde żądanie może pominąć pamięć podręczną niezależnie od ustawień klucza: ``` X-OmniRoute-No-Cache: true ``` --- ## Panel i zarządzanie Trasy zarządzania (`/api/*` z wyjątkiem publicznego uwierzytelniania/logowania) **nie** są autoryzowane za pomocą zwykłych kluczy API do wnioskowania. Rodziny poświadczeń, zakresy i przykłady curl: [Uwierzytelnianie zarządzania](../guides/MANAGEMENT-AUTH.md). ### Uwierzytelnianie | Punkt końcowy | Metoda | Opis | | ----------------------------- | ------- | -------------------------- | | `/api/auth/login` | POST | Logowanie | | `/api/auth/logout` | POST | Wylogowanie | | `/api/settings/require-login` | GET/PUT | Włączanie wymogu logowania | ### Zarządzanie dostawcami | Punkt końcowy | Metoda | Opis | | ---------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/providers` | GET/POST | Wyświetlanie listy / tworzenie dostawców | | `/api/providers/[id]` | GET/PUT/DELETE | Zarządzanie dostawcą | | `/api/providers/[id]/test` | POST | Testowanie połączenia z dostawcą | | `/api/providers/[id]/models` | GET | Wyświetlanie listy modeli dostawcy | | `/api/providers/validate` | POST | Weryfikowanie konfiguracji dostawcy | | `/api/providers/bulk` | POST | Zbiorcze dodawanie kluczy API dla JEDNEGO dostawcy | | `/api/providers/import` | POST | Importowanie heterogenicznej LISTY dostawców z przeanalizowanego pliku CSV/JSON (#6836); wyniki częściowych niepowodzeń dla poszczególnych wierszy | | `/api/provider-nodes*` | Różne | Zarządzanie węzłami dostawców | | `/api/provider-models` | GET/POST/PATCH/DELETE | Modele niestandardowe (dodawanie, aktualizowanie, ukrywanie/pokazywanie, usuwanie) | ### Przepływy OAuth | Punkt końcowy | Metoda | Opis | | -------------------------------- | ------ | ------------------------------ | | `/api/oauth/[provider]/[action]` | Różne | OAuth specyficzny dla dostawcy | ### Routing i konfiguracja | Punkt końcowy | Metoda | Opis | | --------------------- | -------- | --------------------------------------- | | `/api/models/alias` | GET/POST | Aliasy modeli | | `/api/models/catalog` | GET | Wszystkie modele według dostawcy i typu | | `/api/combos*` | Różne | Zarządzanie kombinacjami | | `/api/keys*` | Różne | Zarządzanie kluczami API | | `/api/pricing` | GET | Ceny modeli | ### Użycie i analityka | Punkt końcowy | Metoda | Opis | | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/usage/history` | GET | Historia użycia | | `/api/usage/logs` | GET | Dzienniki użycia | | `/api/usage/request-logs` | GET | Dzienniki na poziomie żądań | | `/api/usage/[connectionId]` | GET | Użycie dla poszczególnych połączeń | | `/api/usage/token-limits` | GET/POST/DELETE | Budżety limitów tokenów dla poszczególnych kluczy API | | `/api/usage/model-latency-stats` | GET | Kroczące zagregowane statystyki opóźnień według dostawcy/modelu (średnia/p50/p95/p99, współczynnik powodzenia); filtry: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) | | `/api/usage/cache-health` | GET | Podsumowanie kondycji pamięci podręcznej promptów na podstawie `call_logs` — stosunek zapisów do odczytów, rozkład wielkości zapisów p50/p90/p99, koncentracja dużych zapisów, podział według modelu oraz ocena `healthy`/`degraded`/`thrash`/`no-data`; parametry zapytania `range` (`1h`\|`24h`\|`7d`\|`30d`, domyślnie `24h`) i opcjonalny `model` (#8827) | ### Ustawienia | Punkt końcowy | Metoda | Opis | | ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/settings` | GET/PUT/PATCH | Ustawienia ogólne | | `/api/settings/proxy` | GET/PUT | Konfiguracja sieciowego serwera proxy | | `/api/settings/proxy/test` | POST | Testowanie połączenia z serwerem proxy | | `/api/settings/ip-filter` | GET/PUT | Lista dozwolonych/zablokowanych adresów IP | | `/api/settings/thinking-budget` | GET/PUT | Tryb przepisywania **żądań** dotyczących budżetu myślenia/rozumowania (przekazywanie bez zmian / automatyczne usuwanie / niestandardowy / adaptacyjny). Niezależny od kompresji. Zobacz [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). | | `/api/settings/system-prompt` | GET/PUT | Globalny prompt systemowy | | `/api/settings/compression` | GET/PUT | Globalna konfiguracja kompresji | | `/api/settings/purge-request-history` | POST | Usuwanie wierszy dziennika żądań i lokalnych artefaktów dziennika wywołań | ### Kontekst i kompresja | Endpoint | Metoda | Opis | | -------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- | | `/api/compression/preview` | POST | Podgląd kompresji off/lite/standard/aggressive/ultra/RTK/stacked | | `/api/compression/language-packs` | GET | Lista dostępnych pakietów językowych Caveman | | `/api/compression/rules` | GET | Lista metadanych reguł Caveman | | `/api/context/caveman/config` | GET/PUT | Alias ustawień specyficznych dla Caveman | | `/api/context/rtk/config` | GET/PUT | Ustawienia specyficzne dla RTK, w tym filtry niestandardowe i przechowywanie surowych danych wyjściowych | | `/api/context/rtk/filters` | GET | Katalog filtrów RTK i diagnostyka filtrów niestandardowych | | `/api/context/rtk/test` | POST | Uruchomienie podglądu/testu RTK dla ładunku tekstowego | | `/api/context/rtk/raw-output/[id]` | GET | Odczyt zachowanych, zredagowanych surowych danych wyjściowych według identyfikatora wskaźnika | | `/api/context/combos` | GET/POST | Wyświetlanie/tworzenie kombinacji kompresji | | `/api/context/combos/[id]` | GET/PUT/DELETE | Szczegóły/aktualizacja/usuwanie kombinacji kompresji | | `/api/context/combos/[id]/assignments` | GET/PUT | Przypisywanie kombinacji kompresji do kombinacji routingu | | `/api/context/analytics` | GET | Alias analityki kompresji | ### Monitorowanie | Endpoint | Metoda | Opis | | ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/sessions` | GET | Śledzenie aktywnych sesji | | `/api/rate-limits` | GET | Limity żądań dla poszczególnych kont | | `/api/monitoring/health` | GET | Kontrola stanu i podsumowanie dostawców (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Widok zarządzania zawiera `credentialHealth`: wartości skalarne pamięci podręcznej sond, `failedConnections`, gdy `failed>0`, oraz `staleDbNonOkCount` (utrwalony w SQLite `test_status`, a nie wskaźnik). Zobacz [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). | | `/api/cache/stats` | GET/DELETE | Statystyki pamięci podręcznej / czyszczenie | | `/api/modality-bridge/stats` | GET | Przechowywane w pamięci `attempts`, powodzenia/`bridged`, niepowodzenia, trafienia w pamięci podręcznej, `totalLatencyMs`, `latencySamples`, obliczana na podstawie liczby próbek wartość `averageLatencyMs` oraz czas ostatniego użycia (resetowane po ponownym uruchomieniu; uwierzytelnianie zarządcze) | | `/api/modality-bridge/video/runtime` | GET | Ścisła kontrola zaufanego interfejsu loopback przed uwierzytelnianiem zarządczym/sondą; oczyszczone informacje o dostępności i wersjach FFmpeg/ffprobe (bez przechowywania) | | `/api/modality-bridge/video/extract` | POST | Wewnętrzny, uwierzytelniony broker bajtów zaufanego interfejsu loopback; wejście 50 MiB, ograniczona kolejka/wyjście 32 MiB, `503` przy przekroczeniu pojemności, `499` przy rozłączeniu, `504` po przekroczeniu terminu; nie jest to publiczny interfejs API do przesyłania plików | ### Kopia zapasowa oraz eksport/import | Endpoint | Metoda | Opis | | --------------------------- | ------ | ------------------------------------------------------- | | `/api/db-backups` | GET | Wyświetlenie dostępnych kopii zapasowych | | `/api/db-backups` | PUT | Utworzenie ręcznej kopii zapasowej | | `/api/db-backups` | POST | Przywrócenie z określonej kopii zapasowej | | `/api/db-backups/export` | GET | Pobranie bazy danych jako pliku .sqlite | | `/api/db-backups/import` | POST | Przesłanie pliku .sqlite w celu zastąpienia bazy danych | | `/api/db-backups/exportAll` | GET | Pobranie pełnej kopii zapasowej jako archiwum .tar.gz | ### Synchronizacja z chmurą | Endpoint | Metoda | Opis | | ---------------------- | ------ | -------------------------------- | | `/api/sync/cloud` | Różne | Operacje synchronizacji z chmurą | | `/api/sync/initialize` | POST | Inicjalizacja synchronizacji | | `/api/cloud/*` | Różne | Zarządzanie chmurą | ### Tunele | Endpoint | Metoda | Opis | | -------------------------- | ------ | ------------------------------------------------------------------------------ | | `/api/tunnels/cloudflared` | GET | Odczyt stanu instalacji i działania Cloudflare Quick Tunnel na potrzeby panelu | | `/api/tunnels/cloudflared` | POST | Włączenie lub wyłączenie Cloudflare Quick Tunnel (`action=enable/disable`) | | `/api/tunnels/ngrok` | GET | Odczyt stanu działania ngrok Tunnel na potrzeby panelu | | `/api/tunnels/ngrok` | POST | Włączenie lub wyłączenie ngrok Tunnel (`action=enable/disable`) | ### Narzędzia CLI | Endpoint | Metoda | Opis | | ---------------------------------- | ------ | -------------------------------- | | `/api/cli-tools/claude-settings` | GET | Stan Claude CLI | | `/api/cli-tools/codex-settings` | GET | Stan Codex CLI | | `/api/cli-tools/droid-settings` | GET | Stan Droid CLI | | `/api/cli-tools/openclaw-settings` | GET | Stan OpenClaw CLI | | `/api/cli-tools/runtime/[toolId]` | GET | Ogólne środowisko wykonawcze CLI | Odpowiedzi CLI zawierają: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. ### Agenci ACP | Endpoint | Metoda | Opis | | ----------------- | ------ | ----------------------------------------------------------------------------------------- | | `/api/acp/agents` | GET | Wyświetlenie wszystkich wykrytych agentów (wbudowanych i niestandardowych) wraz ze stanem | | `/api/acp/agents` | POST | Dodanie niestandardowego agenta lub odświeżenie pamięci podręcznej wykrywania | | `/api/acp/agents` | DELETE | Usunięcie niestandardowego agenta według parametru zapytania `id` | Odpowiedź GET zawiera `agents[]` (id, name, binary, version, installed, protocol, isCustom) oraz `summary` (total, installed, notFound, builtIn, custom). ### Odporność i limity szybkości | Endpoint | Metoda | Opis | | --------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- | | `/api/resilience` | GET/PATCH | Pobieranie lub aktualizowanie kolejki żądań, okresu oczekiwania połączenia, wyłącznika dostawcy i ustawień oczekiwania | | `/api/resilience/reset` | POST | Resetowanie wyłączników obwodu dostawcy | | `/api/resilience/model-cooldowns` | GET | Wyświetlenie aktywnych blokad dla poszczególnych kombinacji (dostawca, połączenie, model), posortowanych według pozostałego czasu | | `/api/resilience/model-cooldowns` | DELETE | Usunięcie blokady modelu — treść `{provider, model}` lub `{all: true}`, aby usunąć wszystkie | | `/api/rate-limits` | GET | Stan limitu szybkości dla poszczególnych kont | | `/api/rate-limit` | GET | Globalna konfiguracja limitu szybkości | > Wszystkie cztery trasy `/api/resilience/*` wymagają **uwierzytelniania zarządzania** (`requireManagementAuth`). Pełne omówienie różnic między wyłącznikiem dostawcy, okresem oczekiwania połączenia i blokadą modelu znajduje się w sekcji [Odporność (rozszerzona)](#resilience-extended). ### Ewaluacje | Endpoint | Metoda | Opis | | ------------ | -------- | ------------------------------------------------------------ | | `/api/evals` | GET/POST | Wyświetlenie zestawów ewaluacyjnych / uruchomienie ewaluacji | ### Zasady | Endpoint | Metoda | Opis | | --------------- | --------------- | ----------------------------- | | `/api/policies` | GET/POST/DELETE | Zarządzanie zasadami routingu | ### Zgodność | Endpoint | Metoda | Opis | | --------------------------- | ------ | --------------------------------------------- | | `/api/compliance/audit-log` | GET | Dziennik audytu zgodności (ostatnie N wpisów) | ### v1beta (zgodność z Gemini) | Endpoint | Metoda | Opis | | -------------------------- | ------ | ------------------------------------- | | `/v1beta/models` | GET | Wyświetlenie modeli w formacie Gemini | | `/v1beta/models/{...path}` | POST | Endpoint Gemini `generateContent` | Te endpointy odzwierciedlają format API Gemini dla klientów wymagających natywnej zgodności z zestawem Gemini SDK. ### Wewnętrzne/systemowe interfejsy API | Endpoint | Metoda | Opis | | ------------------------ | ------ | ---------------------------------------------------------------------- | | `/api/init` | GET | Kontrola inicjalizacji aplikacji (używana przy pierwszym uruchomieniu) | | `/api/tags` | GET | Tagi modeli zgodne z Ollama (dla klientów Ollama) | | `/api/restart` | POST | Wywołanie kontrolowanego ponownego uruchomienia serwera | | `/api/shutdown` | POST | Wywołanie kontrolowanego wyłączenia serwera | | `/api/system/env/repair` | POST | Naprawa zmiennych środowiskowych dostawcy OAuth | > **Uwaga:** Te endpointy są używane wewnętrznie przez system lub w celu zapewnienia zgodności z klientami Ollama. Zazwyczaj nie są wywoływane przez użytkowników końcowych. ### Naprawa środowiska OAuth _(v3.6.1+)_ ```bash POST /api/system/env/repair Content-Type: application/json { "provider": "claude-code" } ``` Naprawia brakujące lub uszkodzone zmienne środowiskowe OAuth dla określonego dostawcy. Zwraca: ```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" } ``` --- ## Transkrypcja audio ```bash POST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` Transkrybuj pliki audio przy użyciu dowolnego skonfigurowanego dostawcy STT. Pierwszy segment ścieżki wybiera natywnego dostawcę (`openai/…`, `deepgram/…`). Bramy, które ponownie udostępniają model innego dostawcy, używają kwalifikowanego identyfikatora (`openrouter/deepgram/nova-3`). **Żądanie:** ```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" ``` **Odpowiedź:** ```json { "text": "Hello, this is the transcribed audio content.", "task": "transcribe", "language": "en", "duration": 12.5 } ``` **Przykładowe identyfikatory modeli:** `openai/whisper-1` (wymaga klucza OpenAI), `openrouter/deepgram/nova-3` (wymaga klucza OpenRouter), `deepgram/nova-3` (wymaga natywnego klucza Deepgram). Żądanie z samym `deepgram/nova-3` **nie** korzysta z OpenRouter. **Obsługiwane formaty:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- ## Zgodność z Ollama Dla klientów korzystających z formatu API Ollama: ```bash # Punkt końcowy czatu (format Ollama) POST /v1/api/chat # Lista modeli (format Ollama) GET /api/tags ``` Żądania są automatycznie tłumaczone między formatem Ollama a formatami wewnętrznymi. ## Tokenizowane aliasy dla VS Code / aliasy bez nagłówków Użyj tych aliasów, gdy integracja nie może dodać nagłówka `Authorization` i wymaga osadzenia klucza API w bazowym adresie URL. ```bash # Alias katalogu w stylu OpenAI GET /api/v1/vscode/{token}/ GET /api/v1/vscode/{token}/models # Aliasy czatu w stylu OpenAI POST /api/v1/vscode/{token}/chat/completions POST /api/v1/vscode/{token}/responses # Aliasy w stylu Ollama POST /api/v1/vscode/{token}/api/chat GET /api/v1/vscode/{token}/api/tags ``` Przykład: ```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"}]}' ``` Uwagi: - Tokenizowane aliasy korzystają ponownie z tych samych procedur obsługi co `/v1/*` i `/api/tags`; struktury odpowiedzi pozostają identyczne. - Zawsze gdy klient obsługuje niestandardowe nagłówki, preferuj `Authorization: Bearer ...`. - Tokeny umieszczone w adresach URL mogą pojawiać się w logach odwrotnego serwera proxy, historii przeglądarki i telemetrii poza OmniRoute. Traktuj je jako opcję zapewniającą zgodność, a nie jako domyślny tryb uwierzytelniania. --- ## Telemetria ```bash # Pobierz podsumowanie telemetrii opóźnień (p50/p95/p99 dla każdego dostawcy) GET /api/telemetry/summary ``` **Odpowiedź:** ```json { "providers": { "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } } } ``` --- ## Budżet ```bash # Pobierz stan budżetu dla wszystkich kluczy API GET /api/usage/budget # Ustaw lub zaktualizuj budż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" } ``` > **Uwagi dotyczące schematu** (`setBudgetSchema`): pole `apiKeyId` jest wymagane; co najmniej jedno z pól `dailyLimitUsd`, `weeklyLimitUsd` lub `monthlyLimitUsd` musi mieć wartość większą od zera. Pola opcjonalne: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Starszy format `{keyId, limit, period}` zwraca błąd `400 Bad Request`. ## Limity tokenów Budżety **tokenów** dla poszczególnych kluczy API (niezależne od powyższego budżetu opartego na USD). Są egzekwowane bezpośrednio podczas obsługi żądania: gdy użycie w bieżącym oknie dla danego klucza osiągnie limit, żądania są odrzucane z kodem `429 Too Many Requests`. Limity mogą być ograniczone do konkretnego `model`, `provider` lub stosowane `global`nie dla całego klucza; gdy do żądania pasuje kilka limitów, obowiązuje najbardziej restrykcyjny. ```bash # Wyświetlenie limitów tokenów klucza (wraz z bieżącym użyciem w oknie) GET /api/usage/token-limits?apiKeyId=key-123 # Utworzenie lub zaktualizowanie limitu tokenów POST /api/usage/token-limits Content-Type: application/json { "apiKeyId": "key-123", "scopeType": "model", "scopeValue": "openai/gpt-4o", "tokenLimit": 1000000, "resetInterval": "monthly", "enabled": true } # Usunięcie limitu tokenów według identyfikatora DELETE /api/usage/token-limits?id=tl-abc ``` > **Uwagi dotyczące schematu** (`setTokenLimitSchema`): `apiKeyId` i `scopeType` (`model` | `provider` | `global`) są wymagane. `scopeValue` jest wymagane, chyba że `scopeType` ma wartość `global` (np. identyfikator modelu dla zakresu `model` lub identyfikator dostawcy dla zakresu `provider`). `tokenLimit` musi być dodatnią liczbą całkowitą (wartość tekstowa zostanie przekonwertowana). Opcjonalne: `id` (pomiń, aby utworzyć; podaj, aby zaktualizować), `resetInterval` (`daily` | `weekly` | `monthly`, domyślnie `monthly`), `resetTime` (`HH:MM`), `enabled` (domyślnie `true`). Odpowiedzi `GET` uzupełniają każdy limit o pola `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` i `nextResetAt`. Jest to punkt końcowy klasy zarządzania (uwierzytelnianie jest egzekwowane centralnie przez potok autoryzacji). ## Przetwarzanie żądań 1. Klient wysyła żądanie do `/v1/*` 2. Procedura obsługi trasy wywołuje `handleChat`, `handleEmbedding`, `handleAudioTranscription` lub `handleImageGeneration` 3. Model zostaje ustalony (bezpośredni dostawca/model albo alias/kombinacja) 4. Poświadczenia są wybierane z lokalnej bazy danych z uwzględnieniem filtrowania dostępności kont 5. W przypadku czatu: `handleChatCore` sprawdza pamięć podręczną semantyczną/sygnatur i ustala ustawienia kompresji kombinacji 6. Gdy kompresja proaktywna jest włączona, jest wykonywana przed translacją do formatu dostawcy (`lite`, Caveman, RTK lub tryb warstwowy) 7. Moduł wykonawczy dostawcy wysyła żądanie do usługi nadrzędnej 8. Odpowiedź jest tłumaczona z powrotem na format klienta (czat) lub zwracana bez zmian (osadzenia/obrazy/dźwięk) 9. Rejestrowane są użycie, dane analityczne kompresji i dzienniki żądań 10. W przypadku błędów stosowany jest mechanizm rezerwowy zgodnie z regułami kombinacji Pełna dokumentacja architektury: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md) --- ## Zarządzanie kombinacjami Kombinacje routingu wyższego poziomu (podsumowane już w sekcji `/api/combos*`) można również mapować w relacji 1:1 na podstawie wzorca identyfikatora modelu, co umożliwia przezroczyste przekierowanie identyfikatora modelu w stylu OpenAI do kombinacji. | Metoda | Ścieżka | Opis | | ------ | -------------------------------- | ------------------------------------------------------------------------------------- | | GET | `/api/model-combo-mappings` | Wyświetlenie wszystkich mapowań model→kombinacja | | POST | `/api/model-combo-mappings` | Utworzenie mapowania — treść: `{pattern, comboId, priority?, enabled?, description?}` | | GET | `/api/model-combo-mappings/[id]` | Pobranie pojedynczego mapowania | | PUT | `/api/model-combo-mappings/[id]` | Zaktualizowanie pól istniejącego mapowania | | DELETE | `/api/model-combo-mappings/[id]` | Usunięcie mapowania | **Uwierzytelnianie:** sesja zarządzania/klucz API (`requireManagementAuth`). --- ## Webhooki Subskrypcje wychodzących webhooków dla zdarzeń OmniRoute (zakończenie żądania, wyczerpanie limitu, rotacja klucza itp.). | Metoda | Ścieżka | Opis | | ------ | ------------------------- | -------------------------------------------------------------------------- | | GET | `/api/webhooks` | Wyświetla webhooki (sekrety są maskowane do postaci `...`) | | POST | `/api/webhooks` | Tworzy webhook — treść: `{url, events?: ["*"], secret?, description?}` | | GET | `/api/webhooks/[id]` | Pobiera webhook | | PUT | `/api/webhooks/[id]` | Aktualizuje url/events/secret/description | | DELETE | `/api/webhooks/[id]` | Usuwa webhook | | POST | `/api/webhooks/[id]/test` | Wysyła testowy ładunek pod adres URL webhooka i zwraca status dostarczenia | **Uwierzytelnianie:** sesja zarządzania/klucz API (`requireManagementAuth`). --- ## Zarejestrowane klucze (automatyczne zarządzanie) Używane przez podsystem automatycznego zarządzania kluczami do wystawiania i rotacji kluczy API u bazowego dostawcy/na koncie, z dziennymi/godzinowymi limitami. | Metoda | Ścieżka | Opis | | ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/registered-keys` | Wyświetla zarejestrowane klucze (tylko zamaskowany prefiks) | | POST | `/api/v1/registered-keys` | Wystawia nowy zarejestrowany klucz — treść: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Zwraca nieprzetworzony klucz **jednorazowo**. Zwraca `429` w przypadku odmowy z powodu limitu. | | GET | `/api/v1/registered-keys/[id]` | Pobiera metadane zarejestrowanego klucza (bez nieprzetworzonej wartości) | | DELETE | `/api/v1/registered-keys/[id]` | Unieważnia zarejestrowany klucz | | POST | `/api/v1/registered-keys/[id]/revoke` | Jawny punkt końcowy unieważniania (taki sam efekt jak DELETE) | **Uwierzytelnianie:** klucz API Bearer (`isAuthenticated`). Zobacz również `/v1/quotas/check` i `/v1/issues/report`. --- ## Protokół agentów Zadania agentów chmurowych (Claude Code, Codex Cloud, OpenHands itp.) wykonywane zdalnie w imieniu użytkowników OmniRoute. | Metoda | Ścieżka | Opis | | ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/agents/tasks` | Wyświetla zadania — opcjonalnie `?provider=`, `?status=`, `?limit=` (1–500, domyślnie 50) | | POST | `/api/v1/agents/tasks` | Tworzy zadanie — treść żądania walidowana przez `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Zwraca `201` z obwiednią zadania | | DELETE | `/api/v1/agents/tasks?id=...` | Usuwa zadanie | | GET | `/api/v1/agents/tasks/[id]` | Odczytuje zadanie — synchronicznie odświeża status z nadrzędnego agenta chmurowego, gdy ustawiono `external_id` | | POST | `/api/v1/agents/tasks/[id]` | Akcja rozróżniana: `{action: "approve"}`, `{action: "message", message}` lub `{action: "cancel"}` | | DELETE | `/api/v1/agents/tasks/[id]` | Usuwa określone zadanie według identyfikatora | > **Uwierzytelnianie:** uwierzytelnianie zarządzania jest wymagane dla każdej metody (`requireCloudAgentManagementAuth`). Przed wersją v3.8.0 metody te nie wymagały uwierzytelniania — zmianę niekompatybilną wstecznie opisano w commicie `588a0333`. ```bash # Utwórz zadanie chmurowe Claude Code curl -X POST http://localhost:20128/api/v1/agents/tasks \ -H "Authorization: Bearer your-management-key" \ -H "Content-Type: application/json" \ -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}' ``` --- ## Serwery proxy zarządzania Wychodzące serwery proxy HTTP(S)/SOCKS, które można przypisać do dostawców, kont lub globalnie. | Metoda | Ścieżka | Opis | | ------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/management/proxies` | Wyświetla serwery proxy (z `?id=` zwraca jeden; z `?id=&where_used=1` zwraca graf przypisań) | | POST | `/api/v1/management/proxies` | Tworzy serwer proxy — treść żądania walidowana przez `createProxyRegistrySchema` | | PATCH | `/api/v1/management/proxies` | Aktualizuje serwer proxy — treść żądania walidowana przez `updateProxyRegistrySchema` (wymaga `id`) | | DELETE | `/api/v1/management/proxies?id=...&force=1` | Usuwa serwer proxy (użyj `force=1`, aby odłączyć przypisania) | | GET | `/api/v1/management/proxies/assignments` | Wyświetla przypisania — filtrowanie według `proxy_id`, `scope`, `scope_id`; przekaż `resolve_connection_id=`, aby ustalić aktywny serwer proxy dla połączenia | | PUT | `/api/v1/management/proxies/assignments` | Przypisuje — treść żądania walidowana przez `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Czyści pamięć podręczną dyspozytora | | PUT | `/api/v1/management/proxies/bulk-assign` | Przypisuje zbiorczo — treść żądania walidowana przez `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) | | GET | `/api/v1/management/proxies/health?hours=24` | Zbiorcze dane o stanie serwerów proxy (liczba sukcesów/niepowodzeń, opóźnienie) w określonym przedziale czasowym | **Uwierzytelnianie:** sesja zarządzania/klucz API na każdej trasie (`requireManagementAuth`). > Endpointy `POST /api/v1/management/proxies/[id]/assignments` i `POST /api/v1/management/proxies/[id]/health` z opisu zadania są obsługiwane przez przedstawione powyżej płaskie trasy `/assignments` i `/health` — w bazie kodu nie ma podtras dla poszczególnych identyfikatorów. --- ## Odporność (rozszerzona) OmniRoute udostępnia trzy niezależne mechanizmy obsługi tymczasowych awarii; poniższe punkty końcowe zarządzania umożliwiają operatorom odczytywanie i nadpisywanie ich ustawień: | Zakres | Przechowywanie stanu | Odczyt | Resetowanie / czyszczenie | | ---------------------------- | ------------------------------------------------ | ----------------------------------------- | --------------------------------------------------------- | | Wyłącznik dostawcy | `domain_circuit_breakers` + pamięć operacyjna | `/api/monitoring/health` | `POST /api/resilience/reset` | | Okres oczekiwania połączenia | `rateLimitedUntil` w połączeniach dostawcy | `/api/rate-limits`, `/api/providers/[id]` | (włącza się ponownie leniwie; wyczyść przez PUT dostawcy) | | Blokada modelu | Rejestr dostępności modeli w pamięci operacyjnej | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` | `PATCH /api/resilience` przyjmuje nadpisania wyłącznika dostawcy w `providerBreaker.oauth` i `providerBreaker.apikey`. Każdy profil obsługuje pola `degradationThreshold`, `failureThreshold` i `resetTimeoutMs`; te same pola są dostępne w Panel → Ustawienia → Odporność. ```bash # Wyczyść blokadę pojedynczego modelu curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ -H "Cookie: auth_token=..." \ -H "Content-Type: application/json" \ -d '{"provider":"openai","model":"gpt-4o-mini"}' # Usuń wszystkie blokady curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ -H "Cookie: auth_token=..." \ -d '{"all":true}' ``` Pełny opis koncepcyjny i domyślne ustawienia wyłączników: zobacz [`CLAUDE.md`](../../CLAUDE.md) → „Stan środowiska wykonawczego odporności”. --- ## Umiejętności Struktura umożliwiająca rozszerzanie OmniRoute za pomocą niestandardowych wykonywalnych procedur obsługi oraz integracji z platformami handlowymi. | Metoda | Ścieżka | Opis | | ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Wyświetla zainstalowane umiejętności — filtrowanie według `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, z podziałem na strony | | GET | `/api/skills/[id]` | Pobiera jedną umiejętność | | PUT | `/api/skills/[id]` | Aktualizuje umiejętność (nazwa, opis, tryb, schemat, procedura obsługi, tagi) | | DELETE | `/api/skills/[id]` | Odinstalowuje umiejętność | | POST | `/api/skills/install` | Instaluje umiejętność z surowego manifestu — treść: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` | | GET | `/api/skills/executions` | Wyświetla ostatnie wykonania umiejętności (dziennik audytu z danymi wejściowymi/wyjściowymi i czasem trwania) | | GET | `/api/skills/marketplace?q=...` | Wyszukuje lub wyświetla listę popularnych pozycji z platformy SkillsMP (wymaga ustawienia `skillsmpApiKey`) | | POST | `/api/skills/marketplace/install` | Instaluje umiejętność według identyfikatora z SkillsMP | | GET | `/api/skills/skillssh?q=&limit=` | Przeszukuje rejestr skills.sh | | POST | `/api/skills/skillssh/install` | Instaluje umiejętność według identyfikatora z skills.sh | **Uwierzytelnianie:** sesja zarządzania/klucz API. Trasy wyszukiwania na platformach handlowych akceptują uwierzytelnianie zarządzania lub klucz API Bearer (`isAuthenticated`). --- ## Pamięć Trwały magazyn pamięci konwersacyjnej/faktograficznej, ograniczony do klucza API / sesji. | Metoda | Ścieżka | Opis | | ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/memory` | Wyświetlanie listy wspomnień — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, z paginacją `offset/limit` lub `page/limit` | | POST | `/api/memory` | Tworzenie wspomnienia — treść żądania walidowana przez Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` | | GET | `/api/memory/[id]` | Pobieranie pojedynczego wspomnienia | | DELETE | `/api/memory/[id]` | Usuwanie wspomnienia | | GET | `/api/memory/health` | Stan podsystemu pamięci (łączność z bazą danych, backend osadzeń, stan indeksu wektorowego) | **Uwierzytelnianie:** sesja zarządzania/klucz API (`requireManagementAuth`). Wartości wyliczenia `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (zobacz `MemoryType` w `src/lib/memory/types.ts`). --- ## Serwer MCP OmniRoute zawiera wbudowany serwer Model Context Protocol z 3 mechanizmami transportu (stdio, SSE, streamable-http) oraz narzędziami o ograniczonym zakresie. Poniższe endpointy panelu odczytują dane o stanie/audycie i pośredniczą w obsłudze transportów HTTP. | Metoda | Ścieżka | Opis | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | `/api/mcp/status` | Sygnał aktywności, transport, stan online, ostatnie wywołanie, najczęściej używane narzędzia, współczynnik powodzenia z 24 godz. | | GET | `/api/mcp/tools` | Lista narzędzi MCP z polami `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` | | GET | `/api/mcp/sse` | Otwarcie strumienia SSE dla transportu SSE (zwraca `503`, jeśli MCP jest wyłączony lub transport jest niezgodny) | | POST | `/api/mcp/sse` | Wysłanie ramki JSON-RPC przez transport SSE | | GET | `/api/mcp/stream` | Otwarcie strony SSE transportu Streamable HTTP (komunikaty inicjowane przez serwer) | | POST | `/api/mcp/stream` | Wysłanie ramki JSON-RPC przez transport Streamable HTTP | | DELETE | `/api/mcp/stream` | Zakończenie sesji Streamable HTTP | | GET | `/api/mcp/audit` | Zapytanie do dziennika audytu — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` | | GET | `/api/mcp/audit/stats` | Zagregowane statystyki audytu (sumy, współczynnik powodzenia, średni czas trwania, najczęściej używane narzędzia) | **Uwierzytelnianie:** transporty `sse`/`stream` korzystają z mechanizmu uwierzytelniania właściwego dla MCP (klucz API Bearer z zakresem `mcp`); trasy `status`/`tools`/`audit*` są dostępne do odczytu z panelu (nie wymagają dodatkowego uwierzytelniania poza dostępem do hosta panelu). > Oba transporty HTTP są kontrolowane przez `settings.mcpEnabled` i `settings.mcpTransport` — niezgodność transportu zwraca `400`, a wyłączony stan MCP zwraca `503`. --- ## Serwer A2A OmniRoute udostępnia punkt końcowy A2A (Agent-to-Agent) zgodny z JSON-RPC 2.0 oraz otoczkę REST przeznaczoną do inspekcji i użycia w panelu. ### JSON-RPC ```bash POST /a2a Authorization: Bearer your-api-key # opcjonalne, chyba że ustawiono 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"}] } } ``` Obsługiwane metody (wszystkie zależne od `settings.a2aEnabled`): | Metoda | Opis | | ---------------- | -------------------------------------------------------------------------- | | `message/send` | Synchroniczne wykonanie umiejętności; zwraca `{task, artifacts, metadata}` | | `message/stream` | Strumieniowe wykonanie tego samego zestawu umiejętności za pomocą SSE | | `tasks/get` | Pobiera zadanie według `taskId` | | `tasks/cancel` | Anuluje zadanie według `taskId` | Wbudowane umiejętności: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`. ### Karta agenta ```bash GET /.well-known/agent.json ``` Zwraca publiczną kartę agenta A2A (nazwa, opis, możliwości, katalog umiejętności, schemat uwierzytelniania) — buforowaną publicznie przez 1 godz. Uwierzytelnianie nie jest wymagane. ### Pomocnicze punkty końcowe REST | Metoda | Ścieżka | Opis | | ------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/a2a/status` | Stan włączenia A2A, statystyki zadań i podsumowanie zbuforowanej karty agenta | | GET | `/api/a2a/tasks` | Wyświetla listę zadań — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` | | POST | `/api/a2a/tasks` | (Nie zaimplementowano jako pomocniczego punktu końcowego REST — utwórz przez JSON-RPC `message/send`) | | GET | `/api/a2a/tasks/[id]` | Pobiera jedno zadanie | | POST | `/api/a2a/tasks/[id]/cancel` | Anuluje zadanie | **Uwierzytelnianie:** pomocnicze punkty końcowe REST działają bez uwierzytelniania administracyjnego (są dostępne do odczytu przez panel); trasa JSON-RPC `/a2a` używa tokenu Bearer `OMNIROUTE_API_KEY`, jeśli został skonfigurowany. --- ## Chmura, ewaluacje i ocena | Metoda | Ścieżka | Opis | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | `/api/cloud/auth` | Weryfikuje klucz Bearer i zwraca zamaskowane połączenia z dostawcami oraz aliasy modeli dla klientów synchronizacji z chmurą | | POST | `/api/cloud/credentials/update` | Aktualizuje zaszyfrowane dane uwierzytelniające dostawcy synchronizowanego z chmurą | | POST | `/api/cloud/model/resolve` | Rozwiązuje logiczny identyfikator modelu do konkretnego dostawcy/modelu przy użyciu lokalnej tabeli routingu | | GET | `/api/cloud/models/alias` | Wyświetla aliasy modeli udostępniane synchronizacji z chmurą | | GET | `/api/assess` | Odczytuje najnowsze kategoryzacje oceny (dla poszczególnych dostawców/modeli) | | POST | `/api/assess` | Uruchamia ocenę — treść żądania: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` | | GET | `/api/evals` | Wyświetla wbudowane zestawy ewaluacyjne i najnowsze uruchomienia | | POST | `/api/evals` | Uruchamia ewaluację | | POST | `/api/evals/suites` | Tworzy niestandardowy zestaw ewaluacyjny — treść żądania walidowana przez `evalSuiteSaveSchema` | | GET | `/api/evals/suites/[id]` | Pobiera niestandardowy zestaw ewaluacyjny | **Uwierzytelnianie:** `/api/cloud/auth` bezpośrednio weryfikuje klucz Bearer; pozostałe trasy `/api/cloud/*`, `/api/evals/*` i `/api/assess` wymagają sesji administracyjnej/klucza API. Żądanie POST do `/api/assess` używa `validateBody` ze schematem zakresu będącym unią rozróżnianą. --- ## Zarządzanie ACP (Agent Client Protocol) jako procesami potomnymi. Te punkty końcowe służą do wykrywania agentów ACP i rejestrowania agentów niestandardowych. | Metoda | Ścieżka | Opis | | ------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/acp/agents` | Wyświetla wszystkich znanych agentów CLI (wbudowanych i niestandardowych) wraz ze stanem instalacji, wersją i plikiem binarnym | | POST | `/api/acp/agents` | Rejestruje niestandardowego agenta ACP lub odświeża pamięć podręczną — treść: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` lub `{action: "refresh"}` | | DELETE | `/api/acp/agents` | Usuwa niestandardowego agenta ACP — parametr zapytania: `?id=` | **Przykład odpowiedzi** (`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 } ``` **Uwierzytelnianie:** Wymaga sesji zarządzania (pliku cookie `auth_token` panelu) lub klucza API z zakresem zarządzania. Pełne informacje można znaleźć w dokumencie [Struktura ACP](../frameworks/ACP.md). --- ## Analityka i obserwowalność Punkty końcowe analityki w czasie rzeczywistym do monitorowania routingu, kompresji i różnorodności dostawców. Obsługują strony `/dashboard/analytics/*`. ### Analityka automatycznego routingu | Metoda | Ścieżka | Opis | | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/analytics/auto-routing` | Zbiorcze statystyki automatycznego routingu: łączna liczba wywołań, rozkład strategii, rozkład poziomów, główni dostawcy | | GET | `/api/analytics/auto-routing?days=7` | Statystyki dla określonego przedziału czasowego (domyślnie 24 godz.) | **Przykład odpowiedzi**: ```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 } ] } ``` ### Analityka kompresji | Metoda | Ścieżka | Opis | | ------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/compression` | Zbiorcze statystyki kompresji: liczba zaoszczędzonych tokenów, procent oszczędności, rozkład trybów, użycie silników | **Przykład odpowiedzi**: ```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 } } ``` ### Śledzenie różnorodności dostawców | Metoda | Ścieżka | Opis | | ------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/diversity` | Śledzenie różnorodności oparte na entropii Shannona: zapobiega pojedynczym punktom awarii poprzez pomiar rozkładu dostawców | **Przykład odpowiedzi**: ```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"] } ``` **Uwierzytelnianie:** Wymaga sesji zarządzania lub klucza API z zakresem zarządzania. --- ## Operacje administracyjne Punkty końcowe dostępne wyłącznie dla administratorów, służące do zarządzania operacyjnego. | Metoda | Ścieżka | Opis | | ------ | ------------------------ | ---------------------------------------------------------------------------------------------------- | | GET | `/api/admin/concurrency` | Odczytuje bieżące limity współbieżności (globalne i dla poszczególnych dostawców) | | POST | `/api/admin/concurrency` | Aktualizuje limity współbieżności — treść: `{global?: number, perProvider?: Record}` | **Uwierzytelnianie:** Wymaga sesji zarządzania z zakresem administratora. --- ## Zarządzanie narzędziami CLI Zarządzaj narzędziami CLI integrującymi się z OmniRoute (antigravity, chipotle, commandCode, devin-cli itp.). Pełna lista znajduje się w dokumencie [Informacje o dostawcach](./PROVIDER_REFERENCE.md). | Metoda | Ścieżka | Opis | | ------ | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cli-tools/all-statuses` | Stan wszystkich narzędzi CLI (zainstalowanie, wersja, ostatnia aktywność) | | GET | `/api/cli-tools/status` | Szczegółowy stan jednego narzędzia CLI (zapytanie `?tool=`) | | POST | `/api/cli-tools/apply` | Zapisuje wygenerowaną konfigurację narzędzia (`dryRun` wyświetla podgląd; `422` + `containerEphemeralTarget` w przypadku konteneryzacji; `migration` wskazuje starszy plik YAML Codex) | | GET | `/api/cli-tools/backups` | Wyświetla kopie zapasowe konfiguracji narzędzi CLI | | POST | `/api/cli-tools/backups` | Tworzy kopię zapasową konfiguracji wszystkich narzędzi CLI | | POST | `/api/cli-tools/backups` | Przywraca kopię: ten sam punkt końcowy z `{tool, backupId}` w treści żądania przywraca wskazaną kopię | | GET | `/api/cli-tools/antigravity-mitm` | Stan proxy MITM Antigravity (narzędzia CLI „antigravity-mitm”) | | POST | `/api/cli-tools/antigravity-mitm/alias` | Konfiguruje aliasy antigravity-mitm | **Uwierzytelnianie:** Wymaga sesji zarządzania. --- ## Umiejętności agentów Zarządzaj umiejętnościami agentów AI (podobnymi do niestandardowych GPT OpenAI, ale przeznaczonymi dla agentów). | Metoda | Ścieżka | Opis | | ------ | ---------------------------- | ----------------------------------------------------------------------------------------------------- | | GET | `/api/agent-skills` | Wyświetla wszystkie umiejętności agentów (wbudowane i niestandardowe) | | GET | `/api/agent-skills/[id]` | Pobiera określoną umiejętność agenta | | POST | `/api/agent-skills` | Tworzy niestandardową umiejętność agenta — treść: `{name, description, prompt, model?, temperature?}` | | PUT | `/api/agent-skills/[id]` | Aktualizuje niestandardową umiejętność agenta | | DELETE | `/api/agent-skills/[id]` | Usuwa niestandardową umiejętność agenta | | GET | `/api/agent-skills/[id]/raw` | Pobiera nieprzetworzony prompt i metadane (bez wykonywania) | | POST | `/api/agent-skills/generate` | Generuje przy użyciu AI nową umiejętność na podstawie opisu w języku naturalnym | **Uwierzytelnianie:** Wymaga sesji zarządzania lub klucza API z zakresem zarządzania. --- ## Zarządzanie pamięcią podręczną Zarządzaj semantyczną pamięcią podręczną i pamięcią podręczną rozumowania. | Metoda | Ścieżka | Opis | | ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cache` | Przegląd pamięci podręcznej: łączna liczba wpisów, współczynnik trafień, rozmiar na dysku | | GET | `/api/cache/entries` | Lista wpisów w pamięci podręcznej (z paginacją) | | DELETE | `/api/cache/entries` | Usuwanie wpisów z pamięci podręcznej (filtrowanie według parametrów zapytania) | | GET | `/api/cache/stats` | Szczegółowe statystyki pamięci podręcznej (według dostawcy i modelu) | | GET | `/api/cache/reasoning` | Stan pamięci podręcznej rozumowania (na potrzeby odtwarzania rozumowania) | | DELETE | `/api/cache/reasoning` | Czyszczenie pamięci podręcznej rozumowania — parametry zapytania: `?toolCallId=` (jeden wpis), `?provider=

` lub brak parametrów (wszystkie wpisy) | **Uwierzytelnianie:** Wymaga sesji zarządzania. --- ## System pamięci Zarządzaj pamięcią trwałą (FTS5 + osadzenia wektorowe). | Metoda | Ścieżka | Opis | | ------ | ------------------ | -------------------------------------------------------------------------------------- | | GET | `/api/memory` | Lista wpisów pamięci (filtrowanie według zakresu, typu i zapytania wyszukiwania) | | POST | `/api/memory` | Tworzenie nowego wpisu pamięci — treść żądania: `{scope, type, content, metadata?}` | | GET | `/api/memory/[id]` | Pobieranie określonego wpisu pamięci | | PUT | `/api/memory/[id]` | Aktualizowanie wpisu pamięci | | DELETE | `/api/memory/[id]` | Usuwanie wpisu pamięci | | GET | `/api/memory?q=` | Przeszukiwanie pamięci (FTS5 + wektory) — statystyki są zawarte w tej samej odpowiedzi | **Uwierzytelnianie:** Wymaga sesji zarządzania lub klucza API z zakresem zarządzania. --- ## Webhooki Zarządzaj subskrypcjami webhooków dla zdarzeń. | Metoda | Ścieżka | Opis | | ------ | ------------------------------- | ----------------------------------------------------------------------------------- | | GET | `/api/webhooks` | Lista wszystkich subskrypcji webhooków | | POST | `/api/webhooks` | Tworzenie subskrypcji webhooka — treść żądania: `{url, events[], secret?, active?}` | | GET | `/api/webhooks/[id]` | Pobieranie określonej subskrypcji webhooka | | PUT | `/api/webhooks/[id]` | Aktualizowanie subskrypcji webhooka | | DELETE | `/api/webhooks/[id]` | Usuwanie subskrypcji webhooka | | GET | `/api/webhooks/[id]/deliveries` | Lista historii dostarczeń webhooka (dziennik powodzeń i niepowodzeń) | | POST | `/api/webhooks/[id]/test` | Wysyłanie zdarzenia testowego do webhooka | **Uwierzytelnianie:** Wymaga sesji zarządzania. Pełną listę typów zdarzeń zawiera dokument [Platforma webhooków](../frameworks/WEBHOOKS.md). --- ## Framework umiejętności Zarządzanie umiejętnościami (frameworkiem rozszerzeń agentowych). | Metoda | Ścieżka | Opis | | ------ | ------------------------ | --------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Wyświetla wszystkie zainstalowane umiejętności (wbudowane i niestandardowe) | | POST | `/api/skills/install` | Instaluje umiejętność ze ścieżki lokalnej lub adresu URL | | DELETE | `/api/skills/[id]` | Odinstalowuje umiejętność | | PUT | `/api/skills/[id]` | Włącza lub wyłącza umiejętność — treść: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` | | POST | `/api/skills/executions` | Uruchamia umiejętność — treść: `{skillName, apiKeyId, input?, sessionId?}` | | GET | `/api/skills/executions` | Wyświetla historię wykonań wszystkich umiejętności (filtrowanie według `?apiKeyId=`) | **Uwierzytelnianie:** Wymaga sesji zarządzania lub klucza API z zakresem zarządzania. Pełne informacje można znaleźć w dokumencie [Framework umiejętności](../frameworks/SKILLS.md). --- ## Wtyczki Zarządzanie wtyczkami OmniRoute (rozszerzeniami innych firm). | Metoda | Ścieżka | Opis | | ------ | ---------------------------------- | --------------------------------- | | GET | `/api/plugins` | Wyświetla zainstalowane wtyczki | | POST | `/api/plugins/marketplace/install` | Instaluje wtyczkę z marketplace'u | | DELETE | `/api/plugins/[name]` | Odinstalowuje wtyczkę | | POST | `/api/plugins/[name]/activate` | Aktywuje wtyczkę | | POST | `/api/plugins/[name]/deactivate` | Dezaktywuje wtyczkę | | GET | `/api/plugins/[name]/config` | Pobiera konfigurację wtyczki | | PUT | `/api/plugins/[name]/config` | Aktualizuje konfigurację wtyczki | **Uwierzytelnianie:** Wymaga sesji zarządzania. Pełne informacje można znaleźć w dokumencie [Framework wtyczek](../frameworks/PLUGIN_SDK.md). --- ## Routing równoległy Równoległe porównywanie dostawców metodą A/B **nie stanowi samodzielnego interfejsu REST** — konfiguruje się je za pośrednictwem routingu combo (zobacz [Auto-Combo](../routing/AUTO-COMBO.md)). Metryki porównawcze dla poszczególnych combo są udostępniane przez `GET /api/combos/metrics`. --- ## Mechanizmy ochronne Inspekcja mechanizmów ochronnych środowiska uruchomieniowego (wykrywanie danych osobowych, wykrywanie wstrzykiwania promptów, obsługa pośrednia danych wizualnych). Mechanizmy ochronne są uruchamiane przy każdym żądaniu; rezygnacja dla pojedynczego wywołania odbywa się za pomocą nagłówka żądania `x-omniroute-disabled-guardrails` — nie istnieje trwały interfejs do ich włączania lub wyłączania. | Metoda | Ścieżka | Opis | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/guardrails` | Wyświetla zarejestrowane mechanizmy ochronne oraz ich stan (nazwa / włączenie / priorytet) | | POST | `/api/guardrails/test` | Przeprowadza testowe uruchomienie potoku przed wywołaniem na przykładowych danych — treść: `{input, disabledGuardrails?}` | **Uwierzytelnianie:** Wymaga sesji zarządzania. Pełne informacje można znaleźć w dokumencie [Bezpieczeństwo > Mechanizmy ochronne](../security/GUARDRAILS.md). --- --- ## Uwierzytelnianie Zobacz [Uwierzytelnianie zarządzania](../guides/MANAGEMENT-AUTH.md), aby poznać cztery rodziny danych uwierzytelniających (sesja panelu, lokalny token CLI, token dostępu `oma_live_…`, klucz API z zakresem zarządzania) oraz różnice między nimi a kluczami wnioskowania. - Trasy panelu (`/dashboard/*`) używają pliku cookie `auth_token` - Logowanie używa zapisanego skrótu hasła; wartością zapasową jest `INITIAL_PASSWORD` - Opcję `requireLogin` można przełączać za pomocą `/api/settings/require-login` - Trasy `/v1/*` mogą opcjonalnie wymagać klucza API Bearer, gdy `REQUIRE_API_KEY=true` - „token zarządzania” / „klucz API z zakresem zarządzania” w tej dokumentacji oznacza jedną z rodzin opisanych w tym przewodniku — nie niezdefiniowany, dodatkowy typ sekretu > **Zmiana niekompatybilna wstecznie (v3.8.0)** — `/api/v1/agents/tasks/*` oraz punkty końcowe zarządzania okresem karencji wymagają teraz **uwierzytelniania zarządzania** (pliku cookie `auth_token` panelu lub klucza API z zakresem zarządzania). Klienci, którzy wcześniej wywoływali te trasy bez uwierzytelnienia, otrzymają odpowiedź `401 Unauthorized`. Zobacz commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).