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.

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:
- A chave de API tem acesso ao modelo. O acesso depende da chave e dos grupos de modelos disponíveis.
- O modelo oferece suporte ao endpoint. Um modelo listado em /v1/models não é automaticamente válido para os dois formatos de solicitação.
- 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
- Abra Modelos e preços e escolha o modelo e o grupo.
- Confirme o formato de API suportado.
- Siga um guia específico para o seu cliente na documentação do Modelflare, quando houver um.
- Envie uma solicitação sem streaming.
- Envie uma solicitação com streaming.
- Teste ferramentas ou saída estruturada.
- 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.