Vai al contenuto principale
OrcaRouter può provare più modelli in ordine finché uno non ha successo. Utile per la resilienza (se un provider è in throttling o non disponibile) e per il controllo dei costi (preferisci un modello più economico, ricorri a uno più potente se necessario).

​
Come usarlo

Inserisci una lista ordinata di ID modello in extra_body.models e imposta extra_body.route su "fallback". Il campo model principale conta ancora — è il primo tentativo — ma OrcaRouter lo ignora a favore della catena se la catena è presente. 
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",
    },
)

​
Regole

  • Massimo 5 modelli nella catena. Quelli in eccesso vengono troncati silenziosamente.
  • Consigliato: tutti i modelli in una catena dovrebbero essere dello stesso tipo di endpoint (tutti chat, o tutti immagine). Mescolare un modello di chat con un modello di immagine non manda in crash il gateway, ma il fallback che effettivamente serve la richiesta deve corrispondere all’endpoint che hai chiamato (es. se chiami /v1/chat/completions, solo i modelli di chat nella catena sono utilizzabili).
  • Comportamento di fallback:
    • Le voci orcarouter/{name} non risolvibili (nome errato, router disabilitato) vengono silenziosamente saltate.
    • I modelli a cui la chiave chiamante non può accedere (mismatch della allowlist dei modelli) vengono silenziosamente saltati.
    • Quando il modello principale fallisce upstream (5xx / 429 / errore di rete), viene provata la voce successiva della catena.
    • La richiesta fallisce solo quando ogni voce della catena è stata esaurita.
    • Avvertenza streaming: una volta che qualsiasi byte della risposta è stato inviato al client, il fallback non può più attivarsi — se l’upstream cade a metà stream, il client vede uno stream troncato, non un retry trasparente sul modello successivo.
  • La fatturazione avviene per il modello che ha effettivamente servito la risposta, alla tariffa di quel modello — non a quella del principale.
  • extra_body.route deve essere esattamente "fallback" affinché la catena si attivi. Qualsiasi altro valore (o mancante) → la catena viene ignorata e viene usato solo il model di livello superiore.

​
Come capire quale modello ha servito la risposta

Controlla gli header di risposta X-Orca-Fallback-Level e X-Orca-Fallback-Model. Vedi Header di risposta. 
response = client.chat.completions.with_raw_response.create(...)
served_by = response.headers.get("X-Orca-Fallback-Model", "primary")
# "primary" means level 0; otherwise the fallback model name

​
Quando non usare questo

Se vuoi che OrcaRouter scelga automaticamente il modello disponibile più economico senza scrivere una catena, usa invece orcarouter/auto. Le catene di fallback servono per i casi in cui vuoi il controllo esplicito sull’ordinamento.