Este guia o acompanhará no uso completo da API OpenAI Responses: ao terminar, você será capaz de enviar uma solicitação para POST /v1/responses, ler a saída aninhada que ela retorna, ativar ferramentas integradas, manter o estado da conversa entre as chamadas e verificar todo o contrato dentro do Apidog. A API Responses é a interface mais recente da OpenAI para gerar saída de modelo, e o guia oficial do Responses explica por que a OpenAI agora direciona novos projetos para ela. Se você já testa o endpoint mais antigo, pode reutilizar a maior parte dessa configuração, assim como o fluxo de trabalho em nosso guia de teste da API ChatGPT com Apidog.
O que você precisa primeiro
Antes de enviar uma solicitação, certifique-se de ter algumas coisas prontas:
- Uma chave de API OpenAI com acesso a um modelo atual de propósito geral. Mantenha a chave em uma variável de ambiente, não colada em um comando ou em um arquivo compartilhado.
- Um nome de modelo que sua conta realmente possa chamar. Em vez de codificar um, verifique a lista de modelos em seu painel OpenAI e confirme-o em relação ao endpoint.
- Uma maneira de enviar solicitações HTTP brutas e inspecionar o JSON que retorna. Um terminal com
curlfunciona para uma primeira chamada, e o Apidog é o que você usará para verificar e simular a resposta mais tarde.
Também ajuda saber o que o endpoint faz antes de chamá-lo. A API Responses expõe um único endpoint, POST /v1/responses. Você envia um nome de modelo e um input, e recebe de volta um objeto de resposta que pode conter texto simples, chamadas de função e os resultados de ferramentas hospedadas pela OpenAI, como pesquisa na web ou pesquisa de arquivos. Uma única chamada pode executar uma sequência de várias etapas: o modelo decide pesquisar na web, lê os resultados, depois escreve uma resposta, e a resposta registra cada etapa que foi tomada.
Duas coisas a diferenciam de um endpoint de texto simples. Primeiro, ele pode executar ferramentas integradas no lado do servidor, então você não precisa configurar sua própria pesquisa ou sandbox. Segundo, ele é com estado por padrão. Cada resposta recebe um id, e você pode passar esse id para a próxima solicitação para que a OpenAI mantenha o histórico da conversa para você. A OpenAI descreve a API Responses como a evolução das Chat Completions e a recomenda para novos projetos, incorporando lições da beta da API Assistants. Assim, em vez de três modelos mentais, você tem um.
Saiba como difere das Chat Completions
Se você já usou POST /v1/chat/completions, a mudança é principalmente na forma e no estado. Chat Completions recebe um array de messages e retorna choices. Você gerencia a transcrição completa por conta própria, reenviando cada turno anterior em cada chamada. As ferramentas são algo que você implementa no seu lado.
A API Responses recebe um input (uma string ou uma lista de itens tipados) e retorna um output (uma lista de itens tipados). Ela pode armazenar o turno para você e executar ferramentas hospedadas sem necessidade de configuração extra.
Aqui está a comparação prática:
| Aspecto | Chat Completions | Responses API |
|---|---|---|
| Endpoint | POST /v1/chat/completions |
POST /v1/responses |
| Corpo da Requisição | Array messages |
input (string ou itens) + instructions |
| Formato da Saída | choices[].message |
Lista de itens tipados output |
| Estado da Conversa | Você reenvia o histórico completo | store + previous_response_id |
| Ferramentas Integradas | Você as constrói | web_search, file_search, code_interpreter e mais |
| Status | Suportado, sem depreciação anunciada | Recomendado para novos projetos |
Chat Completions não vai desaparecer. A OpenAI diz que continuará sendo suportada, e você pode migrar um fluxo de usuário por vez em vez de reescrever tudo de uma vez. A API Assistants é a que está com o tempo contado: a OpenAI a descontinuou em 26 de agosto de 2025, com um fim de vida declarado para 26 de agosto de 2026, então novos trabalhos de agente devem começar com a API Responses.
Faça sua primeira solicitação
Aqui está uma chamada mínima. Troque o nome do modelo pelo que sua conta tem acesso, e mantenha sua chave fora do próprio comando.
curl https://api.openai.com/v1/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"input": "Escreva uma frase descrevendo o que um servidor de mock de API faz.",
"instructions": "Você é um escritor técnico conciso. Sem linguagem de marketing.",
"store": true
}'
Você passa três coisas importantes aqui: o model, o input (seu prompt), e as instructions (a direção em nível de sistema). Definir store como true informa à OpenAI para salvar a resposta para que você possa continuar a conversa mais tarde.
Leia a resposta
Uma resposta simplificada se parece com isto:
{
"id": "resp_abc123",
"object": "response",
"status": "completed",
"model": "gpt-5.5",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "Um servidor de mock retorna respostas de API predefinidas para que os clientes possam ser desenvolvidos e testados antes que o backend real exista."
}
]
}
],
"usage": {
"input_tokens": 28,
"output_tokens": 24,
"total_tokens": 52
}
}
Observe a estrutura, porque é a parte que confunde as pessoas. O texto que você quer está em output[0].content[0].text, não em um campo de nível superior. Os SDKs oficiais adicionam um acessador de conveniência output_text que agrega todos os itens de texto em uma única string, mas essa propriedade é um auxiliar do SDK, não faz parte do JSON HTTP bruto. Ao chamar o endpoint diretamente, você lê o caminho aninhado. O id de nível superior é o que você reutilizará para o estado, e usage.total_tokens informa o custo da chamada.
Adicione ferramentas integradas
O recurso principal é que a OpenAI executa certas ferramentas para você. Você as lista em um array tools e o modelo decide quando chamá-las. Os tipos integrados verificados incluem:
web_searchpara pesquisas em tempo real na internet com citações (o antigoweb_search_previewainda funciona para integrações legadas, mas carece de controles mais recentes).file_searchpara recuperação de arquivos que você carregou.code_interpreterpara executar e analisar código em um sandbox.computer_usepara controlar uma interface de computador.image_generationpara produzir imagens em linha.
Ativar uma delas é uma pequena adição ao corpo:
{
"model": "gpt-5.5",
"input": "O que mudou na última versão da OpenAPI? Cite as fontes.",
"tools": [{ "type": "web_search" }]
}
Quando o modelo usa uma ferramenta, o array output ganha entradas que documentam a etapa, como um item web_search_call junto com a message final. Isso é útil mais tarde: você pode verificar se uma ferramenta realmente foi disparada, não apenas se o texto retornou.
Continue a conversa entre chamadas
O estado funciona através de dois parâmetros. store é verdadeiro por padrão, o que significa que a OpenAI salva o objeto de resposta (retido por 30 dias por padrão) e retorna um id. Passe esse id como previous_response_id em sua próxima chamada e o modelo continuará o tópico sem que você precise reenviar a transcrição:
{
"model": "gpt-5.5",
"input": "Agora reescreva isso para um público não técnico.",
"previous_response_id": "resp_abc123"
}
Se você preferir manter as coisas sem estado, ou tiver um requisito de retenção de dados zero, defina store como falso e gerencie o contexto você mesmo. Para fluxos de voz e áudio em tempo real e de baixa latência, a OpenAI usa uma superfície diferente; nosso guia da API GPT em tempo real aborda esse caso. E se você estiver orquestrando agentes multi-etapas além de tudo isso, os padrões se alinham com o SDK OpenAI Agents.
Como testar no Apidog
Apidog é uma plataforma de teste, design e mock de API. Não é um SDK da OpenAI nem uma biblioteca de código, então você não escreverá Python com ela. Em vez disso, você: constrói a requisição HTTP bruta para /v1/responses, a envia e escreve asserções sobre o JSON que retorna. Esse é exatamente o tipo de verificação de contrato que detecta uma integração quebrada antes que seus usuários o façam.
Aqui está a configuração, passo a passo.
Armazene a chave em uma variável de ambiente
No Apidog, crie um ambiente (digamos, "OpenAI Prod") e adicione uma variável como OPENAI_API_KEY. Mantenha o valor no ambiente, não na requisição, para que o segredo nunca seja salvo em uma coleção compartilhada. Em seguida, crie uma nova requisição POST para https://api.openai.com/v1/responses e adicione o cabeçalho Authorization: Bearer {{OPENAI_API_KEY}}. O Apidog substitui a variável no momento do envio.
Defina o corpo como JSON e cole a solicitação anterior. Clique em enviar. Você verá o objeto de resposta completo, formatado, com o array output aninhado.
Faça asserções nos campos de resposta
Um 200 bem-sucedido não é prova de que a resposta tem o formato esperado pelo seu aplicativo. Adicione asserções para que uma regressão falhe ruidosamente. Verificações úteis contra uma resposta de /v1/responses:
statusé igual acompleted.output[0].content[0].textexiste e não está vazio.usage.total_tokensé maior que 0.- Quando você envia
tools, um item emoutputtemtypeigual aweb_search_call.
O construtor visual de asserções do Apidog permite que você direcione esses caminhos JSON sem escrever scripts de teste, e nosso modelo de caso de teste de API mostra como estruturar verificações como essas. Salve a requisição em uma coleção e ela se torna um teste repetível que você pode executar na CI.
Simule a resposta para desenvolvimento offline
Chamadas à OpenAI custam dinheiro e precisam de acesso à rede, o que é inconveniente quando você está construindo a interface que consome a resposta ou executando testes em um pipeline que não deveria acessar uma API paga. O recurso de mock do Apidog resolve isso. Salve um payload representativo de /v1/responses como um mock, aponte seu aplicativo para a URL de mock do Apidog, e seu frontend obterá o formato JSON correto com custo zero de tokens. Quando o endpoint real mudar, você atualiza um mock em vez de perseguir falhas em cada teste. Nosso explicador de mock de API aborda a abordagem geral.
Essa divisão importa. Você testa contra o endpoint ativo para verificar o contrato da OpenAI, e você o simula para um desenvolvimento rápido, offline e determinístico. Ambos são executados a partir do mesmo projeto Apidog.
Perguntas Frequentes
A API Responses está substituindo o Chat Completions?
Não por força. A OpenAI chama a API Responses de evolução das Chat Completions e a recomenda para novos projetos, mas as Chat Completions continuam suportadas sem data de depreciação anunciada. Você pode migrar um fluxo por vez. A API Assistants é a que está sendo aposentada, com data de fim de vida em 2026.
Qual a diferença entre store e previous_response_id?
store controla se a OpenAI salva o objeto de resposta (por padrão é verdadeiro e retém por 30 dias). previous_response_id é como você vincula uma nova solicitação a uma resposta armazenada para que o modelo continue a conversa no lado do servidor. Você os usa juntos para threads com estado, e desativa store quando deseja um comportamento sem estado.
Quais modelos suportam a API Responses?
Os modelos atuais de propósito geral da OpenAI são projetados para funcionar com a API Responses, mas a disponibilidade depende da sua conta e do modelo que você escolher. Em vez de codificar o nome de um modelo, verifique a lista de modelos em seu painel OpenAI e, em seguida, confirme-o em relação ao endpoint. Enviar uma solicitação rápida através do Apidog e ler o campo model na resposta é uma maneira rápida de verificar o que sua chave pode realmente chamar.
Posso testar as ferramentas integradas sem escrever código?
Sim. Adicione um array tools ao corpo JSON no Apidog, envie a requisição e faça uma asserção de que o item de chamada de ferramenta correspondente (como web_search_call) aparece no array output. Você está verificando o comportamento da OpenAI via HTTP, então nenhum SDK é necessário. Para testar chamadas de ferramentas de agente de forma mais ampla, veja como gerar coleções de testes de API a partir de especificações OpenAPI.
Conclusão
Agora você tem o ciclo completo: um único endpoint, POST /v1/responses, que lida com texto, ferramentas hospedadas e estado de conversação no servidor. Envie uma solicitação, leia o output aninhado, adicione um array tools quando precisar de pesquisa ou execução de código, e encadeie previous_response_id para manter uma conversa em andamento. Como a forma é diferente das Chat Completions, a maneira mais segura é verificar o contrato você mesmo, em vez de confiar na sua memória da API antiga.
É aí que o Apidog se encaixa. Construa a solicitação, armazene sua chave como uma variável de ambiente, faça asserções nos campos output aninhados e simule a resposta para trabalho offline, tudo em um único projeto. Baixe o Apidog e aponte um teste para /v1/responses para ver exatamente o que sua integração recebe. Você pode fazer toda a configuração no Apidog sem escrever uma única linha de código de teste.