Przejdź do głównej treści
OrcaRouter może próbować wielu modeli po kolei, aż któryś się powiedzie. Przydatne dla odporności (gdy jeden dostawca throttluje lub jest niedostępny) oraz dla kontroli kosztów (preferuj tańszy model i przejdź na silniejszy w razie potrzeby).

​
Jak używać

Wstaw uporządkowaną listę identyfikatorów modeli do extra_body.models i ustaw extra_body.route na "fallback". Główne pole model nadal ma znaczenie — to pierwsza próba — ale OrcaRouter ignoruje je na rzecz łańcucha, jeśli łańcuch jest obecny. 
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "..."}],
    extra_body={
        "models": ["openai/gpt-4o", "anthropic/claude-haiku-4.5", "google/gemini-2.5-pro"],
        "route": "fallback",
    },
)

​
Zasady

  • Maksymalnie 5 modeli w łańcuchu. Nadmiarowe są po cichu obcinane.
  • Zalecane: wszystkie modele w łańcuchu powinny być tego samego typu endpointu (wszystkie chat lub wszystkie image). Pomieszanie modelu chat z modelem image nie zawiesi bramy, ale fallback, który faktycznie obsłuży żądanie, musi pasować do wywołanego endpointu (np. jeśli wywołujesz /v1/chat/completions, użyteczne są tylko modele chat w łańcuchu).
  • Zachowanie fallback:
    • Wpisy orcarouter/{name} nierozwiązywalne (zła nazwa, wyłączony router) są po cichu pomijane.
    • Modele, do których wywołujący klucz nie ma dostępu (niezgodność białej listy modeli), są po cichu pomijane.
    • Gdy główny model zawiedzie upstream (5xx / 429 / błąd sieci), próbowany jest następny wpis łańcucha.
    • Żądanie zawodzi tylko wtedy, gdy każdy wpis łańcucha został wyczerpany.
    • Uwaga o streamingu: gdy choć jeden bajt odpowiedzi został wysłany do klienta, fallback nie może już zadziałać — jeśli upstream urwie w środku strumienia, klient widzi obcięty strumień, nie transparentny retry na następnym modelu.
  • Rozliczenia dotyczą modelu, który faktycznie obsłużył odpowiedź, po stawce tego modelu — nie głównego.
  • extra_body.route musi być dokładnie "fallback", aby łańcuch zadziałał. Każda inna wartość (lub jej brak) → łańcuch jest ignorowany i używany jest tylko model z najwyższego poziomu.

​
Jak sprawdzić, który model obsłużył odpowiedź

Sprawdź nagłówki odpowiedzi X-Orca-Fallback-Level i X-Orca-Fallback-Model. Zobacz Nagłówki odpowiedzi. 
response = client.chat.completions.with_raw_response.create(...)
served_by = response.headers.get("X-Orca-Fallback-Model", "primary")
# "primary" oznacza poziom 0; w przeciwnym razie nazwa modelu fallback

​
Kiedy tego nie używać

Jeśli chcesz, by OrcaRouter automatycznie wybierał najtańszy dostępny model bez pisania łańcucha, użyj zamiast tego orcarouter/auto. Łańcuchy fallback są dla przypadków, gdy chcesz jawnej kontroli nad kolejnością.