For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegação principal
Theme

Migre para a API Responses

A API Responses é a nova primitiva da nossa API. Ela é uma evolução de Chat Completions que simplifica suas integrações e oferece recursos avançados para trabalhar com agentes de IA.

Continuamos oferecendo suporte a Chat Completions e recomendamos Responses para todos os novos projetos.

Sobre a API Responses

A API Responses oferece uma interface unificada para criar aplicativos avançados que atuam como agentes. Entre os recursos estão:

Vantagens de Responses

A API Responses oferece várias vantagens em relação a Chat Completions:

  • Melhor desempenho: modelos de raciocínio, como o GPT-5, resolvem problemas melhor com Responses do que com Chat Completions. Nossas avaliações internas mostraram uma melhora de 3% no SWE-bench com o mesmo prompt e a mesma configuração.
  • Ciclo com agentes de IA por padrão: em uma única solicitação à API, o modelo pode chamar várias ferramentas, como web_search, image_generation, file_search, code_interpreter e servidores MCP remotos, além das funções que você definir.
  • Custos menores: o melhor aproveitamento do cache reduz os custos. Nos testes internos, o aproveitamento do cache melhorou de 40% a 80% em relação a Chat Completions.
  • Contexto com estado: use store: true para manter o estado entre turnos e preservar o contexto de raciocínio e de uso das ferramentas.
  • Entradas flexíveis: envie a entrada como uma string ou uma lista de mensagens. Use instruções para orientar o modelo no nível do sistema.
  • Raciocínio criptografado: use recursos avançados de raciocínio sem armazenar o estado.
  • Compatibilidade futura: a API já está preparada para os próximos modelos.
Recursos API chat completions API Responses
Geração de texto
Áudio Em breve
Visão
Saídas estruturadas
Chamada de função
Pesquisa na Web
Pesquisa em arquivos
Uso do computador
Interpretador de código
MCP
Geração de imagens
Resumos de raciocínio

Exemplos

Compare a API Responses com a API chat completions em cenários específicos.

Mensagens e itens

As duas APIs permitem gerar saídas com nossos modelos. Em uma chamada a Chat Completions, tanto a entrada quanto o resultado são arrays de mensagens. Já a API Responses usa itens. Um item é uma união de tipos que representam as diferentes ações que o modelo pode executar. Uma message é um tipo de item, assim como function_call e function_call_output. Em Chat Completions, uma mensagem reúne informações com finalidades distintas em um único objeto. Em Responses, cada item é independente e representa melhor a unidade básica de contexto do modelo.

Além disso, Chat Completions pode retornar várias gerações em paralelo como choices quando você usa o parâmetro n. A API Responses não inclui esse parâmetro e retorna apenas uma geração.

API chat completions
from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[
        {
            "role": "user",
            "content": "Write a one-sentence bedtime story about a unicorn.",
        }
    ],
)

print(completion.choices[0].message.content)
API Responses
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="Write a one-sentence bedtime story about a unicorn.",
)

print(response.output_text)

Os campos da resposta que você recebe da API Responses são um pouco diferentes. Em vez de uma message, você recebe um objeto response tipado com seu próprio id. Por padrão, Responses armazena as respostas. Chat Completions também armazena as respostas por padrão em contas novas. Para desativar o armazenamento em qualquer uma das APIs, defina store: false.

Os objetos retornados pelas duas APIs têm estruturas ligeiramente diferentes. Em Chat Completions, você recebe um array de choices, cada uma com uma message. Em Responses, você recebe um array de itens no campo output.

Chat Completions API
{
  "id": "chatcmpl-C9EDpkjH60VPPIB86j2zIhiR8kWiC",
  "object": "chat.completion",
  "created": 1756315657,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Under a blanket of starlight, a sleepy unicorn tiptoed through moonlit meadows, gathering dreams like dew to tuck beneath its silver mane until morning.",
        "refusal": null,
        "annotations": []
      },
      "finish_reason": "stop"
    }
  ],
  ...
}
Responses API
{
  "id": "resp_68af4030592c81938ec0a5fbab4a3e9f05438e46b5f69a3b",
  "object": "response",
  "created_at": 1756315696,
  "model": "gpt-5.5",
  "output": [
    {
      "id": "rs_68af4030baa48193b0b43b4c2a176a1a05438e46b5f69a3b",
      "type": "reasoning",
      "content": [],
      "summary": []
    },
    {
      "id": "msg_68af40337e58819392e935fb404414d005438e46b5f69a3b",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "logprobs": [],
          "text": "Under a quilt of moonlight, a drowsy unicorn wandered through quiet meadows, brushing blossoms with her glowing horn so they sighed soft lullabies that carried every dreamer gently to sleep."
        }
      ],
      "role": "assistant"
    }
  ],
  ...
}

Outras diferenças

  • Por padrão, Responses armazena as respostas. Chat Completions também armazena as respostas por padrão em contas novas. Para desativar o armazenamento em qualquer uma das APIs, defina store: false.
  • Os modelos de raciocínio têm mais recursos na API Responses, que permite usar ferramentas com mais eficácia. A partir do GPT-5.4, Chat Completions só permite chamadas de ferramenta quando reasoning_effort tem o valor none.
  • O formato das saídas estruturadas muda entre as APIs. Em vez de response_format, use text.format em Responses. Saiba mais no guia de saídas estruturadas.
  • O formato da chamada de função também muda, tanto na configuração da função enviada na solicitação quanto nas chamadas de função retornadas na resposta. Veja todas as diferenças no guia de chamada de função.
  • O SDK de Responses oferece o recurso auxiliar output_text, que não está disponível no SDK de Chat Completions.
  • Em Chat Completions, você precisa gerenciar manualmente o estado da conversa. A API Responses permite usar a API Conversations para manter conversas persistentes. Você também pode enviar um previous_response_id para encadear respostas.

Migração de Chat Completions

A migração envolve três mudanças relacionadas: enviar solicitações para /v1/responses, ler a saída de um array output tipado e decidir como seu aplicativo manterá o estado entre turnos.

1. Atualize os endpoints de geração

Comece alterando os endpoints de geração de post /v1/chat/completions para post /v1/responses.

Se você não usa funções nem entradas multimodais, pode enviar as mesmas mensagens de entrada às duas APIs quando elas contêm apenas texto:

Reutilize mensagens de entrada que contêm apenas texto
const context = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "Hello!" },
];

const completion = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages: context,
});

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: context,
});

Em Chat Completions, você cria um array messages e lê o texto gerado pelo modelo em completion.choices[0].message.content.

Gere texto com um modelo
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const completion = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" },
  ],
});
console.log(completion.choices[0].message.content);

2. Mapeie mensagens para itens

Chat Completions usa messages tanto na entrada quanto na saída. Responses usa input e output, dois arrays de itens tipados. Uma message é um dos tipos de item, assim como reasoning, function_call e function_call_output.

Conceito em Chat Completions Equivalente em Responses
messages[] input, como string ou array de itens de entrada
Orientações do sistema ou do desenvolvedor Campo instructions no nível superior ou itens de mensagem compatíveis quando for preciso preservar um histórico existente
Mensagem do usuário Item de mensagem de entrada com role: "user"
Mensagem do assistente Item de mensagem de saída em response.output. Envie-o de volta em input se você gerencia o estado manualmente
Chamada de ferramenta ou função Item de saída do tipo function_call
Resultado de ferramenta ou função Item de entrada do tipo function_call_output, associado à chamada por meio de call_id
Várias gerações com n Indisponível em Responses. Faça solicitações separadas se precisar gerar várias opções de saída

Quando precisar apenas do texto final, use o recurso auxiliar output_text do SDK. Quando seu fluxo usar raciocínio, ferramentas ou saída multimodal, percorra response.output e trate cada item de acordo com seu type.

3. Atualize as conversas com vários turnos

Se o seu aplicativo mantém conversas com vários turnos, atualize a lógica que gerencia o contexto. Em Responses, há três formas comuns de gerenciar o estado:

  • Use previous_response_id quando quiser que a OpenAI gerencie o contexto das respostas anteriores. Reenvie as instructions que continuam válidas em cada solicitação, pois previous_response_id não inclui as instructions do nível superior da resposta anterior.
  • Reenvie os itens de output anteriores na próxima solicitação quando precisar gerenciar ou reduzir o contexto por conta própria.
  • Use a API Conversations quando precisar de um objeto de conversa persistente.

Em Chat Completions, você armazena o histórico da conversa e envia o array messages com todas as mensagens acumuladas a cada solicitação.

Conversa com vários turnos
let messages = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "What is the capital of France?" },
];
const res1 = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages,
});

messages = messages.concat([res1.choices[0].message]);
messages.push({ role: "user", content: "And its population?" });

const res2 = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages,
});

Mesmo quando você usa previous_response_id, a API cobra como tokens de entrada todos os tokens de entrada das respostas anteriores da cadeia.

4. Decida quando armazenar o estado

Por padrão, Responses armazena as respostas. Chat Completions também armazena as respostas por padrão em contas novas. Para desativar o armazenamento em qualquer uma das APIs, defina store: false.

Políticas de conformidade ou de retenção de dados impedem algumas organizações, como as que exigem zero retenção de dados (ZDR), de usar a API Responses com armazenamento de estado. Para atender a esses casos, a OpenAI oferece itens de raciocínio criptografados. Assim, você pode usar esses itens sem armazenar o estado do fluxo de trabalho.

Para deixar de armazenar o estado e continuar usando o raciocínio:

  • Defina store: false no campo store.
  • Preserve e reenvie todos os itens de raciocínio retornados. Por padrão, cada item inclui encrypted_content quando você cria uma resposta.

A API retornará uma versão criptografada dos tokens de raciocínio. Você poderá reenviá-la em solicitações futuras da mesma forma que reenviaria itens de raciocínio comuns. Para organizações com ZDR, a OpenAI aplica store: false automaticamente. Quando uma solicitação inclui encrypted_content, a API descriptografa esse conteúdo na memória, usa-o para gerar a próxima resposta e o descarta de forma segura. A API criptografa imediatamente os novos tokens de raciocínio e os retorna a você, sem armazenar nenhum estado intermediário.

5. Atualize as definições e as saídas das funções

Há duas diferenças na forma como Chat Completions e Responses definem funções:

  1. Em Chat Completions, o marcador de tipo fica fora da definição da função. Em Responses, ele fica dentro da definição.
  2. Em Chat Completions, as funções usam o modo não estrito por padrão. Em Responses, se você omitir strict, a API tentará usar o modo estrito. Se não for possível tornar o schema compatível, Responses usará o modo não estrito, fará o possível para atender ao schema na chamada de função e retornará a ferramenta com a configuração efetivamente aplicada, strict: false. Para manter explicitamente o modo não estrito em Responses, defina strict: false.

O exemplo de função da API Responses à direita é funcionalmente equivalente ao exemplo de Chat Completions à esquerda.

Chat Completions API
{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Determine weather in my location",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "location"
      ]
    }
  }
}
Responses API
{
  "type": "function",
  "name": "get_weather",
  "description": "Determine weather in my location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string"
      }
    },
    "additionalProperties": false,
    "required": [
      "location"
    ]
  }
}

Siga as boas práticas de chamada de função

Em Responses, as chamadas de ferramenta e suas saídas são dois tipos distintos de item, associados por um call_id. Consulte a documentação de chamada de função para entender como essas chamadas funcionam em Responses.

6. Atualize as definições de saídas estruturadas

Na API Responses, as definições de saídas estruturadas passaram de response_format para text.format:

Saídas estruturadas
const completion = await openai.chat.completions.create({
  model: "gpt-6-astra",
  messages: [
    {
      role: "user",
      content: "Jane, 54 years old",
    },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "person",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: {
            type: "string",
            minLength: 1,
          },
          age: {
            type: "number",
            minimum: 0,
            maximum: 130,
          },
        },
        required: ["name", "age"],
        additionalProperties: false,
      },
    },
  },
  reasoning_effort: "medium",
});

7. Atualize o código que consome dados em streaming

No streaming de Chat Completions, a API retorna blocos incrementais com um campo delta. Em Responses, o streaming usa eventos tipados enviados pelo servidor. Atualize o código que consome o fluxo para selecionar o tratamento de cada evento pelo campo type e processar os eventos de que a interface ou a camada de orquestração precisa.

Para receber texto em streaming, escute eventos como:

  • response.created
  • response.output_text.delta
  • response.completed
  • error

Fluxos de chamada de função também podem emitir eventos como response.function_call_arguments.delta e response.function_call_arguments.done. Consulte o guia de streaming em Responses e a referência de eventos de streaming de Responses.

8. Passe a usar ferramentas nativas

Se as ferramentas nativas da OpenAI forem úteis para o seu aplicativo, você pode atualizar as chamadas de ferramenta para usá-las diretamente.

Chat Completions não oferece suporte nativo às ferramentas hospedadas pela OpenAI. Para usá-las, você precisa implementar sua própria integração. Este exemplo usa o GPT-5.6 Terra com o raciocínio desativado. O GPT-6 Astra e o GPT-6.1 Sol exigem a API Responses para chamar ferramentas.

Ferramenta de pesquisa na Web
async function web_search(query) {
  const res = await fetch(`https://api.example.com/search?q=${query}`);
  const data = await res.json();
  return data.results;
}

const completion = await client.chat.completions.create({
  model: "gpt-5.6-terra",
  reasoning_effort: "none",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Who is the current president of France?" },
  ],
  functions: [
    {
      name: "web_search",
      description: "Search the web for information",
      parameters: {
        type: "object",
        properties: { query: { type: "string" } },
        required: ["query"],
      },
    },
  ],
});

9. Verifique se há erros comuns de migração

Ao migrar o código de Chat Completions para Responses, fique atento a estes erros:

  • Ler choices[0].message.content em vez de response.output_text ou response.output.
  • Tratar cada entrada de output como uma mensagem. Itens de raciocínio, chamadas de ferramenta e chamadas de função têm tipos distintos.
  • Descartar itens de raciocínio, de chamada de função ou de saída de chamada de função ao transferir manualmente o contexto para a próxima resposta.
  • Enviar o resultado de uma função sem o call_id correspondente.
  • Usar response_format em uma solicitação a Responses em vez de text.format.
  • Reutilizar o código que processa blocos de streaming de Chat Completions sem adaptá-lo aos eventos tipados de Responses.
  • Presumir que previous_response_id elimina a cobrança pelo contexto anterior. Os tokens de entrada das respostas anteriores da cadeia continuam sendo cobrados como tokens de entrada.

Lista de verificação para a migração gradual

Chat Completions continua disponível e conta com suporte, então você pode migrar um fluxo de usuário por vez.

  • Comece com um fluxo de geração de texto.
  • Atualize o endpoint, o corpo da solicitação e o tratamento da saída.
  • Decida se o fluxo usará previous_response_id, o reenvio manual de itens ou a API Conversations.
  • Se o fluxo não armazenar estado ou estiver sujeito a ZDR, adicione store: false e inclua itens de raciocínio criptografados quando for necessário preservar o contexto de raciocínio entre turnos.
  • Migre as definições de função e verifique se as saídas das chamadas de função incluem o call_id correto.
  • Mova os schemas de saídas estruturadas de response_format para text.format.
  • Atualize o código que consome dados em streaming para tratar os eventos tipados de Responses.
  • Substitua a orquestração personalizada por ferramentas hospedadas pela OpenAI quando elas forem adequadas ao fluxo de trabalho.
  • Compare o comportamento, a latência, o uso de tokens e os erros antes de direcionar mais tráfego para Responses.

Recomendamos migrar todos os fluxos gradualmente para a API Responses para aproveitar os recursos e as melhorias mais recentes da OpenAI.

API Assistants

Com base no feedback dos desenvolvedores durante a fase beta da API Assistants, incorporamos melhorias importantes à API Responses para torná-la mais flexível, rápida e fácil de usar. A API Responses é a base para o desenvolvimento futuro de agentes na plataforma da OpenAI.

A OpenAI desativou oficialmente a API Assistants em 26 de agosto de 2026, e ela não está mais disponível. Siga o guia de migração para atualizar sua integração para a API Responses.