Responses API vs Chat Completions: Differences and a Practical Migration Guide (2026)

OpenAI recommends the Responses API for all new projects while stating clearly that Chat Completions remains supported. The two endpoints will coexist, but they differ in field structure, state management, and the tool system. This guide breaks the differences into four dimensions, shows the exact code to change when migrating, and ends with a per-scenario decision table — every example runs as-is against EXAIV's endpoints.

Definition: The Responses API is OpenAI's unified interface introduced after Chat Completions: input goes in an input array, output is a typed list of output items, conversation state is stored server-side by default (store), and hosted tools like web search, file search, and code interpreter are built in. Chat Completions is a stateless protocol: each request carries the full messages history and your client owns the context.

The core differences in one table

Code comparison: same task, two shapes

Chat Completions (EXAIV endpoint /api/ai/v1/chat/completions):

curl https://exaiv.com/api/ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      { "role": "user", "content": "Explain what an AI gateway is in one sentence." }
    ]
  }'

Responses API (EXAIV endpoint /api/ai/v1/responses):

curl https://exaiv.com/api/ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-6-sol",
    "input": "Explain what an AI gateway is in one sentence."
  }'

At the SDK level: client.chat.completions.create(...) becomes client.responses.create(...), and reading the result changes from completion.choices[0].message.content to response.output_text. Full parameter references: Chat Completions and Responses.

Migrating in four steps

1. messages → input: plain-text requests pass a string; requests with history rename the messages array to input, keeping role/content structure.
2. Change the result path: choices[0].message.content → iterate output filtering for type === "message", or use the SDK's output_text convenience field.
3. Move system prompts to instructions: the Chat role: "system" message has a dedicated top-level parameter in Responses.
4. Rewrite tool definitions: the two function-definition formats are similar but not identical — verify field by field. Responses' hosted tools (web_search etc.) are enabled by name, no orchestration loop required.

Which one to use, by scenario

EXAIV offers both endpoints under the same API key, so you don't have to pick a side permanently: keep existing traffic on Chat Completions, build new features on Responses, and switch underlying models from the models page.

Why two interfaces exist

The evolution context helps the decision. Chat Completions was OpenAI's early interface; because of its simple shape and provider-agnostic structure it became the de-facto standard the whole industry copied — nearly every model vendor today serves a messages-style compatible endpoint. The Responses API is OpenAI's redesign for the agent era: "the model may need to do several things" (call tools, search, run code) is a first-class concept built into the interface layer, with state management and tool execution moved back to the server. The two target different scenarios — which is exactly why they coexist.

Parameter mapping quick reference

The correspondences you'll reach for most when migrating:

Exact fields live in the reference docs; verify one by one during migration.

State management in depth: store and previous_response_id

This is the deepest philosophical difference between the generations. Chat Completions assumes "the server remembers nothing": every turn you resend the full history, and context-window management and cost control live in your client. The Responses API stores the conversation server-side by default (store: true); the next turn only references previous_response_id, and the server continues with the full conversation and tool context intact.

Practical consequences:

• Less code: modules that maintained the messages array, trimmed history, and compacted context can be deleted
• Fewer tokens: the server reuses existing context; the cost of resending disappears
• Mind compliance: conversation data lives server-side; teams with data-residency requirements can set store: false at the cost of returning to full-resend mode

Five common migration pitfalls

1. Empty results: the result path wasn't changed — content now lives in output, not choices[0].message.content
2. Tool calls silently failing: tool definition formats differ between generations; copying fields verbatim fails quietly — verify each one
3. Broken streaming: SSE event types are completely different; delta logic does not map onto response.output_text.delta
4. Errors on multiple candidates: n is removed in Responses; multi-candidate logic needs a rewrite or should stay on Chat
5. State leaks: store defaults to true, so test data gets persisted — data-sensitive scenarios should disable it explicitly

FAQ

Streaming migration, event by event

The event names are where most migration time actually goes. The mapping at a glance:

Two structural differences to internalize: Chat deltas are anonymous fragments you assemble yourself, while Responses events name what they carry; and in Responses, a multi-tool turn is one request lifecycle rather than several request/response round-trips. Your SSE parser, retry logic, and timeout handling all need to be rewritten against the new event names — this is the part of the migration that always costs more than estimated.

Using Responses through a gateway

Three things worth knowing when the endpoint is proxied:

• Hosted tools execute upstream: web search, code interpreter and friends run on OpenAI's side; the gateway forwards the request and streams the result back untouched
• Server-side state stays upstream: previous_response_id references stored state on OpenAI's side; the gateway transparently relays it
• Your key and billing are the gateway's: one EXAIV key works for both endpoints, usage is billed per model and token regardless of endpoint — check pricing for live rates

The pre-migration checklist

Five questions, in order — stop at the first "no" and fix that layer first:

1. Does a plain-text call work on the new endpoint (no tools, no streaming)?
2. Does the result-reading path return text (not undefined)?
3. Do tool definitions parse without schema errors?
4. Does one full tool round-trip complete (call → execute → continue)?
5. Does streaming render end-to-end with the new event names?

A realistic migration timeline

For a mid-sized codebase with tools and streaming, here is what a calm, three-day migration actually looks like:

Day one — text only. Point a copy of one flow at the new endpoint. messages becomes input, the result path becomes output_text. Run your existing test suite. Most teams find plain-text calls pass with no surprises; the goal today is only to prove the transport works.

Day two — tools. Rewrite one tool definition in the new format and run the full round-trip: model requests the call, you execute it, you continue the same turn. Expect to spend most of the day here — this is the field-mapping work the tables above warn about. Verify tool errors surface correctly, not silently.

Day three — streaming. Swap the SSE parser over to the named events. Render end-to-end in your real UI. Retries and timeouts get adjusted against live behavior, not assumptions.

What this timeline deliberately avoids: migrating every flow at once, rewriting orchestration that could stay on Chat Completions for another quarter, and testing streaming last on a Friday. Traffic can shift flow by flow — via a gateway, per request — while both endpoints run in parallel.

FAQ

FAQ

Related reading

• Chat Completions API reference
• Responses API reference
• Anthropic Messages API reference