Response API primer: a deep dive into the next-generation model interaction interface

The Response API is OpenAI’s next-generation model interaction interface, built for stateful, multi-turn, multi-tool AI applications. Compared with the traditional Chat Completions API, it unifies conversation state, tool calls, reasoning traces, and multi-modal input into a simpler, more powerful programming model.

What is the Response API

The Response API (/v1/responses) is OpenAI’s unified model-invocation interface, introduced in 2025. It consolidates capabilities that used to be scattered across Chat Completions, Assistants, and Tools APIs, letting you do all of the following in a single call:

Multi-turn conversation and context management
Built-in tool calls (web search, file search, code interpreter, computer use, and more)
Custom function calls
Chain-of-thought output from reasoning models (such as the o series)
Multi-modal input and output for text, images, and audio

Core differences from Chat Completions

Stateful vs stateless

Chat Completions requires you to send the full message history on every request. The Response API lets you continue from the previous response directly with previous_response_id, and the server manages the context for you.

Unified input structure

Chat Completions uses a messages array. The Response API uses an input field, which can be a string, a message array, or a multi-modal structure with images and files.

Built-in tools

The Response API natively supports managed tools like web_search, file_search, code_interpreter, and computer_use, so you do not have to implement them yourself.

Transparent reasoning

For reasoning models such as o1 and o3, the Response API returns explicit reasoning items in the output, making them easy to trace and debug.

The simplest possible call

cURL

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": "用一句话解释什么是量子纠缠。"
  }'

Key fields in the response:

id: A unique ID for this response, used for continuations
output: An array of content items generated by the model (text, tool calls, reasoning, and so on)
output_text: A convenience field with all text content concatenated
usage: Token consumption statistics

Multi-turn conversation: no more manual history stitching

Traditionally you send the full messages on every turn. The Response API only needs the previous id:

Python

from openai import OpenAI

client = OpenAI()

first = client.responses.create(
    model="gpt-4.1",
    input="推荐三本科幻小说。"
)

second = client.responses.create(
    model="gpt-4.1",
    previous_response_id=first.id,
    input="其中最短的那本大概多少字？"
)

print(second.output_text)

The server automatically brings in the context of the previous turn, simplifying client logic and reducing duplicated token billing.

Built-in tools: enable web search in one line

Python

response = client.responses.create(
    model="gpt-4.1",
    tools=[{"type": "web_search"}],
    input="2026 年诺贝尔物理学奖得主是谁？"
)

print(response.output_text)

You do not need to maintain your own search service, scrape pages, or stitch citations together. The model decides when to search and how to combine results. Similar built-ins include file_search (RAG over uploaded files), code_interpreter (sandboxed code execution), and computer_use (browser/desktop control).

Streaming output

The Response API uses an event stream (Server-Sent Events) that returns structured events, which are easier to parse than the deltas in Chat Completions:

Python

stream = client.responses.create(
    model="gpt-4.1",
    input="写一首关于秋天的短诗。",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Common event types include response.created, response.output_text.delta, response.tool_call.created, and response.completed.

When to use the Response API

Recommended scenarios for the Response API

Building agents or multi-step task applications
Needing managed tools such as web search, file retrieval, and code execution
Using reasoning models like o1 or o3 and wanting to inspect the chain of thought
Wanting to simplify multi-turn conversation state management

When to stay on Chat Completions for now

You already have a large codebase built around the messages structure with no short-term migration payoff
You only need one-shot, stateless completions and no tools
You depend on third-party wrappers that have not yet migrated to the Response API

Migration guidance

Replace the endpoint

Change /v1/chat/completions to /v1/responses, and rename messages to input.

Manage sessions with previous_response_id

Stop keeping the full history on the client. Store only the most recent response.id.

Replace in-house capabilities with built-in tools

Evaluate whether your custom search, RAG, and code execution can be swapped directly for web_search, file_search, and code_interpreter.

Adapt to the new event stream

If you use streaming, switch from delta parsing to dispatching on event.type.

Summary

The Response API converges “model + tools + state + multi-modality” into a single interface and is OpenAI’s flagship entry point for the agent era. For new projects, start directly with the Response API. For existing projects, migrate incrementally by module and take advantage of built-in tools and state management first to cut down complexity.

Guides

Codex and Harness

Response API primer: a deep dive into the next-generation model interaction interface

What is the Response API

Core differences from Chat Completions

Stateful vs stateless

Unified input structure

Built-in tools

Transparent reasoning

The simplest possible call

Multi-turn conversation: no more manual history stitching

Built-in tools: enable web search in one line

Streaming output

When to use the Response API

Migration guidance

Summary

​What is the Response API

​Core differences from Chat Completions

Stateful vs stateless

Unified input structure

Built-in tools

Transparent reasoning

​The simplest possible call

​Multi-turn conversation: no more manual history stitching

​Built-in tools: enable web search in one line

​Streaming output

​When to use the Response API

​Migration guidance

​Summary

What is the Response API

Core differences from Chat Completions

The simplest possible call

Multi-turn conversation: no more manual history stitching

Built-in tools: enable web search in one line

Streaming output

When to use the Response API

Migration guidance

Summary