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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| model | string | Sim | Id do modelo, de GET /llm/models, no formato provedor/modelo. |
| models | array | Não | Fallback: até 3 modelos de GET /llm/models, tentados em ordem se model falhar antes do primeiro token. |
| messages | array | Sim | A conversa, como na OpenAI. role: system, developer, user, assistant ou tool. |
| max_tokens | integer | Sim | Obrigatório (ou max_completion_tokens). Até o teto da conta e o max_output_tokens de cada modelo da chamada. |
| model | string | Não | Na 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.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
