LLM

Fallback automático entre modelos de LLM pela API

Em POST /llm/chat/completions, o campo opcional models lista até 3 modelos para tentar, em ordem, quando o model falha antes do primeiro token. A resposta diz qual modelo respondeu. Dá para ter um plano B em outro provedor sem escrever lógica de retry.

A chamada

POST /api/llm/chat/completions
Authorization: Bearer <merchant token>

{
  "model": "openai/gpt-5.4-mini",
  "models": [
    "anthropic/claude-haiku-5-5"
  ],
  "max_tokens": 512,
  "messages": [
    {
      "role": "user",
      "content": "What was yesterday's reach?"
    }
  ]
}

O que dá para fazer

  • Definir até 3 modelos de reserva, inclusive de outro provedor, como openai/gpt-5.4-mini com anthropic/claude-haiku-5-5 de fallback.
  • Saber qual modelo respondeu pelo campo model da resposta.
  • Combinar fallback com stream e tools, desde que todos os modelos da chamada suportem o que você pediu.
  • Evitar indisponibilidade quando um provedor falha ou demora.

Regras e limites

  • O fallback entra quando o model falha antes de enviar o primeiro token: erro do provedor, limite ou timeout. Depois do primeiro token, o erro chega até você.
  • Nunca há nova tentativa no mesmo modelo.
  • models aceita no máximo 3 itens, todos de GET /llm/models; um id fora da lista retorna 400 llm_model_not_allowed.
  • Você precisa da chave de cada provedor da cadeia, model e models, senão 400 llm_credential_missing.
  • tools e imagens só valem se todos os modelos da chamada tiverem supports_tools e supports_vision; o fallback recebe o mesmo max_tokens, que precisa caber em todos.

Campos principais

CampoTipoObrigatórioDescrição
modelstringSimId do modelo, de GET /llm/models, no formato provedor/modelo.
modelsarrayNãoFallback: até 3 modelos de GET /llm/models, tentados em ordem se model falhar antes do primeiro token.
messagesarraySimA conversa, como na OpenAI. role: system, developer, user, assistant ou tool.
max_tokensintegerSimObrigatório (ou max_completion_tokens). Até o teto da conta e o max_output_tokens de cada modelo da chamada.
modelstringNãoNa resposta: o modelo que respondeu, o model ou um dos models.

Para quem

  • Assistente de IA sempre no ar

    Seu produto continua respondendo quando um provedor cai, porque o próximo modelo da lista assume.

  • Custo primeiro, qualidade como reserva

    Tente um modelo barato e deixe um maior como reserva para quando ele falhar.

  • Agentes resilientes

    Um agente de longa duração não para por uma falha pontual de um provedor.

Perguntas frequentes

Quando o fallback é acionado?

Quando o model falha antes de enviar o primeiro token: erro do provedor, limite ou timeout. Depois do primeiro token, o erro vai para você e não há troca de modelo.

Como sei qual modelo respondeu?

Pelo campo model da resposta: ele traz o model ou um dos models, se houve fallback.

Posso usar fallback com tools?

Sim, se todos os modelos da chamada (model e cada item de models) tiverem supports_tools. Se algum não tiver, a chamada é recusada com 400 llm_unsupported_field.

Relacionadas

Ver tudo que dá para fazer em LLM

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.