Responses API ou Chat Completions

Responses API e Chat Completions enviam instruções para modelos de linguagem, mas organizam de forma diferente a entrada, a saída, as ferramentas e o streaming. A escolha deve partir do contrato entre o cliente e o modelo, não da ideia de que o endpoint mais recente funciona automaticamente com qualquer fornecedor.

A regra prática é simples:

• Utilize Responses API para um agente de programação ou uma aplicação que já espere itens tipificados, eventos de ferramentas e o ciclo de streaming de Responses.
• Utilize Chat Completions para clientes de chat com ampla compatibilidade e para famílias de fornecedores que exponham o formato OpenAI através de passthrough de Chat Completions.

Confirme sempre o formato suportado pelo modelo em Modelos e preços.

Comparação dos protocolos

Questão	Responses API	Chat Completions
Entrada principal	input e itens tipificados	Uma lista messages
Modelo de saída	Itens e eventos de saída tipificados	Escolhas de mensagens do assistente e deltas
Streaming	Fluxo de eventos Responses	Fluxo de fragmentos Chat Completions
Ferramentas	Chamadas e resultados como itens tipificados	Chamadas associadas a mensagens do assistente
Melhor aplicação	Agentes, ferramentas de código e aplicações nativas de Responses	Clientes de chat e fornecedores amplamente compatíveis com OpenAI
Portabilidade	Apenas modelos validados para Responses	Apenas modelos validados para Chat Completions

A tabela descreve o contrato na rede. Não significa que a Modelflare converta todas as funcionalidades de um fornecedor entre os dois formatos.

Quando Responses API é a melhor opção

Escolha /v1/responses quando o cliente tratar cada execução como uma sequência de itens tipificados, e não como uma única mensagem do assistente. É comum em agentes de programação que precisam de distinguir texto visível, resumos de raciocínio, argumentos de funções, entrada de ferramentas personalizadas e outros eventos.

Pedido mínimo:

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

Valide o streaming de Responses de ponta a ponta. Um cliente que abre a ligação mas só entende fragmentos de Chat Completions pode ligar-se com sucesso e, mesmo assim, não apresentar uma saída útil.

Quando Chat Completions é a escolha mais segura

Escolha /v1/chat/completions se a aplicação se basear em mensagens system, user, assistant e tool, ou se o fornecedor documentar especificamente um endpoint 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": "Responde de forma concisa."},
      {"role": "user", "content": "O que deve verificar um teste de estado da API?"}
    ],
    "stream": true
  }'

Para famílias que não são da OpenAI, a Modelflare pode encaminhar Chat Completions sem transformação, para que campos privados — como controlos de raciocínio ou pesquisa — cheguem intactos ao fornecedor. Esta garantia deliberadamente precisa é mais rigorosa do que alegar compatibilidade universal com Responses.

Não escolher apenas pelo nome do modelo

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

1. A chave API consegue aceder ao modelo. O acesso depende da chave e dos grupos disponíveis.
2. O modelo suporta o endpoint. Estar em /v1/models não significa funcionar nos dois formatos.
3. O cliente entende o fluxo. Os eventos Responses e os fragmentos Chat Completions são contratos diferentes.

Se uma destas verificações falhar, alterar apenas o caminho do endpoint pode transformar um erro claro de compatibilidade numa resposta vazia ou incompleta.

Migrar ferramentas e saída estruturada

Antes de mudar uma integração real:

• compare o esquema de definição das ferramentas;
• verifique como regressam os IDs das chamadas e os respetivos resultados;
• preserve valores opcionais explícitos, como 0 ou false;
• identifique campos privados que tenham de passar sem alterações;
• teste respostas compostas apenas por chamadas de ferramentas, sem texto visível;
• confirme como o cliente deteta a conclusão e a utilização.

Obter texto semelhante com o mesmo prompt não é um teste de protocolo suficiente. O teste deve exercer as funcionalidades de que a aplicação depende.

Processo de escolha recomendado

1. Escolha o modelo e o grupo em Modelos e preços.
2. Confirme o formato de API suportado.
3. Siga um guia específico do cliente na documentação da Modelflare, se existir.
4. Envie um pedido sem streaming.
5. Envie um pedido com streaming.
6. Teste ferramentas ou saída estruturada.
7. Reveja estado, tempos, tokens e custo nos registos de utilização.

Responses API não substitui universalmente Chat Completions, e Chat Completions não está obsoleto. O formato certo é o que o cliente, o modelo escolhido e o contrato do fornecedor suportam em conjunto.