Zum Hauptinhalt springen
OrcaRouter kann mehrere Modelle der Reihe nach versuchen, bis eines erfolgreich ist. Nützlich für Ausfallsicherheit (wenn ein Anbieter drosselt oder ausfällt) und für Kostenkontrolle (ein günstigeres Modell bevorzugen, bei Bedarf auf ein stärkeres zurückgreifen).

​
So verwendest du es

Lege eine geordnete Liste von Modell-IDs in extra_body.models ab und setze extra_body.route auf "fallback". Das primäre model-Feld ist immer noch wichtig — es ist der erste Versuch — aber OrcaRouter ignoriert es zugunsten der Kette, wenn die Kette vorhanden ist. 
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",
    },
)

​
Regeln

  • Maximal 5 Modelle in der Kette. Extras werden stillschweigend abgeschnitten.
  • Empfohlen: alle Modelle in einer Kette sollten vom gleichen Endpunkttyp sein (alle Chat oder alle Image). Ein Chat-Modell mit einem Image-Modell zu mischen, lässt das Gateway nicht abstürzen, aber das Fallback, das die Anfrage tatsächlich bedient, muss zum aufgerufenen Endpunkt passen (z. B. wenn du /v1/chat/completions aufrufst, sind nur Chat-Modelle in der Kette nutzbar).
  • Fallback-Verhalten:
    • Unauflösbare orcarouter/{name}-Einträge (schlechter Name, deaktivierter Router) werden stillschweigend übersprungen.
    • Modelle, auf die der aufrufende Schlüssel keinen Zugriff hat (Modell-Allowlist-Mismatch), werden stillschweigend übersprungen.
    • Wenn das primäre Modell im Upstream fehlschlägt (5xx / 429 / Netzwerkfehler), wird der nächste Ketteneintrag versucht.
    • Die Anfrage schlägt nur fehl, wenn jeder Ketteneintrag erschöpft ist.
    • Streaming-Warnung: Sobald ein Byte der Antwort an den Client gesendet wurde, kann das Fallback nicht mehr greifen — wenn der Upstream mitten im Stream abbricht, sieht der Client einen abgeschnittenen Stream, keinen transparenten Retry am nächsten Modell.
  • Die Abrechnung erfolgt für das Modell, das die Antwort tatsächlich bedient hat, zu dessen Rate — nicht zur Rate des primären.
  • extra_body.route muss genau "fallback" sein, damit die Kette aktiviert wird. Jeder andere Wert (oder fehlend) → die Kette wird ignoriert und nur das model auf oberster Ebene wird verwendet.

​
Wie du erkennst, welches Modell die Antwort bediente

Prüfe die Antwort-Header X-Orca-Fallback-Level und X-Orca-Fallback-Model. Siehe Antwort-Header. 
response = client.chat.completions.with_raw_response.create(...)
served_by = response.headers.get("X-Orca-Fallback-Model", "primary")
# "primary" bedeutet Stufe 0; sonst der Fallback-Modellname

​
Wann du dies nicht verwenden solltest

Wenn du möchtest, dass OrcaRouter automatisch das günstigste verfügbare Modell auswählt, ohne eine Kette zu schreiben, verwende stattdessen orcarouter/auto. Fallback-Ketten sind für Fälle, in denen du explizite Kontrolle über die Reihenfolge haben möchtest.