Responses API ou Chat Completions: qual formato usar?

Compare formatos de solicitação, streaming, ferramentas e compatibilidade entre provedores antes de escolher a Responses API ou Chat Completions para sua aplicação de IA.

Responses API ou Chat Completions: qual formato usar?

A Responses API e o Chat Completions enviam prompts para modelos de linguagem, mas organizam de formas diferentes a entrada, a saída, as ferramentas e o streaming. A escolha entre eles deve começar pelo contrato do cliente e do modelo — e não pela suposição de que um endpoint mais novo funciona automaticamente com qualquer provedor.

A regra de decisão mais curta é:

  • Use a Responses API em um agente de programação ou aplicação que já espera itens do Responses, eventos de ferramentas e o ciclo de streaming do Responses.
  • Use o Chat Completions em clientes de chat amplamente compatíveis e em famílias de provedores que expõem seus modelos no estilo OpenAI por repasse direto (pass-through) do Chat Completions.

Sempre verifique o formato de API suportado pelo modelo selecionado em Modelos e preços.

Comparação dos protocolos

Pergunta Responses API Chat Completions
Formato principal da entrada input e itens de entrada tipados Um array messages
Modelo de saída Itens e eventos de saída tipados Opções de mensagem do assistente e deltas
Streaming Stream de eventos do Responses Stream de chunks do Chat Completions
Atividade de ferramentas Itens tipados de chamada e de saída de ferramenta Chamadas de ferramentas anexadas às mensagens do assistente
Melhor uso Agentes, ferramentas de programação e aplicações nativas do Responses Clientes de chat e provedores compatíveis com OpenAI de amplo suporte
Portabilidade de modelos Somente modelos verificados para Responses Somente modelos verificados para Chat Completions

A tabela descreve o contrato de comunicação. Ela não significa que o Modelflare converta todos os recursos de cada provedor entre os dois formatos.

Quando a Responses API é a melhor opção

Escolha /v1/responses quando o cliente já trata a execução de um modelo como uma sequência de itens tipados, e não como uma única mensagem do assistente. Isso é comum em agentes de programação que precisam distinguir texto visível, resumos de raciocínio, argumentos de funções, entrada de ferramentas personalizadas e outros eventos.

Uma solicitação mínima tem esta forma:

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": "Liste as três verificações a fazer antes de migrar uma API.",
    "stream": true
  }'

O streaming do Responses deve ser validado de ponta a ponta. Um cliente que entende chunks do Chat Completions, mas não eventos do Responses, pode se conectar com sucesso e ainda assim não exibir nenhuma saída útil.

Quando o Chat Completions é a escolha mais segura

Escolha /v1/chat/completions quando a aplicação é construída em torno de mensagens system, user, assistant e tool, ou quando a família de provedores selecionada documenta um endpoint de Chat Completions compatível com OpenAI.

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": "system", "content": "Responda de forma concisa."},
      {"role": "user", "content": "O que uma verificação de integridade de API deve verificar?"}
    ],
    "stream": true
  }'

Em famílias de provedores que não são da OpenAI, o Modelflare pode expor o repasse direto do Chat Completions para que campos privados da solicitação, como controles de raciocínio ou de pesquisa específicos do provedor, cheguem ao serviço do provedor sem alterações. Esse comportamento é intencionalmente mais restrito do que alegar compatibilidade total com o Responses.

Não escolha apenas pelo nome do modelo

São necessárias três verificações separadas:

  1. A chave de API tem acesso ao modelo. O acesso depende da chave e dos grupos de modelos disponíveis.
  2. O modelo oferece suporte ao endpoint. Um modelo listado em /v1/models não é automaticamente válido para os dois formatos de solicitação.
  3. O cliente entende o stream. Eventos do Responses e chunks do Chat Completions são contratos de cliente diferentes.

Se alguma dessas verificações falhar, apenas trocar o caminho do endpoint pode transformar um erro claro de compatibilidade em uma resposta vazia ou exibida pela metade.

Migração de ferramentas e saída estruturada

Antes de migrar uma integração existente:

  • compare o schema de definição de ferramentas usado pelo cliente;
  • verifique como os IDs de chamadas de ferramentas e as saídas das ferramentas são retornados;
  • preserve valores opcionais explícitos em vez de descartar 0 ou false;
  • confira se o provedor exige campos privados que precisam ser repassados sem alterações;
  • teste respostas apenas com ferramentas, que podem não conter nenhum delta de texto visível;
  • confirme como o cliente detecta a conclusão e o uso.

Um mesmo prompt gerar textos parecidos não é um teste de protocolo suficiente. Um teste real deve incluir os recursos dos quais a aplicação depende.

Um fluxo prático de escolha

  1. Abra Modelos e preços e escolha o modelo e o grupo.
  2. Confirme o formato de API suportado.
  3. Siga um guia específico para o seu cliente na documentação do Modelflare, quando houver um.
  4. Envie uma solicitação sem streaming.
  5. Envie uma solicitação com streaming.
  6. Teste ferramentas ou saída estruturada.
  7. Revise a solicitação nos registros de uso: status, tempos, uso de tokens e custo.

A Responses API não substitui universalmente o Chat Completions, e o Chat Completions não está obsoleto. O formato correto é aquele suportado ao mesmo tempo pelo cliente, pelo modelo selecionado e pelo contrato do provedor.

Depois de escolher o formato, use o Guia de streaming de API de IA para implementar o parser de eventos, as métricas de tempo, o cancelamento e a política de timeouts.