> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wangenhui.top/llms.txt
> Use this file to discover all available pages before exploring further.
# Response API Explained: The Next-Gen Model Interface
> A deep dive into OpenAI's Response API: core concepts, how it differs from Chat Completions, when to use it, and migration best practices.
The Response API is OpenAI's next-generation model interface, purpose-built for stateful, multi-turn, tool-orchestrated AI applications. Compared to the classic Chat Completions API, it unifies conversation state, tool calls, reasoning, and multimodal input into a simpler and more powerful programming model.
## What is the Response API
The Response API (`/v1/responses`) is the unified model endpoint OpenAI shipped in 2025. It consolidates capabilities that used to be spread across Chat Completions, Assistants, and Tools into a single call, so a single request can handle:
* Multi-turn conversation and context management
* Built-in tools (web search, file search, code interpreter, computer use)
* Custom function calling
* Reasoning traces from reasoning models (the o-series)
* Multimodal input and output (text, images, audio)
## Key differences from Chat Completions
Chat Completions requires you to resend the full history on every request. The Response API lets you continue from the last response via `previous_response_id`, and manages context server-side.
Chat Completions uses a `messages` array. The Response API uses a single `input` field that accepts a string, a message array, or a multimodal payload with images and files.
The Response API natively supports hosted tools such as `web_search`, `file_search`, `code_interpreter`, and `computer_use`, so you no longer need to build them yourself.
For reasoning models like o1 and o3, the Response API returns explicit `reasoning` items in the output, making the chain of thought easy to inspect and debug.
## The simplest possible call
```bash cURL theme={null}
curl https://api.openai.com/v1/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4.1",
"input": "Explain quantum entanglement in one sentence."
}'
```
Key fields in the response:
* `id`: unique ID for this response, usable to continue the conversation
* `output`: array of items the model produced (text, tool calls, reasoning)
* `output_text`: convenience field with all text items concatenated
* `usage`: token accounting
## Multi-turn conversations without manual history
The old pattern required resending the full `messages` array every turn. With the Response API you just pass the previous `id`:
```python Python theme={null}
from openai import OpenAI
client = OpenAI()
first = client.responses.create(
model="gpt-4.1",
input="Recommend three science-fiction novels."
)
second = client.responses.create(
model="gpt-4.1",
previous_response_id=first.id,
input="Which one is the shortest, and roughly how long is it?"
)
print(second.output_text)
```
The server automatically threads in the previous context, so the client is simpler and you avoid paying for repeated tokens.
## Built-in tools: web search in one line
```python Python theme={null}
response = client.responses.create(
model="gpt-4.1",
tools=[{"type": "web_search"}],
input="Who won the 2026 Nobel Prize in Physics?"
)
print(response.output_text)
```
You don't need to run a search service, scrape pages, or stitch citations together. The model decides when to search and how to weave results into its answer. `file_search` (RAG over uploaded files), `code_interpreter` (sandboxed execution), and `computer_use` (browser and desktop control) work the same way.
## Streaming output
The Response API streams structured Server-Sent Events, which is easier to consume than Chat Completions' raw deltas:
```python Python theme={null}
stream = client.responses.create(
model="gpt-4.1",
input="Write a short poem about autumn.",
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
**Good fits for the Response API**
* Building agents or multi-step task flows
* Needing hosted tools like web search, file search, or code execution
* Using reasoning models (o1, o3) and wanting to inspect the chain of thought
* Wanting to simplify multi-turn state management
**Reasons to stay on Chat Completions for now**
* You have a large codebase built on `messages` and no immediate migration payoff
* You only need stateless, one-shot completions with no tools
* You depend on a third-party wrapper that hasn't adopted the Response API yet
## Migration guide
Replace `/v1/chat/completions` with `/v1/responses` and rename `messages` to `input`.
Stop persisting full histories on the client. Keep only the most recent `response.id`.
Evaluate whether your custom search, RAG, or code execution can be replaced with `web_search`, `file_search`, or `code_interpreter`.
If you use streaming, switch delta parsing to a dispatch based on `event.type`.
## Summary
The Response API collapses model, tools, state, and multimodality into a single interface, and it's OpenAI's recommended entry point for the agent era. Start new projects on it directly; migrate existing ones feature by feature, prioritizing the complexity savings from hosted tools and server-side state.