# 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) · 🇧🇦 [bs](../../../bs/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇹 [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) | 🇧🇦 [Bosanski](../i18n/bs/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md) Podstawowa dokumentacja referencyjna interfejsu API OmniRoute. Obejmuje publiczną powierzchnię `/v1` oraz najczęściej używane punkty końcowe zarządzania; wyczerpującymi źródłami są przeznaczony do odczytu maszynowego plik [`docs/openapi.yaml`](../openapi.yaml) oraz drzewo tras w `src/app/api/`. Szczegółowy opis protokołu zgodnego z OpenAI oraz macierz możliwości dostawców można znaleźć w pliku [`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md). --- ## 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 przez WebSocket](#websocket-streaming) - [Raportowanie limitów i 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 } ``` ### Niestandardowe nagłówki | 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 wyłączenia pamięci podręcznej; pozwala uniknąć narzutu tokenów/kosztów dla każdego wywołania) | | `X-OmniRoute-Progress` | Żądanie | Ustaw na `true`, aby otrzymywać zdarzenia postępu | | `X-Session-Id` | Żądanie | Klucz sesji trwałej używany do zewnętrznego przypisania sesji | | `x_session_id` | Żądanie | Akceptowany jest również wariant z podkreśleniami (bezpośrednie HTTP) | | `X-OmniRoute-Session-Id` | Żądanie | Znacznik sesji/konwersacji dostarczony 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 poszczególnych sesji (#8249) — nigdy nie jest generowany w przypadku braku | | `Idempotency-Key` | Żądanie | Klucz deduplikacji (okno 5 s) | | `X-Request-Id` | Żądanie | Alternatywny klucz deduplikacji | | `x-omniroute-connection` | Żądanie | Przypnij żądanie pojedynczego modelu do jednego połączenia dostawcy (konta) według jego identyfikatora — zobacz [Przypinanie konta dla każdego żądania](#account-pinning-per-request) | | `X-OmniRoute-Cache` | Odpowiedź | `HIT` lub `MISS` (bez strumieniowania) | | `X-OmniRoute-Idempotent` | Odpowiedź | `true`, jeśli przeprowadzono 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=` (`` oznacza strategię 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 znaki podkreślenia (na przykład `x_session_id`), włącz `underscores_in_headers on;`. #### Przypinanie konta dla poszczególnych żądań Gdy dostawca ma kilka połączeń (kont lub kluczy), OmniRoute zwykle wybiera jedno z nich zgodnie ze swoją strategią wyboru konta. Zamiast tego żądanie może przypiąć konkretne połączenie za pomocą nagłówka `x-omniroute-connection`: ```bash curl http://localhost:20128/v1/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "x-omniroute-connection: " \ -d '{"model": "codex/gpt-5.5", "messages": [{"role": "user", "content": "hi"}]}' ``` - **Gdzie znaleźć identyfikator.** Otwórz stronę dostawcy w panelu (**Panel → Dostawcy → **) i kliknij identyfikator `xxxxxxxx…` w wierszu połączenia — pełny identyfikator połączenia zostanie skopiowany. - **Które żądania go uwzględniają.** Żądania dla pojedynczego modelu (`provider/model`) kierowane do `/v1/chat/completions`, `/v1/messages` oraz `/v1/responses`. Kombinacje ignorują ten nagłówek: zamiast tego przypnij konto osobno dla każdego kroku kombinacji, używając własnego połączenia danego kroku. - **Przypięcie jest ścisłe, a nie preferencyjne.** Przypięte połączenie jest używane wyłącznie. Awaria w trakcie żądania rejestruje okres wyłączenia konta, ale **nie** powoduje przełączenia na inne konto tego samego dostawcy. - **Okres wyłączenia i limit zwalniają przypięcie.** Gdy przypięte połączenie jest tymczasowo wyłączone, wyczerpało limit lub zostało zablokowane przez zasady limitów, kolejne żądania przełączają się na inne połączenia dostawcy, dokładnie tak jak ruch bez przypięcia. - **Nieznane lub wyłączone identyfikatory powodują błąd.** Identyfikator, którego nie ma w aktywnej puli dostawcy (został usunięty, dezaktywowany lub należy do innego dostawcy), oznacza brak kwalifikującego się konta, więc żądanie kończy się niepowodzeniem zamiast zostać po cichu przekierowane gdzie indziej. Claude Code wysyła niestandardowe nagłówki przez `ANTHROPIC_CUSTOM_HEADERS`. Umieść tę zmienną w bloku `env` w pliku `~/.claude/settings.json` albo w pliku `.claude/settings.json` na poziomie projektu, aby przypisać inne konto do każdego projektu: ```jsonc { "env": { "ANTHROPIC_BASE_URL": "http://:20128", "ANTHROPIC_AUTH_TOKEN": "", "ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: ", }, } ``` Źródło: `src/sse/handlers/chat.ts` (odczyt nagłówka), `src/sse/services/auth.ts` oraz `src/sse/services/sessionAffinityPin.ts` (zwalnianie przypięcia i sprawdzanie braku w puli). > **Nagłówki telemetrii kosztów:** odpowiedzi zakończone powodzeniem bez strumieniowania zawierają również zestaw telemetrii kosztów `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, stałe 10 miejsc po przecinku; `0.0000000000` dla bezpłatnych pozycji lub pozycji 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` oraz `/v1/moderations` (koszt zawsze wynosi `0`). Koszt multimediów jest obliczany według modalności (za obraz, sekundę, znak lub jednostkę wyszukiwania), gdy informacje o cenach są dostępne; w przeciwnym razie wynosi `0` (zasada 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 usługi nadrzędnej, dlatego `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 `X-OmniRoute-Cost-Saved`. Systemy rozliczeniowe powinny sumować `X-OmniRoute-Response-Cost` (trafienia nic nie kosztują); narzędzia analityczne pamięci podręcznej mogą agregować `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 posiada jedno kwalifikujące się połączenie OmniRoute. Nie dzierżawi ono modelu, nie wymaga OAuth, nie identyfikuje konkretnego klienta ani nie wymaga określonego dostawcy. Uwierzytelniający klucz API musi mieć zakres `lease:exclusive` oraz jawną, niepustą listę `allowedConnections`. Granica mutacji bazy danych wymusza obecność obu pól jednocześnie podczas tworzenia klucza i aktualizacji częściowych. ```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 udostępniają 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 dla swojego 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 nieprzejrzystym identyfikatorem właściciela, uwierzytelnionym zarządzanym kluczem 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ą użytkownikowi i nigdy nie jest wygenerowanym identyfikatorem zgodnego 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 użyciem nieprawidłowego klucza, nieprawidłowego właściciela, nieaktualnej generacji, a także wyszukiwania 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ź informującą o oczekiwaniu na dostępność, nie ma aktywnego powiązania do sprawdzenia. Gdy routing przełącza aktywną dzierżawę, ta sama generacja pozostaje prawidłowa, a operacja sprawdzania stanu atomowo zwraca nowe powiązanie, nigdy stare. Istniejący klienci pozostają bez zmian, ponieważ odpowiedzi dotyczące uzyskania, odnowienia, zwolnienia i oczekiwania zachowują swoje dotychczasowe struktury. Ten kontrakt serwera nie zmienia standardowego punktu końcowego OpenAI Codex `/status`. Standardowy Codex raportuje obecnie swojego dostawcę modelu oraz wbudowany stan uwierzytelniania/konta, ale nie renderuje dowolnych niestandardowych metadanych konta dostawcy; przyszła integracja z klientem musi wywołać tę akcję i zdecydować, jak wyświetlić `connection.displayName`. Każde zarządzane żądanie inferencji 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ą odgradzane bezpośrednio przed każdą obsługiwaną próbą połączenia z usługą nadrzędną. 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 w dziennikach, zachowywane w migawce żądania ani przekazywane do usługi nadrzędnej. Tymczasowy konflikt o zasoby 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ń nie był pusty, a każdy wolny kandydat był zajęty przez obcą aktywną dzierżawę. Nieobsługiwane modele/dostawcy, niezgodność z zasadami, okres karencji, limit, stan kondycji oraz inne zwykłe błędy kwalifikacji zachowują swoje dotychczasowe odpowiedzi OmniRoute. ### `x-omniroute-compression` Nadpisanie planu kompresji dla pojedynczego żądania. Najwyższy priorytet — ma pierwszeństwo przed nadpisaniem kombinacji routingu, aktywnym profilem, automatycznym wyzwalaczem oraz ustawieniem domyślnym panelu. Wartości: | Wartość | Efekt | | ------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `off` | Brak kompresji dla tego żądania. | | `default` | Profil domyślny pochodzący z panelu (ignoruje aktywny profil). Silniki stratne pozostają wyłączone. | | `safe` | Tylko deduplikacja i scalanie białych znaków. | | `allow-lossy` | Zachowuje plan operatora dla tego żądania, w tym podsumowania i przepisywanie stylu. | | `engine:` | Pojedynczy silnik, gdy jest włączony, np. `engine:rtk`. Opcjonalne włączenie tego silnika dla danego żądania. | | `` | 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 normalnej kolejności priorytetów operatora. - Jeśli wiele kombinacji ma tę samą nazwę, przekaż **identyfikator** 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 `` to jedna z wartości `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` lub `off`. --- ## Osadzenia ```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ą format `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 osadzania, ponownego klasyfikowania, klasyfikowania i segmentowania Jina używają w pierwszej kolejności poświadczeń `jina-ai` z panelu; `JINA_AI_API_KEY` jest używany awaryjnie tylko wtedy, gdy w panelu nie istnieje żaden klucz. Karta `jina-reader` służy wyłącznie do obsługi Reader / `r.jina.ai` (`POST /v1/web/fetch`) i nigdy nie udostępnia osadzania ani ponownego klasyfikowania. Modele w rejestrze, które deklarują 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 multimedialne 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 platformy 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 tekstowe 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) oraz osadzane bezpośrednio przed wywołaniem dostawcy. Natywne elementy Jina `{image:"https://..."}` są przekazywane bez zmian po przeprowadzeniu takiej samej kontroli publicznego adresu HTTPS; Jina pobiera adres URL. - Multimedia base64 przesyłane bezpośrednio są ograniczone do 8 MiB zdekodowanych danych na element i 16 MiB zdekodowanych danych w całym żądaniu. Translacja na format dostawcy (elementy kanoniczne nigdy nie są przekazywane bez zmian): - Multimodalne modele Jina: każdy element najwyższego poziomu staje się jednym obiektem z kluczem określającym modalność (`text` / `image` / `audio` / `video` / `pdf`), używającym identyfikatorów URI danych dla multimediów osadzonych bezpośrednio; 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` lub `inline_data`). - llama.cpp (`llama-cpp/`, dowolny model załadowany przez lokalny serwer): kanoniczne elementy `text` stają się zwykłymi ciągami tekstowymi, a elementy `image` / `audio` / `video` stają się pojedynczymi obiektami `{"content": [part]}`, używającymi części zawartości czatu serwera llama (`image_url`, `input_audio` z formatem `wav` / `mp3` / `flac`, `input_video`) z osadzonymi bezpośrednio danymi; jeden wektor na element najwyższego poziomu. Serwer musi działać z opcjami `--embedding --mmproj …`; bez projektora samodzielnie odrzuca multimedia. Typ `document` nie jest obsługiwany. - Nieznane/dynamiczne modele bez jawnych metadanych modalności odrzucają ustrukturyzowane dane wejściowe, zwracając 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ą HTTP 400 zamiast wymuszać konwersję elementu. Pola rozszerzeń niezwiązane z danymi wejściowymi w starszych żądaniach opartych na ciągach tekstowych/tokenach są nadal przekazywane bez zmian. ```bash # Wyświetl wszystkie modele osadzeń 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 obejmują OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, **ZenMux**, SD WebUI (lokalnie), ComfyUI (lokalnie). `n` zwraca `n` obrazów w `data[]`. W przypadku dostawców, których nadrzędne API zwraca jeden obraz na wywołanie (Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI), wykonywanych jest `n` oddzielnych wywołań nadrzędnych, przy czym jednocześnie realizowane są maksymalnie 4. Stała wartość `seed` jest zwiększana o indeks wywołania (`seed`, `seed + 1`, …), dzięki czemu obrazy różnią się, ale pozostają odtwarzalne. Maksymalna wartość `n` wynosi 10. Całe żądanie kończy się niepowodzeniem, jeśli którekolwiek wywołanie się nie powiedzie. Lista formatów korzystających z rozdzielania wywołań znajduje się w `SINGLE_IMAGE_FANOUT_FORMATS` w pliku `open-sse/handlers/imageGeneration/fanOut.ts`. ZenMux ponownie wykorzystuje istniejące połączenie z kluczem API i akceptuje prefiksy `zenmux/` lub `zm/`: - `zenmux/openai/gpt-image-2` korzysta z OpenAI Images API usługi ZenMux. Opcje obejmują `size`, `quality`, `n`, `output_format`, `output_compression`, `background` oraz `response_format`. - Inni wydawcy, tacy jak `zm/meta/muse-image-1.0`, korzystają z punktu końcowego Vertex AI `:predict` usługi ZenMux. `n` jest mapowane na `sampleCount`, `aspect_ratio` na `aspectRatio`, a `image_size` (`1K`, `2K`, `4K`) na `sampleImageSize`. Wartość `size` podana w pikselach określa jedynie proporcje obrazu, bez gwarancji wymiarów w pikselach. Obsługiwane proporcje, rozdzielczości i liczby obrazów zależą od modelu. - `zm/inclusionai/ming-image-0.1-design` samodzielnie dobiera wymiary. Pomiń `size`, `aspect_ratio` oraz `image_size`; jawne wartości powodują zwrócenie HTTP 400. Formaty PNG, JPEG i WebP można wybrać za pomocą `output_format`. Ta integracja obsługuje generowanie obrazu z tekstu, a nie edycję na podstawie obrazu referencyjnego. Dane wyjściowe Vertex są normalizowane do `data[].b64_json`; `response_format: "url"` zwraca nadrzędny adres URL HTTPS albo adres URL danych base64, jeśli dostępne są wyłącznie bajty obrazu. Puste lub odfiltrowane wyniki zwracają błąd zamiast pustej odpowiedzi oznaczającej powodzenie. Dostęp do modeli zależy od konta ZenMux. Zobacz [Vertex API usługi ZenMux](https://docs.zenmux.ai/api/vertexai/generate-images) oraz [OpenAI Images API](https://docs.zenmux.ai/api/openai/generate-an-image). ```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 jego zarejestrowanego dostawcy, a pominięcie `model` powoduje domyślne użycie 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`) | Synchronicznie — odpowiedź jest zwracana bezpośrednio z pojedynczego wywołania nadrzędnego. | | `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Asynchroniczne API nadrzędne (`analyze` + odpytywanie) — zobacz poniżej. | | `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Synchronicznie, za pośrednictwem partnerskiego punktu końcowego Vertex AI `openapi/chat/completions` — informacje o uwierzytelnianiu i adresie URL znajdują się poniżej. | Wszyscy trzej dostawcy odpowiadają za pomocą tego samego formatu treści zgodnego z Mistral: ```json { "pages": [{ "index": 0, "markdown": "# Extracted text..." }], "model": "mistral-ocr-latest", "usage_info": { "pages_processed": 1 } } ``` ### Przepływ odpytywania Azure Document Intelligence API `analyze` usługi Azure Document Intelligence działa asynchronicznie: początkowe żądanie zwraca nagłówek `Operation-Location` zamiast treści, a wynik musi być pobierany przez cykliczne odpytywanie. Procedura obsługi (`open-sse/handlers/ocr.ts`) odpytuje ten adres URL co sekundę, maksymalnie 30 razy, natychmiast przerywa działanie (nie kontynuuje 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 do wywołującego, dzięki czemu kod klienta nie musi obsługiwać tego dostawcy w specjalny sposób. ### Uwierzytelnianie i ustalanie punktu końcowego Vertex AI DeepSeek OCR `vertex-deepseek-ocr` ponownie wykorzystuje to samo uwierzytelnianie Vertex AI, które OmniRoute już obsługuje dla ruchu czatu i obrazów (`open-sse/executors/vertex.ts`): klucz API połączenia jest poświadczeniem JSON konta usługi (wymienianym na krótkoterminowy token dostępu OAuth za pomocą przepływu JWT bearer) albo wcześniej wygenerowanym tokenem dostępu OAuth używanym bez zmian. Adres URL nadrzędnego punktu końcowego to ogólny partnerski punkt końcowy Vertex `openapi/chat/completions`, tworzony na podstawie projektu i regionu połączenia — jawnie podane `providerSpecificData.project`/`providerSpecificData.region` zawsze mają pierwszeństwo; w przeciwnym razie projekt jest ustalany na podstawie `project_id` z pliku JSON konta usługi, a region domyślnie przyjmuje wartość `us-central1`. Obie wartości są ustalane 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 kombinacje w formacie OpenAI ``` ### Ceny modeli (`pricing`) Wpis zawiera obiekt `pricing`, gdy OmniRoute zna cenę modelu. Cena pochodzi z tabeli cen używanej do rozliczania kosztów: wbudowanych wartości domyślnych, zsynchronizowanych cen oraz nadpisań ustawionych za pośrednictwem `/api/pricing`. Są to ceny katalogowe, dlatego dostawcy subskrypcyjni również wyświetlają cenę za token. ```json "pricing": { "prompt": "0.000005", "completion": "0.000025", "input_cache_read": "0.0000005", "input_cache_write": "0.00000625", "input": 5, "output": 25, "cached": 0.5, "cache_creation": 6.25 } ``` | Pola | Jednostka | Uwagi | | --------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `prompt`, `completion`, `input_cache_read`, `input_cache_write` | USD za token, ciąg dziesiętny | Zgodne z OpenRouter, nigdy w notacji wykładniczej. Dwa pola pamięci podręcznej występują tylko wtedy, gdy określono cenę pamięci podręcznej. | | `input`, `output`, `cached`, `cache_creation` | USD za 1 mln tokenów, liczba | Pola z wcześniejszych wersji katalogu, zachowane dla istniejących klientów. `reasoning` i `long_context` również występują, gdy zawiera je wiersz cennika. | - **Kombinacje** otrzymują cenę swojego pierwszego widocznego celu. Wbudowane kombinacje `auto/*` wybierają cel w czasie żądania, dlatego nie mają pola `pricing`. - **Darmowe modele** wyświetlają `"0"` (oraz `0`), gdy ich cena wynosi zero. Model bez wiersza cennika również wyświetla `"0"`, gdy katalog oznacza go jako darmowy (`free: true`) lub znajduje się on we wbudowanym katalogu darmowych modeli. - **Nieznana cena:** wpis nie ma klucza `pricing`. - **Dostawcy rozliczani za pomocą kredytów** (tacy jak Kiro) naliczają opłaty za żądanie, a nie za token. Ich wpisy zachowują wcześniejsze pola liczbowe za 1 mln tokenów i nie zawierają pól tekstowych z ceną za token. - **Warianty** (identyfikatory poziomu wysiłku rozumowania, aliasy bez myślenia oraz serwery lustrzane wykrywania i bramy) kopiują cenę modelu, do którego kierują żądania. - Pola zawierają wyłącznie stawki bazowe. Progi długiego kontekstu (pole liczbowe `long_context`) oraz mnożniki poziomu usługi (na przykład Codex fast lub flex) nie zmieniają `prompt` ani `completion`. - Obiekt jest taki sam dla każdego sposobu uwierzytelniania, w tym dla żądania w stylu Anthropic z `x-api-key` i `anthropic-version` (odpowiedź pozostaje `{ "object": "list", "data": [...] }`). Implementacja: `src/app/api/v1/models/catalogPricing.ts`. ### Prefiksy identyfikatorów modeli (`?prefix=`) Większość modeli jest udostępniana z **prefiksem dostawcy**. Wybór prefiksu jest kontrolowany przez flagę funkcji `MODELS_CATALOG_PREFIX_MODE` i może zostać nadpisany **dla każdego żądania** za pomocą parametru zapytania — jest to przydatne dla klienta, który potrzebuje przejrzystej listy bez zmieniania ogólnoserwerowego ustawienia dla wszystkich pozostałych: ```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 | Emituje | 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 emitują 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ż emitują tutaj swój pojedynczy identyfikator, więc nic nie zostaje pominięte. | Serwer lustrzany 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 robi [rozszerzenie OmniCopilot dla VS Code](../guides/VSCODE-COPILOT.md). ### Filtry wykrywania (`?capability=`, `?min_context=`, `?kind=`, `?q=`) `GET /v1/models` obsługuje opcjonalne filtry wykrywania. Bez żadnego z nich odpowiedź pozostaje niezmieniona. Zawężają one katalog już widoczny dla wywołującego (uprawnienia klucza API są stosowane jako pierwsze) i działają przed stronicowaniem w stylu OpenAI za pomocą `limit` / `after`: ```bash GET /v1/models?capability=vision&capability=tool_calling # każda wymieniona funkcja musi mieć wartość true GET /v1/models?capability=vision,reasoning&min_context=200000 GET /v1/models?kind=embedding # katalogowe `type`; wiersze bez niego mają wartość `chat` GET /v1/models?q=sonnet&limit=10 # dopasowanie identyfikatora lub nazwy bez uwzględniania wielkości liter ``` | Parametr | Wartości | | ------------- | --------------------------------------------------------------------------------------------------- | | `capability` | `attachment`, `reasoning`, `structured_output`, `temperature`, `thinking`, `tool_calling`, `vision` | | `min_context` | nieujemna liczba całkowita, porównywana z `context_length` | | `kind` | `chat`, `audio`, `embedding`, `image`, `moderation`, `music`, `rerank`, `video` | | `q` | 1–200 znaków | Nieznana wartość lub `min_context`, które nie jest nieujemną liczbą całkowitą (na przykład `1.5`), powoduje zwrócenie HTTP `400`, a komunikat zawiera listę prawidłowych wartości. Implementacja: `src/app/api/v1/models/catalogFilters.ts`. ### Skrócona lista modeli (`POST /v1/models/query`) `POST /v1/models/query` zwraca krótką, deterministyczną listę z tego samego katalogu, z takim samym uwierzytelnianiem i widocznością dla poszczególnych kluczy jak `GET /v1/models`: ```bash POST /v1/models/query Authorization: Bearer your-api-key Content-Type: application/json { "capabilities": ["vision", "tool_calling"], "min_context": 128000, "max_output": 16000, "kind": "chat", "q": "gpt", "owned_by": "openai", "exclude": ["openai/gpt-4o"], "limit": 5 } → { "object": "list", "data": [ ...models ] } ``` Każde pole jest opcjonalne. `capabilities` i `exclude` przyjmują tablicę lub ciąg rozdzielony przecinkami; `max_output` jest porównywane z `max_output_tokens`. Wyniki są sortowane najpierw według `owned_by`, a następnie `id`. Domyślna wartość `limit` to `20`, a wartości powyżej `100` są ograniczane do `100`. Nieprawidłowy JSON, nieznane pole lub nieprawidłowa wartość powodują zwrócenie HTTP `400`. ### Indywidualnie ukryte modele czatu Model oznaczony jako **Ukryty** na stronie jego dostawcy jest wykluczany z katalogu, a jawne żądanie tego modelu jest odrzucane z HTTP `404` / `model_not_found`. Kontrola korzysta z ustalonego dostawcy i modelu, z uwzględnieniem aliasów dostawców, prefiksów węzłów zgodnych dostawców oraz domyślnych ustawień połączenia. Kombinacja pomija ukryte cele i może użyć widocznego modelu równorzędnego; jeśli nie pozostanie żaden cel możliwy do wykonania, zwracany jest ten sam kod błędu. Wyłączenie ukrywania zaczyna obowiązywać przy następnym żądaniu. Nadpisania widoczności dotyczące wyłącznie obrazów nie ukrywają modelu czatu o tym samym ID. To indywidualne ustawienie modelu jest niezależne od [list dozwolonych/zabronionych modeli](../routing/MODEL_EXPOSURE_LIST.md), które filtrują modele prezentowane w katalogu i kandydatów do automatycznego routingu, zachowując jednocześnie możliwość jawnego kierowania żądań. Uprawnienia modeli dla kluczy API nadal obowiązują niezależnie. Domyślnym trybem prefiksów katalogu pozostaje `dual`. ### Warianty modeli bez myślenia W przypadku modeli Claude obsługujących myślenie `/v1/models` udostępnia również wariant **bez myślenia**, którego id jest poprzedzone prefiksem `claude-3-omniroute-no-thinking/`: ``` claude-3-omniroute-no-thinking// ``` Wybranie tego id (np. w konfiguracji Claude Code, która zawsze dołącza blok `thinking`) jest rozwiązywane z powrotem do rzeczywistego `/` z wyłączonym rozumowaniem — `thinking:{type:"disabled"}` w ścieżce `/v1/messages` albo z pominięciem 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ą myślenie **i** respektują `disabled` (dlatego wykluczone są np. modele wyłącznie adaptacyjne, które odrzucają `disabled`). Operatorzy mogą wymusić włączenie lub wyłączenie wariantu dla poszczególnych modeli za pomocą `ModelSpec.noThinkingAlias`. --- ## Manifest wtyczek dostawców ```bash GET /api/v1/provider-plugin-manifest ``` Zwraca bezpieczny dla formatu JSON manifest wtyczek dostawców używany przez Bifrost, CLIProxyAPI oraz przyszłe routery sidecar. Odpowiedź jest generowana na podstawie rejestru dostawców TypeScript i celowo nie obejmuje 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ć `open-sse/config/providerPluginManifestRegistry.ts`. --- ## Generowanie dźwięku za pomocą ElevenLabs Skonfiguruj połączenie dostawcy `elevenlabs` w OmniRoute przy użyciu swojego klucza API ElevenLabs. Klienci uwierzytelniają się swoim kluczem **OmniRoute** (`Authorization: Bearer $OMNIROUTE_API_KEY`); brama przekazuje zapisany klucz dostawcy jako `xi-api-key`. Nigdy nie wysyłaj klucza ElevenLabs jako tokenu okaziciela bramy. | Metoda | Ścieżka | Odpowiedź | Kategoria punktu końcowego klucza API | | ------ | --------------------------- | ----------------------------------------------- | ------------------------------------- | | POST | `/v1/sound-generation` | Natywne bajty dźwięku | `elevenlabs` | | POST | `/v1/music` | Natywne bajty dźwięku | `music` | | POST | `/v1/music/stream` | Strumieniowe bajty dźwięku | `music` | | POST | `/v1/music/detailed` | Natywny wieloczęściowy dźwięk i plan kompozycji | `music` | | POST | `/v1/music/detailed/stream` | Natywne metadane SSE i fragmenty dźwięku | `music` | | POST | `/v1/music/plan` | Plan kompozycji w formacie JSON | `music` | Te punkty końcowe uzupełniają istniejące trasy `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/voices`, `/v1/text-to-speech/{voiceId}` oraz `/v1/speech-to-text`. Natywne pola JSON i parametry zapytania, takie jak `output_format` oraz `enable_logging`, są zachowywane. Odpowiedzi `/v1/music/detailed` zachowują swoje granice części; należy je przetwarzać jako dane wieloczęściowe. `/v1/music/detailed/stream` zwraca `text/event-stream` z metadanymi kompozycji oraz fragmentami dźwięku zakodowanymi w base64 w zdarzeniach SSE. Wszystkie sześć tras obsługuje żądania wstępne CORS. ```bash export OMNIROUTE_BASE_URL="http://localhost:20128" export OMNIROUTE_API_KEY="your-omniroute-api-key" # Krótki efekt dźwiękowy. Czas trwania: od 0,5 do 30 sekund. curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/sound-generation?output_format=mp3_44100_128" \ -H "Authorization: Bearer $OMNIROUTE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text":"A single soft bell chime","duration_seconds":1,"model_id":"eleven_text_to_sound_v2"}' \ --output effect.mp3 # Czas trwania muzyki jest wyrażony w milisekundach: od 3000 do 600000. curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music?output_format=mp3_44100_128" \ -H "Authorization: Bearer $OMNIROUTE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt":"Gentle instrumental piano","music_length_ms":10000,"force_instrumental":true,"model_id":"music_v1"}' \ --output music.mp3 ``` Użyj `/v1/music/stream` z tą samą treścią JSON, aby przesyłać dźwięk przyrostowo. Kompozycja akceptuje dokładnie jedno z pól `prompt` lub `composition_plan`; `/v1/music/plan` wymaga pola `prompt` i opcjonalnie akceptuje `source_composition_plan`. Natywne schematy zachowują dodatkowe pola dostawcy, dzięki czemu wersje planów kompozycji i opcje dostrajania docierają do ElevenLabs. Ujednolicony punkt końcowy `/v1/music/generations` również akceptuje `elevenlabs/music_v1`, `elevenlabs/music_v2` oraz `elevenlabs/music_v2_5`. Przy aktywnym połączeniu z ElevenLabs modele te są udostępniane przez katalog muzyki. Ten punkt końcowy zwraca `{"created":...,"data":[{"b64_json":"...","format":"mp3"}]}`. Jego pole `duration` jest wyrażone w sekundach i mapowane na `music_length_ms`; jawnie określone `music_length_ms` ma pierwszeństwo. Pole `instrumental` jest mapowane na `force_instrumental`, przy czym natywne pole ma pierwszeństwo. Używaj natywnych punktów końcowych przesyłania strumieniowego do strumieniowania, a natywnego punktu końcowego kompozycji do żądań opartych wyłącznie na planie kompozycji. ```bash curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music/generations" \ -H "Authorization: Bearer $OMNIROUTE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"elevenlabs/music_v1","prompt":"Gentle instrumental piano","duration":10,"instrumental":true}' ``` Ograniczenia dotyczące punktu końcowego, modelu, budżetu i połączenia są stosowane przed wywołaniem usługi nadrzędnej. Natywne trasy zwracają kody stanu i treści błędów usługi nadrzędnej bez zmian, w tym `402` w przypadku ograniczenia planu oraz `429` w przypadku limitu przydziału. Nagłówki `character-cost`, `song-id`, `request-id` oraz `retry-after` są zachowywane, jeśli występują. Bezpłatne saldo kredytów nie gwarantuje dostępu do każdego modelu muzycznego, formatu wyjściowego ani funkcji API: ElevenLabs określa uprawnienia dla każdego żądania. Ujednolicony punkt końcowy zachowuje kody stanu błędów w znormalizowanej strukturze błędów OmniRoute. Kontrakty usługi nadrzędnej: [efekty dźwiękowe](https://elevenlabs.io/docs/api-reference/text-to-sound-effects/convert), [komponowanie muzyki](https://elevenlabs.io/docs/api-reference/music/compose) oraz [szczegóły strumieniowania muzyki](https://elevenlabs.io/docs/api-reference/music/compose-detailed-stream). --- ## 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/inpainting) | | 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` | Reranking 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/models/query` | Filtrowana lista modeli | | 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` | Alias OpenAI z tokenem | | POST | `/api/v1/vscode/{token}/responses` | Alias OpenAI Responses z tokenem | | POST | `/api/v1/vscode/{token}/api/chat` | Alias Ollama z tokenem | | GET | `/api/v1/vscode/{token}/api/tags` | Alias tagów Ollama z tokenem | Wszystkie trasy POST mają tę samą postać: `Bearer your-api-key` + treść JSON zwalidowana 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órzy nie mogą dołączyć nagłówka `Authorization: Bearer ...`, OmniRoute akceptuje również klucze API w adresie URL — za pośrednictwem zgodnych parametrów zapytania (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) lub dedykowanych punktów końcowych `/api/v1/vscode/{token}/...` opisanych poniżej. ```bash # Reranking (dostawca z rejestru chmurowego lub węzeł dostawcy zgodnego z OpenAI jako "/") 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" } # TTS Soniox wymaga języka i głosu: wartość domyślna `language` to "en"; brakujący # głos lub nazwa standardowego głosu OpenAI (alloy, nova, …) są zastępowane przez "Adrian" POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" } # 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": "kie/suno-v4.0", "prompt": "..." } ``` > **Węzły dostawców rerankingu:** `POST /v1/rerank` kieruje również żądania do węzłów dostawców zgodnych z OpenAI > (oMLX, vLLM, Infinity, TEI za bramą, …), adresowanych jako `/`. Węzły > pętli zwrotnej (`localhost`, `127.0.0.1`, `172.16.0.0/12`) są zawsze dozwolone, podobnie jak nazwy hostów > określone przez operatora w `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` (np. nazwa usługi Docker/Compose, > taka jak `http://reranker:8080/v1`; połączenia z nimi są nawiązywane bezpośrednio, nigdy przez `HTTP(S)_PROXY` ani > serwer proxy przypisany do połączenia). Węzły na każdym innym > hoście — komputerze w sieci LAN lub elemencie równorzędnym Tailscale — są dozwolone tylko wtedy, gdy operator włączy > flagę funkcji `RERANK_REMOTE_PROVIDER_NODES` **i** bazowy adres URL węzła spełnia zasady > wychodzących adresów URL dostawcy (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`). > Etap rerankingu silnika pamięci wywołuje tę trasę przez > pętlę zwrotną, więc ta sama reguła ma zastosowanie do `rerankProviderModel` w ustawieniach pamięci. > > **Formaty serwerów lokalnych:** węzeł jest wywoływany pod adresem `/v1/rerank`, a w przypadku odpowiedzi 404 — pod adresem `/rerank` > (Infinity, TEI). Treść żądania nadrzędnego zawiera zarówno nazewnictwo Cohere/OpenAI (`documents`, > `return_documents`), jak i nazewnictwo TEI (`texts`, `return_text`), a odpowiedź nadrzędna jest > normalizowana do formatu koperty Cohere: nieopakowane dane TEI `[{index, score, text}]`, `{results: [{index, score}]}` > z prostych bram oraz dane w stylu Voyage `{data: [...]}` są zwracane klientowi jako > `{results: [{index, relevance_score, document?}]}`, posortowane według wyniku i ograniczone do `top_n`. > **Wykrywanie węzłów dostawców:** modele w węźle dostawcy zgodnym z OpenAI są widoczne w `GET /v1/models` > pod prefiksem węzła. Wiersze bez metadanych punktu końcowego (typowe dla lokalnych list `/v1/models`) > dziedziczą `apiType` węzła, dzięki czemu modele węzła `embeddings` mają `type: "embedding"`, a modele > węzła `rerank` mają `type: "rerank"` zamiast domyślnego typu czatu; jawnie określone > `supportedEndpoints` w zsynchronizowanym lub ręcznie dodanym wierszu nadal mają pierwszeństwo. ### 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 zwracają `400`. --- ## Files API Punkt końcowy plików zgodny z OpenAI, przeznaczony do wejścia/wyjścia zadań wsadowych oraz przesyłania plików z określonym przeznaczeniem. | 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 Bearer — zakres plików jest określany dla poszczególnych kluczy API za pomocą `getApiKeyRequestScope`. Klucz widzi, pobiera i usuwa wyłącznie własne pliki; sesja panelu bez klucza może odczytywać dane z całej instancji; dostęp do pliku bez właściciela (przesłanego anonimowo lub w ramach sesji panelu) jest odmawiany każdemu wywołującemu spoza sesji. `GET /v1/files` odrzuca anonimowego wywołującego — oraz podany klucz, którego nie można rozpoznać — kodem `401`, nawet gdy `REQUIRE_API_KEY=false`, zamiast wyświetlać listę plików wszystkich dzierżawców (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523). --- ## Batches API Przetwarzanie wsadowe zgodne z OpenAI. | Metoda | Ścieżka | Opis | | ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/batches` | Utwórz zadanie wsadowe — treść żądania walidowana przez `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) | | GET | `/v1/batches` | Wyświetl listę zadań wsadowych | | GET | `/v1/batches/[id]` | Pobierz stan zadania wsadowego i `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 Bearer. Zakres zadań wsadowych jest określany dla poszczególnych kluczy API zgodnie z tą samą trójstronną regułą co w przypadku plików: wyłącznie własny klucz, dostęp sesji panelu do całej instancji, odmowa dostępu do rekordów bez właściciela każdemu wywołującemu spoza sesji (pobieranie, usuwanie, anulowanie oraz sprawdzanie `input_file_id` podczas tworzenia). `GET /v1/batches` odrzuca anonimowego wywołującego 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` | Uruchamia zapytanie wyszukiwania — treść jest walidowana przez `v1SearchSchema`; obsługuje pamięć podręczną i scalanie żądań | | 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 za pomocą `enforceApiKeyPolicy`. ### `provider_options` dla Exa i Tavily Exa i Tavily odczytują pola specyficzne dla dostawcy z przestrzeni nazw: `provider_options.exa` (lub `provider_options["exa-search"]`) oraz `provider_options.tavily` (lub `provider_options["tavily-search"]`). Przekazywane są wyłącznie poniższe klucze. Każdy z nich jest sprawdzany względem własnego schematu Zod w `open-sse/handlers/search/providerOptionsPassthrough.ts`, a klucz o nieprawidłowym typie jest odrzucany. Wszystkie pozostałe klucze są ignorowane, w tym dane uwierzytelniające, bazowy adres URL, `stream` i `outputSchema`. Płaskie klucze używane przez innych dostawców (`cx`, `depth`, ...) działają tak jak wcześniej. | Dostawca | Pola najwyższego poziomu | Zagnieżdżone | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Exa | `type`, `category`, `userLocation`, `moderation`, `additionalQueries`, `objective`, `systemPrompt`, `compliance` (płaskie wartości proste), `startPublishedDate`, `endPublishedDate` | `contents.{text, highlights, summary, extras, subpages, subpageTarget, livecrawlTimeout, maxAgeHours}` scalone z domyślnym `{ text: true, highlights: true }` | | Tavily | `search_depth`, `chunks_per_source`, `time_range`, `start_date`, `end_date`, `include_published_date`, `filter_by_published_date`, `include_answer`, `include_raw_content`, `include_images`, `include_image_descriptions`, `include_favicon`, `include_domains_mode`, `language`, `filter_by_language`, `auto_parameters`, `exact_match`, `include_usage`, `safe_search` | — | Pola ogólne mają zawsze pierwszeństwo: `query`, `max_results`, `filters` (domeny), `country` oraz temat wyprowadzony z `search_type`. W przypadku Exa ustawienie `search_type: "news"` zachowuje `category: "news"`. Tavily akceptuje również `search_type: "finance"` (`topic: "finance"`). Ogólne pole `time_range` jest teraz przekazywane do obu dostawców: Exa otrzymuje `startPublishedDate` (znacznik czasu ISO), a Tavily otrzymuje `start_date` (`YYYY-MM-DD`). Data jawnie określona w `provider_options` zastępuje wartość wynikającą z mapowania. Wyniki Exa zachowują `id`, `highlight_scores`, `summary`, `subpages`, `entities` oraz `extras` w `provider_raw`. Wyniki Tavily zachowują `images` i `favicon`. Rozliczanie kosztów nadal korzysta z płaskiego rejestru `costPerQuery`. Tavily nalicza więcej kredytów za wywołanie przy ustawieniu `search_depth: "advanced"`, a różnica ta nie jest uwzględniana w `usage.search_cost_usd`. --- ## Web Fetch API Wyodrębniaj zawartość z adresu URL za pomocą skonfigurowanego dostawcy pobierania stron internetowych (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract). Parallel Extract (`parallel-search`, ten sam klucz API co w Parallel Search) zwraca wyłącznie Markdown — każdy inny `format` powoduje odpowiedź `400` — i ogranicza zawartość do 100 000 znaków. Gdy nie można wyodrębnić samej strony docelowej, usługa nadrzędna zgłasza ten fakt w odpowiedzi HTTP 200; OmniRoute zwraca to jako `422` ze stałym komunikatem. | Metoda | Ścieżka | Opis | | ------ | --------------- | ------------------------------------------------------------------------ | | POST | `/v1/web/fetch` | Pobiera/ekstrahuje adres URL — treść walidowana przez `v1WebFetchSchema` | **Uwierzytelnianie:** klucz API 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` → `parallel-search`) jest przeglądana w stałej kolejności priorytetów (najpierw zapełnianie) — skonfigurowany dostawca objęty limitem żądań jest pomijany zamiast natychmiastowego przerywania żądania, a błąd usługi nadrzędnej umożliwiający ponowienie próby lub związany z limitem (zawsze HTTP 429; 402/403 dla limitów darmowych planów Firecrawl/Tavily/TinyFish — nie dla Jina Reader i nigdy dla zwykłego błędnego żądania 400) powoduje przejście do następnego, jeszcze niewypróbowanego dostawcy z dostępnymi poświadczeniami podczas obsługi żądania. Gdy wszyscy dostawcy w puli zostaną wyczerpani, punkt końcowy zwraca pojedynczą odpowiedź `429` (z nagłówkiem `Retry-After`) zamiast wcześniejszej ogólnej odpowiedzi `400`. Gdy jawnie zażądano określonego `provider`, **nie** następuje ciche przełączenie awaryjne — jawnie wskazany dostawca objęty limitem lub zwracający błąd przekazuje własny błąd (`429`, jeśli obowiązuje limit, w przeciwnym razie status usługi nadrzędnej). --- ## Strumieniowanie WebSocket ```bash GET /v1/ws?handshake=1 ``` Waliduje uzgadnianie aktualizacji połączenia do WebSocket i zwraca przykładowe komunikaty protokołu transmisji (`request`, `cancel`). Rzeczywiste ramki WS są obsługiwane przez dołączony serwer WS poza tabelą tras Next.js. **Uwierzytelnianie:** klucz API Bearer podczas uzgadniania połączenia. ### Responses API przez WebSocket (tylko codex) ```bash # Ten sam host i port co interfejs HTTP API (domyślnie 20128); zaktualizuj połączenie: wscat -c "ws://localhost:20128/v1/responses?api_key=" # (lub: -H "Authorization: Bearer ") # Pierwsza ramka MUSI być typu response.create: { "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] } ``` Serwer proxy Responses API przez WebSocket jest połączony **wyłącznie z `codex`** (zapleczem ChatGPT). Nasłuchuje na tym samym porcie co API/pulpit pod ścieżkami `/v1/responses`, `/responses` i `/api/v1/responses`. Po otrzymaniu pierwszej ramki `response.create` uwierzytelnia i przygotowuje połączenie za pomocą wewnętrznego mostu `codex-responses-ws`, wybiera połączenie OAuth codex i tworzy tunel do `wss://chatgpt.com/backend-api/codex/responses` przez transport `wreq-js`. **Modele inne niż codex są odrzucane** (`codex_ws_provider_required`). Aby korzystać z routingu współdzielonych limitów, 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 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 nieprefiksowanego identyfikatora ChatGPT (bez prefiksu `codex/`) Interfejs **Codex CLI** firmy OpenAI 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`). Prześlij **nieprefiksowany** identyfikator (np. `gpt-5.5`). Most OmniRoute obsługuje wyłącznie codex, dlatego przed utworzeniem tunelu do usługi nadrzędnej ponownie rozpoznaje nieprefiksowany identyfikator jako model codex (`resolveCodexWsModelInfo`) — mimo że nieprefiksowany `gpt-5.5` zostałby w innym przypadku przekierowany 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" # nieprefiksowany 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 przez 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 połączenie pod adresem `base_url + /responses` do WebSocket, a OmniRoute tuneluje je do wybranego połączenia OAuth codex. Działanie zweryfikowano kompleksowo z lokalnym serwerem: ChatGPT zwraca `codex.rate_limits` + `response.created` i strumieniuje wynik. --- ## Limity i zgłaszanie problemów | Metoda | Ścieżka | Opis | | ------ | ------------------- | ---------------------------------------------------------------------------------------------- | | GET | `/v1/quotas/check` | Wstępna weryfikacja limitu dla `provider` + `accountId` przed wydaniem zarejestrowanego klucza | | POST | `/v1/issues/report` | Zgłoszenie do GitHub błędu limitu/wydania klucza (wymaga `GITHUB_ISSUES_REPO` + tokenu) | **Uwierzytelnianie:** klucz API 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 zarządzającego. Jest to punkt końcowy, którego klient (CLI, panel OmniCopilot) używa do wyświetlania właścicielowi klucza jego wydatków. ```bash # Forma tekstowa (historyczny kontrakt — zwykły tekst do wyświetlenia w terminalu) 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 wyłączoną — menedżer kluczy API w panelu przełącza ją osobno dla każdego klucza). Bez niej punkt końcowy zwraca `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 niczego jeszcze nie zapisano w pamięci podręcznej: "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */} }, // migawki wszystkich połączeń, dzięki czemu interfejs może wyświetlać 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 stan inny niż odmowa, a rozróżnia je wyłącznie forma JSON. **Uwierzytelnianie:** własny klucz API Bearer wywołującego, weryfikowany za pomocą `isValidApiKey` — _nie_ jest to interfejs zarządzania (`/api/keys/…`), który pozostaje chroniony przez `requireManagementAuth`. ### Surowe wartości procentowe limitów a wartości skorygowane o próg odcięcia Podczas korzystania z `/api/usage/om-usage` wywołujący powinni zwrócić uwagę na różnicę między wartościami procentowymi przedstawianymi w **zwykłym tekście** a tymi zawartymi w ustrukturyzowanym **wyjściu JSON**: | Aspekt | Format zwykłego tekstu (`/api/usage/om-usage` / `@@om-usage`) | Format JSON (`?format=json`) | | :---------------------- | :------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | | **Pole wyjściowe** | `NN% left` (np. `20% left`) | `provider.quotas` / `providers[].quotas` | | **Pomiar** | **Dostępny limit skorygowany o próg odcięcia**: pozostała pojemność powyżej progu odcięcia | **Surowy limit zewnętrzny**: nieskorygowany pomiar dostawcy | | **Skalowanie odcięcia** | Skalowane za pomocą `effectiveRemainingPercent()`, aby chroniona rezerwa była wyświetlana jako `0% left` | Brak (surowe wartości migawki zgłoszone przez dostawcę) | | **Dane progowe** | Uwzględnione w wyświetlanej wartości procentowej | Przechowywane w `quotaWindowThresholds` dla każdego połączenia (lub wartości domyślne serwera) | | **Główny odbiorca** | Interaktywne klienty CLI, komunikaty terminala, operatorzy | Integracje programistyczne, panele, analityka, narzędzia do śledzenia rozliczeń | #### Wzór korekty o próg odcięcia OmniRoute obsługuje proaktywne progi odcięcia limitu, aby zapobiec wyczerpaniu zasobów zewnętrznych (konfigurowane za pomocą `quotaWindowThresholds` połączenia, wartości domyślnych dostawcy lub globalnych ustawień odporności). Gdy próg odcięcia (np. `cutoff = 25%`) jest aktywny dla okna limitu, mechanizm renderowania tekstu oblicza pozostały limit następująco: - Jeśli `remaining <= cutoff`: zwraca `0%`. - Jeśli `remaining > cutoff`: zwraca `((remaining - cutoff) / (100 - cutoff)) * 100`. Sformatowane wyjście tekstowe zaokrągla tę wartość do najbliższej liczby całkowitej (`Math.round(...)`). #### Przykład poglądowy Rozważmy okno dostawcy z **60% surowego użycia** (a więc **40% pozostałego surowego limitu**) i skonfigurowanym progiem odcięcia wynoszącym **25% pozostałego limitu**: | Reprezentacja | Obliczenie | Pozostało | Wynikowe użycie | | :------------------------------- | :------------------------------------------------- | :-------: | :-----------------------------------------: | | **Surowy JSON (`?format=json`)** | Migawka zewnętrzna (`quotas[window]`) | **40%** | **60%** | | **Format tekstowy (`NN% left`)** | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **20%** | **80%** (przy obliczeniu `100 - remaining`) | - **Dlaczego tekst pokazuje 20% pozostałego limitu:** Spośród 40% fizycznego limitu pozostałego na koncie 25% jest zarezerwowane przez zasady odcięcia. Wywołującemu pozostaje tylko 15% z 75% dostępnego zapasu, zanim router przestanie kierować ruch do tego połączenia. Skalowanie zapewnia, że połączenie sygnalizuje wyczerpanie (`0% left`) dokładnie wtedy, gdy kierowanie ruchu zostanie zatrzymane. - **Dlaczego JSON zachowuje surowe wartości:** Ładunek JSON zwraca dokładną migawkę dostawcy (`UsageSnapshot`), dzięki czemu zewnętrzne narzędzia mają dostęp do rzeczywistego wykorzystania zasobów zewnętrznych oraz `quotaWindowThresholds` na poziomie połączenia bez stratnego skalowania po stronie serwera. #### Wskazówki dotyczące migracji klientów Jeśli zewnętrzna integracja (taka jak wtyczka edytora lub rozszerzenie agenta) wcześniej pozyskiwała dane z tekstowego punktu końcowego (`NN% left`) i obliczała wykorzystany procent jako `100 - NN`, migracja do `?format=json` oznacza, że: - Odczyt surowych wartości JSON będzie odzwierciedlać **rzeczywiste wykorzystanie po stronie źródła** (60% wykorzystania w powyższym przykładzie). - Jeśli integracja chce zachować semantykę dostępnego limitu z tekstowego punktu końcowego, może obliczać efektywną wartość pozostałego limitu po stronie klienta, używając `quotaWindowThresholds` do nadpisywania ustawień na poziomie połączenia. --- ## Pamięć podręczna semantyczna ```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 semantyczną pamięć podręczną powoduje zwrócenie odpowiedzi z pamięci podręcznej **bez wywołania usługi nadrzędnej**, dlatego raportowane opóźnienie `X-OmniRoute-Response-Latency` jest bliskie 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łkowicie pomija wyszukiwanie w pamięci podręcznej; zawsze wywołuje usługę nadrzędną | Ustaw podczas tworzenia klucza (`POST /api/keys`) lub jego 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** akceptują autoryzacji za pomocą zwykłych kluczy API do wnioskowania. Rodziny poświadczeń, zakresy i przykłady użycia 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/POST | Status logowania (GET, publiczny). POST ustawia hasło / przełącza wymaganie logowania: tylko dla operatora, gdy hasło już istnieje (sesja panelu, lokalny interfejs CLI lub wyłączone logowanie — klucze API i tokeny `oma_` otrzymują `403`); sesja panelu wysyła `currentPassword`, aby zastąpić hasło | ### Zarządzanie dostawcami | Endpoint | 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 | Walidacja konfiguracji dostawcy | | `/api/providers/bulk` | POST | Zbiorcze dodawanie kluczy API dla JEDNEGO dostawcy | | `/api/providers/import` | POST | Importowanie niejednorodnej 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/PUT/PATCH/DELETE | Modele niestandardowe i nadpisania dla poszczególnych modeli (dodawanie, aktualizowanie, ukrywanie/pokazywanie, usuwanie) | | `/api/provider-models/validate-and-add` | POST | Uwierzytelniana na poziomie zarządzania, opcjonalna ścisła walidacja połączenia i atomowa rejestracja modelu niestandardowego; zobacz [Walidacja modeli](../guides/MODEL-VALIDATION.md) | W przypadku modeli zsynchronizowanych/zaimportowanych żądanie `PUT /api/provider-models` przyjmuje pola `provider`, `modelId` i `maxOutputTokenOverride`: dodatnia liczba całkowita ustawia ręczny limit tokenów wyjściowych, a wartość `null` usuwa go, przywracając wartość domyślną. Żądanie `GET /api/provider-models?provider=` zwraca te wartości w polu `modelOutputOverrides`, w tym również dla modeli bez rekordu modelu niestandardowego. Nadpisanie wykorzystuje funkcję środowiska uruchomieniowego `max_output_tokens` i jest zachowywane po ponownej synchronizacji modelu. Strona dostawcy zgodnego z OpenAI udostępnia te same elementy sterujące do edycji/usuwania i oznacza modele z jawną obsługą obrazu. Niestandardowe węzły Chat Completions dostosowują jawne wyłączenie rozumowania do nadrzędnego backendu. Pomyślny test połączenia automatycznie wybiera elementy sterujące szablonem czatu dla każdego dokładnego identyfikatora modelu, którego wpis `/models` potwierdza rozpoznawaną wartość `owned_by`: `vllm`, `sglang` lub `llamacpp`. Przezroczyste otoki zgodne z OpenAI mogą zachowywać oryginalny wpis modelu wewnątrz zagnieżdżonego obiektu `openai`; wykrywanie obejmuje maksymalnie trzy takie otoki. Modele z brakującymi, nieznanymi lub sprzecznymi informacjami o właścicielu zachowują standardowe działanie OpenAI. Wykrywanie ponownie wykorzystuje istniejące żądanie katalogu, nie generuje tokenów uzupełnienia i jest unieważniane po zmianie endpointu połączenia. Aby przypisać to zachowanie do backendu, który nie udostępnia tych metadanych, użyj istniejącego interfejsu API częściowej aktualizacji dostawcy: ```json { "providerSpecificData": { "reasoningControl": "chat-template" } } ``` Wyślij tę treść w żądaniu `PUT /api/providers/`. W tym połączeniu jawny poziom rozumowania `none` jest wysyłany jako `chat_template_kwargs.thinking=false` oraz `chat_template_kwargs.enable_thinking=false`. Jawne natywne wartości szablonu pozostają nadrzędne, chyba że reguła rozumowania po stronie serwera wymusza określony poziom. Ustawienie ma zastosowanie tylko wtedy, gdy niestandardowe połączenie zgodne z OpenAI wysyła treść żądania Chat Completions; żądania Responses i standardowi dostawcy zachowują swój natywny format żądania. Ustaw `reasoningControl` na `openai`, aby wymusić standardowe przekazywanie `reasoning_effort` OpenAI, albo pomiń to pole/ustaw je na `null`, aby użyć automatycznego wykrywania. Żądania klasyfikatora trybu automatycznego Claude Code domyślnie wyłączają natywne rozumowanie, jeśli nie zawierają jawnych elementów sterujących rozumowaniem. Wykrywanie wykorzystuje znacznik systemowy klasyfikatora w żądaniach w formacie Claude, a nie nazwy modeli ani limity uzupełnienia. Jawne elementy sterujące w treści, obsługiwane nagłówki poziomu rozumowania, reguły routingu i ustalony poziom rozumowania modelu zachowują swój dotychczasowy priorytet. Oba etapy klasyfikatora zachowują swoje prompty, limity uzupełnienia, sekwencje zatrzymania oraz rzeczywiste decyzje dotyczące uprawnień z systemu nadrzędnego; drugi etap nadal może generować żądane widoczne rozumowanie jako zwykły tekst. ### Przepływy OAuth | Endpoint | Metoda | Opis | | -------------------------------- | ------ | ------------------------------ | | `/api/oauth/[provider]/[action]` | Różne | OAuth specyficzny dla dostawcy | ### Routing i konfiguracja | Endpoint | 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 | Endpoint | 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 rozmiaru zapisów p50/p90/p99, koncentracja dużych zapisów, podział według modeli oraz werdykt `healthy`/`degraded`/`thrash`/`no-data`; parametry zapytania: `range` (`1h`\|`24h`\|`7d`\|`30d`, domyślnie `24h`) oraz opcjonalnie `model` (#8827) | ### Uprawnienia kluczy API `PATCH /api/keys/{id}` aktualizuje uprawnienia istniejącego klucza. Podobnie jak każda trasa `/api/keys*`, wymaga autoryzacji do zarządzania (zobacz [Uwierzytelnianie zarządzania](../guides/MANAGEMENT-AUTH.md)), a nie klucza inferencyjnego. Wysyłaj tylko pola, które chcesz zmienić; żądanie bez żadnego z nich zostanie odrzucone z komunikatem `No valid fields to update`. Akceptowane pola są zdefiniowane przez `updateKeyPermissionsSchema` w pliku `src/shared/validation/schemas/keys.ts`. | Pole | Typ | Uwagi | | ------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | ciąg znaków, 1–200 znaków | | | `isActive` | wartość logiczna | | | `isBanned` | wartość logiczna | | | `expiresAt` | data i czas w formacie ISO 8601 lub `null` | `null` usuwa termin wygaśnięcia | | `modelAccessMode` | `all` \| `restricted` | `allowedModels` musi być puste, gdy tryb to `all` | | `allowedModels`, `blockedModels` | tablica ciągów znaków, maksymalnie 1000 | | | `allowedCombos` | tablica ciągów znaków, maksymalnie 500 | Określa, które kombinacje klucz może wywoływać; modele bezpośrednie podlegają ustawieniom `modelAccessMode` / `allowedModels` | | `connectionAccessMode` | `all` \| `restricted` | `allowedConnections` nie może być puste przy `restricted` i musi być puste przy `all` | | `allowedConnections` | tablica UUID, maksymalnie 100 | | | `allowAutoCombos` | wartość logiczna | `false` odrzuca żądania dotyczące modeli `auto/*` wysyłane z tym kluczem; klucze, w których nigdy jej nie ustawiono, są dozwolone | | `catalogScope` | `all` \| `combos` \| `models` | Określa, co `GET /v1/models` wyświetla dla tego klucza (tylko kombinacje, tylko modele lub oba); nie zmienia tego, co klucz może wywoływać | | `forcedModel` | ciąg znaków o długości do 300 znaków lub `null` | Kieruje żądania czatu do tego modelu lub tej kombinacji, z pierwszeństwem przed `X-Route-Model` i `body.model`; ograniczenia klucza nadal obowiązują | | `noLog`, `autoResolve` | wartość logiczna | | | `throttleDelayMs` | liczba całkowita, 0–300000 | | | `maxSessions` | liczba całkowita, 0–10000 | | | `rateLimits` | tablica `{ limit, window }` (dodatnie liczby całkowite, maksymalnie 50) lub `null` | `null` usuwa limity | | `accessSchedule` | obiekt harmonogramu lub `null` | `null` usuwa harmonogram | | `scopes` | tablica ciągów znaków, maksymalnie 32 | | | `allowedEndpoints` | tablica ciągów znaków, maksymalnie 20 | | | `streamDefaultMode` | `legacy` \| `json` | | | `cacheDefaultMode` | `legacy` \| `bypass` | Zobacz [Pomijanie pamięci podręcznej dla poszczególnych kluczy](#per-key-cache-bypass) | | `compressionEnabled` | wartość logiczna | | | `codexServiceMode` | jeden z trybów usługi Codex | | | `disableNonPublicModels` | boolean | | | `allowUsageCommand` | boolean | | | `usageLimitEnabled` | boolean | | | `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | number >= 0 lub `null` | | | `chaosModeEnabled` | boolean | | ```bash curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "allowAutoCombos": false, "catalogScope": "combos" }' ``` ### Ustawienia | Punkt końcowy | Metoda | Opis | | ------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/settings` | GET/PUT/PATCH | Ustawienia ogólne. Klucze zasad bezpieczeństwa (`requireLogin`, `newPassword`, `oidc*`, `corsOrigins`, `bruteForceProtection`) wymagają `currentPassword` i poświadczenia operatora — klucze API i tokeny `oma_` otrzymują odpowiedź `403`; każda modyfikacja wymaga zakresu `admin` tokenu dostępu | | `/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 | Czyszczenie wierszy dziennika żądań i lokalnych artefaktów dziennika wywołań | ### Kontekst i kompresja | Punkt końcowy | 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 niestandardowe filtry i przechowywanie nieprzetworzonych 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 tekstowych danych wejściowych | | `/api/context/rtk/raw-output/[id]` | GET | Odczyt zachowanych, zanonimizowanych nieprzetworzonych danych wyjściowych na podstawie identyfikatora wskaźnika | | `/api/context/combos` | GET/POST | Wyświetlanie listy/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 | Punkt końcowy | Metoda | Opis | | ------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/sessions` | GET | Śledzenie aktywnych sesji | | `/api/rate-limits` | GET | Limity szybkości dla poszczególnych kont | | `/api/monitoring/health` | GET | Kontrola kondycji 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 `test_status` SQLite, 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 wartoś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ądzania) | | `/api/modality-bridge/video/runtime` | GET | Ścisła kontrola zaufanego interfejsu pętli zwrotnej przed uwierzytelnianiem zarządzania/sondowaniem; oczyszczone informacje o dostępności i wersjach FFmpeg/ffprobe (bez przechowywania) | | `/api/modality-bridge/video/extract` | POST | Wewnętrzny, uwierzytelniony broker danych binarnych dla zaufanego interfejsu pętli zwrotnej; dane wejściowe do 50 MiB, ograniczona kolejka/dane wyjściowe do 32 MiB, `503` w przypadku wyczerpania przepustowości, `499` przy rozłączeniu, `504` po przekroczeniu terminu; nie jest to publiczne API przesyłania plików | ### Kopie zapasowe 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 określonej kopii zapasowej | | `/api/db-backups` | PATCH | Zapisanie ustawień przechowywania kopii zapasowych (tylko dla operatora) | | `/api/db-backups` | DELETE | Usunięcie przechowywanych kopii zgodnie z ustawieniami przechowywania (tylko dla operatora) | | `/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 (`?dryRun=true` tylko przeprowadza walidację) | | `/api/db-backups/exportAll` | GET | Pobranie pełnej kopii zapasowej jako archiwum .tar.gz | `/api/db-backups/export`, `/api/db-backups/exportAll` oraz `/api/settings/export-json` udostępniają wszystkie zapisane dane uwierzytelniające, dlatego wymagają sesji panelu, lokalnego CLI (lub wyłączonego logowania). Klucze API o dowolnym zakresie oraz tokeny dostępu `oma_` otrzymują `403`. Przywracanie podlega temu samemu ograniczeniu: `POST /api/db-backups/import` (w tym `dryRun=true`), `POST /api/db-backups` (przywracanie według identyfikatora) oraz `POST /api/settings/import-json` zastępują aktywną bazę danych lub ustawienia, dlatego maszynowe dane uwierzytelniające również otrzymują tam `403`; `omniroute sync import` wysyła dane uwierzytelniające lokalnego CLI. To samo dotyczy `DELETE /api/db-backups` (usuwanie przechowywanych kopii zapasowych) oraz `PATCH /api/db-backups` (ustawienia przechowywania: zapisane wartości sterują automatycznym usuwaniem po każdej kopii zapasowej). Wyświetlanie listy (`GET`) i tworzenie ręcznej kopii zapasowej (`PUT`) nadal wymagają standardowego uwierzytelniania administracyjnego. ### 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 tunelu ngrok na potrzeby panelu | | `/api/tunnels/ngrok` | POST | Włączenie lub wyłączenie tunelu ngrok (`action=enable/disable`) | ### Narzędzia CLI | Endpoint | Metoda | Opis | | ---------------------------------- | ------ | ------------------------------------ | | `/api/cli-tools/claude-settings` | GET | Stan CLI Claude | | `/api/cli-tools/codex-settings` | GET | Stan CLI Codex | | `/api/cli-tools/droid-settings` | GET | Stan CLI Droid | | `/api/cli-tools/openclaw-settings` | GET | Stan CLI OpenClaw | | `/api/cli-tools/runtime/[toolId]` | GET | Ogólne środowisko uruchomieniowe 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 | Punkt końcowy | Metoda | Opis | | --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/api/resilience` | GET/PATCH | Pobieranie/aktualizowanie ustawień kolejki żądań, okresu wyciszenia połączenia, bezpiecznika dostawcy i oczekiwania | | `/api/resilience/reset` | POST | Resetowanie bezpieczników obwodu dostawców | | `/api/resilience/model-cooldowns` | GET | Wyświetlanie aktywnych blokad dla poszczególnych kombinacji (dostawca, połączenie, model), posortowanych według pozostałego czasu | | `/api/resilience/model-cooldowns` | DELETE | Usuwanie blokady modelu — treść żądania `{provider, model}` lub `{all: true}`, aby usunąć wszystkie blokady | | `/api/rate-limits` | GET/POST | Stan limitu szybkości dla poszczególnych kont (GET) lub przełączanie ochrony przed przekroczeniem limitu szybkości dla połączenia (POST `{connectionId, enabled}`). Obsługiwana ścieżka zapisu dla `rateLimitProtection` (nigdy nie jest modyfikowana za pomocą `PUT /api/providers/[id]`). Uwaga: `enabled: false` wyłącza jawną ochronę, ale nie wyłącza aktywnego połączenia z kluczem API z globalnego mechanizmu automatycznego włączania zabezpieczeń (`autoEnableApiKeyProviders`). | | `/api/rate-limit` | GET | Globalna konfiguracja limitu szybkości (przestarzała; alias dla `/api/rate-limits`) | > Wszystkie cztery trasy `/api/resilience/*` wymagają **uwierzytelniania zarządzania** (`requireManagementAuth`). Pełne omówienie różnic między bezpiecznikiem dostawcy, okresem wyciszenia połączenia a blokadą modelu znajduje się w sekcji [Odporność (rozszerzona)](#resilience-extended). ### Ewaluacje | Punkt końcowy | Metoda | Opis | | ------------- | -------- | ------------------------------------------------------------ | | `/api/evals` | GET/POST | Wyświetlanie zestawów ewaluacyjnych / uruchamianie ewaluacji | ### Zasady | Punkt końcowy | Metoda | Opis | | --------------- | --------------- | ----------------------------- | | `/api/policies` | GET/POST/DELETE | Zarządzanie zasadami routingu | ### Zgodność | Punkt końcowy | Metoda | Opis | | --------------------------- | ------ | --------------------------------------------- | | `/api/compliance/audit-log` | GET | Dziennik audytu zgodności (ostatnie N wpisów) | ### v1beta (zgodność z Gemini) | Punkt końcowy | Metoda | Opis | | -------------------------- | ------ | -------------------------------------- | | `/v1beta/models` | GET | Wyświetlanie modeli w formacie Gemini | | `/v1beta/models/{...path}` | POST | Punkt końcowy Gemini `generateContent` | Te punkty końcowe odwzorowują format API Gemini dla klientów wymagających natywnej zgodności z zestawem SDK Gemini. ### Wewnętrzne/systemowe interfejsy API | Punkt końcowy | Metoda | Opis | | ------------------------ | ------ | -------------------------------------------------------------------------------- | | `/api/init` | GET | Sprawdzanie inicjalizacji aplikacji (używane przy pierwszym uruchomieniu) | | `/api/tags` | GET | Tagi modeli zgodne z Ollama (dla klientów Ollama) | | `/api/restart` | POST | Wyzwalanie łagodnego ponownego uruchomienia serwera | | `/api/shutdown` | POST | Wyzwalanie łagodnego wyłączenia serwera | | `/api/system/env/repair` | POST | Naprawianie zmiennych środowiskowych dostawcy OAuth | | `/api/system/version` | GET | Bieżąca/najnowsza wersja, stan aktualizacji i kanał wydania | | `/api/system/version` | POST | Rozpoczynanie aktualizacji uwzględniającej sposób wdrożenia do najnowszej wersji | > **Uwaga:** Te punkty końcowe są używane wewnętrznie przez system lub w celu zapewnienia zgodności z klientami Ollama. Zwykle 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" } ``` ### Wersja i kanał wydań ```bash GET /api/system/version ``` Trasa zarządzania dostępna wyłącznie przez interfejs pętli zwrotnej (uwierzytelnianie administratora). Zwraca uruchomioną wersję, najnowszą opublikowaną wersję oraz stan automatycznych aktualizacji. `releaseChannel` i `channels` to pola dodane (gałąź 3.8.54); `channel` zachowuje swoje znaczenie — jest to tryb wdrożenia używany przez mechanizm aktualizacji panelu (`npm`, `source` lub `docker-compose`). ```json { "current": "3.8.52", "latest": "3.8.52", "updateAvailable": false, "channel": "npm", "autoUpdateSupported": true, "autoUpdateError": null, "news": null, "releaseChannel": "latest", "channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" } } ``` - `releaseChannel` — kanał npm uruchomionej kompilacji: `nightly` dla wersji `-nightly.*`, `next` dla innych wersji przedpremierowych (`-rc.*`, `-beta.*`, `-alpha.*`), `lts` dla stabilnej wersji starszej głównej linii wydań niż `channels.latest`, a w pozostałych przypadkach `latest`. Obowiązują te same reguły co w `scripts/release/dist-tag.mjs`, który wybiera znacznik dystrybucji npm podczas publikowania. - `channels` — najnowsza opublikowana wersja dla każdego znacznika dystrybucji, pobierana przez `npm view omniroute dist-tags` (zapasowo przez HTTP rejestru), buforowana z takim samym 10-minutowym czasem TTL jak `latest`. Pole `latest` jest zawsze obecne (wartością zapasową jest pole `latest`, a następnie `"unavailable"`); `next`, `nightly` i `lts` pojawiają się tylko wtedy, gdy odpowiedni znacznik dystrybucji istnieje. Żądanie z nagłówkiem `Cache-Control: no-cache` odświeża oba wyszukiwania. Model kanałów (`latest` = v3 do wydania 4.0 GA, `next` = rc, `nightly` = kompilacje z gałęzi `develop`, `lts` = poprawki v3 po wydaniu 4.0 GA) opisano w `docs/ops/RELEASE_STRATEGY.md`. --- ## 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 używające samego `deepgram/nova-3` **nie** korzysta z OpenRouter. **Obsługiwane formaty:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- ## Zgodność z Ollama Dla klientów używających 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 VS Code / aliasy bez nagłówków Użyj tych aliasów, gdy integracja nie może wstrzyknąć 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 ponownie wykorzystują te same procedury obsługi co `/v1/*` i `/api/tags`; struktury odpowiedzi pozostają identyczne. - Preferuj `Authorization: Bearer ...`, gdy klient obsługuje niestandardowe nagłówki. - Tokeny umieszczone w adresach URL mogą pojawiać się w dziennikach odwrotnego serwera proxy, historii przeglądarki i telemetrii poza OmniRoute. Traktuj je jako opcję zgodności, a nie 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`). Starsza struktura `{keyId, limit, period}` zwraca `400 Bad Request`. ## Limity tokenów Budżety **tokenów** dla poszczególnych kluczy API (odrębne od powyższego budżetu opartego na USD). Są egzekwowane bezpośrednio na ścieżce żądania: gdy wykorzystanie klucza w bieżącym oknie 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 wykorzystaniem 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`): wymagane są `apiKeyId` oraz `scopeType` (`model` | `provider` | `global`). Pole `scopeValue` jest wymagane, chyba że `scopeType` ma wartość `global` (np. identyfikator modelu dla zakresu `model` lub identyfikator dostawcy dla zakresu `provider`). Pole `tokenLimit` musi być dodatnią liczbą całkowitą (wartość tekstowa jest konwertowana). Opcjonalne: `id` (pomiń, aby utworzyć; podaj, aby zaktualizować), `resetInterval` (`daily` | `weekly` | `monthly`, domyślnie `monthly`), `resetTime` (`HH:MM`), `enabled` (domyślnie `true`). Odpowiedzi `GET` rozszerzają każdy limit o pola `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` oraz `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 rozpoznany (bezpośrednia para dostawca/model albo alias/kombinacja) 4. Dane uwierzytelniające są wybierane z lokalnej bazy danych z uwzględnieniem dostępności kont 5. Dla czatu: `handleChatCore` sprawdza pamięć podręczną semantyczną/podpisów i ustala ustawienia kompresji kombinacji 6. Jeśli kompresja proaktywna jest włączona, zostaje wykonana przed translacją do formatu dostawcy (`lite`, Caveman, RTK lub wariant warstwowy) 7. Moduł wykonawczy dostawcy wysyła żądanie do usługi nadrzędnej 8. Odpowiedź zostaje przetłumaczona z powrotem na format klienta (czat) lub zwrócona bez zmian (osadzenia/obrazy/audio) 9. Rejestrowane są użycie, analityka 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 (opisane już w skrócie w sekcji `/api/combos*`) mogą być również mapowane 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]` | Aktualizacja 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 (ukończenie żądania, wyczerpanie limitu, rotacja kluczy itp.). | Metoda | Ścieżka | Opis | | ------ | ------------------------- | ---------------------------------------------------------------------- | | GET | `/api/webhooks` | Wyświetla webhooki (sekrety są maskowane jako `...`) | | 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 testowe dane do adresu URL webhooka i zwraca stan dostarczenia | **Uwierzytelnianie:** sesja zarządzania/klucz API (`requireManagementAuth`). --- ## Zarejestrowane klucze (automatyczne zarządzanie) Używane przez podsystem automatycznego zarządzania kluczami do wydawania i rotacji kluczy API u bazowego dostawcy lub na koncie, z dziennymi i godzinowymi limitami. | Metoda | Ścieżka | Opis | | ------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/registered-keys` | Wyświetla zarejestrowane klucze (tylko zamaskowany prefiks) | | POST | `/api/v1/registered-keys` | Wydaje nowy zarejestrowany klucz — treść: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Zwraca nieprzetworzony klucz **tylko raz**. W przypadku odmowy z powodu limitu zwraca `429`. | | GET | `/api/v1/registered-keys/[id]` | Pobiera metadane zarejestrowanego klucza (bez nieprzetworzonej wartości klucza) | | DELETE | `/api/v1/registered-keys/[id]` | Unieważnia zarejestrowany klucz | | POST | `/api/v1/registered-keys/[id]/revoke` | Jawny punkt końcowy unieważniania (ten sam skutek co DELETE) | **Uwierzytelnianie:** sesja zarządzania/klucz API (`requireManagementAuth`) — ten sam mechanizm ochrony co w `/api/keys`: sesja panelu, lokalny token CLI lub klucz API z zakresem `manage`/`admin`; klucze API przeznaczone wyłącznie do inferencji otrzymują `403`. Zobacz także `/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 listę zadań — opcjonalne `?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 stan 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 te punkty końcowe nie wymagały uwierzytelniania — zmianę niezgodną wstecznie opisuje commit `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 listę serwerów 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 listę przypisań — można filtrować 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` | Agreguje stan serwerów proxy (liczba sukcesów/niepowodzeń, opóźnienie) w określonym przedziale czasu | **Uwierzytelnianie:** sesja zarządzania/klucz API są wymagane dla każdej trasy (`requireManagementAuth`). > Punkty końcowe `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 awarii tymczasowych; 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 karencji połączenia | `rateLimitedUntil` w połączeniach dostawców | `/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 | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` | `PATCH /api/resilience` przyjmuje nadpisania wyłącznika dostawcy w ramach `providerBreaker.oauth` i `providerBreaker.apikey`. Każdy profil obsługuje `degradationThreshold`, `failureThreshold` i `resetTimeoutMs`; te same pola są dostępne w Panelu → 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"}' # Wyczyść 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łącznika: zobacz [`CLAUDE.md`](../../CLAUDE.md) → „Stan środowiska wykonawczego odporności” oraz [`docs/architecture/RESILIENCE_GUIDE.md`](../architecture/RESILIENCE_GUIDE.md). ### Kolejka limitów szybkości i mechanizm zabezpieczający automatycznego włączania - **Obsługiwana ścieżka zapisu**: `POST /api/rate-limits` z treścią `{"connectionId": "", "enabled": true|false}` jest obsługiwanym punktem końcowym zarządzania służącym do przełączania ochrony przed limitami szybkości dla połączenia. `PUT /api/providers/[id]` celowo nie modyfikuje ani nie przełącza `rateLimitProtection` (#11278). - **Semantyka `enabled: false`**: Ustawienie `enabled: false` usuwa jawną ochronę połączenia, ale **nie** wyłącza aktywnego połączenia z kluczem API z globalnego mechanizmu zabezpieczającego automatycznego włączania (`autoEnableApiKeyProviders = true`). W `reconcileEnabledConnections` (`open-sse/services/rateLimitManager.ts`) wartości `false` i `undefined` są równoważne; aktywne połączenia z kluczem API bez jawnej ochrony pozostają chronione przez mechanizm zabezpieczający automatycznego włączania. - **Wyłączenie globalne**: Aby uruchamiać połączenia z kluczem API bez kolejek limitów szybkości, wyłącz globalnie mechanizm zabezpieczający za pomocą `RATE_LIMIT_AUTO_ENABLE=false` (zmienna środowiskowa) lub `resilienceSettings.requestQueue.autoEnableApiKeyProviders = false` (Ustawienia → Odporność / `PATCH /api/resilience`). --- ## Umiejętności Struktura umiejętności służąca do rozszerzania OmniRoute o niestandardowe wykonywalne procedury obsługi oraz integracje 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 platformie handlowej akceptują uwierzytelnianie zarządzania lub klucz API Bearer (`isAuthenticated`). --- ## Pamięć Trwały magazyn pamięci konwersacyjnej/faktograficznej, z zakresem ograniczonym do klucza API / sesji. | Metoda | Ścieżka | Opis | | ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/memory` | Lista wpisów pamięci — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, z paginacją `offset/limit` lub `page/limit` | | POST | `/api/memory` | Utworzenie wpisu pamięci — treść żądania walidowana przez Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` | | GET | `/api/memory/[id]` | Pobranie pojedynczego wpisu pamięci | | DELETE | `/api/memory/[id]` | Usunięcie wpisu pamięci | | GET | `/api/memory/health` | Stan podsystemu pamięci (łączność z bazą danych, backend osadzeń, stan indeksu wektorowego) | **Uwierzytelnianie:** sesja zarządzająca/klucz API (`requireManagementAuth`). Wyliczenie `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (zobacz `MemoryType` w `src/lib/memory/types.ts`). --- ## Serwer MCP OmniRoute zawiera wbudowany serwer Model Context Protocol z 3 transportami (stdio, SSE, streamable-http) i narzędziami o określonych zakresach. 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ł kontrolny, transport, stan online, ostatnie wywołanie, najczęściej używane narzędzia, wskaźnik 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, wskaźnik 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 typu Bearer z zakresem `mcp`); trasy `status`/`tools`/`audit*` są dostępne do odczytu z panelu (nie jest wymagane dodatkowe uwierzytelnianie poza dostępem do hosta panelu). > Oba transporty HTTP są kontrolowane przez `settings.mcpEnabled` i `settings.mcpTransport` — niezgodność transportu powoduje zwrócenie `400`, a wyłączony stan MCP powoduje zwrócenie `503`. --- ## Serwer A2A OmniRoute udostępnia punkt końcowy A2A (Agent-to-Agent) zgodny z JSON-RPC 2.0 oraz nakładkę REST do inspekcji i wykorzystania 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 SSE tego samego zestawu umiejętności | | `tasks/get` | Pobranie zadania według `taskId` | | `tasks/cancel` | Anulowanie zadania 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 (nazwę, opis, możliwości, katalog umiejętności i schemat uwierzytelniania) — publicznie buforowaną 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 karty agenta z pamięci podręcznej | | GET | `/api/a2a/tasks` | Lista zadań — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` | | POST | `/api/a2a/tasks` | (Niezaimplementowane jako pomocniczy punkt końcowy REST — utwórz za pomocą JSON-RPC `message/send`) | | GET | `/api/a2a/tasks/[id]` | Pobranie pojedynczego zadania | | POST | `/api/a2a/tasks/[id]/cancel` | Anulowanie zadania | **Uwierzytelnianie:** pomocnicze punkty końcowe REST działają bez uwierzytelniania administracyjnego (panel może je odczytywać); 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` | Rozpoznaje 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 i zwraca zamaskowany klucz oraz `projectId` każdego połączenia wyłącznie dla klucza z zakresem `manage` / `admin`; pozostałe trasy `/api/cloud/*`, `/api/evals/*` i `/api/assess` wymagają sesji administracyjnej lub klucza API. Żądanie POST do `/api/assess` używa `validateBody` ze schematem zakresu będącym sumą rozłączną. --- ## 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 (plik cookie `auth_token` panelu) lub klucza API z zakresem zarządzania. Pełne informacje zawiera dokument [Framework ACP](../frameworks/ACP.md). --- ## Analityka i obserwowalność Punkty końcowe analityki w czasie rzeczywistym służące do monitorowania routingu, kompresji i różnorodności dostawców. Zasilają strony `/dashboard/analytics/*`. ### Analityka automatycznego routingu | Metoda | Ścieżka | Opis | | ------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/auto-routing` | Zagregowane statystyki automatycznego routingu: łączna liczba wywołań, rozkład strategii i poziomów, główni dostawcy | | GET | `/api/analytics/auto-routing?days=7` | Statystyki z określonego przedziału czasu (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` | Zagregowane statystyki kompresji: zaoszczędzone tokeny, procent oszczędności, rozkład trybów, użycie silnika | **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` | Odczyt bieżących limitów współbieżności (globalnych i dla poszczególnych dostawców) | | POST | `/api/admin/concurrency` | Aktualizacja limitów 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, 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, czas ostatniego wykrycia) | | GET | `/api/cli-tools/status` | Szczegóły stanu jednego narzędzia CLI (zapytanie `?tool=`) | | POST | `/api/cli-tools/apply` | Zapis wygenerowanej konfiguracji narzędzia (`dryRun` wyświetla podgląd; `422` + `containerEphemeralTarget` w przypadku konteneryzacji; `migration` wskazuje starszy plik YAML Codex) | | GET | `/api/cli-tools/backups` | Lista kopii zapasowych konfiguracji narzędzi CLI | | POST | `/api/cli-tools/backups` | Utworzenie kopii zapasowej konfiguracji wszystkich narzędzi CLI | | POST | `/api/cli-tools/backups` | Przywracanie: ten sam punkt końcowy z `{tool, backupId}` w treści przywraca wskazaną kopię zapasową | | GET | `/api/cli-tools/antigravity-mitm` | Stan serwera proxy MITM Antigravity (narzędzie CLI „antigravity-mitm”) | | POST | `/api/cli-tools/antigravity-mitm/alias` | Konfiguracja aliasów antigravity-mitm | **Uwierzytelnianie:** Wymaga sesji zarządzania. --- ## Umiejętności agentów Zarządzaj umiejętnościami agentów AI (podobnymi do niestandardowych modeli GPT OpenAI, ale przeznaczonymi dla agentów). | Metoda | Ścieżka | Opis | | ------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------- | | GET | `/api/agent-skills` | Lista wszystkich umiejętności agentów (wbudowanych i niestandardowych) | | GET | `/api/agent-skills/[id]` | Pobranie konkretnej umiejętności agenta | | POST | `/api/agent-skills` | Utworzenie niestandardowej umiejętności agenta — treść: `{name, description, prompt, model?, temperature?}` | | PUT | `/api/agent-skills/[id]` | Aktualizacja niestandardowej umiejętności agenta | | DELETE | `/api/agent-skills/[id]` | Usunięcie niestandardowej umiejętności agenta | | GET | `/api/agent-skills/[id]/raw` | Pobranie nieprzetworzonego promptu i metadanych (bez wykonywania) | | POST | `/api/agent-skills/generate` | Wygenerowanie przez AI nowej umiejętności 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` | Wyświetla wpisy w pamięci podręcznej (z paginacją) | | DELETE | `/api/cache/entries` | Usuwa wpisy z pamięci podręcznej (filtrowanie według parametrów zapytania) | | GET | `/api/cache/stats` | Szczegółowe statystyki pamięci podręcznej (dla poszczególnych dostawców i modeli) | | GET | `/api/cache/reasoning` | Stan pamięci podręcznej rozumowania (na potrzeby odtwarzania rozumowania) | | DELETE | `/api/cache/reasoning` | Czyści pamięć podręczną rozumowania — parametry zapytania: `?toolCallId=` (pojedynczy), `?provider=

` lub brak (wszystkie) | **Uwierzytelnianie:** Wymaga sesji zarządzania. --- ## System pamięci Zarządzaj pamięcią trwałą (FTS5 + osadzenia wektorowe). | Metoda | Ścieżka | Opis | | ------ | ------------------ | ------------------------------------------------------------------------------------------------- | | GET | `/api/memory` | Wyświetla wpisy pamięci (filtrowanie według zakresu, typu i zapytania wyszukiwania) | | POST | `/api/memory` | Tworzy nowy wpis pamięci — treść żądania: `{scope, type, content, metadata?}` | | GET | `/api/memory/[id]` | Pobiera określony wpis pamięci | | PUT | `/api/memory/[id]` | Aktualizuje wpis pamięci | | DELETE | `/api/memory/[id]` | Usuwa wpis pamięci | | GET | `/api/memory?q=` | Przeszukuje pamięć (FTS5 + wyszukiwanie wektorowe) — 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` | Wyświetla wszystkie subskrypcje webhooków | | POST | `/api/webhooks` | Tworzy subskrypcję webhooka — treść żądania: `{url, events[], secret?, active?}` | | GET | `/api/webhooks/[id]` | Pobiera określoną subskrypcję webhooka | | PUT | `/api/webhooks/[id]` | Aktualizuje subskrypcję webhooka | | DELETE | `/api/webhooks/[id]` | Usuwa subskrypcję webhooka | | GET | `/api/webhooks/[id]/deliveries` | Wyświetla historię dostarczeń webhooka (dziennik powodzeń i niepowodzeń) | | POST | `/api/webhooks/[id]/test` | Wysyła zdarzenie testowe do webhooka | **Uwierzytelnianie:** Wymaga sesji zarządzania. Pełną listę typów zdarzeń znajdziesz w dokumencie [Framework 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` | Wykonuje 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 zawiera dokument [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 zawiera dokument [Framework wtyczek](../frameworks/PLUGIN_SDK.md). --- ## Routing w tle Porównywanie dostawców w tle / metodą A/B **nie jest samodzielnym interfejsem REST** — konfiguruje się je za pomocą 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 danych wizyjnych). Mechanizmy ochronne są uruchamiane dla każdego żądania; rezygnacja dla pojedynczego wywołania odbywa się za pomocą nagłówka żądania `x-omniroute-disabled-guardrails` — nie ma trwałego interfejsu do ich włączania ani wyłączania. | Metoda | Ścieżka | Opis | | ------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/guardrails` | Wyświetla zarejestrowane mechanizmy ochronne i ich stan (nazwa / włączenie / priorytet) | | POST | `/api/guardrails/test` | Przeprowadza próbne uruchomienie potoku poprzedzającego wywołanie dla przykładowych danych wejściowych — treść: `{input, disabledGuardrails?}` | **Uwierzytelnianie:** Wymaga sesji zarządzania. Pełne informacje zawiera dokument [Bezpieczeństwo > Mechanizmy ochronne](../security/GUARDRAILS.md). --- --- ## Uwierzytelnianie Zobacz [Uwierzytelnianie zarządzania](../guides/MANAGEMENT-AUTH.md), aby poznać cztery rodziny poświadczeń (sesja panelu, lokalny token CLI, token dostępu `oma_live_…`, klucz API z zakresem zarządzania) oraz różnice między nimi a kluczami inferencji. - Trasy panelu (`/dashboard/*`) używają pliku cookie `auth_token` - Logowanie korzysta z zapisanego skrótu hasła; wartością rezerwową 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 tym dokumencie oznacza jedną z rodzin opisanych w tym przewodniku — nie dodatkowy, niezdefiniowany typ sekretu > **Zmiana niezgodna wstecznie (v3.8.0)** — `/api/v1/agents/tasks/*` oraz punkty końcowe zarządzania okresem oczekiwania wymagają teraz **uwierzytelniania zarządzania** (pliku cookie panelu `auth_token` lub klucza API z zakresem zarządzania). Klienci, którzy wcześniej wywoływali te trasy bez uwierzytelniania, otrzymają odpowiedź `401 Unauthorized`. Zobacz commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).