Saltar al contenido principal
OrcaRouter puede probar múltiples modelos en orden hasta que uno tenga éxito. Útil para resiliencia (si un proveedor está limitando o caído) y para control de costes (preferir un modelo más barato, recurrir a uno más fuerte si es necesario).

​
Cómo usar

Pon una lista ordenada de IDs de modelo en extra_body.models y configura extra_body.route a "fallback". El campo model principal sigue importando — es el primer intento — pero OrcaRouter lo ignora a favor de la cadena si la cadena está 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",
    },
)

​
Reglas

  • Máximo 5 modelos en la cadena. Los extras se truncan en silencio.
  • Recomendado: todos los modelos en una cadena deberían ser del mismo tipo de endpoint (todos chat, o todos imagen). Mezclar un modelo chat con uno de imagen no estrellará la pasarela, pero el respaldo que sirve realmente la solicitud necesita coincidir con el endpoint que llamaste (p. ej. si llamas a /v1/chat/completions, solo los modelos chat en la cadena son utilizables).
  • Comportamiento del respaldo:
    • Las entradas orcarouter/{name} no resolubles (mal nombre, enrutador deshabilitado) se omiten en silencio.
    • Los modelos a los que la clave llamante no puede acceder (desajuste de lista permitida) se omiten en silencio.
    • Cuando el modelo principal falla en el upstream (5xx / 429 / error de red), se prueba la siguiente entrada de la cadena.
    • La solicitud falla solo cuando cada entrada de la cadena se ha agotado.
    • Advertencia de streaming: una vez que se haya enviado cualquier byte de la respuesta al cliente, el respaldo ya no puede activarse — si el upstream se cae a mitad del flujo, el cliente ve un flujo truncado, no un reintento transparente en el siguiente modelo.
  • La facturación ocurre para el modelo que realmente sirvió la respuesta, a su tasa — no la del principal.
  • extra_body.route debe ser exactamente "fallback" para que la cadena se active. Cualquier otro valor (o ausencia) → la cadena se ignora y solo se usa el model de nivel superior.

​
Cómo saber qué modelo sirvió la respuesta

Consulta las cabeceras de respuesta X-Orca-Fallback-Level y X-Orca-Fallback-Model. Ver Cabeceras de respuesta. 
response = client.chat.completions.with_raw_response.create(...)
served_by = response.headers.get("X-Orca-Fallback-Model", "primary")
# "primary" significa nivel 0; en otro caso el nombre del modelo de respaldo

​
Cuándo no usar esto

Si quieres que OrcaRouter elija automáticamente el modelo disponible más barato sin escribir una cadena, usa orcarouter/auto en su lugar. Las cadenas de respaldo son para casos donde quieres control explícito sobre el orden.