Roteamento com reserva

Nas rotas com corpo JSON, liste modelos de reserva no campo models. A Veloz tenta model primeiro; se ele falhar antes de começar a responder, passa para o próximo da lista. O primeiro que responder atende a requisição. Dá para misturar modelos do catálogo e dos seus provedores próprios, até 5 no total.

curl https://platform.onveloz.com/api/ai/v1/chat/completions \
  -H "Authorization: Bearer $VELOZ_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1-mini",
    "models": ["anthropic/claude-haiku-4-5", "meta-llama-llama-3.1-8b-instruct"],
    "messages": [{ "role": "user", "content": "Olá!" }]
  }'

Neste exemplo, se a OpenAI estiver fora do ar ou recusar a requisição, a Anthropic responde; se ela também falhar, o Llama 3.1 8B do catálogo responde.

Pelo SDK da OpenAI

O campo models não existe no SDK da OpenAI, então passe como campo extra.

resposta = client.chat.completions.create(
    model="openai/gpt-4.1-mini",
    messages=[{"role": "user", "content": "Olá!"}],
    extra_body={"models": ["meta-llama-llama-3.1-8b-instruct"]},
)

const resposta = await client.chat.completions.create({
  model: "openai/gpt-4.1-mini",
  models: ["meta-llama-llama-3.1-8b-instruct"],
  messages: [{ role: "user", content: "Olá!" }],
});

Em TypeScript, o tipo do SDK não conhece models; monte o corpo numa variável antes de passar, ou use um @ts-expect-error na linha.

Como funciona

• Ordem: model primeiro, depois models na ordem da lista. Sem model, a lista começa pelo primeiro de models. Um modelo repetido é tentado uma vez só.
• Quando passa para o próximo: quando o modelo responde com erro (um limite de uso, a chave recusada, um erro do provedor ou do próprio pedido) ou não responde. A troca acontece antes de qualquer parte da resposta chegar até você: depois que um modelo começa a responder, inclusive em streaming, ele vai até o fim.
• Quando todos falham: a resposta é o erro do último modelo da lista.
• Cobrança: só o modelo que respondeu conta. As tentativas que falharam não descontam créditos.
• Rotas: POST /chat/completions, POST /completions, POST /embeddings e POST /rerank. Os modelos dos provedores próprios só entram em /chat/completions e /embeddings. A transcrição não aceita reserva.

Erros que não passam para o próximo

Antes de chamar qualquer modelo, a Veloz confere a lista inteira. Um modelo que a organização não pode chamar recusa a requisição toda, para que um erro de digitação não fique escondido atrás da reserva:

• um id que não existe no catálogo: 404 com model_not_found;
• um provedor que não foi adicionado ou está pausado: 404 com provider_not_configured;
• um modelo que não serve para a rota, como um modelo de embeddings em /chat/completions: 400 com model_not_supported_for_endpoint;
• mais de 5 modelos somando model e models: 400 com too_many_models.

Saldo zerado

Com o saldo de IA zerado, os modelos do catálogo saem da lista e só os seus provedores respondem. Se a lista só tiver modelos do catálogo, a resposta é 402 com insufficient_credits.

Isso permite usar um modelo do catálogo como principal e o seu provedor como reserva para quando os créditos acabarem:

{
  "model": "qwen-qwen3.6-27b",
  "models": ["openai/gpt-4.1-mini"]
}

Ver o que aconteceu

Em Inferência de IA > Uso, o detalhe de cada requisição mostra cada modelo tentado, na ordem, com a duração e o erro de quem falhou. Veja Uso e rastreamento.