Roteamento inteligente

Quando o modelo indicado em uma requisição está fora do ar, o roteamento inteligente responde com uma alternativa semelhante em vez de um erro. Seu app continua funcionando durante uma indisponibilidade sem uma linha de código de retentativa. O modo automático cobre modelos de chat e imagemm. Para voz, a troca de modelo só acontece quando você escolhe as alternativas, e para vídeos ela nunca acontece.

Como funciona

1. Toda requisição vai primeiro para o modelo que você pediu. A maioria dos problemas termina aqui: se uma rota até o modelo trava ou retorna um erro, a requisição é reenviada por outra antes que você perceba.
2. O roteamento inteligente só entra em ação quando o próprio modelo não consegue responder (todas as rotas falharam ou nenhuma está disponível).
3. Ele tenta as alternativas em ordem, cada uma com a mesma recuperação automática, até que uma responda.
4. A resposta informa qual modelo respondeu (model no corpo, cabeçalhos x-zurelay-model e x-zurelay-routed-from), e a cobrança segue o preço desse modelo.

Todas as rotas até o modelo que você pediu são tentadas antes de uma alternativa, então você só recebe outro modelo quando o seu realmente não consegue responder. Se tudo falhou rapidamente, o modelo e cada uma das alternativas recebem mais uma tentativa antes de você ver um erro. Um modelo que já se sabe estar fora do ar é ignorado de imediato.

Como ativar

A configuração de uma chave pode ser:

Por requisição

Uma lista de alternativas

Passe models junto de model: até três alternativas, tentadas em ordem se model estiver fora do ar, independentemente da configuração da chave ou do cabeçalho. Essa lista nunca é enviada ao modelo. O SDK Python da OpenAI a envia por extra_body. Requisições de imagem e voz também a aceitam, e uma edição de imagem enviada como formulário a aceita em um campo models (repetido, ou como uma única lista separada por vírgulas).

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.zurelay.com/v1",
    api_key=os.environ["ZURELAY_API_KEY"],
)
response = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[
      {
        "role": "user",
        "content": "Summarize this ticket in one line: ..."
      }
    ],
    extra_body={
      "models": [
        "gpt-6.1-sol",
        "gpt-6-astra"
      ]
    },
)
print(response.choices[0].message.content)

O cabeçalho

x-zurelay-fallback: off    # never reroute this request
x-zurelay-fallback: auto   # use the automatic alternatives (chat and image models)

Ordem de prioridade: primeiro o models da requisição, depois o cabeçalho, depois a configuração da chave e, por fim, o padrão do workspace.

Quais alternativas podem responder

• São modelos do mesmo tipo. As alternativas de um modelo de chat são modelos de chat; as de um modelo de imagem, modelos de imagem; as de um modelo de voz, modelos de voz. Uma regra para qualquer outro modelo (*) pode listar vários tipos; cada requisição usa os do seu próprio tipo.
• Leem o que você enviou. Uma requisição com PDF ou vídeo só vai para alternativas capazes de ler esse conteúdo. Se nenhuma for capaz, você recebe o erro em vez de uma resposta que ignora seu arquivo.
• A chave tem permissão para usá-las. Alternativas fora dos modelos permitidos para a chave são ignoradas.
• São compatíveis com o endpoint. No /v1/messages, as alternativas são modelos Claude.
• A requisição em si é válida. Se o modelo recusou a requisição (um parâmetro inválido, um prompt longo demais, um prompt que ele não aceita desenhar ou um texto que ele não aceita falar), ela não é redirecionada: as alternativas também a recusariam.

Imagens

No modo automático, uma imagem vai primeiro para a mesma família (GPT Image 2.5 Sunburst para Flare, Nano Banana Pro para Nano Banana 2.1), e apenas para modelos que geram imagens com qualidade semelhante. Uma alternativa automática nunca custa mais de 1.5 vezes o preço do modelo que você pediu, no tamanho solicitado. Suas próprias regras e a lista models de uma requisição não têm esse limite. Em ambos os casos:

• O mesmo tamanho e formato. Os modelos Nano Banana interpretam size e aspect_ratio da mesma forma. GPT Image só substitui um tamanho do Nano Banana quando ambos geram a mesma imagem: 1K quadrado (1024x1024), 1K 3:2 ou 2:3, 2K quadrado, 4K 16:9 ou 9:16. Nano Banana só substitui um tamanho em pixels do GPT Image quando gera exatamente essas dimensões (1024x1024, 2048x2048), ou quando você não pediu um tamanho.
• Suas imagemns de referência. Uma alternativa precisa aceitar tantas imagens quanto você enviou (Nano Banana 14, GPT Image 16).
• Suas opções. Um background transparente só vai para modelos GPT Image.
• Um modelo por resposta. Com n acima de 1, todas as imagens vêm do mesmo modelo.

Voz

A geração de fala só troca de modelo com suas próprias regras ou com a lista models de uma requisição, nunca no modo automático. Todos os modelos de fala usam as mesmas vozes, então um modelo alternativo lê seu texto no voice que você pediu, com seu instructions. Os cabeçalhos de tokens de entrada e saída são do modelo que respondeu.

Alternativas automáticas

Direto do catálogo: as alternativas usadas por cada modelo de chat e imagemm no modo automático.

O que você precisa saber

• Um modelo alternativo pode custar mais ou menos que o modelo que você pediu. Seu log de requisições mostra o modelo que respondeu e o custo.
• O streaming funciona da mesma forma: nada é enviado até que um modelo esteja respondendo, e os trechos identificam esse modelo.
• As respostas de imagem e fala trazem os mesmos cabeçalhos x-zurelay-model e x-zurelay-routed-from, e as imagens na sua biblioteca são identificadas com o modelo que as criou.
• Vídeos não são redirecionados: a tarefa de vídeo permanece com o modelo que você pediu e é reenviada até ser concluída ou falhar (sem custo).