LLM

Fallback automático entre modelos de LLM con la API

En POST /llm/chat/completions, el campo opcional models lista hasta 3 modelos para probar, en orden, cuando model falla antes del primer token. La respuesta dice qué modelo respondió. Tienes un plan B en otro proveedor sin escribir lógica de reintentos.

La llamada

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?"
    }
  ]
}

Qué puedes hacer

  • Definir hasta 3 modelos de respaldo, incluso de otro proveedor, como openai/gpt-5.4-mini con anthropic/claude-haiku-5-5 de fallback.
  • Saber qué modelo respondió por el campo model de la respuesta.
  • Combinar el fallback con stream y tools, siempre que todos los modelos de la llamada soporten lo que pides.
  • Evitar la indisponibilidad cuando un proveedor falla o tarda.

Reglas y límites

  • El fallback entra cuando model falla antes de enviar el primer token: error del proveedor, límite o timeout. Después del primer token, el error te llega a ti.
  • Nunca hay un nuevo intento en el mismo modelo.
  • models acepta como máximo 3 ítems, todos de GET /llm/models; un id fuera de la lista devuelve 400 llm_model_not_allowed.
  • Necesitas la clave de cada proveedor de la cadena, model y models; si no, 400 llm_credential_missing.
  • tools e imágenes solo valen si todos los modelos de la llamada tienen supports_tools y supports_vision; el fallback recibe el mismo max_tokens, que debe caber en todos.

Campos principales

CampoTipoObligatorioDescripción
modelstringSíId del modelo, de GET /llm/models, con formato proveedor/modelo.
modelsarrayNoFallback: hasta 3 modelos de GET /llm/models, probados en orden si model falla antes del primer token.
messagesarraySíLa conversación, como en OpenAI. role: system, developer, user, assistant o tool.
max_tokensintegerSíObligatorio (o max_completion_tokens). Hasta el tope de la cuenta y el max_output_tokens de cada modelo de la llamada.
modelstringNoEn la respuesta: el modelo que respondió, model o uno de models.

Para quién

  • Un asistente de IA siempre activo

    Tu producto sigue respondiendo cuando un proveedor cae, porque el siguiente modelo de la lista asume.

  • Costo primero, calidad de respaldo

    Prueba un modelo barato y deja uno mayor de respaldo para cuando falle.

  • Agentes resilientes

    Un agente de larga duración no se detiene por una falla puntual de un proveedor.

Preguntas frecuentes

¿Cuándo se activa el fallback?

Cuando model falla antes de enviar el primer token: error del proveedor, límite o timeout. Después del primer token, el error va a ti y no se cambia de modelo.

¿Cómo sé qué modelo respondió?

Por el campo model de la respuesta: trae model o uno de models, si hubo fallback.

¿Puedo usar fallback con tools?

Sí, si todos los modelos de la llamada (model y cada ítem de models) tienen supports_tools. Si alguno no lo tiene, la llamada se rechaza con 400 llm_unsupported_field.

Relacionadas

Ver todo lo que puedes hacer con LLM

Mira Connect aplicado a tu producto.

Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.