Building with Claude Sonnet 5.5: Which to Pick, What It Costs, How to Migrate from Sonnet 5

Anthropic has released Claude Sonnet 5.5, the second model in the 5.5 family after Opus 5.5. Anthropic says it is smarter than Sonnet 5, uses fewer tokens, and is 30% faster. The per-token price is unchanged, but because the same work usually takes fewer tokens, the bill for most workloads can come out up to 30% lower.

This is a getting-started guide written by Anthropic engineer Addy Osmani on the official claude.dev blog. It skips launch-event benchmarks and answers three developer questions: whether to pick Sonnet 5.5 or Opus 5.5, how the pricing works, and which parts of your code need to change when you migrate from Sonnet 5. This piece follows that order, keeping parameters and code as close to the original as possible so you can copy them straight in.

A quick visual comparison: models repainting a photo in code

The article opens with a demo by Lance Martin: three models get the same aerial photo of a city at sunset, and each writes Python code to repaint it. No image model is involved; every stroke in the picture is painted by code the model wrote.

The process and the results are easy to tell apart:

• Sonnet 5 paints a nice sky gradient, but the city is rows of vertical color bars with a jarringly bright yellow strip in the middle, and the bridge and river are flattened into planes.
• Sonnet 5.5 paints dense block-by-block texture, with light and shadow and reflections on the central cluster of buildings, plus a bridge, a white tower and a blue-roofed building in the foreground. The overall color and depth are closer to the photo.
• Opus 5.5, judging from the video result, is at the same level of detail as Sonnet 5.5, with sharper building outlines and a finer bridge. Anthropic did not score the three images; this is an impression from looking at them.

Under each canvas the video also shows an "engine calls" counter: the model first wrote its own "brush engine," then kept calling it to paint. In the end Sonnet 5 made 12,249 calls and Sonnet 5.5 made 44,561, about 3.6 times as many. That suggests 5.5 painted in finer detail, but it is the number of brush-engine calls in this demo, not token usage and not price, so it can't be used to estimate cost. It is also one demo with one photo; Anthropic gives no score and no call count for Opus 5.5.

Run it first: one pattern you must get right

The article gives a minimal request you can run as is:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Note the loop at the end. It picks out text by the type of each content block (block.type) instead of reading content[0].text directly. The reason is that Sonnet 5.5 thinks by default, so the first block of a response may be a thinking block, and reading the text of the first block breaks. If your existing code reads content[0].text, fix that first when you migrate.

Sonnet 5.5 or Opus 5.5

Anthropic's split is simple: Opus 5.5 is for complex work that needs careful judgment; Sonnet 5.5 is for well-scoped everyday tasks such as fixing bugs and iterating quickly on features. It can also produce reasonably polished documents, slides and spreadsheets, and Anthropic says it has "a strong eye for design"; its speed suits repeated edits. Haiku 5.5 will join the family in the coming weeks for high-volume, low-latency use.

A more practical rule: if the task has a clear spec and you have a way to check the result, Sonnet 5.5 fits. The official prompting guide also says that for the hardest long-horizon work, an Opus model is the better choice.

Epic Games COO Daniel Vogel gave this assessment after early testing: Sonnet 5.5 cleared a quality bar you would expect from a higher-tier model on a system design audit and a data-flow review, managed tens of thousands of lines of code for gameplay system architecture, kept responses snappy, handled multi-hour tasks, and needed less prescriptive prompting.

Pricing: same unit price, different bill

Sonnet 5.5 pricing (USD per million tokens) next to Opus 5.5:

All Sonnet 5.5 prices, including batch processing and prompt caching, are identical to Sonnet 5's, so swapping the model ID leaves your per-token price unchanged. US-only inference (inference_geo: "us") costs 1.1 times the standard price.

What changes is the total bill: Anthropic says Sonnet 5.5 typically uses fewer tokens than Sonnet 5 for the same task. So "same unit price" does not mean "same spend"; after switching, look at your own actual usage.

Two more things are easy to miss:

• Default effort differs. Effort is the setting that controls how long the model thinks. Different products ship different defaults for Sonnet: high on Claude Platform, medium in Claude Code. The same model can behave and cost differently in the two places, so don't apply your experience from one to the other.
• Images cost more. Sonnet 5.5 uses the high-resolution image tier, up to 2576 pixels on the long edge, and a 2000×1500 image costs about 2.5 times as many tokens as on Sonnet 4.6, Sonnet 4.5 or Haiku 4.5. If you don't need the detail, downscale before you send.

Model details at a glance

The Claude API defaults to high so you start from strong results. Anthropic suggests starting there, evaluating, and then picking the effort level your workload needs. If you're tempted to use xhigh or max, keep in mind that the model will think longer and cost more; on some tasks you may lose some of what makes Sonnet useful, its balance of quality, speed and cost. In that case, consider Opus 5.5.

Migrating from Sonnet 5: change the model ID, then work through six items

First change the model ID to claude-sonnet-5-5. Then handle five breaking changes (several of which return a 400 error), plus one change that raises no error but can make your UI show less. The official Sonnet 5.5 migration guide covers each in full.

Anthropic also offers a shortcut: in Claude Code, run /claude-api migrate this project to claude-sonnet-5-5. It invokes the bundled Claude API skill, which swaps the model ID and applies the breaking parameter changes across your code base.

1. To turn off upfront thinking, use between_tools

On Sonnet 5.5, a request with no thinking field runs with adaptive thinking, and thinking: {"type": "disabled"} returns a 400 error. To turn off upfront thinking, use the new between_tools: the model thinks only between tool calls, and total response time is the same or faster.

# Before: Claude Sonnet 5
client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "..."}],
)

# After: Claude Sonnet 5.5
client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "between_tools"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

The example also drops effort from xhigh to high, because between_tools has these limits:

• It supports only low, medium and high; at xhigh or max it returns a 400 error, and to run there you need adaptive thinking.
• It takes no other field; sending display, budget_tokens or block_binding with it is also a 400.
• With it, effort can't change mid-conversation; to vary effort per turn, use adaptive thinking.
• The short progress updates the model writes between tool calls still come back as thinking blocks, with summary text. So read content blocks by type, and pass these blocks back unchanged along with the rest of the assistant turn. Without tools, the response contains only text.
• It works on every platform that offers Sonnet 5.5, with no beta header; if your SDK version doesn't define between_tools, update it.

Also, if you turn off upfront thinking with between_tools, requests without tools that need a few steps of working out are better served by adaptive thinking.

2. Forced tool_choice no longer works; use auto plus strict tools

A tool_choice of type any or tool returns a 400 error, including on the token counting endpoint. Send auto instead, mark the tool strict: true (so its input matches your schema), and say in the prompt when to use it:

weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"],
        "additionalProperties": False,
    },
    "strict": True,
}

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    tools=[weather_tool],
    tool_choice={"type": "auto"},  # was {"type": "tool", "name": "get_weather"}
    messages=[
        {"role": "user", "content": "What's the weather in Paris? Use the get_weather tool."}
    ],
)

Strict tool use needs additionalProperties: false on every object.

3. Keep conversations append-only

Sonnet 5.5's thinking blocks are tied to the model and the conversation. Sonnet 5.5 reads Sonnet 5's thinking blocks, so a conversation you switch from Sonnet 5 to Sonnet 5.5 keeps its reasoning; but no other model can read Sonnet 5.5's blocks. In other words, don't hand a 5.5 conversation history to a different model to continue.

4. Move computer use to the toolset

On the Claude API and Google Cloud, Sonnet 5.5 supports computer use (the model operating a computer interface) only through {"type": "computer_toolset_20260801"}; declaring the old computer_20251124 returns a 400 error. There is quite a bit to change:

• Drop the anthropic-beta: computer-use-2025-11-24 header from your requests; in the SDKs, remove the betas parameter and call the Messages API through the standard client rather than the beta namespace.
• Replace the tools entry, and update your agent loop to handle member tool_use blocks, batch actions and toolset_name on results.
• If you send the fine-grained-tool-streaming-2025-05-14 beta header, remove it too, because alongside a toolset entry it returns a 400 error; set eager_input_streaming: true on each tool that needs it instead.
• Amazon Bedrock still accepts computer_20251124.

5. Check your advisor pairing

The advisor tool lets one model (the executor) consult a stronger one (the advisor). With a Sonnet 5.5 executor, Opus 4.8, Opus 4.7 and Sonnet 5 are rejected as advisors; accepted advisors include Opus 5.5, Opus 5 and Sonnet 5.5 itself. Advice from every accepted advisor comes back encrypted, in an advisor_redacted_result block, so your code can't read the advice text.

6. Read text between tool calls from thinking blocks

This change causes no errors, but your UI may stop showing the model's notes between tool calls. Notes longer than a sentence or two now come back as progress-update thinking blocks, which are empty at the default display.

With adaptive thinking, set thinking.display to "updates" (beta, with the thinking-display-updates-2026-08-18 header) or "summarized", and render each non-empty thinking block before the tool_use block that follows it. With between_tools, the text comes back without display.

Sonnet 5.5 also adds per-message effort (beta), mid-conversation system messages and mid-conversation tool changes (beta). If you're moving from Sonnet 4.6 or earlier, or from Haiku 4.5, the migration guide has a checklist for each starting model.

Tuning: a few things to do before touching parameters

Re-run your effort sweep. Effort levels have been recalibrated, so a level doesn't produce the same amount of thinking as on Sonnet 5, and your old setting won't carry over. Anthropic's starting points:

• Start with high, unless your workload is agentic or latency-sensitive.
• For agentic coding and multistep tool use, start with medium for well-specified tasks and move to high for harder or longer ones.
• For chat and other latency-sensitive work, start with medium or low.
• Use xhigh or max only where your evals show a quality gain.

Thinking counts toward max_tokens, so leave room. For agentic coding, set max_tokens to 128,000, the model's maximum, and stream the response. To get less thinking, lower the effort level; asking the model in the system prompt to think less doesn't reliably reduce it.

Remove Sonnet 5 workarounds. Existing Sonnet 5 prompts should perform well without changes. If they carry workarounds such as refusal steering, tool-call retry shims or "do not be lazy," remove them and re-run your evals before tuning anything else.

At low effort, ask for real checks. Sonnet 5.5 generally checks its work before reporting a change as done, but at low effort it sometimes skips a check that exercises the change. If you see changes reported as done without test or build output, Anthropic's prompting guide recommends adding this paragraph to the system prompt (original text, ready to copy):

When you change code that can be run, built, or type-checked, run a real
check that exercises the change before reporting it done: the project's
tests, type-checker, or build, or the changed command itself. A syntax-only
check, or a check command that failed to start, does not count; if all
that is missing is the project's declared dependencies, install them with
its own package manager and lockfile (e.g. npm install, pip
install -r requirements.txt), never via sudo or the system package manager,
unless told not to. Only if no real check can run here, say which one you
did not run and why instead of reporting the change as done.

In short: when you change code that can be run, built or type-checked, run a real check that exercises the change before reporting it done; a syntax-only check, or a check command that failed to start, doesn't count; if all that's missing is the project's declared dependencies, install them with its own package manager and lockfile, never with sudo or the system package manager, unless told not to; and if no real check can run, say which one you didn't run and why instead of reporting the change as done.

For progress, read thinking.display, and don't ask the model to write its reasoning in the response. Asking the model to write out its reasoning invites reasoning_extraction declines. To show thinking progress, read summarized thinking:

thinking={"type": "adaptive", "display": "summarized"}

For user-facing progress notes on their own, use display: "updates" (beta). If you want updates at predictable points, such as a line before the first tool call and a short recap at the end, say so in the system prompt.

Cache more of your prompt. The minimum cacheable prompt drops to 512 tokens, so shorter system prompts and tool definitions now qualify. For Sonnet 5.5, a cache read costs a tenth of the input price. Note that changing the top-level effort between requests invalidates the cache; to run one turn at a different level, use per-message effort (beta), which keeps the cache.

What happens when a request is declined

In Anthropic's automated behavioral audit, Sonnet 5.5 improves on or matches Sonnet 5 on most measures of alignment and honesty. It is also the first Sonnet model with cybersecurity safeguards similar to those on Anthropic's most capable models; Anthropic says most routine software development is unaffected.

If a request is declined, the API still returns HTTP 200, but stop_reason is "refusal", and stop_details names one of five categories: cyber, bio, frontier_llm, reasoning_extraction or general_harms.

Server-side fallback (fallbacks: "default", beta, on the Claude API) retries cyber and frontier_llm declines on Sonnet 5; it doesn't retry the other three. You can also use SDK middleware or your own retry. For legitimate security work, Anthropic says the Cyber Verification Program will soon expand to include Sonnet 5.5.

Where to use it

Sonnet 5.5 is available today on the platforms below, with these model IDs:

• Claude API: claude-sonnet-5-5
• Amazon Bedrock: anthropic.claude-sonnet-5-5
• Claude Platform on AWS: claude-sonnet-5-5
• Google Cloud: claude-sonnet-5-5
• Microsoft Foundry: claude-sonnet-5-5, on Global Standard deployments only

In Claude Code: from v2.1.284 (Agent SDK for TypeScript v0.3.284 or later), the sonnet alias resolves to Sonnet 5.5 on the Claude API. It runs at medium effort by default, with the 1M context window native. You can't turn thinking off for Sonnet 5.5 in Claude Code, and effort sets how much the model thinks; it has no fast mode. The default model stays Opus 5.5; to use Sonnet for well-scoped tasks, switch with /model sonnet.