Claude Opus 5.5 API migration: handle four breaking changes before switching model IDs

Quick answer

Claude Opus 5.5 launched on September 22, 2026 as claude-opus-5-5. It keeps a 1-million-token context window and 128,000-token maximum output, while standard pricing falls from Opus 5's $5/$25 to $4/$20 per million input/output tokens. Cache reads cost $0.20 per million tokens. Those savings are real list-price changes, but a model-ID swap is not a safe migration by itself.

Four API changes can break an Opus 5 integration: thinking can no longer be disabled; forced tool_choice modes return an error; thinking blocks are bound to the model and conversation; and the old computer_20251124 tool is rejected on the Claude API and Google Cloud. A fifth, quieter behavior change can remove visible progress updates because text between tool calls now arrives in thinking blocks.

Treat the launch as a request-contract migration. Replay real conversations, tool loops, and UI streaming before moving production traffic.

Who this is for

This guide is for developers calling the Claude API or a supported cloud platform from an agent, coding assistant, or long-running workflow. It covers API behavior, not the model picker inside GitHub Copilot; use the separate Claude Opus 5 Copilot rollout checklist for that product boundary.

What changed

Boundary	Opus 5 behavior	Opus 5.5 migration action
Thinking	Could accept disabled or manual-budget configurations	Remove those fields; use adaptive thinking and set effort explicitly
Default effort	high	medium; rerun quality, latency, and cost tests
Forced tools	tool_choice types any and tool could force selection	Use auto plus strict tool schemas or structured outputs
Preserved thinking	Earlier blocks were less restrictive	Return thinking blocks unmodified and do not edit preceding context
Computer use	computer_20251124 may be accepted	Claude API and Google Cloud require computer_toolset_20260801; Bedrock differs
Progress UI	Inter-tool narration could appear as text	Read blocks by type and configure thinking.display when users need updates

Platform identity matters. Anthropic lists claude-opus-5-5 for the Claude API, Google Cloud, Microsoft Foundry, and Claude Platform on AWS, but Amazon Bedrock uses anthropic.claude-opus-5-5. Do not hide these IDs behind one untested string substitution.

A seven-step migration workflow

1. Inventory request shapes. Search production traces and fixtures for thinking, tool_choice, computer-use declarations, content-block parsing, edited history, and model fallbacks. Record the provider beside each route.
2. Create a frozen replay set. Include a plain response, a multi-turn edit, a forced-tool case, a multi-tool loop, a computer-use request, a refusal, and a fallback to another model. Remove secrets while preserving message order and tool schemas.
3. Update the request contract. Pin the platform-specific model ID. Remove disabled/manual thinking. Set effort instead of inheriting the new medium default. Replace forced tool selection with auto plus strict validation.
4. Preserve returned blocks. Store and resend thinking and redacted_thinking blocks exactly as returned. Do not mutate earlier messages, system instructions, or tool definitions before a preserved block unless the documented flow permits it.
5. Fix stream rendering. Parse every content block by type. If your UI previously displayed short notes between tool calls, test thinking.display and render only non-empty permitted updates; a quiet UI is not proof that the agent stopped.
6. Split provider canaries. Test Claude API, Bedrock, Google Cloud, and Foundry routes independently. Computer-use declarations and model IDs are not identical, so one passing provider cannot certify another.
7. Promote with a rollback receipt. Keep Opus 5 available until the replay set meets acceptance, cost, latency, refusal, and tool-integrity gates. Record the exact model, provider, effort, prompt version, and rollback route.

Measure cost per accepted result

The new token prices are useful inputs, not a completed migration result. For each replay task, calculate:

request_cost = input_tokens × input_rate
             + cache_write_tokens × cache_write_rate
             + cache_read_tokens × cache_read_rate
             + output_tokens × output_rate

accepted_result_cost = (request_cost + retry_cost + tool_cost) / accepted_results

Opus 5.5 list prices are $4 input, $20 output, $5 for a five-minute cache write, $8 for a one-hour cache write, and $0.20 for a cache read per million tokens. Batch input/output is half price. Fast mode is a Claude API research preview at $8/$40 and is not available on partner cloud platforms. Keep effort, speed, cache duration, provider, and acceptance rubric constant when comparing runs.

Decision tree

Does the route use thinking controls, forced tools, computer use, or edited history?
  yes -> migrate the request contract and replay that exact case
  no  -> still test default effort and content-block parsing

Does the application show progress between tool calls?
  yes -> test thinking.display and non-empty thinking updates

Can a fallback change models mid-conversation?
  yes -> verify whether the target can read Opus 5.5 thinking blocks;
         otherwise expect reasoning context to be discarded

Did every acceptance gate pass on the same provider used in production?
  yes -> shift a bounded traffic percentage and retain rollback
  no  -> keep Opus 5 on that route

Common mistakes

• Replacing only the model ID and discovering invalid thinking or forced-tool fields in production.
• Comparing Opus 5 at high effort with Opus 5.5 at its default medium effort.
• Treating HTTP 200 as success when stop_reason: "refusal" needs an explicit fallback path.
• Dropping, rewriting, or reordering signed thinking blocks inside tool loops.
• Assuming the Claude API computer-use declaration also applies to Bedrock.
• Claiming Anthropic's typical-workload savings as your own before measuring accepted results.
• Trying to strip the text watermark. Anthropic says Opus 5.5 includes watermarking; it adds no visible characters, user identity, or extra token charge, and it does not change output ownership.

Building something? Turn your product page into a show people want to watch with PromoFast—hosted, embeddable, and ready to export.

FAQ

Can I disable thinking on Claude Opus 5.5?

No. Anthropic documents adaptive thinking as always on. A disabled setting or a manual thinking-token budget returns a 400 error. Control depth with effort instead.

Can I move an existing Opus 5 conversation to Opus 5.5?

Anthropic says Opus 5.5 can read thinking blocks from Opus 5 and earlier Opus, Sonnet, and Haiku models. Preserve the blocks and their preceding context. Other fallback directions have different compatibility, so test the exact route.

Does watermarking identify my company or user?

Anthropic says no. The watermark indicates that Claude was likely involved in a passage; it carries no identifying information and does not change ownership or responsibility.

Is Opus 5.5 available on every supported provider with the same configuration?

No. Availability is broad, but model IDs and computer-use declarations differ. Validate each production provider separately.

Sources

• Anthropic: Introducing Claude Opus 5.5
• Claude Platform: Claude Opus 5.5 overview
• Claude Platform: What's new in Claude Opus 5.5
• Claude Platform: Migrating to Claude Opus 5.5
• Anthropic: How Claude's text watermark works

Originally published on IndieSeek.