Saltar para o conteúdo principal
O OrcaRouter pode tentar múltiplos modelos em ordem até que um tenha sucesso. Útil para resiliência (se um provedor está limitando ou fora) e para controle de custo (prefira um modelo mais barato, caia em um mais forte se necessário).

​
Como usar

Coloque uma lista ordenada de IDs de modelo em extra_body.models e defina extra_body.route como "fallback". O campo principal model ainda importa — é a primeira tentativa — mas o OrcaRouter o ignora em favor da cadeia se a cadeia estiver 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",
    },
)

​
Regras

  • Máximo de 5 modelos na cadeia. Extras são silenciosamente truncados.
  • Recomendado: todos os modelos em uma cadeia devem ser do mesmo tipo de endpoint (todos de chat, ou todos de imagem). Misturar um modelo de chat com um modelo de imagem não quebrará o gateway, mas o fallback que realmente serve a requisição precisa corresponder ao endpoint que você chamou (ex.: se você chama /v1/chat/completions, apenas modelos de chat na cadeia são utilizáveis).
  • Comportamento de fallback:
    • Entradas orcarouter/{name} não resolvíveis (nome inválido, roteador desabilitado) são silenciosamente puladas.
    • Modelos que a chave chamadora não pode acessar (mismatch de allowlist de modelo) são silenciosamente pulados.
    • Quando o modelo principal falha no upstream (5xx / 429 / erro de rede), a próxima entrada da cadeia é tentada.
    • A requisição falha apenas quando todas as entradas da cadeia se esgotaram.
    • Ressalva de streaming: uma vez que qualquer byte da resposta tenha sido enviado ao cliente, o fallback não pode mais entrar em ação — se o upstream cair no meio do stream, o cliente vê um stream truncado, não uma nova tentativa transparente no próximo modelo.
  • O faturamento acontece para o modelo que realmente serviu a resposta, à taxa daquele modelo — não a do principal.
  • extra_body.route deve ser exatamente "fallback" para a cadeia ser ativada. Qualquer outro valor (ou ausente) → a cadeia é ignorada e apenas o model de nível superior é usado.

​
Como saber qual modelo serviu a resposta

Verifique os cabeçalhos de resposta X-Orca-Fallback-Level e X-Orca-Fallback-Model. Veja Cabeçalhos de resposta. 
response = client.chat.completions.with_raw_response.create(...)
served_by = response.headers.get("X-Orca-Fallback-Model", "primary")
# "primary" significa nível 0; caso contrário, o nome do modelo de fallback

​
Quando não usar isso

Se você quer que o OrcaRouter automaticamente escolha o modelo disponível mais barato sem escrever uma cadeia, use orcarouter/auto em vez disso. As cadeias de fallback são para casos em que você quer controle explícito sobre a ordem.