Claude Opus 5.5 API Guide: The Model ID, Four Breaking Changes, and the Silent Fifth

Change the model string from claude-opus-5 to claude-opus-5-5 and your code still compiles, still type-checks, and still passes whatever passes for a test suite. Then it 400s in production. Four request shapes that Claude Opus 5 accepted are rejected outright by Claude Opus 5.5, and a fifth change breaks nothing at all — which is exactly why it will be the one that reaches your users. This is the integration reference for the model: the identifier, the surfaces that serve it, the request contract, the four errors, the silent fifth, and how the effort parameter now works. Where behavior matches Claude Fable 5.1, a team that already migrated there has done part of the work, so each change below says whether it applies to that model too.

Everything here is read from Anthropic's own Claude documentation on 2026-09-24, two days after the model shipped. Vendor claims are labelled as vendor claims, independent numbers as independent, and the two are never presented at the same effort setting as if they were comparable.

The model id, and where it is served

The identifier is claude-opus-5-5 — a fixed model id with no date suffix, the same scheme as claude-opus-5. There is no separate pinned-snapshot form to adopt and no alias that resolves to something else.

Anthropic's models overview lists five surfaces, with these exact strings:

• Claude API — claude-opus-5-5, available to all customers.

• Amazon Bedrock — anthropic.claude-opus-5-5 (the only surface that prefixes the vendor).

• Claude Platform on AWS — claude-opus-5-5, using Claude API ids rather than Bedrock-style ids.

• Google Cloud — claude-opus-5-5.

• Microsoft Foundry — claude-opus-5-5; the deployment name is what you send, and Foundry follows the Claude API lifecycle schedule.

Two of those five matter more than the rest of this section. Amazon Bedrock and Google Cloud set their own lifecycle and retirement dates, and — as the breaking changes below show — Bedrock is also the one platform where the old computer-use tool still works. If you are on Bedrock, you are not on the same migration as everyone else.

What every request has to satisfy now

Anthropic's migration guide states the contract as a list, and the list is short enough to check your own client against. Whichever model you are coming from, a request to claude-opus-5-5 must:

• Send either no thinking field or thinking: {"type": "adaptive"} — the two are equivalent, because adaptive thinking is always on.

• Control thinking depth with effort, the only request parameter that does so; all five levels are supported and the default is medium.

• Use tool_choice of {"type": "auto"} (the default) or {"type": "none"}. Forcing a tool is rejected.

• Omit temperature, top_p and top_k, or leave them at their defaults. Any other value is rejected, on this model as on everything from Claude Opus 4.7 onward.

• Not end messages with a prefilled assistant turn; that was already rejected on Opus 4.6 and later.

• Declare computer use as the computer_toolset_20260801 toolset on the Claude API and Google Cloud.

• Send no context-window beta header. The 1M context window is the default, and a header written for an older model has no effect.

Where the guide says a setting is rejected, the API returns HTTP 400. That is the whole failure mode of moving to this model: not degraded output, not a warning in a log — a request that never runs.

The four breaking changes

1. Thinking cannot be disabled

Adaptive thinking is always on. thinking: {"type": "disabled"} returns a 400, and so does a manual budget — thinking: {"type": "enabled", "budget_tokens": N}. The error text names the type you sent and then names the replacement:

• "thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

• "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

The practical consequence is not the error, it is what happens after you fix it. On Claude Opus 4.8 and earlier, a request with no thinking field ran without thinking. On Claude Opus 5.5 every request thinks, and max_tokens remains a hard limit covering thinking plus response text. Thinking tokens bill as output tokens even when the thinking text is never returned to you. An endpoint that previously ran thinking-free can therefore produce more output tokens per request after the "fix" than it did before. Anthropic's guidance is to lower effort where you used to disable thinking, and — at xhigh or max effort — to start max_tokens at 64k and tune from there.

The response shape changes too. A response can begin with one or more thinking blocks before the first text block, so code that reads the reply by position — content[0].text, or a stream handler that treats the first content_block_start as text — breaks on these responses even when the request succeeded. Select blocks by their type field instead.

2. Forced tool use returns an error

tool_choice types any and tool return a 400, and the same validation applies to the token-counting endpoint, so a pre-flight count fails the same way the real call does:

• tool_choice: type "tool" and "any" are not supported for this model.

Auto and none are unaffected. The documented replacement is to keep tool_choice: {"type": "auto"}, mark tools with strict: true for schema-valid arguments, or move the schema to structured outputs — and to say in the prompt when the tool applies, since auto does not guarantee a call. Strict tool use accepts a subset of JSON Schema: every object in a tool's input_schema must set additionalProperties: false, so check each schema before flipping the flag. And note the gap this leaves: if your code depended on forcing a call rather than merely permitting one, auto restores the permission and not the guarantee. Check that a tool_use block actually came back.

3. Thinking blocks are bound to the model and to the conversation

Every thinking block records which model produced it, and each model reads its own blocks plus a defined set of others'. The rules run in both directions:

• Claude Opus 5.5 reads thinking blocks from Claude Opus 5 and earlier Opus, Sonnet and Haiku models — but not from Claude Fable or Claude Mythos models.

• On the Claude API, Claude Fable 5.1 and Claude Mythos 5.1 read Claude Opus 5.5 blocks. No other model does.

• A conversation moving from Claude Opus 5.5 to anything other than those two runs its later turns without the earlier reasoning.

A router or fallback that moves a conversation is the obvious way to hit this. The subtler half is that the block is also bound to the conversation prefix — the system prompt, the tools, and every message before it. Anthropic enforces the prefix check by default for accounts created on or after 2026-08-31 00:00 UTC, on the Claude API and on cloud platforms: replay a block after editing the system prompt, the tool list, or an earlier message and the request returns 400. Two escape hatches exist. Send the thinking-binding-controls-2026-08-01 beta header and set thinking.block_binding.prefix_mismatch_behavior to "drop_block" to drop the affected blocks instead of failing the request. Or keep the conversation append-only and change instructions with a mid-conversation system message rather than an edit — which is what Claude Code, claude.ai, Claude Managed Agents and the Claude Agent SDK already do.

There is one piece of good news that is easy to miss: when a request carries a block the target model cannot read, the API drops it before the model sees it. The request succeeds, and dropped blocks are not billed.

4. The older computer-use tool is rejected on the Claude API and Google Cloud

A tools entry of type computer_20251124 returns a 400 on the Claude API and Google Cloud. The message names the rejected type and then lists the types the model does accept:

• 'claude-opus-5-5' does not support tool types: computer_20251124.

The replacement is the computer_toolset_20260801 toolset: drop the computer-use-2025-11-24 beta header, and send the tools entry with no name and no display dimensions. This is not only a request change — the agent loop changes with it. Actions arrive as member tool_use blocks rather than a single computer tool, there can be several in a turn, the action is the block's name rather than input.action, and every result has to echo toolset_name back. On Amazon Bedrock, computer_20251124 keeps working exactly as it does on Claude Opus 5 and no change is needed.

Which of the four also apply to Claude Fable 5.1

Anthropic states that the first three apply on Claude Fable 5.1 as well — always-on thinking, no forced tool choice, and model- and conversation-bound thinking blocks. The computer-use change does not: that one is specific to this model on the Claude API and Google Cloud. So a team that already moved to Claude Fable 5.1 has retired its thinking-disabled code paths and its forced tool choices, and has an append-only conversation pattern; what remains is the model id and the computer-use toolset. A team coming from Claude Opus 5 faces all four at once. That is the migration worth scheduling, and it is a different amount of work depending on where you start.

The fifth change: nothing errors, and your progress feed goes quiet

On Claude Opus 5, the short notes the model writes between tool calls come back as ordinary text blocks. On Claude Opus 5.5 — as on Claude Fable 5.1 — that narration returns as progress-update thinking blocks, at most one before each tool call. And thinking.display defaults to "omitted", so those blocks arrive with an empty thinking field alongside their signature.

No request fails. No error is logged. An application that streams the between-tool text to its users as a progress indicator simply stops showing progress between tool calls and starts showing nothing. The visible symptom is a UI that appears frozen during the exact stretch of work where the user most wants reassurance, and it will be reported as a performance problem, a network problem, or a hang — not as a migration bug. This is the change that ships to production.

The fix is a display setting, plus a read that matches it:

• Set thinking.display to "updates" — beta, behind the thinking-display-updates-2026-08-18 header — to get the progress updates back while the reasoning itself stays hidden. This is the setting a progress feed wants.

• Or set it to "summarized" to receive progress updates and reasoning summaries mixed together in the same blocks.

• Then read the text from thinking blocks rather than text blocks, render each non-empty thinking block ahead of the tool_use block it precedes, and pass the blocks back unchanged with the rest of the assistant turn.

Anthropic's own note on this is worth quoting in spirit: an interface that renders text between tool calls is expected to set a display value rather than rely on the default. If your integration ignores thinking blocks entirely today, that is the one place the default is safe.

Effort is the API surface

With thinking un-disableable, output_config.effort becomes the only dial on how much the model reasons, and therefore the only dial on cost and latency at a given task. Four things about it are worth knowing before you copy a setting across from the old model.

The default moved. Claude Opus 5.5 defaults to medium effort, where Claude Opus 5 and earlier Opus models defaulted to high. A request that omits effort now runs one level lower than it did before the swap. Anthropic also documents that the model tends to think more per turn at a given effort setting than Claude Opus 5 did, most of all at xhigh and max. Those two effects push in opposite directions, which is precisely why the vendor's instruction is to run a fresh effort sweep on your own evals rather than translating a setting across.

The scale is low / medium / high / xhigh / max, all five supported here. The named level is not a fixed token budget in the first place — Anthropic describes effort as a behavioral signal, not a strict budget — and the token allocation behind each level changed between models, so "high" on Claude Opus 5.5 is not "high" on Claude Opus 5. Setting effort to the model's default is identical to omitting it.

Two operational details, because both cost money when missed. First, changing the top-level effort value between requests invalidates the prompt cache: pick a level and hold it constant within a conversation that relies on cache hits, and vary it across workloads instead. Second, this model supports per-message effort (beta header mid-conversation-output-config-2026-07-01), which changes the level from a later turn without restarting the cache. The prompt-cache minimum here is 512 tokens, down from 1,024 on the previous generation, so prompts that were previously too short to cache can now create entries with no code change.

Output ceilings: 128K synchronous, 300K on Batch

The synchronous Messages API caps output at 128K tokens. The Message Batches API goes to 300K output tokens behind the output-300k-2026-03-24 beta header — that exact string. Input is the full 1M-token context window by default with no header required.

The practical reading: the 128K ceiling is unchanged from Claude Opus 5, so nothing about a synchronous integration needs re-budgeting on that axis alone. What does need re-budgeting is the thinking inside it. Since max_tokens covers thinking plus text on every request now, a value that was snug for response text on Claude Opus 5 is tighter here — and at xhigh or max effort the vendor suggests starting at 64k and tuning. If a long-running job was sized against the 128K synchronous ceiling and now truncates, the ceiling is not what moved.

Safeguard routing is part of the spec

This is an integration fact, not a policy footnote: on some prompts, the model string you send does not describe what answered.

Claude Opus 5.5 ships with safety classifiers, and a declined request comes back as HTTP 200 with stop_reason: "refusal" and a stop_details object naming the policy area. This model covers more categories than Claude Opus 5 — expect bio, frontier_llm and reasoning_extraction alongside the familiar cyber. The reasoning_extraction refusal is blocked outright rather than retried: Anthropic's server-side fallback does not retry it, and the refusal is returned to you.

For the categories that do retry, the mechanism is a parameter. Set fallbacks to "default" with the server-side-fallback-2026-07-01 beta header and the API re-runs a declined request on the model Anthropic recommends for that category, inside a single call, returning one response. Anthropic's help centre names the routing for this model directly: flagged cybersecurity requests fall back to Claude Opus 4.8, and its biology classifiers — the Fable-5-style set — cause a fallback to Claude Opus 5 for dual-use life-sciences work. A narrow set of frontier-LLM-development capabilities routes to Claude Opus 5 as well. Anthropic also notes the checks review everything the model reads, not just your latest message, so memory, connector content, search results and files can trigger a switch.

Three things follow for your integration. Read the top-level model field on every response, because it reports the model that actually produced the message, and a fallback content block marks each handoff point. Verify the fallback's own rate limits, because a rate-limited fallback is not attempted and the refusal is returned instead — fallbacks degrade to refusals under load. And treat any published benchmark run with safeguards enabled as a measurement of the routed system rather than of Claude Opus 5.5 alone, which is exactly what Anthropic says about its own numbers below.

Server-side fallback is beta and Claude API only: it is not supported on the Message Batches API, and not available on Amazon Bedrock, Google Cloud or Microsoft Foundry, where the SDK middleware is the documented path instead. On the verification side, access routes exist for both categories — the Cyber Verification Program and the Life Sciences Verification Program — but note the asymmetry Anthropic's help centre documents as of this writing: Claude Opus 5.5 is not currently listed in the Cyber Verification Program, while the life-sciences program is described as giving verified organisations access to the most capable models.

Context, cutoff, retirement, and Fast mode

The rest of the envelope, from the model page and the deprecations table:

• Context window — 1M tokens, default, no beta header.

• Knowledge cutoff — June 2026, which is also the training-data cutoff.

• Retirement — no sooner than 2027-09-22 on Anthropic-operated platforms, with at least 60 days' notice. Amazon Bedrock and Google Cloud set their own dates. Claude Opus 5 is Active until at least 2027-07-24, so there is no forced cutover.

• Rate card — $4.00 per million input, $20.00 per million output, $5.00 per million 5-minute cache writes, $8.00 per million 1-hour cache writes, $0.20 per million cache reads. Batch is half price in both directions at $2.00 / $10.00.

• Cache reads are the outlier worth noticing: $0.20 is 5% of base input, where most Claude models sit at 10% and Claude Fable 5.1 at 2.5%. Mixed workloads with heavy cache reuse feel that as a real discount.

• Fast mode — still documented as a research preview, Claude API only, priced separately at $8.00 input / $40.00 output per million. Enable with speed: "fast" and the fast-mode-2026-02-01 beta header. It is not available on Bedrock, Claude Platform on AWS, Google Cloud or Microsoft Foundry, not with the Batch API, and not with a Priority Tier commitment. Note that Claude Opus 5.5 does not support Priority Tier at all.

What the benchmarks say, and at which setting

Effort settings are the reason a vendor table and an independent table cannot be compared row by row, and why every number below carries its setting.

Vendor-reported, Anthropic's own harness. Anthropic's launch note says that, unless otherwise noted, all Claude Opus 5.5 results use adaptive thinking at max effort; the exception is Terminal-Bench 4.0, reported at xhigh for Claude Opus 5.5 and high for GPT-6 Astra because those are each model's highest score. On that basis the vendor reports Terminal-Bench 4.0 at 66.4%, FrontierCode v1.1 Main at 54.4%, CursorBench 4.0 at 57.8%, GDPval-AA v2.1 at 1,846 Elo, AutomationBench at 40.0%, Humanity's Last Exam with tools at 67.7%, Terminal-Bench-Science 0.1 at 58.7%, OSWorld 2.0 at 81.8% partial, and Chartography with tools at 89.0%. At the model's default medium effort the vendor gives FrontierCode at 54.6% and CursorBench at 52.5%. Note what the same note discloses: the evaluations ran with production safeguards enabled, and when those triggered, cybersecurity tasks were completed by Claude Opus 4.8 and biology and frontier-LLM-development tasks by Claude Opus 5 — Anthropic says this likely reduces Claude Opus 5.5's performance on those benchmarks. Published scores on the affected evaluations are therefore not clean measurements of this model.

Independent, Artificial Analysis. On Intelligence Index v4.3.2, Claude Opus 5.5 scores 58 in the configuration Artificial Analysis labels "Adaptive Reasoning, Max Effort, Default Fallback" — its highest measured score by several points, and it leads six of the ten constituent evaluations. On the same index and the same harness, Claude Fable 5.1 scores 53 and Claude Opus 5 scores 51. Artificial Analysis publishes the full effort ladder, which is the most useful independent artifact here: max 58, xhigh 56, high 54, medium 51, low 42. Its own measurements put Claude Opus 5.5 at roughly 119,000 output tokens per index task at max effort, against about 73,000 for Claude Opus 5, 78,000 for Claude Fable 5.1 and 27,000 for GPT-6 Astra — tokens that bill as output tokens — and its page reports a cost of $5.98 per index task. It also measures Terminal-Bench 4.0 at 59.6% and Humanity's Last Exam at 61.4%, against the vendor's 66.4% and 67.7% at max effort on a different harness.

Read those two paragraphs against each other and the honest conclusion is narrow. The vendor's 66.4% Terminal-Bench and the independent 59.6% are the same benchmark run by different people at settings not guaranteed to match, and neither is evidence about your workload. The effort ladder is the transferable finding: on an independent index, this model's own settings span sixteen points, which is a wider spread than the gap between it and its predecessor. Choosing an effort level matters more than choosing between these models, and the "Default Fallback" clause in that label is the safeguard routing described above, not a benchmark artifact.

Vendor-reported efficiency, attributed. Anthropic says Claude Opus 5.5 performs at Claude Fable 5.1's level on most work at about 40% lower cost to run, and that typical workloads cost roughly 40% less than on Claude Opus 5 against a 20% sticker price cut. Output is more than 30% faster. These are vendor characterisations of averages across workloads the vendor selected. The launch-time customer statements are the same kind of evidence: Box reports a third of the tokens and answers around 40% less verbose, Kiro roughly half the tokens and about 40% fewer calls, Factory 20–25% fewer output tokens, GitHub among the fewest tokens and steps it has measured. Anthropic also reports an internal fact-checking test in which 16 of its 18 reports passed a quality bar that neither Claude Fable 5.1 nor Claude Opus 5 cleared in any attempt. All of it is vendor-reported and none of it is audited. The disclosed limitation is unusually candid and worth carrying: Anthropic says Claude Opus 5.5 "frequently suspects it is being evaluated".

Finally, the sibling models: Anthropic says Claude Sonnet 5.5 and Claude Haiku 5.5 arrive "in the coming weeks". Neither is shipped, neither is priced, and neither is on any surface today.

Testing the four changes without a full cutover

The migration risk here is not quality — it is that a code path you never exercised in staging is the one that returns 400 in production. The four breaking changes are all request-shape changes, which means they fail deterministically and immediately, and the only way to find the paths you missed is to run real traffic through them.

Claude Opus 5.5 is on OrcaRouter as anthropic/claude-opus-5.5 at Anthropic's own list price with 0% markup — provider list price passed through, so a vendor price change is live here the same day.

That lets you point a percentage of production traffic at the model while the rest still runs on Claude Opus 5, watch which requests fail and why, and fix them one at a time. The four errors are self-describing: each names the parameter it rejected and, in three of the four cases, the replacement. Automatic failover covers the gap while a path is still broken — a request that fails against a model you have not fully characterised falls back to one you have, rather than surfacing the 400 to a user.

A practical order of work: swap the model id and set effort explicitly first, since the default moved to medium; strip the thinking-disabled and forced-tool-choice paths next; then fix the streaming reader — block selection by type and the thinking.display setting — because that is the one that fails silently rather than loudly; and leave the computer-use toolset migration for last if you are on Bedrock, since it is the one that does not apply there. Everything else — price, context window, cache rates and the 1M-token default — is already where you left it.

Route a share of live traffic at the new model without a full cutover: Claude Opus 5.5 on OrcaRouter runs at Anthropic's list price with automatic failover to a model you have already characterised.