OpenRouter, jeden interfejs do setek modeli

OpenRouter, jeden interfejs do setek modeli

OpenRouter to pośrednik między Twoją aplikacją a dostawcami modeli językowych. Wystawia jeden punkt końcowy zgodny ze specyfikacją OpenAI, przez który sięgasz po modele kilkudziesięciu firm, przełącza dostawców przy awarii i rozlicza wszystko z jednego salda kredytów. W dniu sprawdzenia, 20 sierpnia 2026 roku, katalog zwracany przez publiczne API liczył 417 pozycji od 59 wydawców, a lista dostawców infrastruktury 102 wpisy.

Czym to jest i jak wygląda w kodzie

Najkrótszy opis brzmi tak: OpenRouter stoi w torze Twojego żądania, przyjmuje je w formacie, który znasz z biblioteki OpenAI, wybiera konkretnego dostawcę i przekazuje dalej. Odpowiedź wraca w tym samym formacie, wzbogacona o pola opisujące, co się wydarzyło po drodze.

Adres bazowy to https://openrouter.ai/api/v1, a najczęściej używana ścieżka to /chat/completions. Skoro kontrakt jest zgodny ze specyfikacją OpenAI, przejście istniejącego kodu na OpenRouter sprowadza się do podmiany adresu bazowego i klucza. Działa też punkt końcowy /api/v1/messages, który przyjmuje kształt żądania znany z bibliotek Anthropic, więc kod pisany pod Claude też można przekierować bez przepisywania warstwy transportu.

Poza samym API dostajesz oficjalne biblioteki klienckie. Pakiet @openrouter/sdk ma wersję 1.2.49, pakiet openrouter na PyPI wersję 1.1.69 i wymaga Pythona 3.10 lub nowszego, a @openrouter/ai-sdk-provider w wersji 3.0.0 podpina OpenRouter pod Vercel AI SDK i deklaruje Node w wersji co najmniej 22. Wszystkie trzy niosą licencję Apache 2.0, i to jest przypadek, w którym trzy niezależne źródła się zgadzają: pole license w rejestrze npm, metadane repozytorium w API GitHuba oraz plik LICENSE.md wewnątrz opublikowanej paczki mówią to samo.

Jedno rozróżnienie jest tu istotne i łatwo je przeoczyć. Otwarte są wyłącznie biblioteki klienckie. Sama usługa, czyli klasyfikator promptów, logika wyboru dostawcy i system rozliczeń, pozostaje zamknięta i działa wyłącznie na serwerach firmy. Nie ma wersji, którą postawisz u siebie, więc decyzja o wpięciu OpenRoutera jest decyzją o dołożeniu zewnętrznej zależności do ścieżki krytycznej.

# najprostsze wywołanie, z nagłówkami atrybucji aplikacji
curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "HTTP-Referer: https://moja-aplikacja.example" \
  -H "X-OpenRouter-Title: Moja aplikacja" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "models": ["openai/gpt-5.6-luna", "google/gemini-3.7-flash"],
    "messages": [{"role": "user", "content": "Podsumuj ten akapit w jednym zdaniu."}]
  }'

# katalog modeli i saldo klucza, bez żadnej biblioteki
curl -s https://openrouter.ai/api/v1/models | jq '.data | length'
curl -s https://openrouter.ai/api/v1/key -H "Authorization: Bearer $OPENROUTER_API_KEY"

Nagłówek HTTP-Referer jest wymagany, jeśli chcesz, żeby Twoja aplikacja pojawiła się w publicznych rankingach, bo to on pełni rolę identyfikatora. Nagłówek nazywa się dziś X-OpenRouter-Title, a starsze X-Title nadal działa dla zgodności wstecznej. Sam tytuł bez HTTP-Referer nie tworzy wpisu, co bywa źródłem zdziwienia u osób, które ustawiły tylko jedno z dwóch.

Cennik, czyli narzut na doładowanie, a nie na tokeny

To jest część, dla której większość osób w ogóle sięga po ten tekst, więc opiszę mechanizm dokładnie, bo działa inaczej niż w typowej usłudze pośredniczącej.

Za same tokeny płacisz stawkę dostawcy, bez narzutu. OpenRouter deklaruje to wprost w dokumentacji i powtarza w kilku miejscach: cena za milion tokenów jest ta sama, którą zapłaciłbyś, kupując bezpośrednio u źródła. Zarobek pojawia się gdzie indziej, przy zasilaniu konta.

Opłata platformy wynosi 5,5 procent wartości doładowania kredytów, z minimum 0,80 dolara, przy płatności kartą. Płatność kryptowalutą w USDC ma opłatę 5 procent. Obie liczby są zaszyte wprost w kodzie strony z najczęściej zadawanymi pytaniami, a strona z cennikiem podaje te same 5,5 procent w kolumnie planu z płatnością za zużycie.

Minimum 0,80 dolara ma konkretne konsekwencje przy małych kwotach. Dla doładowania rzędu kilkunastu dolarów procent daje mniej niż to minimum, więc realny narzut rośnie powyżej deklarowanych 5,5 procent i przy najmniejszych kwotach zbliża się do kilku procent więcej. Przy doładowaniach liczonych w setkach dolarów minimum przestaje mieć znaczenie i zostaje czysty procent. Wniosek praktyczny jest banalny, ale często pomijany: doładowania warto robić rzadziej i większe.

Kredyty są denominowane w dolarach amerykańskich. Zwrot za niewykorzystane środki można zgłosić w ciągu dwudziestu czterech godzin od transakcji, przyciskiem na stronie kredytów, przy czym opłaty platformy nie podlegają zwrotowi, a płatności kryptowalutą nie podlegają zwrotowi nigdy. Po roku od zakupu niewykorzystane kredyty mogą wygasnąć. Jeśli usuniesz konto, saldo przepada i nie da się go odzyskać po ponownej rejestracji. Rabatów za wolumen usługa oficjalnie nie oferuje.

Jest jeszcze jeden mechanizm cenowy, o którym łatwo zapomnieć przy ocenie kosztów. Włączenie opcjonalnego logowania promptów i odpowiedzi daje 1 procent zniżki na koszty zużycia. Domyślnie treść zapytań nie jest logowana, więc jest to świadomy handel prywatnością za pieniądze, a nie ustawienie, które można przestawić bezrefleksyjnie.

Osobno rozliczane jest korzystanie z własnych kluczy dostawcy. Plan z płatnością za zużycie zawiera 25 000 dolarów miesięcznie liczonych po cenniku katalogowym bez żadnej opłaty, plan korporacyjny 200 000 dolarów, a powyżej tego progu opłata wynosi 5 procent tego, ile to samo żądanie kosztowałoby normalnie w OpenRouterze, i schodzi z salda kredytów. Limit mierzy się wartością zużycia, nie liczbą żądań.

Darmowe modele i to, co naprawdę można na nich zrobić

Darmowe modele istnieją i są prawdziwe, ale ich rola jest inna, niż sugeruje słowo w nazwie.

W dniu sprawdzenia katalog zawierał 17 identyfikatorów kończących się na :free, w tym warianty rodziny Gemma od Google, kilka modeli Nemotron od NVIDII oraz openai/gpt-oss-20b. Do tego dochodzi openrouter/free, czyli router z zerową ceną, który losowo wybiera model spośród aktualnie dostępnych darmowych. Strona z cennikiem mówi o ponad dwudziestu pięciu darmowych modelach i czterech darmowych dostawcach, więc liczba w API i liczba na stronie marketingowej nie muszą się pokrywać co do jednego.

Limity są twarde i dobrze udokumentowane. Warianty darmowe mają 20 żądań na minutę niezależnie od stanu konta. Dzienny limit zależy od tego, ile kredytów kiedykolwiek kupiłeś: poniżej 10 dolarów jest to 50 żądań dziennie, od 10 dolarów wzwyż 1000 żądań dziennie. Limity są liczone globalnie dla konta, więc zakładanie dodatkowych kluczy czy kont nic nie zmienia.

Dwie rzeczy zaskakują ludzi najczęściej. Pierwsza: ujemne saldo kredytów blokuje również modele darmowe i objawia się kodem 402, więc konto z długiem przestaje działać całkowicie. Druga: skład listy darmowych modeli się zmienia, bo wpisy pojawiają się i znikają wraz z promocjami dostawców. Kod, który ma na stałe wpisany jeden identyfikator z sufiksem :free, przestanie działać w momencie, w którym ten wpis zniknie z katalogu.

Praktyczny wniosek jest taki, że darmowe warianty świetnie nadają się do prototypu, do testów integracji i do pracy warsztatowej. Do produkcji z realnym ruchem nie nadają się przez sam limit 20 żądań na minutę, niezależnie od tego, ile kredytów masz na koncie.

Routing między dostawcami

Ten sam model bywa serwowany przez wielu dostawców infrastruktury, i to jest miejsce, w którym OpenRouter robi coś więcej niż przekazywanie żądania dalej.

Domyślna strategia to równoważenie obciążenia z priorytetem ceny. Najpierw odpadają dostawcy, którzy w ciągu ostatnich trzydziestu sekund mieli poważne awarie. Spośród pozostałych wybierany jest jeden, z prawdopodobieństwem proporcjonalnym do odwrotności kwadratu ceny. Dokumentacja podaje własny przykład: przy dostawcach kosztujących 1, 2 i 3 dolary za milion tokenów szansa trafienia na pierwszego jest dziewięciokrotnie większa niż na trzeciego. Pozostali stają się fallbackami na wypadek błędu.

Zachowanie zmienia się przez obiekt provider w ciele żądania. Pola sort z wartościami price, throughput albo latency porządkują dostawców jawnie i wyłączają równoważenie obciążenia. To samo robi order, czyli lista identyfikatorów dostawców próbowanych po kolei. Skróty :nitro i :floor doklejane do identyfikatora modelu są odpowiednikami sortowania po przepustowości i po cenie.

Reszta pól służy do zawężania puli. only i ignore przyjmują listy identyfikatorów dostawców do dopuszczenia albo pominięcia. quantizations filtruje po poziomie kwantyzacji, z wartościami takimi jak int4, int8, fp8, bf16 czy fp16. max_price przyjmuje obiekt z polami prompt, completion, request i image i odrzuca dostawców droższych niż podany próg. require_parameters odrzuca dostawców, którzy nie obsługują wszystkich parametrów Twojego żądania. data_collection z wartością deny wyklucza dostawców mogących przechowywać dane, a zdr zawęża routing do punktów końcowych z zerową retencją. Są też preferred_min_throughput i preferred_max_latency, które przyjmują liczbę albo obiekt z progami percentylowymi p50, p75, p90 i p99.

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="<OPENROUTER_API_KEY>",
)

completion = client.chat.completions.create(
    model="meta-llama/llama-4-maverick",
    messages=[{"role": "user", "content": "Wypisz trzy zalety indeksu częściowego."}],
    extra_headers={
        "HTTP-Referer": "https://moja-aplikacja.example",
        "X-OpenRouter-Title": "Moja aplikacja",
    },
    extra_body={
        "models": ["mistralai/mistral-large-2512", "deepseek/deepseek-v3.2"],
        "provider": {
            "sort": "throughput",
            "require_parameters": True,
            "data_collection": "deny",
            "quantizations": ["fp8", "bf16"],
            "max_price": {"prompt": 3, "completion": 6},
            "ignore": ["some-provider-slug"],
        },
    },
)

print(completion.model)
print(completion.choices[0].message.content)

Im ciaśniej ustawisz te warunki, tym większa szansa, że żadna kombinacja ich nie spełni. Odpowiedzią jest wtedy kod 503, oznaczający brak dostawcy pasującego do wymagań. To nie jest awaria usługi, tylko skutek własnej konfiguracji, i pierwszym ruchem powinno być rozluźnienie preferencji, a nie ponawianie żądania.

Osobną warstwą są routery wybierające model za Ciebie. Identyfikator openrouter/auto przepuszcza prompt przez lekki klasyfikator przypisujący go do jednego z około trzydziestu typów zadań, takich jak code:debugging czy agent:multi_step_planning, po czym wybiera model według udziału w wydatkach społeczności z ostatnich siedmiu dni. Poziom kosztu ustawia się polem cost_tier z wartościami od low do max, przekazywanym przez wtyczkę o identyfikatorze auto-router. W katalogu modeli wpis openrouter/auto ma cenę -1, bo realna stawka zależy od tego, co router wybierze. Wygoda jest oczywista, ale cena za żądanie przestaje być przewidywalna, więc przy budżetowaniu jest to raczej pułapka niż ułatwienie.

Fallback modeli i granice tego mechanizmu

Fallback między dostawcami tego samego modelu dzieje się automatycznie. Fallback między różnymi modelami trzeba zadeklarować, i robi to pole models z listą identyfikatorów w kolejności priorytetu.

Wyzwalaczem jest praktycznie każdy błąd: przekroczenie limitu długości kontekstu, oznaczenie treści przez moderację, ograniczenie liczby żądań po stronie dostawcy oraz niedostępność. Rozliczenie idzie po modelu, który ostatecznie obsłużył żądanie, a jego identyfikator wraca w polu model w odpowiedzi. To pole jest jedynym wiarygodnym źródłem informacji o tym, co faktycznie odpowiedziało, i powinno trafiać do logów.

Granice są dwie i obie bolą dopiero na produkcji. Pierwsza: jeśli model zapasowy również zwróci błąd, dostajesz ten błąd i łańcuch się kończy. Fallback nie jest gwarancją odpowiedzi, tylko drugą próbą. Druga: na punkcie końcowym zgodnym z Anthropic obowiązuje osobne pole fallbacks, które przyjmuje wyłącznie klucz model, dopuszcza najwyżej trzy pozycje i nie może współwystępować z polem models. Złamanie któregokolwiek z tych warunków kończy się kodem 400.

Jest też problem, o którym dokumentacja mówi mniej, a który wychodzi w każdym poważnym wdrożeniu. Modele z różnych rodzin inaczej trzymają się schematów wywołań narzędzi i inaczej reagują na ten sam prompt systemowy. Lista zapasowa złożona z modeli OpenAI, Google Gemini i Mistral AI uratuje dostępność, ale może zwrócić strukturę, której Twój parser nie przyjmie. Jeśli polegasz na wywołaniach narzędzi albo na wymuszonym formacie odpowiedzi, ustaw require_parameters i sprawdź każdy model z listy osobno, zanim wpiszesz go jako zapasowy.

Osobno trzeba obsłużyć błędy pojawiające się w trakcie strumienia. Skoro status 200 został już wysłany, błąd nie może przyjść jako kod HTTP i przychodzi jako zdarzenie SSE z polem finish_reason ustawionym na error. Kod, który sprawdza tylko status odpowiedzi, uzna takie żądanie za udane i zapisze pustą treść.

Rozliczenie, kredyty i kontrola kosztów

Każda odpowiedź zawiera obiekt usage z liczbą tokenów wejściowych i wyjściowych policzoną natywnym tokenizatorem modelu, kosztem w kredytach, liczbą tokenów rozumowania oraz polami cached_tokens i cache_write_tokens opisującymi pamięć podręczną promptu. Przy strumieniu obiekt przychodzi w ostatniej wiadomości SSE. W rozbiciu kosztu pole cost to kwota pobrana z Twojego konta, a cost_details.upstream_inference_cost to kwota naliczona przez dostawcę, przy czym przy pobieraniu danych po identyfikatorze generacji to drugie pole ma sens tylko dla żądań na własnych kluczach.

Stan klucza sprawdza się żądaniem GET /api/v1/key. Odpowiedź zawiera limit, limit_reset i limit_remaining opisujące opcjonalny limit wydatków na pojedynczym kluczu, include_byok_in_limit, sumy zużycia w polach usage, usage_daily, usage_weekly i usage_monthly, ich odpowiedniki dla własnych kluczy z przedrostkiem byok_, a także is_free_tier. To wystarczy, żeby zbudować alert przed wyczerpaniem środków, zamiast dowiadywać się o nim z kodu 402.

{
  "id": "gen-abc123",
  "model": "anthropic/claude-sonnet-5",
  "provider": "anthropic",
  "usage": {
    "prompt_tokens": 1420,
    "completion_tokens": 318,
    "total_tokens": 1738,
    "cost": 0.0121,
    "cost_details": {
      "upstream_inference_cost": 0.0121
    }
  }
}

Warto znać jeszcze jedno zabezpieczenie, bo zdejmuje realny koszt przy awariach. Ubezpieczenie od pustych odpowiedzi działa domyślnie na wszystkich modelach i dostawcach: jeśli odpowiedź ma zero tokenów wyjściowych i puste pole finish_reason, albo finish_reason równe error, tokeny nie są naliczane, nawet gdy dostawca policzył OpenRouterowi przetworzenie promptu. Nie obejmuje to jednak usług dodatkowych, które zdążyły się wykonać: opłat za wyszukiwanie w sieci, za parsowanie plików i rozpoznawanie tekstu w plikach PDF oraz za pobieranie stron. One zostają na rachunku.

Twarde ograniczenie wydatków buduje się z trzech elementów: limitu na pojedynczym kluczu, budżetu przestrzeni roboczej oraz tego, że saldo kredytów jest przedpłacone. Ta ostatnia właściwość jest zaletą, o której rzadko się mówi. Konto bez środków przestaje generować koszty, zamiast produkować fakturę na koniec miesiąca.

OpenRouter a alternatywy

Cztery kryteria wystarczą, żeby ustawić te rozwiązania obok siebie: gdzie działa warstwa pośrednicząca, ile kosztuje sama w sobie, czy ma wbudowany fallback i czy możesz zajrzeć do jej kodu.

Z tej tabeli wynika prosty podział. Jeśli zależy Ci na tym, żeby nie utrzymywać żadnej infrastruktury i mieć jedno rozliczenie zamiast pięciu umów z dostawcami, płacisz za to opłatą przy doładowaniu i akceptujesz zamkniętą usługę w torze żądania. Jeśli masz zespół, który i tak utrzymuje własne usługi, LiteLLM daje tę samą funkcję bez narzutu, kosztem konfiguracji i dyżurów. Warto sprawdzić też Vercel AI Gateway, który deklaruje zerowy narzut i zerową opłatę platformy na tokeny, co przy dużym wolumenie jest różnicą liczoną wprost w procentach rachunku.

Zupełnie inna droga to rezygnacja z chmury. Jeśli obciążenie da się obsłużyć modelem otwartym, Ollama na własnym sprzęcie eliminuje zarówno opłatę, jak i przesyłanie promptów do trzeciej strony. To wybór dla wąskich, powtarzalnych zadań, nie dla aplikacji potrzebującej modelu z najwyższej półki.

Jest jeszcze droga pośrednia, tańsza od obu: pójście wprost do dostawcy, który sam ustawia się poniżej rynku. DeepSeek wystawia interfejs zgodny z OpenAI, więc zmieniasz adres bazowy i nazwę modelu, a nie bibliotekę, i schodzisz o rząd wielkości w rachunku za tokeny. Cena ma dwie strony: dostawca działa poza Unią Europejską, co przy danych osobowych trzeba rozstrzygnąć przed wdrożeniem, a nazwy modeli są aliasami wskazującymi na bieżące wydanie, więc nie da się przypiąć konkretnej wersji tak jak u innych dostawców.

Typowe błędy

Pierwszy to liczenie kosztu jak przy bezpośrednim API. Stawka za tokeny jest ta sama, ale każdy dolar, który przez tę usługę przepłynie, został kupiony z opłatą 5,5 procent. Przy porównywaniu ofert trzeba tę opłatę doliczyć do stawki dostawcy, a przy małych doładowaniach dodatkowo uwzględnić minimum 0,80 dolara, które podnosi realny procent.

Drugi to traktowanie listy models jak gwarancji dostępności. Jeśli ostatni model z listy zwróci błąd, ten błąd trafia do Twojej aplikacji. Ponawianie z wykładniczym odstępem i honorowanie nagłówka Retry-After nadal jest Twoją odpowiedzialnością.

Trzeci to ignorowanie różnic między dostawcami tego samego modelu. Ten sam identyfikator może trafić do dostawcy z inną kwantyzacją, innym maksymalnym kontekstem i inną obsługą wywołań narzędzi. Jeśli jakość odpowiedzi skacze między żądaniami bez zmiany promptu, przyczyną jest zwykle właśnie to, a lekarstwem quantizations, require_parameters albo jawne order.

Czwarty to nagłówki atrybucji. Sam X-OpenRouter-Title nie tworzy wpisu aplikacji, bo identyfikatorem jest HTTP-Referer. Osoby, które kopiują starsze przykłady, wysyłają dodatkowo X-Title, co nadal działa, ale nie zastępuje brakującego adresu.

Piąty to nieobsłużone błędy w strumieniu. Odpowiedź ze statusem 200, która kończy się zdarzeniem z finish_reason równym error, jest błędem, mimo że kod HTTP mówi co innego. Bez sprawdzania tego pola aplikacja zapisuje puste odpowiedzi i nikt tego nie zauważa przez tygodnie.

Szósty to budowanie produkcji na darmowych wariantach. Limit 20 żądań na minutę obowiązuje zawsze, a skład listy darmowych modeli zmienia się w czasie. Identyfikator z sufiksem :free wpisany na sztywno w konfiguracji jest awarią odłożoną w czasie.

Siódmy to pominięcie faktu, że dokładasz trzecią stronę do ścieżki krytycznej. Prompty przechodzą przez cudzą infrastrukturę, dochodzi jeden skok sieciowy, a awaria pośrednika wyłącza wszystkich dostawców naraz, czego żaden fallback nie naprawi. Domyślnie treść zapytań nie jest logowana, ale ustawienia polityki danych i wybór dostawców, którzy logują, zostają po Twojej stronie. Warstwa obserwowalności w rodzaju Langfuse nie zmienia tego rachunku, tylko daje wgląd w to, co się dzieje, i sama też jest kolejnym elementem do utrzymania.

FAQ

Ile realnie kosztuje OpenRouter ponad stawki dostawcy?

Opłata wynosi 5,5 procent wartości doładowania kredytów kartą, z minimum 0,80 dolara, oraz 5 procent przy płatności w USDC. Za same tokeny płacisz stawkę dostawcy, bez narzutu. Osobno rozliczane jest użycie własnych kluczy: powyżej progu zawartego w planie opłata wynosi 5 procent tego, ile żądanie kosztowałoby normalnie.

Czy darmowe modele wystarczą do produkcji?

Do prototypu i testów tak, do produkcji z realnym ruchem nie. Warianty z sufiksem :free mają twardy limit 20 żądań na minutę, a dzienny limit to 50 żądań przy zakupach poniżej 10 dolarów i 1000 żądań powyżej tego progu. Skład listy darmowych modeli zmienia się w czasie.

Jak sprawdzić, który model i który dostawca obsłużyli żądanie?

Odpowiedź zawiera pole model z identyfikatorem modelu, który faktycznie odpowiedział, oraz pole provider. Przy liście zapasowej jest to jedyny wiarygodny sposób, żeby wiedzieć, za co płacisz, i te dwa pola powinny trafiać do logów przy każdym żądaniu.

Czy mogę wymusić konkretnego dostawcę i zablokować resztę?

Tak. Pole provider.order ustawia kolejność prób, provider.only ogranicza pulę do wskazanych dostawców, a provider.allow_fallbacks ustawione na false wyłącza sięganie po pozostałych. Im ciaśniejsze warunki, tym częściej zobaczysz kod 503 oznaczający brak pasującego dostawcy.

Czy przejście z OpenRoutera na bezpośrednie API jest trudne?

Warstwa transportu jest zgodna ze specyfikacją OpenAI, więc powrót do bezpośredniego API OpenAI sprowadza się do zmiany adresu bazowego i klucza. Trudniejsze jest odtworzenie tego, co usługa robiła za Ciebie: wyboru dostawcy, przełączania przy awarii i wspólnego rozliczenia. Przy modelach Meta Llama dochodzi jeszcze wybór konkretnego dostawcy infrastruktury, bo tych samych wag nie serwuje jedna firma.

Czy warto włączyć logowanie promptów dla zniżki?

Zniżka wynosi 1 procent kosztów zużycia i wymaga zgody na przechowywanie treści zapytań oraz odpowiedzi. Przy danych osobowych albo poufnych treściach klientów to zwykle zły interes, bo jeden procent nie pokrywa ryzyka. Przy publicznych, nieosobowych zapytaniach decyzja jest czysto rachunkowa.

Dokumentację znajdziesz na stronie OpenRouter, aktualny cennik i limity planów na stronie z cennikiem, a pełny katalog modeli w publicznym API.