Guia de API compatível com OpenAI: mude a URL base

Entenda o que a compatibilidade com OpenAI cobre, como migrar um cliente existente para o Modelflare e quais limites verificar antes de enviar tráfego de produção.

Guia de API compatível com OpenAI: mude a URL base

Uma API compatível com OpenAI permite que um cliente existente mantenha o cabeçalho de autenticação, o formato JSON das solicitações e o padrão de streaming que já conhece, enquanto envia o tráfego para outro gateway. A mudança pode se resumir a trocar a URL base e a chave de API, mas a compatibilidade continua sendo um contrato de protocolo — e não uma promessa de que todo modelo aceita todos os endpoints ou campos específicos de cada provedor.

Este guia explica o caminho seguro de migração para aplicações, scripts e ferramentas de IA que já usam uma API no estilo OpenAI.

O que a compatibilidade com OpenAI realmente cobre

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

  • Autenticação por token Bearer no cabeçalho Authorization.
  • Solicitações e respostas JSON em endpoints versionados sob /v1.
  • Endpoints comuns, como /v1/models, /v1/chat/completions e /v1/responses.
  • Server-sent events (SSE) nas solicitações de streaming suportadas.
  • Campos de solicitação conhecidos, como model, messages, input, stream e definições de ferramentas, quando o protocolo escolhido oferece suporte a eles.

Compatibilidade não significa que um modelo possa ser movido livremente entre Chat Completions e Responses. Um modelo pode estar disponível por apenas um protocolo verificado. Campos de raciocínio, pesquisa ou entrada multimodal específicos de um provedor também podem exigir repasse direto (pass-through), em vez de tradução feita pelo gateway.

Trate o catálogo atualizado de Modelos e preços como a fonte oficial do modelo, do grupo e do formato de API que você pretende usar.

Prepare a migração

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

  1. Crie uma chave dedicada em Chaves de API, em vez de reutilizar uma chave pessoal ou de outra integração.
  2. Selecione um grupo de modelos principal que tenha acesso ao modelo desejado.
  3. Adicione grupos de contingência em ordem definida somente se eles também oferecerem suporte a esse modelo e seguirem a mesma política de custo e confiabilidade.
  4. Anote o endpoint atual, o ID do modelo, a configuração de streaming e o uso de ferramentas para poder comparar o comportamento antes e depois.

A URL base canônica da API compatível com OpenAI do Modelflare é:

https://modelflare.dev/v1

A maioria dos SDKs espera que a URL base termine em /v1 e acrescenta /chat/completions ou /responses por conta própria. Consulte a documentação do cliente antes de adicionar um segundo sufixo de endpoint.

Verifique primeiro a autenticação e o acesso aos modelos

Armazene a chave em uma variável de ambiente, e não no código-fonte:

export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'

Em seguida, confirme que a chave consegue listar os modelos disponíveis:

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

Uma resposta bem-sucedida comprova que o hostname, o caminho TLS e a chave são válidos. Ela ainda não comprova que determinado formato de solicitação é válido para todos os modelos retornados; por isso, a próxima verificação deve usar o endpoint pretendido.

Envie uma solicitação com o protocolo pretendido

Para um modelo de Chat Completions listado como compatível com esse formato:

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": "Responda 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": "Responda com o nome do modelo ativo.",
    "stream": false
  }'

Use o ID exato do modelo mostrado no catálogo atualizado. Um resultado model_not_found geralmente significa que a chave ou o grupo selecionado não tem acesso a esse modelo — e não que mudar letras maiúsculas e minúsculas vai corrigir a solicitação.

Valide o streaming separadamente

Sucesso sem streaming não basta para uma aplicação que depende de streaming. Repita a solicitação com "stream": true, confirme que os eventos chegam de forma incremental e garanta que o cliente não acumule a resposta completa em buffer antes de exibi-la.

Ao diagnosticar um stream lento, separe:

  • o tempo gasto na autenticação e na seleção da rota;
  • o tempo até os cabeçalhos de resposta do provedor;
  • o tempo até o primeiro conteúdo efetivo ou delta de ferramenta;
  • a velocidade de geração depois que a saída visível começa.

Os registros de uso do Modelflare mantêm metadados de tempo por solicitação para essa finalidade, sem armazenar prompts, texto de resposta, corpos brutos de solicitação, chaves de API, e-mails ou endereços IP em texto simples.

Checklist de migração para produção

  • Mantenha a chave de API em um cofre de segredos ou em uma variável de ambiente.
  • Fixe a URL base em https://modelflare.dev/v1.
  • Use um modelo que ofereça suporte explícito ao endpoint escolhido.
  • Teste os modos com e sem streaming de forma independente.
  • Teste ferramentas, saída estruturada, controles de raciocínio e entrada multimodal, se a aplicação usar esses recursos.
  • Preserve valores explícitos zero ou false quando eles tiverem significado na solicitação do cliente.
  • Configure os timeouts do cliente para a carga de trabalho real, e não para um prompt curto de verificação de integridade.
  • Depois da migração, revise nos registros de uso o status, a latência, o uso de tokens, o grupo selecionado e o custo.

Depois que o limite do protocolo estiver verificado, o cliente geralmente pode manter o ciclo de vida atual das solicitações, enquanto o Modelflare fornece acesso a modelos, política de roteamento e visibilidade por solicitação por trás do endpoint compatível.

Para conhecer a camada operacional por trás desse endpoint, leia O que é um gateway de API de IA?. Se o cliente puder usar mais de um formato da OpenAI, compare Responses API ou Chat Completions antes de mudar os caminhos.