Passer au contenu principal
OrcaRouter peut essayer plusieurs modèles dans l’ordre jusqu’à ce que l’un réussisse. Utile pour la résilience (si un fournisseur limite ou est en panne) et pour le contrôle des coûts (préférer un modèle moins cher, se rabattre sur un plus fort si nécessaire).

​
Comment l’utiliser

Mettez une liste ordonnée d’IDs de modèles dans extra_body.models et définissez extra_body.route à "fallback". Le champ model principal compte encore — c’est la première tentative — mais OrcaRouter l’ignore au profit de la chaîne si la chaîne est présente. 
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",
    },
)

​
Règles

  • Maximum 5 modèles dans la chaîne. Les extras sont tronqués silencieusement.
  • Recommandé : tous les modèles d’une chaîne devraient être du même type d’endpoint (tous chat ou tous image). Mélanger un modèle chat avec un modèle image ne fera pas planter la passerelle, mais le fallback qui sert réellement la requête doit correspondre à l’endpoint que vous avez appelé (par ex. si vous appelez /v1/chat/completions, seuls les modèles chat de la chaîne sont utilisables).
  • Comportement du fallback :
    • Les entrées orcarouter/{name} non résolvables (mauvais nom, routeur désactivé) sont sautées silencieusement.
    • Les modèles auxquels la clé d’appel ne peut accéder (non-match de liste autorisée de modèles) sont sautés silencieusement.
    • Quand le modèle principal échoue en amont (5xx / 429 / erreur réseau), l’entrée suivante de la chaîne est essayée.
    • La requête échoue uniquement quand chaque entrée de la chaîne a été épuisée.
    • Avertissement streaming : une fois qu’un seul octet de la réponse a été envoyé au client, le fallback ne peut plus se déclencher — si l’amont coupe en milieu de flux, le client voit un flux tronqué, pas une nouvelle tentative transparente sur le modèle suivant.
  • La facturation se produit pour le modèle qui a réellement servi la réponse, à son taux — pas celui du principal.
  • extra_body.route doit être exactement "fallback" pour que la chaîne s’active. Toute autre valeur (ou absence) → la chaîne est ignorée et seul le model de niveau supérieur est utilisé.

​
Comment savoir quel modèle a servi la réponse

Vérifiez les en-têtes de réponse X-Orca-Fallback-Level et X-Orca-Fallback-Model. Voir En-têtes de réponse. 
response = client.chat.completions.with_raw_response.create(...)
served_by = response.headers.get("X-Orca-Fallback-Model", "primary")
# "primary" signifie niveau 0 ; sinon le nom du modèle fallback

​
Quand ne pas utiliser ceci

Si vous voulez qu’OrcaRouter choisisse automatiquement le modèle disponible le moins cher sans écrire de chaîne, utilisez orcarouter/auto à la place. Les chaînes de fallback sont pour les cas où vous voulez un contrôle explicite sur l’ordonnancement.