Começando pela conclusão: a escolha entre Responses e Chat Completions não depende de qual interface é mais recente, mas de três fatores em conjunto: cliente, modelo e gateway. O cliente determina quais requisições você pode enviar, o modelo define qual endpoint oferece os recursos necessários, e o gateway determina se a requisição consegue chegar ao serviço de destino sem alterações.
Por isso, não force uma troca de interface só para integrar um novo modelo. Guarde esta regra: se o cliente não oferece suporte, não use a interface, por mais recente que seja; se o modelo só oferece suporte a um endpoint, não tente encaixá-lo à força em outro. As 7 verificações, a tabela de decisão por cenário e o checklist de rollback a seguir ajudam a identificar incompatibilidades em chamadas de ferramentas, parâmetros de raciocínio ou eventos de streaming antes de entrar em produção.
Qual é a diferença entre Responses e Chat Completions?
A principal diferença entre as duas interfaces está no modelo de dados: Chat Completions gira em torno de um array de mensagens, enquanto Responses gira em torno de um objeto de resposta.
As requisições de Chat Completions são centradas em messages. Cada mensagem contém role e content, e outros campos comuns incluem temperature, max_tokens, tools e stream. A interface não mantém estado: quem faz a chamada precisa gerenciar o histórico. Na resposta, message e finish_reason são obtidos de choices, e o consumo fica em usage. É a interface com suporte mais amplo em SDKs e clientes.
As requisições de Responses são centradas em input e podem incluir tools, reasoning e previous_response_id. A resposta contém o array output, além de output_text, status, id e usage. Alguns modelos de raciocínio mais recentes e recursos de ferramentas só estão disponíveis em Responses, mas nem todos os modelos, SDKs, clientes e gateways oferecem suporte a essa interface.
| Item a verificar | Chat Completions | Responses | Risco na migração |
|---|---|---|---|
| Endpoint e formato da requisição | /v1/chat/completions, usa messages |
/v1/responses, usa input |
Caminho ou corpo da requisição incompatível, fazendo o código de análise falhar |
| Estado em conversas com várias rodadas | Quem faz a chamada envia todo o histórico | É possível usar previous_response_id para referenciar a rodada anterior |
Estado expirado ou contexto inconsistente |
| Parâmetros de raciocínio e tokens | max_tokens ou max_completion_tokens |
O raciocínio é configurado por reasoning |
Parâmetros ignorados ou erro direto |
| Chamada de ferramentas | tools e resultados de ferramentas nas mensagens |
Itens de ferramenta em output e seus respectivos itens de resultado |
IDs de chamada associados incorretamente, interrompendo o loop do agente |
| Eventos de streaming | Fragmentos incrementais SSE | Eventos SSE com tipo definido | Encerramento prematuro ou erro na concatenação do texto |
| Entrada multimodal | Fragmentos de conteúdo como image_url |
Itens de entrada como input_image |
Imagens ou arquivos rejeitados |
| Compatibilidade | Amplo suporte em clientes e gateways | Depende do cliente, do gateway e do modelo | É possível preencher a Base URL, mas não chamar o endpoint |
Na hora de escolher, siga esta ordem. Se houver conflito entre os critérios, priorize uma combinação de cliente e modelo que funcione:
- Primeiro, verifique o cliente: ele oferece suporte a Chat Completions, Responses ou ao formato nativo do provedor?
- Depois, verifique o modelo: o modelo escolhido está disponível apenas em um endpoint? Ele depende de ferramentas integradas ou de parâmetros de raciocínio?
- Em seguida, verifique o gateway: ele atua como proxy para o endpoint escolhido? Consegue mapear modelos e registrar logs?
- Por último, avalie o custo: para a mesma tarefa, os custos de tokens, cache e novas tentativas diferem entre as duas interfaces?
Recomendação de integração: a tabela ajuda a identificar riscos, mas é preciso confirmar no ambiente real quais endpoints cada modelo suporta. Você pode começar consultando o modelo escolhido no console da APIYI, em apiyi.com, e depois decidir como validá-lo.
Como verificar a camada de requisição: checagens 1 a 3 da integração com Responses
A conclusão é simples: se endpoint, estado e parâmetros não estiverem alinhados, não adianta testar ferramentas e streaming.
Checagem 1: endpoints e formatos de requisição de Responses e Chat Completions
Aqui, confirme se a requisição foi enviada para o caminho correto e se o corpo e a interpretação da resposta usam a estrutura correspondente.
- Diferença: um usa
/v1/chat/completions, o outro usa/v1/responses. O primeiro recebemessagese retornachoices; o segundo recebeinpute retornaoutput. - Armadilha comum: mudar só o caminho, sem adaptar a leitura da resposta. A requisição pode ter dado certo, mas o código não encontra
choices[0].message, dando a impressão de que o modelo não retornou conteúdo. - Como validar: envie uma requisição mínima de texto para cada endpoint e registre o código de status, os campos de primeiro nível da resposta e o
usage. Ao usar a interface compatível com OpenAI da APIYI, a Base URL éhttps://api.apiyi.com/v1. Consulte o console e a documentação para verificar a disponibilidade do endpoint e do modelo desejados. - Como escolher: se o modelo aceita ambos e a aplicação só precisa de texto, continue usando a interface atual. Se o modelo estiver disponível apenas em um endpoint, adapte a integração a ele.
Checagem 2: gerenciamento de estado em conversas de várias rodadas
Onde o estado fica armazenado determina como investigar problemas e quanto controle você tem sobre o contexto.
- Diferença: no Chat Completions, cada rodada envia o histórico completo em
messages. No Responses, você pode usarprevious_response_idpara referenciar a resposta anterior e deixar parte do estado no servidor. - Armadilha comum: achar que enviar menos conteúdo significa pagar menos. Consulte a documentação oficial e a fatura para verificar se o contexto anterior continua sendo contabilizado como tokens de entrada. Outro risco é a expiração do estado: ao retomar uma tarefa longa, um response id antigo pode não funcionar mais.
- Como validar: execute três rodadas consecutivas e confirme se a terceira consegue recuperar informações da primeira. Depois, teste o caminho de falha com um id mais antigo e veja se o erro pode ser identificado. Se houver múltiplas rotas de provedores por trás do gateway, confirme também se o id pode ser reutilizado em requisições posteriores, de acordo com o suporte do gateway.
- Como escolher: se você precisa controlar totalmente o contexto e facilitar auditorias e cortes no histórico, enviar tudo é mais direto. Avalie o Responses quando conversas longas ou ciclos de Agent realmente se beneficiarem do estado no servidor.
Checagem 3: parâmetros de raciocínio e tokens na migração para Responses
O maior risco com parâmetros muitas vezes não é um erro explícito, mas a rejeição silenciosa: a requisição funciona, porém a configuração de raciocínio não entra em vigor.
- Diferença: em alguns modelos mais recentes,
max_tokensfoi substituído pormax_completion_tokens; o campo antigo pode ser ignorado ou gerar erro. O nome da configuração de intensidade de raciocínio também varia entre fornecedores e interfaces. Algumas formas comuns são reasoning effort ethinking. - Armadilha comum: usar o mesmo modelo de parâmetros para todos os modelos. Se o cliente ou o gateway descartar campos desconhecidos, a resposta pode parecer normal, mas a profundidade de raciocínio e o limite de saída talvez não correspondam aos valores definidos.
- Como validar: altere o limite de saída e a intensidade de raciocínio um de cada vez, comparando o tamanho da resposta, o
usagee as mensagens de erro. Se não houver diferença, verifique primeiro se o parâmetro está sendo repassado e se o modelo oferece suporte a ele. Depois, consulte a documentação oficial e as orientações do gateway. - Como escolher: mantenha uma tabela de mapeamento de parâmetros por “modelo + endpoint”, em vez de agrupar tudo apenas por fornecedor. Se a aplicação depende da configuração
reasoning, priorize um caminho de interface que transmita esse campo sem alterações.
Como avaliar a camada de recursos: verificações 4 a 6 da migração do Chat Completions
A conclusão sobre a camada de recursos é: as duas interfaces podem executar a mesma função, mas o código de interpretação das respostas, em geral, não pode ser reaproveitado diretamente.
Verificação 4: Chamadas de ferramentas no Chat Completions e no Responses
O Chat Completions oferece suporte a chamadas de ferramentas. Na migração, o que realmente precisa ser adaptado são os schemas das ferramentas, os IDs das chamadas e a forma de enviar os resultados de volta.
- Diferença: as duas interfaces têm definições de ferramentas, mas com estruturas diferentes. No Chat Completions, as chamadas geralmente aparecem em
tool_callsna mensagem do assistant; no Responses, elas são retornadas como itens deoutput, e os resultados também precisam ser enviados de volta nos itens de entrada correspondentes. Consulte a documentação oficial para conferir os campos específicos. - Armadilhas comuns: processar apenas a primeira ferramenta em chamadas paralelas ou alterar o ID da chamada antes de enviá-lo de volta. Na próxima rodada, o modelo pode apresentar um erro ou continuar o raciocínio com o resultado errado — e esse segundo caso é mais difícil de identificar.
- Como verificar: prepare um caso com uma ferramenta e outro com chamadas paralelas. Confira se cada ID é enviado de volta sem alterações e se cada chamada corresponde ao resultado correto. Depois, faça uma ferramenta retornar um erro de propósito e confirme que o ciclo do Agent é encerrado corretamente.
- Como escolher: se a cadeia de ferramentas atual é estável e você não precisa de ferramentas integradas, continue com o Chat Completions. Se as ferramentas integradas do modelo desejado estiverem disponíveis apenas no Responses, migre e reescreva a camada de interpretação das respostas.
Verificação 5: Eventos de streaming no Responses e no Chat Completions
No streaming, não basta conferir se o texto aparece: também é preciso verificar o tratamento da conclusão e dos erros.
- Diferença: ambos usam SSE, mas os tipos de evento e os marcadores de término são diferentes. O Chat Completions se baseia principalmente em fragmentos incrementais; o Responses usa diferentes tipos de evento para distinguir texto, ferramentas e estado de conclusão.
- Armadilhas comuns: considerar a resposta concluída assim que receber
dataou concatenar apenas os incrementos de texto, sem tratar os incrementos dos parâmetros das ferramentas e os eventos de erro. Isso pode truncar a resposta ou deixar os parâmetros das ferramentas incompletos. - Como verificar: capture uma transmissão SSE completa em formato bruto e confira a ordem dos incrementos, o evento de término, onde aparece
usagee como os erros são apresentados durante a transmissão. Se o gateway converter ou armazenar eventos em buffer, faça outra captura no fluxo que passa por ele. - Como escolher: se o parser de streaming do cliente só reconhece o formato do Chat Completions, não mude diretamente para o Responses. Para fazer a troca, primeiro atualize o SDK ou adapte a camada de interpretação.
Verificação 6: Entrada multimodal na integração com o Responses
Os campos multimodais dependem tanto da interface quanto do fornecedor. Conseguir processar texto não significa que imagens e arquivos também vão funcionar.
- Diferença: os campos de imagem podem usar
image_url,input_imageou base64. As formas de entrada de arquivos e áudio também variam conforme a interface e o fornecedor. - Armadilhas comuns: reutilizar a estrutura antiga dos fragmentos de conteúdo ou presumir que tanto URL quanto base64 são aceitos. Quando o gateway converte formatos, também podem surgir diferenças de tamanho, codificação ou tipo de arquivo.
- Como verificar: envie requisições mínimas separadas com uma imagem por URL, uma imagem em base64 e o tipo de arquivo desejado. Confirme que o modelo realmente leu o conteúdo. Fazer uma pergunta que só possa ser respondida ao ver a imagem é mais confiável do que verificar apenas o código de status.
- Como escolher: se você só precisa de compreensão de imagens, priorize o formato já validado no cliente atual. Se os recursos de arquivo ou áudio dependerem de um endpoint específico, consulte a documentação oficial e o suporte do gateway.
Como verificar a integração: checagem 7 de compatibilidade com Responses
A conclusão é simples: poder configurar uma Base URL não significa que o cliente, o SDK e o gateway sejam compatíveis com Responses.
Checagem 7: compatibilidade de SDKs, clientes e gateways com Responses
Uma requisição passa por quatro camadas: cliente, SDK, gateway e modelo. Se qualquer uma delas não for compatível, a nova interface não poderá ser usada.
| Camada | O que confirmar | Equívoco comum |
|---|---|---|
| Cliente | Se suporta o endpoint desejado e se a versão é recente o suficiente | Achar que suporta Responses só porque permite configurar uma Base URL |
| SDK | Se oferece métodos e tipos de evento para o endpoint desejado | Achar que, se a requisição é enviada, o SDK também consegue interpretar streaming e ferramentas |
| Gateway | Se encaminha o endpoint desejado e se é preciso habilitá-lo separadamente | Achar que a compatibilidade com OpenAI cobre todos os seus endpoints |
| Mapeamento de modelos | Se o ID do modelo está na lista e se precisa ser mapeado | Achar que o nome oficial do modelo é igual no gateway |
- Diferença: Chat Completions tem a compatibilidade mais ampla; a disponibilidade de Responses depende da combinação de cliente, SDK, gateway e modelo.
- Armadilha comum: o cliente pode montar o caminho silenciosamente como
/chat/completions, ou o gateway pode encaminhar apenas alguns campos. Se você olhar só para o nome do modelo, é fácil concluir erroneamente que o problema está nas capacidades dele. - Como verificar: primeiro, contorne o código da aplicação e envie uma requisição mínima com uma ferramenta de teste de API; depois, envie a mesma requisição pelo cliente e compare o caminho usado, o corpo da requisição e a resposta.
- Como escolher: se qualquer camada não suportar o endpoint desejado, mantenha a interface atual por enquanto ou use um formato que ela realmente suporte.
Em cenários com vários modelos, é melhor que o gateway reduza as alterações necessárias no cliente. APIYI apiyi.com permite chamar modelos de vários provedores, como OpenAI, Claude e Gemini, com uma única chave. Além disso, é compatível com o padrão da API OpenAI e com os formatos nativos de Claude e Gemini. Assim, o cliente pode se conectar usando o protocolo que suporta, sem precisar adaptar uma configuração de integração para cada modelo.
Não preencha o ID do modelo de memória nem copie diretamente a nomenclatura de outras plataformas. Antes da migração, confirme o ID do modelo e os endpoints disponíveis na lista de modelos do console da APIYI apiyi.com. Para preços e disponibilidade, consulte também o console e a documentação. Essa etapa leva pouco tempo e ajuda a eliminar muitos erros de “modelo inexistente” ou “endpoint não suportado”.
Responses ou Chat Completions: como escolher em cada cenário
Na maioria das tarefas simples, Chat Completions é suficiente. Vale migrar para Responses quando você realmente precisar dos recursos mais recentes.
| Cenário | Interface recomendada | Motivo | O que mais verificar |
|---|---|---|---|
| Agente de programação (Claude Code, Codex CLI, Cline etc.) | Escolha conforme o formato aceito pelo cliente | A implementação do protocolo pelo cliente determina as opções disponíveis; a maioria ainda usa Chat Completions ou Anthropic Messages | Configuração do protocolo na versão atual, chamadas de ferramentas e análise do streaming |
| Novo modelo de raciocínio da OpenAI com ferramentas integradas | Prefira Responses | Alguns recursos de raciocínio e ferramentas estão disponíveis apenas em Responses | Se o gateway oferece proxy para o endpoint e se as ferramentas integradas estão disponíveis |
| Conversas longas ou ciclos de agentes | Avalie Responses | O estado mantido no servidor pode reduzir a retransmissão de dados | Prazo de expiração do estado, consistência e custo real em tokens |
| Chamadas de ferramentas personalizadas | Mantenha a interface estável que já usa | Chat Completions também oferece chamadas de ferramentas; o custo da migração está principalmente na camada de análise | Chamadas paralelas, correspondência dos IDs de chamada e retorno de erros |
| Acesso unificado a vários modelos | Prefira um gateway que aceite vários formatos | Evita alterar o cliente para cada modelo | Mapeamento de modelos, logs e diferenças entre os parâmetros de cada modelo |
| Perguntas e respostas somente para leitura ou classificação simples | Chat Completions | Oferece recursos suficientes, ampla compatibilidade e baixo custo de adaptação | Se o parâmetro de limite de saída é compatível com o modelo escolhido |
Para usar a tabela, encontre seu cenário e confira a última coluna. Por exemplo, se o modelo escolhido só oferece Responses, mas seu cliente só aceita Chat Completions, não tente forçar uma adaptação dos campos. Atualize ou troque o cliente, ou escolha outro modelo disponível nessa interface.
Deixe o custo para a decisão final. Responses não é necessariamente mais barato: acertos no cache, número de tentativas e uso real de tokens afetam o resultado. A comparação só faz sentido ao analisar as faturas para a mesma tarefa.
Sugestão: se você tiver vários modelos candidatos, compare-os usando o mesmo conjunto de comandos e casos de uso de ferramentas. Com a APIYI apiyi.com, você pode alternar entre modelos usando a mesma chave API e aproveitar o crédito gratuito de teste para novos usuários para fazer uma validação em pequena escala. Isso ajuda a reduzir o trabalho inicial de integração e configuração.
Perguntas frequentes sobre Responses e Chat Completions
A resposta comum a essas perguntas é: antes de tirar conclusões, analise o fluxo real.
P1: Os modelos novos só funcionam com Responses?
Não necessariamente. Depende do modelo e do gateway: alguns modelos de raciocínio mais recentes ou recursos de ferramentas estão disponíveis apenas em Responses, enquanto outros modelos continuam compatíveis com Chat Completions. Antes da integração, consulte a documentação oficial e as informações sobre o modelo no gateway.
P2: Chat Completions ainda permite chamar ferramentas?
Sim. Chat Completions oferece suporte à chamada de ferramentas. A diferença está na estrutura dos campos, no formato de retorno dos resultados e no gerenciamento de estado. Ao migrar para Responses, normalmente é preciso ajustar o código que interpreta as chamadas de ferramentas; não dá para reutilizá-lo diretamente.
P3: O que fazer se o gateway não oferece suporte a Responses?
Primeiro, confira se o modelo desejado também funciona com Chat Completions ou com o formato nativo do fornecedor. Se funcionar, mantenha o caminho atual. Se o modelo estiver disponível apenas por Responses, será preciso usar um gateway compatível com esse endpoint ou uma conexão direta. Ao usar APIYI apiyi.com, você pode confirmar no console e na documentação quais endpoints são compatíveis com o modelo desejado.
P4: Por que a cobrança mudou depois da migração?
Entre as causas comuns estão mudanças na forma de passar o contexto, na quantidade de tokens de raciocínio e na taxa de acertos do cache, além de mais rodadas de chamadas de ferramentas e novas tentativas após falhas. Para investigar, compare o `usage` para a mesma tarefa e confira o modelo, o volume de requisições e o consumo de tokens nos logs de uso da APIYI apiyi.com.
P5: Quando é hora de reverter a migração?
É hora de reverter quando há falhas no fluxo principal, resultados de ferramentas associados incorretamente, interrupções frequentes no streaming ou desvios significativos na taxa de sucesso, na latência ou no custo em relação à linha de base, sem explicação em curto prazo. Defina os critérios de reversão antes da migração para evitar discussões de última hora após a entrada em produção.
Checklist de migração e rollback para Responses
A conclusão é simples: valide em etapas pequenas, mantenha o caminho antigo e use a linha de base para decidir se vale continuar.
Checklist de validação antes e depois da migração para Responses
- Faça um inventário das versões: liste as versões do cliente, do SDK e do gateway e confirme que o endpoint desejado é compatível.
- Confirme o mapeamento: confira o endpoint, o ID do modelo, os parâmetros de raciocínio e os parâmetros de token.
- Registre a linha de base: salve a taxa de sucesso, a latência e o custo em tokens da interface original.
- Mantenha o caminho antigo: preserve a configuração da interface original e o ID do modelo. Use um interruptor ou variável de ambiente para alternar, sem fixar a escolha no código.
- Valide primeiro o texto: confirme que uma solicitação mínima de texto funciona e que a resposta é interpretada corretamente.
- Depois, valide o streaming: verifique se os incrementos são concatenados por completo e se os eventos de encerramento e erro são tratados corretamente.
- Valide as ferramentas: teste chamadas com uma única ferramenta e com ferramentas em paralelo, garantindo que os IDs das chamadas correspondam aos resultados.
- Por último, valide a multimodalidade: confirme que o modelo consegue ler corretamente as entradas usadas na prática, como imagens e arquivos.
- Entenda a cobrança: compare a cobrança por tokens e o uso de cache, verificando se as diferenças podem ser explicadas.
- Faça uma liberação gradual com pouco tráfego: comece com uma pequena parcela de tráfego não crítico e registre as diferenças e os casos de falha.
Durante a validação da migração, vale comparar lado a lado os resultados das solicitações antigas e novas. O console da APIYI em apiyi.com permite consultar o uso e as cobranças. Com os logs, você pode verificar se os modelos e o consumo das solicitações na liberação gradual estão dentro do esperado. Se houver alguma anomalia, volte à configuração da interface original e use os casos de falha para reproduzir o problema.
Condições para acionar o rollback para Chat Completions
| Item observado | Ação recomendada | Critério para rollback |
|---|---|---|
| Falha em solicitações de texto | Pause a liberação gradual e verifique o endpoint e a interpretação da resposta | Faça rollback se não for possível corrigir em curto prazo |
| Streaming truncado ou que não termina | Compare os eventos SSE originais | Faça rollback imediatamente se isso afetar a saída exibida ao usuário |
| Associação incorreta de chamadas de ferramentas | Verifique os IDs das chamadas e o formato de retorno | Faça rollback imediatamente se houver risco de operações incorretas |
| Parâmetros de raciocínio não aplicados | Confira o encaminhamento dos parâmetros e a compatibilidade do modelo | Faça rollback se a qualidade da saída for afetada e não houver configuração alternativa |
| Custo fora da linha de base | Analise tokens, cache e novas tentativas | Faça rollback se ultrapassar o limite definido pela equipe e não houver explicação |
Responses ou Chat Completions: pontos principais
- Ordem de escolha: primeiro o cliente, depois o modelo, em seguida o gateway e, por último, a comparação de custos.
- Limites de compatibilidade: Responses é adequado para modelos que dependem de recursos exclusivos dessa interface, mas nem todos os modelos são compatíveis.
- Chamadas de ferramentas: Chat Completions também permite chamar ferramentas; na migração, o foco está nos campos e na associação entre chamadas e resultados.
- Ordem de validação: primeiro texto, depois streaming, ferramentas e, por último, multimodalidade.
- Pré-requisitos para rollback: mantenha a configuração antiga, registre a linha de base com antecedência e use um interruptor para alternar.
Resumo: como decidir entre Responses e Chat Completions
Se o fluxo atual com Chat Completions é estável, atende às suas necessidades e permite integrar o novo modelo, não há motivo para trocar de interface só por trocar. Se o modelo desejado ou as ferramentas integradas dependerem de Responses, siga as 7 verificações para validar a integração por etapas. E lembre-se: se o cliente não for compatível, não use a interface, por mais nova que seja; se o modelo só aceitar um endpoint, não tente forçar o outro.
Quando for começar, você pode confirmar o ID do modelo e a compatibilidade do endpoint pela APIYI em apiyi.com, percorrer o checklist com solicitações mínimas e só então decidir se aumenta o tráfego.
Autor: Equipe técnica da APIYI
Discussões técnicas: entre em contato conosco pela página inicial do site da APIYI. Para mais materiais de integração, acesse a central de documentação em docs.apiyi.com
