Encaminhamento inteligente

Quando o modelo indicado num pedido está indisponível, o encaminhamento inteligente responde com uma alternativa semelhante em vez de um erro. A sua aplicação continua a funcionar durante uma falha sem uma única linha de código para novas tentativas. O modo automático abrange modelos de chat e de imagemm. Nos pedidos de voz, só há mudança de modelo se escolher as alternativas, e nos vídeos nunca há.

Como funciona

1. Cada pedido é enviado primeiro para o modelo que escolheu. A maioria dos problemas resolve-se aqui: se uma via de acesso ao modelo bloquear ou der erro, o pedido é repetido por outra via antes de receber qualquer resposta.
2. O encaminhamento inteligente só intervém quando o próprio modelo não consegue responder (todas as vias falharam ou nenhuma está disponível).
3. Experimenta as alternativas por ordem, cada uma com o mesmo mecanismo de recuperação automática, até uma responder.
4. A resposta indica qual o modelo que respondeu (model no corpo, cabeçalhos x-zurelay-model e x-zurelay-routed-from), e é cobrada ao preço desse modelo.

Todas as vias de acesso ao modelo que escolheu são tentadas antes de experimentar uma alternativa, por isso só recebe outro modelo quando o seu não consegue mesmo responder. Se tudo falhar rapidamente, o modelo e as suas alternativas têm mais uma tentativa cada antes de receber um erro. Um modelo que se sabe estar indisponível é ignorado de imediato.

Como ativar

A definição de uma chave é uma das seguintes:

Por pedido

Uma lista de alternativas

Envie models juntamente com model: até três alternativas, tentadas por ordem se model estiver indisponível, independentemente da definição da chave ou do cabeçalho. A lista nunca é enviada ao modelo. O SDK de Python da OpenAI envia-a através de extra_body. Os pedidos de imagem e de voz também a aceitam, e uma edição de imagem enviada como formulário aceita-a num 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)

O que se aplica, por ordem de prioridade: o models do pedido, depois o cabeçalho, depois a definição da chave e, por fim, a predefinição do espaço de trabalho.

Que 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 são modelos de imagem e as de um modelo de voz são modelos de voz. Uma regra para qualquer outro modelo (*) pode incluir vários tipos; cada pedido usa os do seu próprio tipo.
• Conseguem ler o que enviou. Um pedido com um PDF ou um vídeo só é enviado para alternativas que o consigam ler. Se nenhuma conseguir, recebe o erro em vez de uma resposta que ignora o seu ficheiro.
• A chave pode usá-las. As alternativas que não constem dos modelos permitidos para a chave são ignoradas.
• São compatíveis com o endpoint. Em /v1/messages, as alternativas são modelos Claude.
• O pedido em si é válido. Se o modelo recusou o pedido (um parâmetro inválido, um prompt demasiado longo, um prompt que não aceita desenhar ou texto que não aceita reproduzir em voz), o pedido não é reencaminhado: as alternativas também o recusariam.

Imagens

No modo automático, um pedido de imagem vai primeiro para a mesma família (de GPT Image 2.5 Sunburst para Flare, de 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 escolheu para o tamanho pedido. As suas próprias regras e a lista models de um pedido não têm esse limite. Em qualquer dos casos:

• O mesmo tamanho e formato. Os modelos Nano Banana interpretam size e aspect_ratio da mesma forma. GPT Image só substitui um tamanho Nano Banana quando ambos produzem a mesma imagem: 1K quadrada (1024x1024), 1K 3:2 ou 2:3, 2K quadrada, 4K 16:9 ou 9:16. Nano Banana só substitui um tamanho em píxeis de GPT Image quando produz exatamente essas dimensões em píxeis (1024x1024, 2048x2048), ou quando não especificou um tamanho.
• Como suas imagens de referência. Uma alternativa tem de aceitar tantas imagens quantas enviou (Nano Banana 14, GPT Image 16).
• Como suas opções. Um background transparente só é enviado para modelos GPT Image.
• Um modelo por resposta. Com n acima de 1, todas as imagens vêm do mesmo modelo.

Voz

A síntese de voz só muda de modelo com as suas próprias regras ou com a lista models de um pedido, nunca em modo automático. Todos os modelos de voz disponibilizam as mesmas vozes, por isso uma alternativa lê o seu texto com a voice que pediu e com o seu instructions. Os cabeçalhos de tokens de entrada e saída são os do modelo que respondeu.

Alternativas automáticas

Diretamente do catálogo: as alternativas a que cada modelo de chat e imagemm recorre em modo automático.

O que deve saber

• Uma alternativa pode custar mais ou menos do que o modelo que pediu. O registo de pedidos mostra o modelo que respondeu e o respetivo custo.
• O streaming funciona da mesma forma: nada é enviado até um modelo começar a responder, e os blocos identificam esse modelo.
• As respostas de imagem e voz incluem os mesmos cabeçalhos x-zurelay-model e x-zurelay-routed-from, e as imagens na sua biblioteca estão identificadas com o modelo que as criou.
• Os vídeos não são reencaminhados: uma tarefa de vídeo mantém o modelo que pediu e é reenviada até ser concluída ou falhar (sem custos).