OpenAI Responses API vs Chat Completions: Migration Guide (2026)

Last verified: July 24, 2026

Short path: Compare the endpoints, then decide whether you need provider-managed response state or a stable OpenAI-compatible request path. Start with the OpenAI-compatible API guide · LumeAPI OpenAI-compatible API · AI API pricing.

The OpenAI Responses API vs Chat Completions decision is not really about which endpoint has a nicer JSON shape. It is about where your application keeps state, how much migration risk you can tolerate, and whether your production traffic needs to remain on an OpenAI-compatible Chat Completions interface.

If your app already has reliable conversation storage, tool execution, tracing, and retry handling around Chat Completions, do not rewrite it just because Responses is newer. Move when Responses-specific state and workflow primitives remove code you actually maintain. Otherwise, reducing repeated context and changing your model route will usually move the bill more than changing endpoints.

Quick Answer

In short

The right default is conservative: do not migrate a working Chat Completions integration solely because the Responses API exists. Responses can reduce state-management work for teams that benefit from its native response chaining, but it is not a universal cost optimization.

The expensive failure mode is usually simpler: your agent keeps replaying a growing transcript, tool schemas, and old tool results on every call. Fix that first. Then choose the endpoint whose state model matches your architecture.

What most guides get wrong

The common myth is that the Responses API automatically makes an application cheaper because it is newer and more stateful.

That skips the actual billing mechanism. A model invoice is driven by processed input and generated output tokens, not by whether your HTTP request says /chat/completions or /responses. If your current Chat Completions service sends a 30-message history plus two large tool results on every turn, that is expensive. If you migrate and still construct large prompts, preserve every verbose tool payload, or retry failed work without idempotency, it stays expensive.

Responses can change where state is represented. That may reduce application code and make a workflow easier to reason about. But it does not excuse poor context discipline.

The reverse mistake is also common: teams stay on Chat Completions while manually rebuilding the entire conversation, including irrelevant debugging output, because “stateless means portable.” Portability is useful. Re-sending a 60 KB JSON blob seven times is not.

A realistic production scenario

Nina maintains a support-triage service built with Python, PostgreSQL, Redis, and an internal tool that looks up subscription status. The service uses Chat Completions with gpt-5.6-terra. Every customer reply loads the full ticket transcript, the system prompt, three tool schemas, and the last two raw billing-tool responses.

The classifier itself produces roughly 250 output tokens. By Thursday, the team sees requests averaging more than 12,000 input tokens because a failed lookup is retried, then its full JSON error object is included in the next turn. Someone proposes a Responses migration because “state will fix it.”

It will not fix the retry loop. Nina first stores a compact ticket summary, caps tool output passed back to the model, and assigns an idempotency key before retrying the lookup. Input volume falls before the endpoint changes. At that point, a Responses proof of concept becomes an architectural choice, not an emergency billing patch.

Expert take

Chat Completions and Responses represent two different application boundaries.

With Chat Completions, your application generally constructs the message history sent to the model. That can feel repetitive, but it gives you direct control over what crosses the request boundary. You can summarize, redact, truncate, store a canonical transcript in your database, and send only the context needed for the next decision. It is also the request shape supported by many OpenAI-compatible services.

With the Responses API, you adopt OpenAI’s newer response-oriented interface and can use its native mechanisms for carrying work forward. Read the current Responses API reference and migration guide before treating it as a drop-in replacement. Your message objects, tool-call handling, response parsing, stored identifiers, observability fields, and test fixtures may all need changes.

Use Responses when its native workflow model removes a meaningful amount of code you own: for example, a product that has many multi-turn operations and wants to standardize around provider-native response chaining.

Do not follow this advice blindly when portability is the requirement. If your application must route compatible Chat Completions traffic across approved models or gateways, keeping a clean Chat Completions boundary is often the lower-risk choice. LumeAPI is an independent third-party gateway, not OpenAI, Anthropic, or Google, and it should not be assumed to provide identical behavior for every provider-native endpoint or feature.

OpenAI Responses API vs Chat Completions: the practical differences

The endpoint choice affects application architecture more than it affects raw per-token pricing.

For the canonical request formats, use OpenAI’s Chat Completions API reference and Responses documentation rather than copying old SDK snippets from blog posts. Endpoint-level changes are exactly where stale examples cause a broken release.

Where the migration effort actually lands

The transport layer is the easy part. Most teams can change an endpoint in minutes. The work appears in the code that assumes a Chat Completions-shaped response.

1. Replace message construction with an input boundary

A typical Chat Completions service has a function that accepts messages like:

• system instructions
• prior user and assistant turns
• tool-call messages
• tool outputs
• retry annotations

A Responses integration needs a new adapter. Do not scatter conditional endpoint logic across route handlers. Create one model-service boundary that accepts your application’s canonical turn format and produces your application’s canonical result format.

That lets you run both endpoint implementations during the migration without making every controller aware of provider response details.

2. Rebuild tool-call parsing and retries

The risky migration point is not “can the model call a tool?” It is “what happens after the third tool call fails halfway through a customer workflow?”

Audit these behaviors before switching:

• How your code identifies a tool invocation.
• Where arguments are validated.
• Whether a tool execution is idempotent.
• How the model receives a compact tool result.
• How partial failures are recorded.
• Whether a retry replays a charge, email, write operation, or external API mutation.
• How you preserve an audit trail for support staff.

Do not pass raw exception dumps back to the model by default. Convert them into a short structured error such as ACCOUNT_NOT_FOUND, preserve the full trace in your logs, and decide whether the next model call needs the detail.

3. Make state ownership explicit

Responses can be attractive because the provider can carry response context forward. That is useful, but it changes the failure question from “did we persist this conversation?” to “can this request resume safely with the state reference we retained?”

Document the answer for:

• user deletion requests
• retention windows
• incident replay
• multi-region recovery
• provider outage handling
• switching models or providers later

If your product already stores a canonical conversation summary and task state in PostgreSQL, Chat Completions may remain cleaner. The transcript is yours, portable, and inspectable. You can still cut token use by sending summaries rather than full history.

Responses API cost vs Chat Completions: model math, not endpoint magic

For a fair comparison, hold the model and workload constant. The following scenario assumes a service uses gpt-5.6-terra for 10 million input tokens and 2 million output tokens per month.

The calculation is:

monthly cost = (input tokens ÷ 1,000,000 × input rate)
             + (output tokens ÷ 1,000,000 × output rate)

The rate comparison uses the catalog pricing dated July 22, 2026. Confirm the current official reference rate on OpenAI API pricing before committing a budget.

The important part: neither row becomes cheaper merely because the application uses Responses instead of Chat Completions. If a Responses implementation reduces billed input by reducing repeated context, calculate that separately.

For example, if compact state management cuts the same workload from 10 million to 6 million input tokens:

Output tokens still matter. A verbose agent that produces long tool plans, repeated explanations, or speculative answers can make output pricing dominate. Track input and output separately; a single “cost per request” metric hides the problem.

A migration checklist before you change production traffic

Use this checklist for an OpenAI Responses API migration rather than treating it as a one-file refactor.

1. Write a canonical internal task format. Keep user input, approved context, tool definitions, and expected output separate from either API’s wire format.
2. Capture baseline metrics. Record request count, input tokens, output tokens, tool calls per task, retry count, task completion rate, and failure classes.
3. Build an endpoint adapter. Keep the rest of the application unaware of Chat Completions or Responses-specific response objects.
4. Replay safe production-like fixtures. Use redacted, deterministic cases: plain Q&A, tool success, tool timeout, malformed tool arguments, and multi-turn continuation.
5. Set idempotency rules before retries. A retry policy must know whether an external side effect already happened.
6. Run a small shadow evaluation. Compare completion quality, parse failures, tool-call correctness, and total tokens per completed task—not just first-call latency.
7. Keep rollback simple. A feature flag should return traffic to the existing Chat Completions adapter without changing stored business state.
8. Review data handling. Confirm what conversation and response identifiers you retain, delete, and expose to support staff.

Most migration guides skip step five. That is the one that turns a model timeout into duplicate invoices, duplicate emails, or repeated writes.

Keep a portable Chat Completions path with LumeAPI

If you decide that Responses is not worth the migration work today, you can still reduce cost while preserving your existing Chat Completions integration. LumeAPI uses an OpenAI-compatible Chat Completions endpoint at https://api.lumeapi.site/v1.

This curl request uses the catalog model ID gpt-5.6-terra:

curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {
        "role": "system",
        "content": "You classify support tickets. Return a concise category and priority."
      },
      {
        "role": "user",
        "content": "My invoice shows two charges for the same subscription."
      }
    ]
  }'

For a Python service, keep the base URL and model choice in configuration rather than hard-coding them across workers:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LUMEAPI_KEY"],
    base_url="https://api.lumeapi.site/v1",
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[
        {
            "role": "system",
            "content": (
                "Classify the ticket. Return JSON with category, priority, "
                "and a one-sentence rationale."
            ),
        },
        {
            "role": "user",
            "content": "Our account was charged twice after upgrading.",
        },
    ],
)

print(response.choices[0].message.content)

Before deploying, validate the exact SDK version and parameter behavior against the official OpenAI Python library documentation. Compatibility at the Chat Completions request layer does not mean every native provider feature, beta endpoint, or streaming behavior is automatically interchangeable.

For a fuller implementation pattern, see the OpenAI-compatible Python example and the guide on how to switch from the OpenAI API to a compatible gateway.

A decision rule that prevents pointless rewrites

Use this rule:

• Choose Responses when provider-native response state eliminates enough custom workflow code to justify changing your adapters, tools, tests, and operational runbooks.
• Keep Chat Completions when your application already has good state ownership, you need OpenAI-compatible routing, or a migration would mostly rename fields without reducing context or operational complexity.
• Reduce token waste first when the same prompt history, tool schemas, and tool payloads are being sent repeatedly.
• Change model economics separately from endpoint architecture. A model route can cut cost without requiring a state-model rewrite.

A useful test is to ask one blunt question: “If we migrated tomorrow, which specific request would contain fewer tokens or require less code?” If the answer is vague, do not schedule the migration yet.

FAQ

Is OpenAI Responses API vs Chat Completions cheaper for the same model?

No. For the same model and the same input and output token volume, the endpoint itself is not the cost driver. Savings come when the new state pattern reduces duplicated context, unnecessary tool output, retries, or generated output.

Should I migrate Chat Completions to Responses API for a new application?

Usually, yes—if the application is intentionally built around OpenAI’s current native response workflow and you accept that dependency. For a product that requires an OpenAI-compatible gateway boundary or multi-provider portability, start with a clean Chat Completions adapter instead.

Can I use the Responses API through LumeAPI?

Do not assume that you can. LumeAPI’s provided gateway contract is OpenAI-compatible Chat Completions at https://api.lumeapi.site/v1; it does not promise Responses API compatibility or parity with every native OpenAI feature.

What should I measure before an OpenAI Responses API migration?

Measure input tokens, output tokens, tool calls per completed task, retry count, parse failures, completion quality, and the amount of conversation or tool data repeated on each request. A migration decision without this baseline is mostly guesswork.

Does provider-managed response state replace my application database?

No. You still need application-owned records for users, permissions, business actions, audit trails, retention policies, and support workflows. Provider-managed response state can simplify model workflow continuation, but it is not a replacement for product state.

When should I avoid moving away from Chat Completions?

Avoid a migration when your existing Chat Completions layer is stable, your application already compacts and persists context well, and the main motivation is “the newer endpoint must cost less.” That assumption is not a budget model.

Next steps

1. Instrument one representative workflow and separate input-token, output-token, tool-result, and retry costs for seven days.
2. Build a small Responses adapter behind a feature flag, then compare completed-task quality and token volume against your existing Chat Completions path.
3. If Chat Completions remains the better operational fit, price the same workload through the LumeAPI OpenAI-compatible API using gpt-5.6-terra before committing to a larger rewrite.