OpenAI API: Guia de Especificação e Implementação da Responses API e Structured Outputs

Introdução

Entrando em 2025, a API da OpenAI atingiu um grande ponto de inflexão. Em março de 2025, a Responses API foi oficialmente lançada (GA), consolidando as capacidades de conversação da Chat Completions API e os recursos de integração de ferramentas da Assistants API em um único endpoint. A Assistants API legada está programada para ser descontinuada em 26 de agosto de 2026.

Além disso, os Structured Outputs, que garantem que as saídas do modelo aderem estritamente a um esquema JSON, demonstram seu verdadeiro potencial quando combinados com a Responses API. Desde seu lançamento em agosto de 2024, melhoraram significativamente a confiabilidade dos workflows agentic e dos pipelines de extração de dados.

Este artigo primeiro descreve o panorama geral da API da OpenAI em 2025, depois mergulha nas especificações e detalhes de implementação desses dois tópicos principais.

Informações de Origem
As especificações e dados de desempenho neste artigo referem-se à Documentação Oficial da OpenAI (developers.openai.com/api), ao Guia Oficial de Migração (developers.openai.com/api/docs/guides/migrate-to-responses), e ao Blog Oficial (openai.com/index/introducing-structured-outputs-in-the-api).

1. Visão Geral do Panorama de APIs

As principais categorias da API da OpenAI em 2025 são organizadas da seguinte forma:

A OpenAI posicionou a Responses API como o destino principal para novos recursos, e a descontinuação da Assistants API em 26 de agosto de 2026 foi oficialmente confirmada (Fonte: Guia Oficial de Migração). Embora a Chat Completions API continue a ser suportada sem data de descontinuação, a Responses API é a recomendação atual para novos projetos.

Os Structured Outputs não são um endpoint independente como os da tabela acima, mas sim uma opção de controle de formato de saída disponível tanto para a Responses API quanto para a Chat Completions API. É especificado usando o parâmetro text.format na primeira e o parâmetro response_format na segunda. Este artigo foca particularmente em sua combinação com a Responses API.

2. Responses API

2.1 Visão Geral

A Responses API é uma nova primitiva que sucede a Chat Completions API e integra os recursos da Assistants API. Atingiu Disponibilidade Geral (GA) em março de 2025.

A mudança mais significativa é a capacidade de persistir o estado da conversa no lado do servidor. Diferente das Chat Completions tradicionais, que exigiam incluir todo o histórico da conversa em cada requisição, a Responses API permite continuar uma conversa simplesmente passando um previous_response_id.

2.2 Requisição Básica

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Qual é o clima em Tóquio?",
});

console.log(response.output_text); // Recuperar texto diretamente usando o helper output_text

2.3 O Helper output_text

output_text é uma propriedade de conveniência fornecida pelo SDK da OpenAI, não parte da especificação da API em si.

Na resposta bruta da Responses API, o texto está aninhado na seguinte estrutura:

response.output[0].content[0].text

output_text resume o processo de percorrer esse caminho. Internamente, retorna o texto do primeiro elemento no array output que tem type: "message" e um bloco content com type: "output_text".

// Ambos resultam na mesma saída
console.log(response.output_text);
console.log(response.output[0].content[0].text);

No entanto, pode não funcionar como esperado se o primeiro item no array output não for uma mensagem de texto — por exemplo, quando ocorre uma chamada de ferramenta. Para código agentic robusto que usa ferramentas, é melhor percorrer o array output e verificar o type.

for (const item of response.output) {
  if (item.type === "message") {
    for (const block of item.content) {
      if (block.type === "output_text") {
        console.log(block.text);
      }
    }
  }
}

2.4 role nas Mensagens de Input

Ao passar um array para input, você pode especificar um role para cada mensagem. O role informa ao modelo "quem está fazendo esta declaração", e há três tipos.

const response = await client.responses.create({
  model: "gpt-4o",
  input: [
    {
      role: "system",
      content: "Você é um assistente útil em português. Por favor, responda de forma concisa.",
    },
    {
      role: "user",
      content: "Fale sobre os métodos de array em JavaScript.",
    },
  ],
});

Se você passar uma string diretamente para input (como no exemplo em 2.2), essa string é tratada como uma mensagem com role: "user". Use o formato de array se quiser controle granular sobre o comportamento do modelo ou se quiser fornecer instruções system.

2.5 Estrutura da Resposta

Diferente de choices nas Chat Completions, os resultados são retornados em um array output.

{
  "id": "resp_68af4030...",
  "object": "response",
  "created_at": 1756315696,
  "model": "gpt-4o",
  "output": [
    {
      "id": "msg_68af4033...",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "O clima em Tóquio está ensolarado."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 12,
    "total_tokens": 27
  }
}

2.6 Conversa de Múltiplos Turnos

Há duas maneiras de obter uma conversa de múltiplos turnos com a Responses API.

1. Passando o Histórico como um Array em input

Este é o método tradicional da Chat Completions API. Você mantém e gerencia o histórico da conversa no lado do cliente e inclui todas as mensagens em cada requisição.

const history = [
  { role: "system", content: "Você é um assistente útil." },
  { role: "user", content: "Qual é o clima em Tóquio?" },
  { role: "assistant", content: "Está ensolarado em Tóquio hoje." },
];

const response = await client.responses.create({
  model: "gpt-4o",
  input: [...history, { role: "user", content: "E amanhã?" }],
});

Como o estado não é mantido no servidor, a vantagem é que você pode manipular livremente o histórico, como deletar ou resumir mensagens específicas. No entanto, à medida que a conversa cresce, o número de tokens de input aumenta, impactando tanto o custo quanto a latência.

2. Passando previous_response_id (exclusivo da Responses API)

Este é o método de gerenciamento de estado no servidor recém-introduzido com a Responses API. Passando apenas o ID da resposta anterior, os servidores da OpenAI carregarão o histórico da conversa.

// Primeiro turno
const response1 = await client.responses.create({
  model: "gpt-4o",
  input: "Qual é o clima em Tóquio?",
});

// Segundo turno: Contexto é herdado usando apenas previous_response_id
const response2 = await client.responses.create({
  model: "gpt-4o",
  input: "E amanhã?",
  previous_response_id: response1.id,
});

O cliente não precisa manter ou enviar todo o histórico, mantendo o tamanho da requisição pequeno. Além disso, ao usar modelos de raciocínio como o1 ou o3, os tokens de raciocínio são preservados entre os turnos, o que é uma vantagem significativa pois melhora a precisão para tarefas que requerem raciocínio contínuo.

Para usar este método, a resposta deve ser salva no servidor. Note que enquanto o parâmetro store tem padrão true, definir store: false tornará a referência por ID impossível.

Critérios de Seleção

Se for necessário gerenciamento de conversa persistente, a integração com a Conversations API também é possível.

2.7 Ferramentas Integradas

Um dos maiores benefícios da Responses API é o conjunto de ferramentas integradas disponíveis sem infraestrutura extra.

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Pesquise as últimas notícias da OpenAI e faça um resumo.",
  tools: [
    { type: "web_search_preview" },
    { type: "file_search" },
    { type: "code_interpreter" },
  ],
});

Integração MCP (Model Context Protocol)

Connectors são wrappers MCP mantidos pela OpenAI para serviços populares como Google Workspace ou Dropbox, enquanto Remote MCP servers são qualquer servidor na internet pública que implementa o protocolo MCP remoto (Fonte: Guia de Conectores e MCP da OpenAI).

A Responses API pode se integrar com servidores MCP remotos que suportam os protocolos de transporte HTTP com Streaming ou HTTP/SSE. Quando uma ferramenta é especificada, a API primeiro recupera a lista de ferramentas disponíveis do servidor (mcp_list_tools), e o modelo então chama as ferramentas necessárias dessa lista.

Exemplo de Conexão Básica (Fonte: Guia de Ferramentas da OpenAI)

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Role 2d6 e me diga o resultado.",
  tools: [
    {
      type: "mcp",
      server_label: "dice_server",           // Identificador para o servidor (arbitrário)
      server_url: "https://example.com/mcp", // URL do servidor MCP
      require_approval: "never",             // Aprovar automaticamente chamadas de ferramentas
    },
  ],
});

console.log(response.output_text);

Controle de Aprovação com require_approval

Por padrão, todas as chamadas de ferramentas requerem aprovação explícita do desenvolvedor. Você pode controlar esse comportamento com require_approval (Fonte: Guia de Conectores e MCP da OpenAI).

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Fale sobre os protocolos de transporte da especificação MCP.",
  tools: [
    {
      type: "mcp",
      server_label: "deepwiki",
      server_url: "https://mcp.deepwiki.com/mcp",
      require_approval: {
        never: {
          // Essas duas ferramentas não requerem aprovação; outras sim
          tool_names: ["ask_question", "read_wiki_structure"],
        },
      },
    },
  ],
});

Conectando a Servidores que Requerem Autenticação

Se o servidor MCP requer autenticação, passe o token usando o parâmetro headers.

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Busque alguns dados.",
  tools: [
    {
      type: "mcp",
      server_label: "my_server",
      server_url: "https://my-mcp-server.example.com/mcp",
      require_approval: "never",
      headers: {
        Authorization: `Bearer ${process.env.MCP_ACCESS_TOKEN}`,
      },
    },
  ],
});

Cache da Lista de Ferramentas: Enquanto a recuperação da lista de ferramentas do servidor MCP (mcp_list_tools) ocorre por requisição, em conversas de múltiplos turnos usando previous_response_id, a lista de ferramentas está incluída na resposta anterior, então a re-recuperação é pulada (Fonte: OpenAI Cookbook: Guia de Ferramentas MCP).

2.8 Parâmetros de Requisição Principais

2.9 Comparação com Chat Completions

2.10 Modelos de Raciocínio (série o)

Distintos da série GPT, a OpenAI oferece um grupo de modelos chamados Modelos de Raciocínio. Esses modelos executam um processo de pensamento passo a passo interno (Chain-of-Thought) antes de gerar uma resposta. Esse pensamento interno é contado como tokens de raciocínio, que não são incluídos na saída final.

Eles demonstram precisão significativamente maior que o GPT-4o para tarefas que requerem raciocínio em múltiplas etapas, como matemática, codificação, inferência lógica e análise complexa. Por outro lado, a latência e os custos são maiores porque o raciocínio leva tempo.

Principais modelos em 2025 são:

A profundidade do raciocínio pode ser ajustada com o parâmetro reasoning_effort (veja 2.8). low é um raciocínio leve que reduz latência e custo, enquanto high é um raciocínio profundo para máxima precisão.

const response = await client.responses.create({
  model: "o3",
  input: "Encontre o termo geral para esta sequência: 1, 1, 2, 3, 5, 8, 13, ...",
  reasoning_effort: "high",
});

Além disso, em conversas de múltiplos turnos usando previous_response_id (veja 2.6, método 2), os tokens de raciocínio são persistidos entre os turnos. Ao aprofundar o mesmo problema em múltiplos turnos, a precisão e eficiência melhoram porque o modelo herda o raciocínio do turno anterior em vez de começar do zero.

3. Structured Outputs

3.1 Visão Geral e Contexto

Forçar de forma confiável as saídas de LLM para o formato JSON tem sido um desafio chave para a integração de aplicações. A OpenAI resolveu isso incrementalmente:

Modo JSON (recurso legado) garante JSON sintaticamente correto, mas não garante adesão a um esquema. Havia risco de campos obrigatórios ausentes ou campos adicionais indesejados.

Os Structured Outputs, lançados em agosto de 2024, garantem 100% de adesão a um esquema JSON especificado pelo desenvolvedor (Fonte: Blog Oficial da OpenAI).

Avaliações internas (evals) na OpenAI mostram que o gpt-4o-2024-08-06 atinge 100% de adesão a esquemas JSON complexos usando Structured Outputs, um salto enorme em relação ao menos de 40% do gpt-4-0613 (Fonte: Blog Oficial da OpenAI).

3.2 Como Funciona

A API da OpenAI atinge saídas estruturadas convertendo o JSON Schema especificado em uma Gramática Livre de Contexto (CFG). Essa gramática restringe os tokens que podem ser gerados durante a amostragem, garantindo conformidade com o esquema. Por isso, na primeira vez que um novo esquema é enviado, há latência adicional para pré-processar a gramática, mas requisições subsequentes com o mesmo esquema não incorrem nessa penalidade.

Nota (modelos ajustados fino): Para modelos ajustados fino, latência adicional ocorre na primeira requisição usando um novo esquema. Requisições subsequentes com o mesmo esquema não têm isso. Outros modelos não têm essa limitação. (Fonte: Guia de Structured Outputs)

3.3 Duas Formas de Usar

Os Structured Outputs são fornecidos de duas formas na API.

A primeira é via Function calling (tools), habilitada definindo strict: true dentro da definição de função. Está disponível em todos os modelos a partir do gpt-4-0613 e é adequada para conectar as capacidades do modelo com aplicações (ex.: acessar uma função de consulta a banco de dados).

A segunda é via o parâmetro response_format / text.format, onde especificar um json_schema é adequado para o modelo responder ao usuário em um formato estruturado (ex.: exibindo diferentes partes separadamente em uma UI de tutorial de matemática).

3.4 Exemplo de Implementação (Responses API)

Na Responses API, o parâmetro foi movido de response_format para text.format (Fonte: Guia Oficial de Migração).

Sobre description no Esquema

É fortemente recomendado incluir uma description para cada campo no seu JSON Schema. A description atua como uma instrução para o modelo, fornecendo pistas para ajudá-lo a determinar corretamente o que deve ir naquele campo. Nomes de campos gerais como explanation ou output são particularmente propensos a ser mal interpretados pelo modelo sem uma description.

Ao usar Zod, use .describe("..."). Ao escrever JSON Schema diretamente, especifique-o com a chave "description" dentro do objeto de propriedade.

Definição de Esquema usando Zod (Recomendado)

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const client = new OpenAI();

const Step = z.object({
  explanation: z.string().describe("Explicação do que está sendo feito nesta etapa de cálculo."),
  output: z.string().describe("O resultado do cálculo para esta etapa (fórmula ou valor numérico)."),
});

const MathResponse = z.object({
  steps: z.array(Step).describe("Uma lista de etapas para a solução."),
  final_answer: z.string().describe("A resposta final para a equação (ex.: x = -3.75)."),
});

const response = await client.responses.parse({
  model: "gpt-4o",
  input: [
    { role: "system", content: "Você é um professor de matemática. Explique passo a passo." },
    { role: "user", content: "Resolva 8x + 7 = -23" },
  ],
  text: { format: zodResponseFormat(MathResponse, "math_response") },
});

const result = response.output_parsed;
console.log(result.final_answer);
for (const step of result.steps) {
  console.log(step.explanation, "->", step.output);
}

Especificando JSON Schema Diretamente

const response = await client.responses.create({
  model: "gpt-4o",
  input: [
    { role: "system", content: "Você é um professor de matemática." },
    { role: "user", content: "Resolva 8x + 7 = -23" },
  ],
  text: {
    format: {
      type: "json_schema",
      name: "math_response",
      strict: true,
      schema: {
        type: "object",
        description: "Uma resposta mostrando a solução passo a passo de uma equação.",
        properties: {
          steps: {
            type: "array",
            description: "Uma lista de etapas para a solução.",
            items: {
              type: "object",
              properties: {
                explanation: {
                  type: "string",
                  description: "Explicação do que está sendo feito nesta etapa de cálculo.",
                },
                output: {
                  type: "string",
                  description: "O resultado do cálculo para esta etapa (fórmula ou valor numérico).",
                },
              },
              required: ["explanation", "output"],
              additionalProperties: false,
            },
          },
          final_answer: {
            type: "string",
            description: "A resposta final para a equação (ex.: x = -3.75).",
          },
        },
        required: ["steps", "final_answer"],
        additionalProperties: false,
      },
    },
  },
});

Nota: O campo correto na Responses API é text.format. A chave antiga response_format está depreciada na Responses API (Fonte: Comunidade de Desenvolvedores OpenAI).

3.5 Structured Outputs em Function Calling

Para aplicar Structured Outputs a uma chamada de ferramenta, adicione strict: true à definição da função.

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Me diga a data de entrega do pedido #12345",
  tools: [
    {
      type: "function",
      name: "get_delivery_date",
      description: "Obter a data de entrega programada para um pedido.",
      strict: true,
      parameters: {
        type: "object",
        properties: {
          order_id: { type: "string" },
        },
        required: ["order_id"],
        additionalProperties: false,
      },
    },
  ],
});

Restrição: Ao usar Structured Outputs para Function Calling, parallel_tool_calls deve ser definido como false.

3.6 O Que os Structured Outputs Garantem (e o Que Não Garantem)

Exemplo de tratamento de refusal:

const response = await client.responses.parse({
  model: "gpt-4o",
  input: [/* ... */],
  text: { format: zodResponseFormat(MathResponse, "math_response") },
});

if (response.output[0].content[0].type === "refusal") {
  console.log("Modelo recusou:", response.output[0].content[0].refusal);
} else {
  const result = response.output_parsed;
}

3.7 Restrições de Esquema no modo strict

No modo strict: true, alguns recursos do JSON Schema são restritos (Fonte: Guia de Structured Outputs).

• additionalProperties: false é obrigatório.
• Todas as propriedades devem ser incluídas no array required.
• O uso direto de anyOf no objeto raiz não é permitido.
• Restrições se aplicam a combinações como oneOf, anyOf, etc.

Para evitar discrepâncias entre esquemas e definições de tipos, a OpenAI recomenda oficialmente e com veemência usar o SDK com suporte nativo ao Zod.

4. Realtime API

A Realtime API, que atingiu Disponibilidade Geral (GA) em 2025, é uma API especializada para streaming bidirecional de voz e texto com baixa latência via WebRTC, WebSocket ou SIP. É projetada para casos de uso de interação em tempo real, como agentes de voz conectados diretamente de um navegador ou integração com sistemas de telefonia (PBX), distinguindo claramente seu uso da Responses API. Para mais detalhes, consulte o Guia Oficial da Realtime API.

5. Streaming

A Responses API suporta streaming no formato Server-Sent Events (SSE), permitindo receber respostas longas de forma incremental.

const stream = await client.responses.stream({
  model: "gpt-4o",
  input: "Me fale em detalhes sobre o início do universo.",
});

for await (const event of stream) {
  if (
    event.type === "response.output_text.delta" &&
    event.delta
  ) {
    process.stdout.write(event.delta);
  }
}

Os Structured Outputs também podem ser combinados com streaming; nesse caso, um JSON completo e em conformidade com o esquema é retornado no final.

6. Cabeçalhos de Resposta HTTP

As respostas da API incluem cabeçalhos úteis para depuração e monitoramento de rate limits.

Se você quiser especificar um ID de requisição do lado do cliente, adicione o cabeçalho X-Client-Request-Id.

7. Rate Limits

Os rate limits são aplicados por Organização e Projeto (não por usuário).

• RPM (Requests Per Minute): Número de requisições por minuto.
• TPM (Tokens Per Minute): Número de tokens por minuto.

Os níveis de uso são atualizados automaticamente com base em pagamentos acumulados e histórico de uso. Se 429 Too Many Requests for retornado, recomenda-se fazer retry com backoff exponencial (Fonte: Guia de Rate Limits).

import retry from "async-retry";

async function callApiWithBackoff(params) {
  return retry(
    async () => {
      return await client.responses.create(params);
    },
    {
      retries: 6,
      minTimeout: 1000,
      maxTimeout: 60000,
      randomize: true,
    }
  );
}

8. Estabilidade de Versão e Fixação de Modelo

Aliases como gpt-4o são periodicamente atualizados para novos snapshots, o que pode mudar a saída mesmo para o mesmo prompt. Em produção, recomenda-se fixar um nome de snapshot como gpt-4o-2024-08-06 e sempre realizar avaliação (eval) ao atualizar.

Resumo

Links Úteis

• Guia de Migração para a Responses API — Guia Oficial de Migração.
• Guia de Structured Outputs — Guia Oficial de Structured Outputs.
• Introduzindo Structured Outputs na API — Blog oficial de lançamento.
• Guia da Realtime API — Detalhes sobre voz e texto bidirecionais em tempo real.
• Guia de Rate Limits — Detalhes sobre rate limits.
• OpenAI Changelog — Histórico de atualizações da API.