API compatível com OpenAI: mudar o Base URL

Uma API compatível com OpenAI permite que um cliente existente mantenha os cabeçalhos de autenticação, a estrutura JSON e o padrão de streaming que já conhece, embora o tráfego passe por outro gateway. Por vezes basta alterar o URL base e a chave API. Ainda assim, compatibilidade é um contrato de protocolo — não é uma promessa de que todos os modelos aceitam todos os endpoints ou campos específicos de cada fornecedor.

Este guia descreve uma migração segura para aplicações, scripts e ferramentas de IA que já comunicam com uma API ao estilo OpenAI.

O que abrange realmente a compatibilidade com OpenAI

As partes mais reutilizáveis do contrato são:

• autenticação por token Bearer no cabeçalho Authorization;
• pedidos e respostas JSON em endpoints versionados sob /v1;
• endpoints comuns, como /v1/models, /v1/chat/completions e /v1/responses;
• eventos enviados pelo servidor (SSE) nos pedidos de streaming suportados;
• campos conhecidos, como model, messages, input, stream e as definições de ferramentas previstas pelo protocolo escolhido.

Compatibilidade não significa que um modelo possa passar livremente de Chat Completions para Responses. Um modelo pode estar disponível apenas através de um dos protocolos verificados. Campos de raciocínio, pesquisa ou entrada multimodal próprios de um fornecedor podem também ter de ser encaminhados sem alterações, em vez de traduzidos pelo gateway.

Consulte sempre o catálogo atualizado de Modelos e preços para confirmar o modelo, o grupo e o formato de API que pretende utilizar.

Preparar a migração

Antes de alterar o código da aplicação:

1. Crie uma chave dedicada em Chaves API, em vez de reutilizar uma chave pessoal ou de outra integração.
2. Escolha um grupo principal com acesso ao modelo pretendido.
3. Adicione grupos de contingência numa ordem explícita e apenas se suportarem o mesmo modelo e respeitarem a política de custo e fiabilidade.
4. Registe o endpoint atual, o ID exato do modelo, a opção de streaming e as ferramentas utilizadas, para poder comparar o comportamento antes e depois.

O URL base canónico da API compatível com OpenAI da Modelflare é:

https://modelflare.dev/v1

A maioria dos SDK espera que o URL termine em /v1 e acrescenta /chat/completions ou /responses automaticamente. Consulte a documentação do cliente antes de duplicar o sufixo do endpoint.

Verificar primeiro a autenticação e o acesso ao modelo

Guarde a chave numa variável de ambiente, nunca no código-fonte:

export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'

Confirme depois que a chave consegue listar os modelos disponíveis:

curl -sS https://modelflare.dev/v1/models \
  -H "Authorization: Bearer $MODELFLARE_API_KEY"

Uma resposta válida confirma o domínio, a ligação TLS e a chave. Ainda não prova que um determinado formato de pedido é aceite por todos os modelos devolvidos; o teste seguinte deve usar o endpoint efetivamente previsto.

Enviar um pedido com o protocolo pretendido

Para um modelo indicado como compatível com Chat Completions:

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "user", "content": "Responde com o nome do modelo ativo."}
    ],
    "stream": false
  }'

Para um modelo de programação compatível com Responses:

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Responde com o nome do modelo ativo.",
    "stream": false
  }'

Utilize exatamente o ID apresentado no catálogo. Um resultado model_not_found costuma indicar que a chave ou o grupo não tem acesso ao modelo; alterar maiúsculas e minúsculas raramente resolve o problema.

Validar o streaming separadamente

Um pedido sem streaming bem-sucedido não basta quando a aplicação depende de uma resposta incremental. Repita com "stream": true, confirme que os eventos chegam progressivamente e verifique que o cliente não retém a resposta completa antes de a apresentar.

Ao diagnosticar streaming lento, separe:

• o tempo de autenticação e seleção da rota;
• a espera pelos cabeçalhos de resposta do fornecedor;
• o tempo até ao primeiro texto, raciocínio ou evento de ferramenta útil;
• a velocidade de geração depois de começar a saída visível.

Os registos de utilização da Modelflare guardam estas métricas por pedido sem armazenar prompts, texto de resposta, corpos brutos, chaves API, endereços de e-mail ou IP em texto simples.

Lista de verificação para produção

• Guarde a chave num cofre de segredos ou numa variável de ambiente.
• Fixe o URL base em https://modelflare.dev/v1.
• Utilize um modelo que suporte explicitamente o endpoint escolhido.
• Teste separadamente os modos com e sem streaming.
• Teste ferramentas, saída estruturada, controlos de raciocínio e entradas multimodais, se a aplicação os utilizar.
• Preserve valores explícitos como 0 e false quando tiverem significado.
• Ajuste o timeout à carga real, não a um prompt curto de diagnóstico.
• Após a mudança, reveja estado, latência, tokens, grupo selecionado e custo nos registos de utilização.

Depois de validada a fronteira do protocolo, o cliente pode normalmente manter o seu ciclo de pedidos. A Modelflare trata do acesso aos modelos, das regras de encaminhamento e da visibilidade por pedido atrás do mesmo endpoint.