Moving an app or agent from OpenAI to Claude: the request mapped field by field, the changes that return a 400, cost per task, and how to test it.
To switch from OpenAI to Claude, move your requests from Chat Completions or the Responses API to Anthropic's Messages API. Then test the agent's behavior, not just its answers. The API differences are well documented and take a day to fix. The rest takes longer: Claude may call different tools with different arguments, and that only shows up when you replay real runs on both models and diff the results.
Most of what breaks in the move is not in the obvious places:
- +
tool_choice: "required"has no direct equivalent on the newest Claude models. Claude Opus 5.5, Sonnet 5.5 and Fable 5.2 return a 400 for forced tool use. You useautowith strict tools and say in the prompt when the tool applies. - +
temperatureis gone. On API version2026-10-21, the default in the new Anthropic SDK majors, a request that sendstemperature,top_portop_kreturns a 400 on every Claude model, even at the default value. - +Tool calls and results change shape. Claude returns tool arguments as an object, not a JSON
string. Results go back as
tool_resultblocks inside a user message, and the thinking blocks from the assistant turn must be sent back unchanged. - +Same list price is not same cost. Claude Sonnet 5.5 and GPT-6.2 Sol both cost $2 and $10 per million tokens. Tokenizers, thinking tokens and caching rules differ, so the bill per task does not match.
This post maps an OpenAI request to Claude field by field and covers each change that can break an app or agent. It ends with a six-step migration whose core is replaying recorded runs on both models. The facts come from Anthropic's and OpenAI's API docs, read on November 18, 2026. Check the linked pages before you rely on a price or a model name, because both companies changed theirs in 2026.
A disclosure: I build EvalShift, a tool for testing model changes on agents. It has a short section near the end. Everything before it works without it.
OpenAI vs Claude API: the request mapped field by field #
| OpenAI (Chat Completions / Responses) | Claude Messages API | What changes |
|---|---|---|
client.chat.completions.create /client.responses.create |
client.messages.create |
One endpoint, POST /v1/messages |
system ordeveloper message, Responsesinstructions |
top-level system parameter |
System text leaves the message list |
max_completion_tokens , optional |
max_tokens , required |
A request without it fails |
tools: [{type: "function", function: {name, parameters}}] |
tools: [{name, description, input_schema}] |
Schema key renamed, no wrapper |
tool_choice: "required" or a named function |
tool_choice: {type: "any"} or{type: "tool"} |
400 on Opus 5.5, Sonnet 5.5 and Fable 5.2 |
parallel_tool_calls: false |
disable_parallel_tool_use: true insidetool_choice |
Moves into another object |
function.arguments , a JSON string |
tool_use.input , an object |
No json.loads |
role: "tool" message /function_call_output item |
tool_result block in auser message |
Results go in the user turn |
response_format /text.format withjson_schema |
output_config.format withjson_schema |
Different schema limits |
reasoning_effort /reasoning.effort |
output_config.effort with adaptive thinking |
Different levels and defaults |
temperature ,top_p |
none | 400 on API version 2026-10-21 |
finish_reason |
stop_reason |
Adds refusal and_turn |
Chunks with choices[].delta , then[DONE] |
Typed SSE events, no [DONE] |
New stream parser |
Anthropic's Messages API reference ↗ and OpenAI's Chat Completions reference ↗ list every field. The sections below cover the ones that change behavior, not just names.
System prompts become a top-level field #
OpenAI puts instructions in the message list. With recent models they go in a developer message,
which replaced system from o1 on ↗,
or in the Responses API's top-level instructions. Claude takes the system prompt as a separate
system parameter, a string or a list of text blocks, and messages holds only user and
assistant turns.
If your app adds instructions partway through a conversation, Claude has an equivalent. You append
a message with role: "system" to messages, and it applies from that point on. Anthropic's
mid-conversation system messages page ↗
lists the models that support it: Opus 5.5, Sonnet 5.5, Haiku 5.5 and the Fable models, but not
Sonnet 5. Such a message must follow a user turn, and either end messages or be followed by an
assistant turn. On Sonnet 5.5 and Haiku 5.5 one placed right
after a tool result can be read as untrusted text, because those models are trained to resist
prompt injection through tool results.
Two smaller rules come with the move. max_tokens is required on every Claude request, where
OpenAI's max_completion_tokens is optional. And Claude 4.6 and later models reject a conversation
that ends on an assistant turn. Anthropic's error reference ↗
gives the message, "This model does not support assistant message prefill. The conversation must
end with a user message." If you used a partial assistant message to steer the format, use
structured output or a system prompt instruction instead.
Tool calls and tool results change shape #
A tool definition loses its wrapper. OpenAI's Chat Completions nests the schema under
function.parameters, and the Responses API flattens it. Claude takes name, description and
input_schema at the top level. Claude allows tool names up to 128 characters, OpenAI up to 64, so
names carry over unchanged.
The response is where code breaks. OpenAI returns tool arguments as a JSON-encoded string that you
parse. Claude returns a tool_use block whose input is already an object. A json.loads call
left in place raises a TypeError on the first tool call.
Tool results move too. OpenAI expects a role: "tool" message with a tool_call_id, or a
function_call_output item in the Responses API. Claude expects a tool_result block inside the
next user message. Anthropic's tool-call guide ↗
sets three rules an OpenAI-style loop tends to break:
- +One result per call, all in one message. When Claude calls several tools at once, every
tool_resultgoes back together in the next user message. - +Results come first. In that message the
tool_resultblocks come before any text. - +Nothing in between. No message can sit between the assistant's tool call and the user message with the results.
A failed tool gets a tool_result with is_error: true rather than being left out. To limit Claude
to one tool call per turn, set disable_parallel_tool_use: true inside tool_choice. It is not a
top-level parameter like OpenAI's parallel_tool_calls.
Send the thinking blocks back
Current Claude models think before they answer, and a tool-calling turn can contain thinking
blocks next to the tool_use blocks. Anthropic's error reference says to "pass back every
thinking and redacted_thinking block from the assistant turn exactly as received", and an edited
block is rejected. The simplest loop appends the whole response.content as the assistant message
instead of rebuilding it from the text and tool calls. OpenAI asks for the same with reasoning
items in the Responses API, so if your loop already passes those back, keep that pattern.
tool_choice "required" has no equivalent on the newest Claude models #
OpenAI's tool_choice: "required" makes the model call at least one tool, and a named function
forces that tool. Claude's matching options are {"type": "any"} and
{"type": "tool", "name": ...}. On current models they fail. Anthropic's
error reference ↗ says Fable 5.2, Opus 5.5,
Sonnet 5.5 and Fable 5.1 "don't support forced tool use", and the request returns a 400:
tool_choice: type "tool" and "any" are not supported for this model.
Haiku 5.5 still accepts forced tool use. On the other models Anthropic's advice is to "use auto
with strict tool use to keep tool inputs schema-valid, or structured outputs when you need the
response itself in a fixed JSON shape", and to say in the prompt when the tool applies.
This is a behavior change, not only a syntax change. With auto, the model decides whether to call
the tool, so a route that always called lookup_order under OpenAI can now answer without it.
That is exactly the kind of change a replay catches and a read-through of the outputs misses.
Structured output: response_format becomes output_config.format #
OpenAI's Structured Outputs use response_format with a json_schema in Chat Completions and
text.format in the Responses API. Claude uses output_config.format, also with a json_schema
type, and strict: true on a tool for schema-valid tool inputs. The schema rules differ, and a
schema that works on one side can fail on the other.
| Schema rule | OpenAI | Claude |
|---|---|---|
| Optional properties in strict mode | Not allowed, every field must be required |
Allowed, up to 24 across all strict schemas |
| Recursive schemas | Supported | Not supported |
oneOf |
Not listed, use anyOf |
Not supported, use anyOf |
minimum ,maximum |
Supported | Not supported |
minLength ,maxLength |
Not listed, only pattern andformat |
Not supported |
| Strict tools per request | No stated cap | 20 |
Sources: Anthropic's structured outputs page ↗,
OpenAI's function calling ↗ and
structured outputs ↗ guides.
Anthropic also notes that Claude doesn't guarantee the capitalization of string enum values, and
that the first request with a new schema pays a compilation step that is then cached for 24 hours
from last use. Range checks that the schema did for you on OpenAI need to move into your own
validation code.
temperature, top_p and top_k return a 400 #
On October 21, 2026 Anthropic released API version 2026-10-21, which Python SDK 2.0.0 and
TypeScript SDK 1.0.0 send by default. Its migration page ↗
says a request that sends temperature, top_p or top_k "returns a 400 error, even at the
parameter's default value." On the older API version, current models already reject any
non-default value.
If your OpenAI code set temperature=0 for repeatable output, delete it. Anthropic's Opus 5.5
migration guide points out that temperature = 0 "never guaranteed identical outputs" anyway. To
compare models fairly without it, run each case several times rather than once. OpenAI is moving the
same way: its GPT-6.2 guide says to omit temperature and top_p when migrating Chat Completions
requests.
Reasoning effort becomes thinking and effort #
OpenAI controls reasoning with reasoning_effort in Chat Completions or reasoning.effort in the
Responses API. Claude uses adaptive thinking, where the model decides how much to think, and sets
the depth with output_config.effort: low, medium, high, xhigh or max. The defaults
differ by model, so set the level explicitly instead of relying on them.
| Default effort | Can thinking be turned off? | |
|---|---|---|
| Claude Opus 5.5 | medium |
No, 400 for {"type": "disabled"} |
| Claude Sonnet 5.5 | high |
No, but {"type": "between_tools"} drops up-front thinking |
| Claude Haiku 5.5 | medium |
Yes, {"type": "disabled"} is accepted |
| Claude Fable 5.2 | high |
No |
| OpenAI GPT-6.2 Astra / Sol | medium , the API default |
No, the API rejects none |
| OpenAI GPT-6 Luna | medium |
Yes, none is supported |
Sources: Anthropic's effort page ↗ and
error reference ↗, OpenAI's
reasoning guide ↗,
API reference ↗ and
model pages ↗. The budget_tokens setting you may
know from older Claude models is not accepted after Opus 4.6 and Sonnet 4.6.
Thinking text is hidden by default on current Claude models (display: "omitted"), but the tokens
are still generated and billed as output. If you show reasoning to users while it streams, set
display: "summarized".
Streaming events are typed and there is no [DONE] #
OpenAI's Chat Completions stream sends chunks with choices[].delta and ends with data: [DONE].
Claude's stream ↗ is a sequence of
typed events: message_start, then content_block_start, content_block_delta and
content_block_stop for each block, one or more message_delta events and a final
message_stop. There is no [DONE]. The stream can include ping events at any point, and new
event types may appear, so a parser should skip types it doesn't know.
Three details catch hand-written parsers:
- +Tool arguments stream as partial JSON.
input_json_deltaevents carry fragments of a JSON string, and only the finishedtool_use.inputis an object. - +Usage in
message_deltais cumulative , not an increment to add up. - +Errors can arrive inside a 200 stream , for example an
errorevent withoverloaded_error.
The Anthropic SDK's stream helpers handle the first two. A mid-stream error still needs your own retry.
Stop reasons, refusals and overload errors #
OpenAI reports why a response ended in finish_reason: stop, length, tool_calls or
content_filter. On Claude, stop_reason splits stop into end_turn and stop_sequence,
length becomes max_tokens and tool_calls becomes tool_use. It adds _turn, when a
server-tool loop hits its iteration limit, and model_context_window_exceeded. The nearest thing
to content_filter is refusal. Anthropic's
refusals page ↗ says
Opus 5.5, Sonnet 5.5, Haiku 5.5 and the Fable models have safety classifiers that can decline a
request. A declined request comes back as a normal response with stop_reason: "refusal" and a
stop_details.category, not as an error, so check stop_reason before reading the content. A beta
fallbacks parameter can rerun a declined request on another model.
Overload errors use a different status code. OpenAI returns 503 server_is_overloaded, while
Claude returns 529 overloaded_error and can also send it mid-stream. Retry logic that only treats
429 and 503 as retryable will not retry Claude's overloads. Anthropic's SDKs retry twice by default
and honor the retry-after header.
Cost: prices match, bills don't #
At list price the two lineups line up tier for tier:
| Tier | Claude model | Claude price (input / output per 1M tokens) | OpenAI model | OpenAI price |
|---|---|---|---|---|
| Top | claude-fable-5-2 |
$8 / $40 | gpt-6.2-astra |
$8 / $40 |
| Upper middle | claude-opus-5-5 |
$4 / $20 | gpt-5.6-sol , previous generation |
$4 / $20 |
| Middle | claude-sonnet-5-5 |
$2 / $10 | gpt-6.2-sol |
$2 / $10 |
| Small | claude-haiku-5-5 |
$0.10 / $0.50 for prompts up to 100K tokens | gpt-6-luna |
$0.10 / $0.50 |
Sources: Anthropic's pricing page ↗ and
OpenAI's pricing page ↗. OpenAI's current lineup
has nothing between $2 and $8 per million input tokens. Its closest model at Opus 5.5's price is
the previous-generation gpt-5.6-sol, and gpt-6.1-sol, which OpenAI describes as near-Astra
performance at a lower cost, is priced like GPT-6.2 Sol at $2 / $10.
Four things make the cost per task differ even when the price per token matches:
- +Tokenizers. The same text is a different number of tokens on each side. Anthropic says its tokenizer from Claude Opus 4.7 on produces about 30% more tokens than earlier Claude models, but neither company publishes a comparison with the other's. Count your own prompts with Claude's freetoken counting endpoint ↗ instead of reusing OpenAI's counts.
- +Thinking tokens. Both bill reasoning as output tokens, and the defaults differ (see the effort table above). A model that thinks more per turn costs more per task at the same price.
- +Long prompts. Claude charges a flat rate up to the full 1M-token context, except Haiku 5.5, which costs $0.50 / $2.50 above 100K-token prompts. OpenAI doubles the input price and charges 1.5 times for output above 272K input tokens.
- +Caching. Both now charge 1.25 times the input price for a cache write. OpenAI does from
GPT-5.6 on, with a 30-minute default lifetime, and Claude does for its 5-minute cache. Cache
reads cost 0.05 times the input price on Opus 5.5, Sonnet 5.5 and GPT-6.2 Astra and Sol. The
difference is in what gets cached. OpenAI caches automatically from 1,024 tokens, while Claude
caches only when you add
cache_controland from 512 tokens on current models. One top-levelcache_controlfield turns on automatic caching. A prompt marked for caching below the minimum is simply not cached, with no error.
Both companies take 50% off through their batch APIs. Latency depends on the same factors, effort and thinking first. Measure it on your own requests instead of trusting a benchmark chart.
Can I keep using the OpenAI SDK with Claude? #
For testing, yes. Anthropic runs an OpenAI SDK compatibility layer ↗:
point the OpenAI client at https://api.anthropic.com/v1/ with an Anthropic API key and the
Chat Completions calls reach Claude. Anthropic describes it as "primarily intended to test and
compare model capabilities", not "a long-term or production-ready solution", and its limits explain
why:
- +
stricton tools is ignored, so tool inputs aren't guaranteed to match the schema. - +
tool_choice: "required"and a named function still force a tool call, and some models return a 400 for that, as above. - +
temperaturebelow 1 returns a 400 on Claude 4.7 and later models, so omit it. - +
response_formataccepts onlyjson_schemawithstrict: true.json_objectreturns a 400. - +Prompt caching is not supported.
- +Thinking is not returned, and
reasoning_effortis ignored along withseed,logprobsand most other unsupported fields.
Use it to try Claude on a few requests without rewriting code. For production, use the Anthropic SDK. Anthropic documents only the Chat Completions shape there, so Responses API code has to be moved either way.
Step 1: List the OpenAI features your code depends on #
Grep the code for every call to the OpenAI client and note, per route, what each one relies on:
tool_choice: "required" or a named function, parallel_tool_calls, response_format and the
schemas behind it, temperature, reasoning_effort, streaming, prefilled assistant messages,
seed, logprobs, image or audio inputs, and prompt caching. Every item on that list maps to one
of the sections above. The list tells you which routes are a rename and which change behavior.
Also check the retry and error handling around the client. It needs to treat Claude's 529 as
retryable and handle a refusal stop reason that arrives as a success.
Step 2: Record real runs before you touch the code #
Before you change anything, capture 100 to 300 real inputs per route from production. With them, record the tools the model called, their arguments in order, the structured fields it returned, and anything it refused. That is the baseline the Claude version has to match. Hand-written test prompts cover what you thought to test. Recorded traffic covers what users actually send, including the multi-turn conversations and odd tool sequences that break first.
Step 3: Translate the request to the Messages API #
Here is a typical OpenAI tool-calling request on gpt-4.1, which OpenAI shuts down on January 14,
2027:
import json
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
model="gpt-4.1",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": user_message},
],
tools=[{
"type": "function",
"function": {"name": "lookup_order", "parameters": ORDER_SCHEMA, "strict": True},
}],
tool_choice="required",
temperature=0,
)
call = response.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)
On GPT-6.2 Astra and Sol the same call would already need changes on OpenAI's side: OpenAI's
GPT-6.2 guide ↗ says tool calling on
those models requires the Responses API, and to omit temperature. Here is the request on Claude:
import anthropic
client = anthropic.Anthropic()
messages = [{"role": "user", "content": user_message}]
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=16000, # required
system=SYSTEM_PROMPT, # top-level, not a message
messages=messages,
tools=[{
"name": "lookup_order",
"description": "Look up an order by its ID. Call it whenever the user mentions an order.",
"input_schema": ORDER_SCHEMA,
"strict": True,
}],
output_config={"effort": "medium"}, # set it, don't rely on the default
)
if response.stop_reason == "tool_use": # with auto, Claude may answer without a tool
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": [
{"type": "tool_result", "tool_use_id": block.id, "content": run_tool(block.name, block.input)}
for block in response.content
if block.type == "tool_use" # block.input is already a dict
]})
Because tool_choice is gone, the instruction that the tool should be called moves into its
description and the system prompt. Anthropic's compatibility page warns that a heavily adjusted
prompt is "likely to be well-tuned to OpenAI specifically". Plan to rework the prompt, not only the
request.
Step 4: Pick the Claude model and effort per route #
Start each route on the Claude model at the same price as the OpenAI model it replaces: Sonnet 5.5
for GPT-6.2 Sol, Haiku 5.5 for GPT-6 Luna, Fable 5.2 for GPT-6.2 Astra. Then run the same cases at
a lower effort as well. Anthropic's effort page ↗
suggests medium for well-specified agentic and multistep tool-use work, high for harder or
longer tasks, and medium or low for chat. Move a route up a tier only when the replay in step 5
shows the cheaper setup failing it. Routes that truly need forced tool use can try Haiku 5.5, which
still accepts it, but Anthropic notes that forcing a tool also skips thinking on every model that
accepts it.
Step 5: Replay the same runs on both models and diff them #
Run every recorded input from step 2 through the OpenAI model and the Claude version with identical history, tools and system prompt. Then compare each pair:
- +Tool calls : same tools, same order, same arguments. Check them deterministically, not with a
judge. A route that used
tool_choice: "required"needs extra attention here. - +Structured fields : parse every output against the schema and compare values, not only validity.
- +Refusals and stop reasons : count
refusalandmax_tokensstops per route. - +Cost and latency per task , from the usage each API reports, including thinking tokens.
Without temperature, each case varies from run to run, so sample each one several times. Then
decide with thresholds you wrote down before you saw the results. For example: no more than 5% of
cases call a different tool, and every structured field matches. What actually breaks when you
switch LLMs explains why the worst differences read as
correct answers, which is why a text-only review misses them.
Step 6: Switch one route at a time #
Put the model choice behind a flag per route, move the routes that passed step 5 first, and keep the OpenAI path working until each route has run on Claude in production for a while. Watch error rates, including 529s and refusals, cost per task and latency per route. Keep the recorded suite: when Anthropic releases the next model, the same replay tells you whether to move again.
Doing this with EvalShift #
Disclosure again: I'm the founder of EvalShift, and steps 2 and 5 are the part it automates. The
capture SDK wraps the OpenAI client and records real runs with their tool calls, and compare
replays them on Claude:
from openai import OpenAI
from evalshift import capture
from evalshift.adapters.openai import wrap_openai
client = wrap_openai(OpenAI()) # each create() inside a capture records one model call
TOOLS = [...] # the tools the agent is offered, or [] for none
@capture.agent(suite="support", redact=True, tools=TOOLS) # no-op unless EVALSHIFT_CAPTURE=1
def handle_ticket(message): ...
pip install evalshift
EVALSHIFT_CAPTURE=1 python my_agent.py # record production-shaped runs
evalshift capture sync # recorded runs -> golden suite
evalshift compare --suite-name support --to claude-sonnet-5-5
Both arms are live calls through LiteLLM, which translates the recorded OpenAI requests into Claude
ones. EvalShift sends temperature=0 on every call. When Claude rejects it, EvalShift resends
without it and marks the run as non-deterministic in the report, so set
defaults.samples_per_example above 1. A capture that recorded tool_choice: "required" replays it
as Claude's any, which fails on Sonnet 5.5 the same way your app would. Fix the request, then
compare again. EvalShift's config has no effort setting, so compare measures Claude at the model's
default effort. Docs: /docs/sdk-adapters, /docs/captures,
/docs/migration-policy.
FAQ #
Can I use the OpenAI SDK to call Claude? Yes, through Anthropic's OpenAI SDK compatibility
layer at https://api.anthropic.com/v1/. Anthropic says it is meant for testing and comparing
models, not as a production solution: it ignores strict on tools, doesn't support prompt caching,
doesn't return thinking and ignores reasoning_effort. For production, use the Anthropic SDK.
Does Claude support tool_choice "required"? Not on its newest models. Claude's equivalents,
tool_choice any and tool, return a 400 on Claude Opus 5.5, Sonnet 5.5, Fable 5.2 and
Fable 5.1. Haiku 5.5 still accepts them. Anthropic recommends auto with strict tools, plus a
prompt that says when the tool applies, or structured outputs when you need JSON back.
Why does Claude return a 400 for temperature? API version 2026-10-21, released October 21,
2026 and sent by default from Python SDK 2.0.0 and TypeScript SDK 1.0.0, removed temperature,
top_p and top_k. A request that sends any of them returns a 400 on every model, even at the
default value. Remove the parameter, and sample each test case several times instead.
Is Claude more expensive than OpenAI? Per token, the tiers match. Claude Sonnet 5.5 and GPT-6.2 Sol both cost $2 per million input tokens and $10 per million output tokens, and Fable 5.2 matches GPT-6.2 Astra at $8 and $40. Per task the cost differs, because the tokenizers, thinking defaults and caching rules differ. Count your own prompts with Claude's token counting endpoint and compare the cost of real runs.
Which Claude model replaces GPT-6.2 Sol? Claude Sonnet 5.5, at the same $2 and $10 per million tokens. For GPT-6 Luna the same-price model is Claude Haiku 5.5, and for GPT-6.2 Astra it is Claude Fable 5.2. Start there and confirm with a replay of your own traffic before switching.
Does Claude support structured outputs? Yes. Claude uses output_config.format with a JSON
schema, and strict: true on tools for schema-valid tool inputs. The schema rules differ from
OpenAI's. Claude allows optional properties in strict mode but doesn't support recursive schemas,
oneOf, or minimum, maximum and length constraints.
Do I need to rewrite my prompts for Claude? Usually some of them. Anthropic says a prompt tuned extensively for OpenAI is likely tuned to OpenAI specifically. When forced tool use goes, the instruction to call a tool moves into the prompt and the tool's description. Replay real runs on both models to find the prompts that need work.
Keep reading #
- +What actually breaks when you switch LLMs — why the worst regressions from a model swap read as correct.
- +How to test an LLM model migration before you ship it — step 5 as a full method.
- +Anthropic model deprecation schedule — every Claude retirement date, and what changes from Sonnet 4.5 to Sonnet 5.5.
- +Evaluating agent tool calls — the checks that see tool behavior text evaluators miss.