Repository Public
1---2title: Migrating to Claude Opus 53url: https://platform.claude.com/docs/en/models/opus-5/migration-guide4description: "Migrate to Claude Opus 5 from earlier Claude models: model IDs, breaking changes, recommended changes, and migration checklists."5---67<Note>8 This guide covers migrating [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) code. If you use [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), no changes beyond updating the model name are required.9</Note>1011<Tip>12 **Automate your migration with the Claude API skill.** In Claude Code, run `/claude-api migrate` to invoke the bundled [Claude API skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model). It works for any current Claude model as the target:1314 ```text wrap15 /claude-api migrate this project to claude-opus-516 ```1718 The skill applies the model ID swap and, as needed, breaking parameter changes, prefill replacement, and effort calibration for your target model across your code base, then produces a checklist of items to verify manually. It asks you to confirm the migration scope (entire working directory, a subdirectory, or a specific file list) before editing any files. The skill also detects Amazon Bedrock and Claude Platform on AWS clients and adjusts model ID formats and feature changes for those platforms.19</Tip>2021Claude Opus 5 is a step-change improvement over Claude Opus 4.8, strong on deep reasoning, agentic and long-horizon tasks, and test-time compute scaling. For behavioral differences and model-specific prompting patterns, see [Prompting Claude Opus 5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5).2223Claude Opus 5 is a drop-in upgrade for Claude Opus 4.8 at the same pricing of $5 USD per million input tokens and $25 USD per million output tokens; see [Claude pricing](https://platform.claude.com/docs/en/about-claude/pricing). There are two breaking changes for code already running on Claude Opus 4.8, covered under [Breaking changes](https://platform.claude.com/docs/en/models/opus-5/migration-guide#breaking-changes). Claude Opus 5 supports the same set of features as Claude Opus 4.8, including the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) (the default, with no beta header), [128k max output tokens](https://platform.claude.com/docs/en/models/overview), [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking), [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), [batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing), the [Files API](https://platform.claude.com/docs/en/build-with-claude/files), [PDF support](https://platform.claude.com/docs/en/build-with-claude/pdf-support), [vision](https://platform.claude.com/docs/en/build-with-claude/vision), and server-side and client-side [tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview), with two exceptions: [web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) is not available on Claude Opus 5, and [Priority Tier](https://platform.claude.com/docs/en/api/service-tiers#supported-models) is not supported on Claude Opus 5. See each tool page for model availability.2425## Migrating to Claude Opus 5 from Claude Opus 4.82627<Note>28 This section covers the delta from Claude Opus 4.8 only. If your code is on Claude Opus 4.7 or earlier, use these sections instead: [Migrating to Claude Opus 5 from Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-5/migration-guide#migrating-from-claude-opus-47) or [Migrating to Claude Opus 5 from Claude Opus 4.6 and earlier Opus models](https://platform.claude.com/docs/en/models/opus-5/migration-guide#migrating-from-claude-opus-46). They include this delta plus the breaking changes from earlier models (sampling parameters rejected, manual extended thinking rejected, prefill removed, new tokenizer).29</Note>3031### Update your model name3233```python34# Opus migration35model = "claude-opus-4-8" # Before36model = "claude-opus-5" # After37```3839`claude-opus-5` is a fixed model ID with no date suffix, the same scheme as `claude-opus-4-8` and `claude-sonnet-5`.4041### Breaking changes42431. **Thinking on by default:** On Claude Opus 4.8, requests without a `thinking` field run without thinking; on Claude Opus 5, the same requests run with [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking). `max_tokens` remains a hard limit on total output, thinking plus response text, so revisit it for workloads that ran without thinking on Claude Opus 4.8. Thinking tokens are billed as output tokens even when the thinking text is not returned to you, so although per-token pricing is unchanged, a workload that ran without thinking on Claude Opus 4.8 can produce more output tokens per request on Claude Opus 5; see [Cost control](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#cost-control). To preserve the old behavior, pass `thinking: {type: "disabled"}`, subject to the effort cap in the next item; note that with thinking disabled the model can occasionally emit tool calls as plain text or include internal XML tags in its visible output, so prefer lower effort levels with thinking enabled where you can, and see [Running with thinking disabled](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#running-with-thinking-disabled) for mitigations where you can't.4445 The response shape changes with it. With thinking on, a response can begin with one or more `thinking` blocks before the first `text` block, and because `thinking.display` defaults to `"omitted"` on Claude Opus 5, those blocks arrive with an empty `thinking` field alongside their `signature`. Code that reads the reply by position, such as `content[0].text` or a stream handler that treats the first `content_block_start` event as text, breaks on these responses. Select content blocks by their `type` field instead: read `text` from the blocks whose `type` is `"text"`, and branch on the block type when handling stream events. To receive readable thinking summaries instead of an empty `thinking` field, set `display: "summarized"`; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).4647 If you run a tool-use loop, pass the `thinking` blocks from each assistant response back to the API complete and unmodified when you return tool results, including blocks whose `thinking` field is empty. Echo the assistant message as received rather than filtering its content blocks by type or rebuilding it: the API rejects edited, reordered, or partially dropped thinking blocks with a 400 error. See [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks).48492. **Disabling thinking is capped at `high` effort:** You can still turn thinking off with `thinking: {type: "disabled"}`, but only at an [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level of `high` or below. A request that combines `thinking: {type: "disabled"}` with effort `xhigh` or `max` returns a 400 error. Claude Opus 4.8 accepts this combination, so audit requests that disable thinking before you migrate.5051 The check is enforced on each request: every request's effort and thinking configuration is validated independently, so a request that raises effort to `xhigh` or `max` while thinking is disabled is rejected even if earlier requests in the conversation were accepted.5253 Before (accepted on Claude Opus 4.8, rejected on Claude Opus 5):5455 ```python56 client.messages.create(57 model="claude-opus-4-8",58 max_tokens=16000,59 thinking={"type": "disabled"},60 output_config={"effort": "xhigh"},61 messages=[{"role": "user", "content": "..."}],62 )63 ```6465 After (Claude Opus 5), either remove the `thinking` field to re-enable thinking:6667 ```python68 client.messages.create(69 model="claude-opus-5",70 max_tokens=16000,71 output_config={"effort": "xhigh"}, # thinking is on by default72 messages=[{"role": "user", "content": "..."}],73 )74 ```7576 or keep thinking disabled and lower the effort:7778 ```python79 client.messages.create(80 model="claude-opus-5",81 max_tokens=16000,82 thinking={"type": "disabled"},83 output_config={"effort": "high"}, # or "medium", "low"84 messages=[{"role": "user", "content": "..."}],85 )86 ```8788### Recommended changes8990These are not required but will improve your experience:91921. **Test `max` effort for capability-critical work:** Claude Opus 5 supports the full set of [effort levels](https://platform.claude.com/docs/en/build-with-claude/effort) (`low`, `medium`, `high`, `xhigh`, `max`). Where maximum capability matters more than token spend, test `max` effort. It can deliver gains on the most demanding tasks but may show diminishing returns from increased token usage and can be prone to overthinking on simpler ones. If you run at `xhigh` or `max` effort, set a large `max_tokens` so the model has room to think and act; start at 64k tokens and tune from there.93942. **Consider automatic fallbacks:** Claude Opus 5 ships with cybersecurity safety classifiers whose cyber-category refusals can fall back to Claude Opus 4.8. To re-run refused requests on another model automatically, consider the `fallbacks` parameter with the `"default"` mode (`fallbacks: "default"`), which selects a recommended fallback model based on the refusal category instead of a hand-maintained model list. Server-side fallback is in beta; the `"default"` mode requires the `server-side-fallback-2026-07-01` beta header. See [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback).95963. **Cache shorter prompts:** The minimum cacheable prompt length on Claude Opus 5 is 512 tokens, down from 1,024 tokens on Claude Opus 4.8. Prompts that were too short to cache on Claude Opus 4.8 can now create cache entries, with no code changes required. See [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations) for per-model minimums.97984. **Change tools mid-conversation (beta):** You can add or remove tools between turns of a conversation without invalidating [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits on earlier turns. Send the beta header `mid-conversation-tool-changes-2026-07-01`. This is useful for agentic workloads that expose tools progressively or retire them as a task advances; without it, a changed tool list invalidates the cached prefix.991005. **Re-tune length and verbosity prompts:** Default visible responses and written deliverables run longer on Claude Opus 5 than on Claude Opus 4.8, and lowering effort reduces thinking volume without reliably shortening the visible response. Prompt explicitly for conciseness or a target length instead. See [Response length and verbosity](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#response-length-and-verbosity) and [Written deliverable length](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#written-deliverable-length).1011026. **Remove carried-over verification instructions and constrain scope:** Claude Opus 5 verifies its own work without being told to, so remove explicit verification or self-check instructions carried over from prompts tuned for earlier models; leaving them in causes over-verification. For narrow tasks, constrain the task scope explicitly. In multi-agent frameworks, give explicit guidance on which scenarios warrant delegation or cap the number of subagents, because Claude Opus 5 delegates more readily than earlier models. See [Task scope and over-verification](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#task-scope-and-over-verification) and [Controlling subagent spawning](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#controlling-subagent-spawning).103104### Migration checklist105106* Update the model name from `claude-opus-4-8` to `claude-opus-5`.107* Review workloads that ran without a `thinking` field: they run with thinking on Claude Opus 5. Revisit `max_tokens`, which remains a hard limit on total output (thinking plus response text), or pass `thinking: {type: "disabled"}` at effort `high` or below to preserve the old behavior. If you disable thinking, review [Running with thinking disabled](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#running-with-thinking-disabled) for the output artifacts that can appear and their prompting mitigations.108* Update response parsing that reads content by position, such as `content[0].text` or a stream handler that assumes the first content block is text: with thinking on, `thinking` blocks arrive before `text` blocks. Select content blocks by `type` instead.109* If you run a tool-use loop, pass `thinking` blocks back complete and unmodified when you return tool results; modified blocks return a 400 error. See [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks).110* Verify any code that parses the `thinking` field treats it as display text only. `thinking.display` defaults to `"omitted"` on Claude Opus 5, the same as on Claude Opus 4.8, so thinking blocks arrive with an empty `thinking` field; set `display: "summarized"` to receive readable summaries. See [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).111* Audit requests that disable thinking: `thinking: {type: "disabled"}` with effort `xhigh` or `max` returns a 400 error, enforced on each request. Re-enable thinking or lower the effort to `high` or below.112* Re-evaluate your `effort` setting: run a fresh [effort](https://platform.claude.com/docs/en/build-with-claude/effort) sweep on your own evals rather than carrying over a setting tuned for an earlier model. `low` and `medium` effort are worth testing as cost and latency controls, and test `max` effort where maximum capability matters more than token spend. If you run at `xhigh` or `max` effort, raise `max_tokens` to at least 64k as a starting point.113* Review prompts near the caching minimum: prompts of 512 tokens or more can now create cache entries, down from 1,024 tokens on Claude Opus 4.8.114* Handle `stop_reason: "refusal"`, and consider `fallbacks: "default"` (beta) to re-run refused requests on a recommended fallback model automatically.115* If your organization has a [Priority Tier](https://platform.claude.com/docs/en/api/service-tiers#supported-models) commitment, plan capacity separately: Priority Tier is not supported on Claude Opus 5, while Claude Opus 4.8 keeps it.116* For agentic workloads, consider [task budgets](https://platform.claude.com/docs/en/build-with-claude/task-budgets) (beta) and mid-conversation tool changes (beta).117* Re-tune length and verbosity prompts: default visible responses and written deliverables run longer on Claude Opus 5, and lowering effort reduces thinking volume without reliably shortening the visible response. Prompt explicitly for conciseness or a target length. See [Response length and verbosity](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#response-length-and-verbosity) and [Written deliverable length](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#written-deliverable-length).118* Remove verification and self-check instructions carried over from prompts tuned for earlier models (they cause over-verification on Claude Opus 5), constrain task scope explicitly for narrow tasks, and in multi-agent frameworks steer or cap subagent delegation. See [Task scope and over-verification](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#task-scope-and-over-verification) and [Controlling subagent spawning](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#controlling-subagent-spawning).119* Re-baseline cost and latency on your own workloads. Per-token pricing is unchanged from Claude Opus 4.8, but thinking tokens are billed as output tokens, so workloads that ran without thinking can produce more output tokens per request.120121## Migrating to Claude Opus 5 from Claude Opus 4.7122123Claude Opus 5 should have strong out-of-the-box performance on existing Claude Opus 4.7 prompts and evals, at the same pricing of $5 USD per million input tokens and $25 USD per million output tokens. It supports the same set of features as Claude Opus 4.7, including the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows), [128k max output tokens](https://platform.claude.com/docs/en/models/overview), [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking), [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), [batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing), the [Files API](https://platform.claude.com/docs/en/build-with-claude/files), [PDF support](https://platform.claude.com/docs/en/build-with-claude/pdf-support), [vision](https://platform.claude.com/docs/en/build-with-claude/vision), and server-side and client-side [tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview), with two exceptions: [web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) is not available on Claude Opus 5, and [Priority Tier](https://platform.claude.com/docs/en/api/service-tiers#supported-models) is not supported on Claude Opus 5. It also adds [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) and publicly documents [refusal stop details](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response). On the Claude API and Google Cloud, Claude Opus 5 also supports [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) as the stable `computer_toolset_20260801` toolset and the [browser use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) for tasks inside webpages, neither of which Claude Opus 4.7 supports; existing integrations on the earlier `computer_20251124` version continue to work unchanged on both models. To upgrade an existing integration, see [Migrate from `computer_20251124`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124).124125<Note>126 If your code is on Claude Opus 4.6 or earlier, use [Migrating to Claude Opus 5 from Claude Opus 4.6 and earlier Opus models](https://platform.claude.com/docs/en/models/opus-5/migration-guide#migrating-from-claude-opus-46) instead. That section includes breaking changes (sampling parameters rejected, manual extended thinking rejected, new tokenizer) that the upgrade from Claude Opus 4.7 alone does not cover.127</Note>128129### Update your model name130131```python132# Opus migration133model = "claude-opus-4-7" # Before134model = "claude-opus-5" # After135```136137### Breaking changes1381391. **Thinking on by default:** On Claude Opus 4.7, requests without a `thinking` field run without thinking; on Claude Opus 5, the same requests run with [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking). `max_tokens` remains a hard limit on total output, thinking plus response text, so revisit it for workloads that ran without thinking on Claude Opus 4.7. Thinking tokens are billed as output tokens even when the thinking text is not returned to you, so although per-token pricing is unchanged, a workload that ran without thinking on Claude Opus 4.7 can produce more output tokens per request on Claude Opus 5; see [Cost control](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#cost-control). To preserve the old behavior, pass `thinking: {type: "disabled"}`, subject to the effort cap in the next item; note that with thinking disabled the model can occasionally emit tool calls as plain text or include internal XML tags in its visible output, so prefer lower effort levels with thinking enabled where you can, and see [Running with thinking disabled](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#running-with-thinking-disabled) for mitigations where you can't.140141 The response shape changes with it. With thinking on, a response can begin with one or more `thinking` blocks before the first `text` block, and because `thinking.display` defaults to `"omitted"` on Claude Opus 5, those blocks arrive with an empty `thinking` field alongside their `signature`. Code that reads the reply by position, such as `content[0].text` or a stream handler that treats the first `content_block_start` event as text, breaks on these responses. Select content blocks by their `type` field instead: read `text` from the blocks whose `type` is `"text"`, and branch on the block type when handling stream events. To receive readable thinking summaries instead of an empty `thinking` field, set `display: "summarized"`; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).142143 If you run a tool-use loop, pass the `thinking` blocks from each assistant response back to the API complete and unmodified when you return tool results, including blocks whose `thinking` field is empty. Echo the assistant message as received rather than filtering its content blocks by type or rebuilding it: the API rejects edited, reordered, or partially dropped thinking blocks with a 400 error. See [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks).1441452. **Disabling thinking is capped at `high` effort:** You can turn thinking off with `thinking: {type: "disabled"}`, but only at an [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level of `high` or below. A request that combines `thinking: {type: "disabled"}` with effort `xhigh` or `max` returns a 400 error. Claude Opus 4.7 accepts this combination, so audit requests that disable thinking before you migrate.146147 The check is enforced on each request: every request's effort and thinking configuration is validated independently, so a request that raises effort to `xhigh` or `max` while thinking is disabled is rejected even if earlier requests in the conversation were accepted.148149 Before (accepted on Claude Opus 4.7, rejected on Claude Opus 5):150151 ```python152 client.messages.create(153 model="claude-opus-4-7",154 max_tokens=16000,155 thinking={"type": "disabled"},156 output_config={"effort": "xhigh"},157 messages=[{"role": "user", "content": "..."}],158 )159 ```160161 After (Claude Opus 5), either remove the `thinking` field to run with thinking:162163 ```python164 client.messages.create(165 model="claude-opus-5",166 max_tokens=16000,167 output_config={"effort": "xhigh"}, # thinking is on by default168 messages=[{"role": "user", "content": "..."}],169 )170 ```171172 or keep thinking disabled and lower the effort:173174 ```python175 client.messages.create(176 model="claude-opus-5",177 max_tokens=16000,178 thinking={"type": "disabled"},179 output_config={"effort": "high"}, # or "medium", "low"180 messages=[{"role": "user", "content": "..."}],181 )182 ```183184### What changed185186The following items are not breaking changes; they describe behavior differences worth checking after you swap the model ID.1871881. **Sampling parameters (unchanged):** Setting `temperature`, `top_p`, or `top_k` to a non-default value returns a 400 error on Claude Opus 5, the same as on Claude Opus 4.7. Most SDKs still define these fields for compatibility with earlier models, so code that sets them type-checks even though the API rejects the request. The Python SDK (v1.0 and later) does not define them, and passing them raises a `TypeError`. If you removed these parameters when migrating to Opus 4.7, no further changes are needed.1891902. **Effort default is `high`:** The [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) default on Claude Opus 5 is `high` on the Claude API and Claude Code. If you already set effort explicitly, your setting is unchanged.1911923. **Effort levels recalibrated:** The token allocation behind each effort level changes on Claude Opus 5 compared to Claude Opus 4.7, and Claude Opus 5 supports the full set of effort levels (`low`, `medium`, `high`, `xhigh`, `max`). Run a fresh effort sweep on your own evals rather than carrying over a setting tuned for Claude Opus 4.7. `low` and `medium` effort are worth testing as cost and latency controls, and test `max` effort where maximum capability matters more than token spend. If you run at `xhigh` or `max` effort, set a large `max_tokens` so the model has room to think and act; start at 64k tokens and tune from there. See [Effort](https://platform.claude.com/docs/en/build-with-claude/effort).1931944. **1M context window is the default:** Claude Opus 5 serves the full 1M token [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) by default with no beta header and no long-context premium. If your client passes a context-window beta header for compatibility with older models, you can remove it on Claude Opus 5.1951965. **Mid-conversation system messages:** Claude Opus 5 accepts `role: "system"` messages immediately after a user turn in the `messages` array (subject to [placement rules](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations)). Use the top-level `system` field for instructions that apply from the start. Claude Opus 4.7 rejects `role: "system"` in `messages` with a 400 error. If you maintain code paths that rebuild the full message history to update instructions, you can simplify them and preserve [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits on earlier turns.1971986. **Refusal stop details:** The `stop_details` object on refusal responses (available since Claude Opus 4.7) is now publicly documented. When the model declines a request, it identifies the category of refusal, in addition to the existing `refusal` stop reason. No beta header is required, and there is no opt-out. See [Handling stop reasons](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons).1992007. **Lower prompt caching minimum:** The minimum cacheable prompt length on Claude Opus 5 is 512 tokens, lower than on Claude Opus 4.7. Prompts that were too short to cache on Claude Opus 4.7 can now create cache entries, with no code changes required. See [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations) for per-model minimums.2012028. **Fast mode:** Claude Opus 5 supports [fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) (research preview); fast mode is not available on Claude Opus 4.7, where requests with `speed: "fast"` return an error. The `speed: "fast"` parameter and `fast-mode-2026-02-01` beta header work unchanged on Claude Opus 5.203204### Recommended changes205206These are not required but will improve your experience:2072081. **Consider automatic fallbacks:** Claude Opus 5 ships with cybersecurity safety classifiers whose cyber-category refusals can fall back to Claude Opus 4.8. To re-run refused requests on another model automatically, consider the `fallbacks` parameter with the `"default"` mode (`fallbacks: "default"`), which selects a recommended fallback model based on the refusal category instead of a hand-maintained model list. Server-side fallback is in beta; the `"default"` mode requires the `server-side-fallback-2026-07-01` beta header. See [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback).2092102. **Change tools mid-conversation (beta):** You can add or remove tools between turns of a conversation without invalidating [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits on earlier turns. Send the beta header `mid-conversation-tool-changes-2026-07-01`. This is useful for agentic workloads that expose tools progressively or retire them as a task advances; without it, a changed tool list invalidates the cached prefix.2112123. **Re-tune length and verbosity prompts:** Default visible responses and written deliverables run longer on Claude Opus 5 than on earlier Opus models, and lowering effort reduces thinking volume without reliably shortening the visible response. Prompt explicitly for conciseness or a target length instead. See [Response length and verbosity](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#response-length-and-verbosity) and [Written deliverable length](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#written-deliverable-length).2132144. **Remove carried-over verification instructions and constrain scope:** Claude Opus 5 verifies its own work without being told to, so remove explicit verification or self-check instructions carried over from prompts tuned for earlier models; leaving them in causes over-verification. For narrow tasks, constrain the task scope explicitly. In multi-agent frameworks, give explicit guidance on which scenarios warrant delegation or cap the number of subagents, because Claude Opus 5 delegates more readily than earlier models. See [Task scope and over-verification](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#task-scope-and-over-verification) and [Controlling subagent spawning](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#controlling-subagent-spawning).215216### Migration checklist217218* Update model name from `claude-opus-4-7` to `claude-opus-5` (or update aliases).219* Review workloads that ran without a `thinking` field: they run with thinking on Claude Opus 5. Revisit `max_tokens`, which remains a hard limit on total output (thinking plus response text), or pass `thinking: {type: "disabled"}` at effort `high` or below to preserve the old behavior. If you disable thinking, review [Running with thinking disabled](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#running-with-thinking-disabled) for the output artifacts that can appear and their prompting mitigations.220* Update response parsing that reads content by position, such as `content[0].text` or a stream handler that assumes the first content block is text: with thinking on, `thinking` blocks arrive before `text` blocks. Select content blocks by `type` instead.221* If you run a tool-use loop, pass `thinking` blocks back complete and unmodified when you return tool results; modified blocks return a 400 error. See [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks).222* Verify any code that parses the `thinking` field treats it as display text only. `thinking.display` defaults to `"omitted"` on Claude Opus 5, the same as on Claude Opus 4.7, so thinking blocks arrive with an empty `thinking` field; set `display: "summarized"` to receive readable summaries. See [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).223* Audit requests that disable thinking: `thinking: {type: "disabled"}` with effort `xhigh` or `max` returns a 400 error, enforced on each request. Re-enable thinking or lower the effort to `high` or below.224* If you removed sampling parameters during the Opus 4.7 migration, no action is needed. If you re-added them with a 400-retry path, remove that retry path.225* Re-evaluate your `effort` setting: run a fresh [effort](https://platform.claude.com/docs/en/build-with-claude/effort) sweep on your own evals rather than carrying over a setting tuned for Claude Opus 4.7. Test `low` and `medium` effort as cost and latency controls, and `max` effort where maximum capability matters more than token spend. If you run at `xhigh` or `max` effort, raise `max_tokens` to at least 64k as a starting point.226* Remove any context-window beta header. The 1M context window is the default on the Claude API, Amazon Bedrock, Claude Platform on AWS, Google Cloud, and Microsoft Foundry.227* If you rebuild conversation history to update instructions, consider switching to a mid-conversation system message to preserve prompt cache hits.228* Verify your stop-reason handling reads `stop_details` on refusals (available since Claude Opus 4.7; now publicly documented), and consider `fallbacks: "default"` (beta) to re-run refused requests on a recommended fallback model automatically.229* Review prompts near the caching minimum: prompts of 512 tokens or more can now create cache entries.230* If you use [web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool), plan an alternative: it is not available on Claude Opus 5.231* If your organization has a [Priority Tier](https://platform.claude.com/docs/en/api/service-tiers#supported-models) commitment, note that Priority Tier is not supported on Claude Opus 5.232* If you used fast mode on Claude Opus 4.7, no request changes are needed beyond the model ID: `speed: "fast"` and the `fast-mode-2026-02-01` beta header work unchanged on Claude Opus 5.233* For agentic workloads, consider [task budgets](https://platform.claude.com/docs/en/build-with-claude/task-budgets) (beta) and mid-conversation tool changes (beta).234* Re-tune length and verbosity prompts, and remove verification and self-check instructions carried over from prompts tuned for earlier models.235* Re-baseline cost and latency at your chosen effort level. Per-token pricing is unchanged from Claude Opus 4.7, but thinking tokens are billed as output tokens, so workloads that ran without thinking can produce more output tokens per request.236237## Migrating to Claude Opus 5 from Claude Opus 4.6 and earlier Opus models238239Claude Opus 5 should have strong out-of-the-box performance on existing Claude Opus 4.6 prompts and evals at the same pricing, but there are a handful of behavioral and API changes worth knowing about as you migrate. Most of these changes took effect in Claude Opus 4.7; two more, thinking on by default and an effort cap on disabling thinking, take effect on Claude Opus 5. All of them are covered in this section, so it is complete for code coming straight from Claude Opus 4.6. Claude Opus 5 supports the same set of features as Claude Opus 4.6, including:240241* [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) at standard API pricing with no long-context premium242* [128k max output tokens](https://platform.claude.com/docs/en/models/overview)243* [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking)244* [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)245* [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing)246* [Files API](https://platform.claude.com/docs/en/build-with-claude/files)247* [PDF support](https://platform.claude.com/docs/en/build-with-claude/pdf-support)248* [Vision](https://platform.claude.com/docs/en/build-with-claude/vision)249* Server-side and client-side [tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) ([bash](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool), [code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool), [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool), [text editor](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool), [web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool), [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector), [memory](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool))250251Two exceptions: [web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) is not available on Claude Opus 5, and [Priority Tier](https://platform.claude.com/docs/en/api/service-tiers#supported-models) is not supported on Claude Opus 5. On the Claude API and Google Cloud, Claude Opus 5 also supports [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) as the stable `computer_toolset_20260801` toolset and the [browser use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) for tasks inside webpages, neither of which Claude Opus 4.6 or earlier Opus models support; existing integrations on the earlier `computer_20251124` version continue to work unchanged on Claude Opus 5. To upgrade an existing integration, see [Migrate from `computer_20251124`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124).252253### Update your model name254255```python256# Opus migration257model = "claude-opus-4-6" # Before258model = "claude-opus-5" # After259```260261### Breaking changes2622631. **Extended thinking removed:** `thinking: {type: "enabled", budget_tokens: N}` is no longer supported on Claude Opus 4.7 or later models and returns a 400 error. Switch to [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) (`thinking: {type: "adaptive"}`) and use the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) to control thinking depth. On Claude Opus 5, adaptive thinking is **on by default**: `thinking: {type: "adaptive"}` is valid and equivalent to omitting the `thinking` field entirely (see the next item).264265 Before (Claude Opus 4.6):266267 <CodeGroup>268 ```bash cURL269 curl https://api.anthropic.com/v1/messages \270 -H "x-api-key: $ANTHROPIC_API_KEY" \271 -H "anthropic-version: 2023-06-01" \272 -H "content-type: application/json" \273 -d '{274 "model": "claude-opus-4-6",275 "max_tokens": 16000,276 "thinking": {277 "type": "enabled",278 "budget_tokens": 10000279 },280 "messages": [281 {282 "role": "user",283 "content": "..."284 }285 ]286 }'287 ```288289 ```bash CLI290 ant messages create <<'YAML'291 model: claude-opus-4-6292 max_tokens: 16000293 thinking:294 type: enabled295 budget_tokens: 10000296 messages:297 - role: user298 content: "..."299 YAML300 ```301302 ```python Python303 client.messages.create(304 model="claude-opus-4-6",305 max_tokens=16000,306 thinking={"type": "enabled", "budget_tokens": 10000},307 messages=[{"role": "user", "content": "..."}],308 )309 ```310311 ```typescript TypeScript312 await client.messages.create({313 model: "claude-opus-4-6",314 max_tokens: 16000,315 thinking: { type: "enabled", budget_tokens: 10000 },316 messages: [{ role: "user", content: "..." }]317 });318 ```319320 ```csharp C#321 using Anthropic;322 using Anthropic.Models.Messages;323324 AnthropicClient client = new();325326 var parameters = new MessageCreateParams327 {328 Model = "claude-opus-4-6",329 MaxTokens = 16000,330 Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),331 Messages = [new() { Role = Role.User, Content = "..." }]332 };333334 var response = await client.Messages.Create(parameters);335 Console.WriteLine(response);336 ```337338 ```go Go339 client := anthropic.NewClient()340341 response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{342 Model: "claude-opus-4-6",343 MaxTokens: 16000,344 Thinking: anthropic.ThinkingConfigParamOfEnabled(10000),345 Messages: []anthropic.MessageParam{346 anthropic.NewUserMessage(anthropic.NewTextBlock("...")),347 },348 })349 if err != nil {350 log.Fatal(err)351 }352 fmt.Println(response)353 ```354355 ```java Java356 AnthropicClient client = AnthropicOkHttpClient.fromEnv();357358 MessageCreateParams params = MessageCreateParams.builder()359 .model("claude-opus-4-6")360 .maxTokens(16000L)361 .enabledThinking(10000L)362 .addUserMessage("...")363 .build();364365 Message response = client.messages().create(params);366 IO.println(response);367 ```368369 ```php PHP370 $client = new Client();371372 $message = $client->messages->create(373 maxTokens: 16000,374 messages: [['role' => 'user', 'content' => '...']],375 model: 'claude-opus-4-6',376 thinking: ['type' => 'enabled', 'budget_tokens' => 10000],377 );378 ```379380 ```ruby Ruby381 client = Anthropic::Client.new382383 message = client.messages.create(384 model: "claude-opus-4-6",385 max_tokens: 16000,386 thinking: {387 type: "enabled",388 budget_tokens: 10000389 },390 messages: [391 { role: "user", content: "..." }392 ]393 )394 ```395 </CodeGroup>396397 After (Claude Opus 5):398399 <CodeGroup>400 ```bash cURL401 curl https://api.anthropic.com/v1/messages \402 -H "x-api-key: $ANTHROPIC_API_KEY" \403 -H "anthropic-version: 2023-06-01" \404 -H "content-type: application/json" \405 -d '{406 "model": "claude-opus-5",407 "max_tokens": 16000,408 "thinking": {409 "type": "adaptive"410 },411 "output_config": {412 "effort": "high"413 },414 "messages": [415 {416 "role": "user",417 "content": "..."418 }419 ]420 }'421 ```422423 ```bash CLI424 ant messages create <<'YAML'425 model: claude-opus-5426 max_tokens: 16000427 thinking:428 type: adaptive429 output_config:430 effort: high431 messages:432 - role: user433 content: "..."434 YAML435 ```436437 ```python Python438 client.messages.create(439 model="claude-opus-5",440 max_tokens=16000,441 thinking={"type": "adaptive"},442 output_config={"effort": "high"}, # or "max", "xhigh", "medium", "low"443 messages=[{"role": "user", "content": "..."}],444 )445 ```446447 ```typescript TypeScript448 await client.messages.create({449 model: "claude-opus-5",450 max_tokens: 16000,451 thinking: { type: "adaptive" },452 output_config: { effort: "high" }, // or "max", "xhigh", "medium", "low"453 messages: [{ role: "user", content: "..." }]454 });455 ```456457 ```csharp C#458 using Anthropic;459 using Anthropic.Models.Messages;460461 AnthropicClient client = new();462463 var parameters = new MessageCreateParams464 {465 Model = "claude-opus-5",466 MaxTokens = 16000,467 Thinking = new ThinkingConfigAdaptive(),468 OutputConfig = new OutputConfig { Effort = Effort.High }, // or Max, Xhigh, Medium, Low469 Messages = [new() { Role = Role.User, Content = "..." }]470 };471472 var response = await client.Messages.Create(parameters);473 Console.WriteLine(response);474 ```475476 ```go Go477 client := anthropic.NewClient()478479 response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{480 Model: "claude-opus-5",481 MaxTokens: 16000,482 Thinking: anthropic.ThinkingConfigParamUnion{483 OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},484 },485 OutputConfig: anthropic.OutputConfigParam{486 Effort: anthropic.OutputConfigEffortHigh, // or Max, Xhigh, Medium, Low487 },488 Messages: []anthropic.MessageParam{489 anthropic.NewUserMessage(anthropic.NewTextBlock("...")),490 },491 })492 if err != nil {493 log.Fatal(err)494 }495 fmt.Println(response)496 ```497498 ```java Java499 AnthropicClient client = AnthropicOkHttpClient.fromEnv();500501 MessageCreateParams params = MessageCreateParams.builder()502 .model("claude-opus-5")503 .maxTokens(16000L)504 .thinking(ThinkingConfigAdaptive.builder().build())505 .outputConfig(OutputConfig.builder()506 .effort(OutputConfig.Effort.HIGH) // or MAX, XHIGH, MEDIUM, LOW507 .build())508 .addUserMessage("...")509 .build();510511 Message response = client.messages().create(params);512 IO.println(response);513 ```514515 ```php PHP516 $client = new Client();517518 $message = $client->messages->create(519 maxTokens: 16000,520 messages: [['role' => 'user', 'content' => '...']],521 model: 'claude-opus-5',522 thinking: ['type' => 'adaptive'],523 outputConfig: ['effort' => 'high'], // or 'max', 'xhigh', 'medium', 'low'524 );525 ```526527 ```ruby Ruby528 client = Anthropic::Client.new529530 message = client.messages.create(531 model: "claude-opus-5",532 max_tokens: 16000,533 thinking: {534 type: "adaptive"535 },536 output_config: {537 effort: "high" # or "max", "xhigh", "medium", "low"538 },539 messages: [540 { role: "user", content: "..." }541 ]542 )543 ```544 </CodeGroup>545546 Adaptive thinking is steerable through prompting and the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort); see [Choosing an effort level](https://platform.claude.com/docs/en/models/opus-5/migration-guide#choosing-an-effort-level).5475482. **Thinking on by default:** On Claude Opus 4.6 and Claude Opus 4.7, requests without a `thinking` field run without thinking; on Claude Opus 5, the same requests run with [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking). `max_tokens` remains a hard limit on total output, thinking plus response text, so revisit it for workloads that ran without thinking. Thinking tokens are billed as output tokens even when the thinking text is not returned to you, so although per-token pricing is unchanged, a workload that ran without thinking can produce more output tokens per request on Claude Opus 5; see [Cost control](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#cost-control). To preserve the old behavior, pass `thinking: {type: "disabled"}`, subject to the effort cap in the next item; note that with thinking disabled the model can occasionally emit tool calls as plain text or include internal XML tags in its visible output, so prefer lower effort levels with thinking enabled where you can, and see [Running with thinking disabled](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#running-with-thinking-disabled) for mitigations where you can't.549550 The response shape changes with it. With thinking on, a response can begin with one or more `thinking` blocks before the first `text` block, and because thinking content is omitted by default on Claude Opus 5 (item 5 in this list), those blocks arrive with an empty `thinking` field alongside their `signature`. Code that reads the reply by position, such as `content[0].text` or a stream handler that treats the first `content_block_start` event as text, breaks on these responses. Select content blocks by their `type` field instead: read `text` from the blocks whose `type` is `"text"`, and branch on the block type when handling stream events.551552 If you run a tool-use loop, pass the `thinking` blocks from each assistant response back to the API complete and unmodified when you return tool results, including blocks whose `thinking` field is empty. Echo the assistant message as received rather than filtering its content blocks by type or rebuilding it: the API rejects edited, reordered, or partially dropped thinking blocks with a 400 error. See [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks).5535543. **Disabling thinking is capped at `high` effort:** You can turn thinking off with `thinking: {type: "disabled"}`, but only at an [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level of `high` or below. A request that combines `thinking: {type: "disabled"}` with effort `xhigh` or `max` returns a 400 error on Claude Opus 5, enforced on each request. Audit requests that disable thinking before you migrate: re-enable thinking or lower the effort to `high` or below.5555564. **Sampling parameters removed:** Setting `temperature`, `top_p`, or `top_k` to any non-default value on Claude Opus 4.7 or later models, including Claude Opus 5, returns a 400 error. The Python SDK (v1.0 and later) does not define them, and passing them raises a `TypeError`. The safest migration path is to omit these parameters entirely from request payloads. Prompting is the recommended way to guide model behavior on Claude Opus 5. If you were using `temperature = 0` for determinism, note that it never guaranteed identical outputs on prior models.5575585. **Thinking content omitted by default:** Thinking blocks still appear in the response stream on Claude Opus 4.7 and later models, but their `thinking` field is empty unless you explicitly opt in. This is a silent change from Claude Opus 4.6, where the default was to return summarized thinking text. To restore summarized thinking content, set `thinking.display` to `"summarized"`:559560 <CodeGroup exclude="shell">561 ```python Python562 thinking = {563 "type": "adaptive",564 "display": "summarized",565 }566 ```567568 ```typescript TypeScript569 const thinking = {570 type: "adaptive",571 display: "summarized"572 };573 ```574575 ```csharp C#576 var thinking = new ThinkingConfigAdaptive { Display = Display.Summarized };577 ```578579 ```go Go580 thinking := anthropic.ThinkingConfigParamUnion{581 OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{582 Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized,583 },584 }585 ```586587 ```java Java588 ThinkingConfigAdaptive thinking = ThinkingConfigAdaptive.builder()589 .display(ThinkingConfigAdaptive.Display.SUMMARIZED)590 .build();591 ```592593 ```php PHP594 $thinking = ['type' => 'adaptive', 'display' => 'summarized'];595 ```596597 ```ruby Ruby598 thinking = {599 type: "adaptive",600 display: "summarized"601 }602 ```603 </CodeGroup>604605 The default is `"omitted"` on Claude Opus 4.7 and later models. If your product streams reasoning to users, the new default appears as a long pause before output begins; set `display: "summarized"` to restore visible progress during thinking. See [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display) for details.6066076. **Updated token counting:** Claude Opus 4.7 introduced a new tokenizer, which later Opus models, including Claude Opus 5, also use. It contributes to improved performance on a wide range of tasks, and it may use roughly 1x to 1.35x as many tokens when processing text compared to models before Claude Opus 4.7 (up to \~35% more, varying by content).608609 [`/v1/messages/count_tokens`](https://platform.claude.com/docs/en/build-with-claude/token-counting) returns a different number of tokens for Claude Opus 5 than it did for Claude Opus 4.6. Token efficiency can vary by workload shape.610611 Prompting interventions, `task_budget`, and `effort` can help control costs and ensure appropriate token usage. These controls may trade off model intelligence. Update your `max_tokens` parameters to give additional headroom, including compaction triggers. Claude Opus 5 provides a 1M context window at standard API pricing with no long-context premium.6126137. **Prefill removal (carried over from Opus 4.6):** Prefilling assistant messages returns a 400 error on Claude Opus 4.7 and later models, including Claude Opus 5. Use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs), system prompt instructions, or `output_config.format` instead.614615### Choosing an effort level616617The [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) allows you to tune Claude's intelligence versus token spend, trading off capability for faster speed and lower costs. Claude Opus 5 supports the full set of effort levels and defaults to `high`. Run a fresh effort sweep on your own evals rather than carrying over a setting tuned for an earlier model:618619* **`max`:** Can deliver gains on the most demanding tasks but may show diminishing returns from increased token usage and can be prone to overthinking on simpler ones. Test it where maximum capability matters more than token spend.620* **`xhigh`:** Extended capability for long-running agentic and coding work that needs more depth than the default.621* **`high`:** The default. Balances token usage and intelligence for most tasks.622* **`medium`:** Cost-saving step-down from the default, worth testing as a cost and latency control.623* **`low`:** Most efficient. Reserve for short, scoped tasks and latency-sensitive workloads.624625If you run at `xhigh` or `max` effort, set a large `max_tokens` so the model has room to think and act; start at 64k tokens and tune from there. Effort is more important for this model than for any prior Opus. Experiment with it actively when you upgrade.626627### Behavior changes628629Claude Opus 4.7 introduced several behavioral differences from Claude Opus 4.6 that are not API breaking changes but may require prompt updates or scaffolding removal. They carry forward to Claude Opus 5, with the adjustments noted in this list.6306311. **Response length varies by use case:** Claude Opus 4.7 calibrates response length to how complex it judges the task to be, rather than defaulting to a fixed verbosity. This usually means shorter answers on simple lookups and much longer ones on open-ended analysis.632633 If your product depends on a certain style or verbosity of output, you may need to tune your prompts. For example, to decrease verbosity, add: "Provide concise, focused responses. Skip non-essential context, and keep examples minimal." If you see specific kinds of over-explaining, add targeted instructions in your prompt to prevent them.634635 Positive examples showing how Claude can communicate with the appropriate level of concision tend to be more effective than negative examples or instructions that tell the model what not to do. On Claude Opus 5, default visible responses and written deliverables run longer than on earlier Opus models, and lowering effort reduces thinking volume without reliably shortening the visible response; prompt explicitly for conciseness or a target length. See [Response length and verbosity](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#response-length-and-verbosity).6366372. **More literal instruction following:** Claude Opus 4.7 interprets prompts more literally and explicitly than Claude Opus 4.6, particularly at lower effort levels. It does not silently generalize an instruction from one item to another, and it does not infer requests you didn't make. The upside of this literalism is precision and less thrash. It generally performs better for API use cases with carefully tuned prompts, structured extraction, and pipelines where you want predictable behavior. A prompt and harness review may be especially helpful for migration to Claude Opus 5.6386393. **More direct tone:** As with any new model, prose style on long-form writing may shift. Claude Opus 4.7 is more direct and opinionated, with less validation-forward phrasing and fewer emoji than Claude Opus 4.6's warmer style. If your product relies on a specific voice, re-evaluate style prompts against the new baseline.6406414. **Built-in progress updates in agentic traces:** Claude Opus 4.7 provides more regular, higher-quality updates to the user throughout long agentic traces. If you've added scaffolding to force interim status messages ("After every 3 tool calls, summarize progress"), try removing it. If you find that the length or contents of Claude Opus 4.7's user-facing updates are not well-calibrated to your use case, explicitly describe what these updates should look like in the prompt and provide examples.6426435. **Subagent spawning changed:** Claude Opus 4.7 tends to spawn fewer subagents by default than Claude Opus 4.6, while Claude Opus 5 delegates to subagents more readily than earlier models. The behavior is steerable through prompting in either direction; give explicit guidance around when subagents are desirable, or cap the number of subagents. See [Controlling subagent spawning](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#controlling-subagent-spawning).6446456. **Stricter effort calibration:** Meaningfully changing from Claude Opus 4.6, Claude Opus 4.7 respects [effort levels](https://platform.claude.com/docs/en/build-with-claude/effort) strictly, especially at the low end. At `low` and `medium`, the model scopes its work to what was asked rather than doing more than requested.646647 This is good for latency and cost, but on moderately complex tasks running at `low` effort there is some risk of under-thinking. If you observe shallow reasoning on complex problems, raise effort to `high` or `xhigh` rather than prompting around it.648649 If you need to keep effort at `low` for latency, add targeted guidance: "This task involves multistep reasoning. Think carefully through the problem before responding." See [Recommended effort levels for Claude Opus 4.7](https://platform.claude.com/docs/en/build-with-claude/effort#recommended-effort-levels-for-claude-opus-4-7).6506517. **Fewer tool calls by default:** Claude Opus 4.7 has a tendency to use tools less often than Claude Opus 4.6 and to use reasoning more. This produces better results in most cases.652653 To increase tool usage, raise the effort setting. `high` or `xhigh` effort settings show substantially more tool usage in agentic search and coding. You can also adjust your prompt to explicitly instruct the model about when and how to properly use its tools.6546558. **Real-time cybersecurity safeguards:** Newly added in Claude Opus 4.7, requests that involve prohibited or high-risk topics may lead to refusals. For legitimate security work such as penetration testing, vulnerability research, or red-teaming, apply to the [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet) to request reduced restrictions. The application route depends on how you access Claude.6566579. **High-resolution image support:** Claude Opus 4.7 is the first Claude model with high-resolution image support. Maximum image resolution is 2,576 pixels on the long edge, up from 1,568 pixels on prior models. This unlocks gains on vision-heavy workloads and is particularly valuable for computer use, screenshot understanding, and document analysis.658659 High-resolution support is automatic and requires no beta header or client-side opt-in. Two things to plan for:660661 * Full-resolution images can use up to approximately 3x more image tokens than on prior models (up to 4,784 tokens per image, compared to the previous cap of roughly 1,600 tokens per image). Re-budget `max_tokens` and cost expectations for image-heavy workloads, or downsample before sending if you do not need the additional fidelity.662 * Pointing and bounding-box coordinates returned by the model are 1:1 with actual image pixels on Claude Opus 4.7, so no scale-factor conversion is required.663664 See [High-resolution image support on Claude Opus 4.7](https://platform.claude.com/docs/en/build-with-claude/vision#high-resolution-image-support-on-claude-opus-4-7) for details.665666### Recommended changes667668These are not required but will improve your experience:6696701. **Re-evaluate `max_tokens`:** Because the same text produces a higher token count on Claude Opus 4.7 and later models, update your `max_tokens` parameters to give additional headroom, including compaction triggers. Prompting interventions, [`task_budget`](https://platform.claude.com/docs/en/build-with-claude/task-budgets), and [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) can help control costs and ensure appropriate token usage.6716722. **Audit token-count expectations:** Any code path that estimates tokens client-side or assumes a fixed token-to-character ratio should be re-tested against Claude Opus 5. Use the [Token counting endpoint](https://platform.claude.com/docs/en/build-with-claude/token-counting) to verify.6736743. **Adopt [task budgets](https://platform.claude.com/docs/en/build-with-claude/task-budgets) (beta):** Claude Opus 4.7 introduces task budgets. These budgets let you inform Claude how many tokens it has for a full agentic loop, including thinking, tool calls, tool results, and final output. The model sees a running countdown and uses it to prioritize work and finish the task gracefully as the budget is consumed. To use, set the beta header `task-budgets-2026-03-13` and add the following to your output config:675676 <CodeGroup exclude="shell">677 ```python Python678 output_config = {679 "effort": "high",680 "task_budget": {"type": "tokens", "total": 128000},681 }682 ```683684 ```typescript TypeScript685 const output_config = {686 effort: "high",687 task_budget: { type: "tokens", total: 128000 }688 };689 ```690691 ```csharp C#692 var outputConfig = new BetaOutputConfig693 {694 Effort = Effort.High,695 TaskBudget = new BetaTokenTaskBudget696 {697 Total = 128000,698 },699 };700 ```701702 ```go Go703 outputConfig := anthropic.BetaOutputConfigParam{704 Effort: anthropic.BetaOutputConfigEffortHigh,705 TaskBudget: anthropic.BetaTokenTaskBudgetParam{706 Total: 128000,707 },708 }709 ```710711 ```java Java712 BetaOutputConfig outputConfig = BetaOutputConfig.builder()713 .effort(BetaOutputConfig.Effort.HIGH)714 .taskBudget(BetaTokenTaskBudget.builder()715 .total(128000L)716 .build())717 .build();718 ```719720 ```php PHP721 $outputConfig = [722 'effort' => 'high',723 'taskBudget' => [724 'type' => 'tokens',725 'total' => 128000,726 ],727 ];728 ```729730 ```ruby Ruby731 output_config = {732 effort: :high,733 task_budget: {734 type: :tokens,735 total: 128_000736 }737 }738 ```739 </CodeGroup>740741 You may need to experiment with different task budgets for your use case. If the model is given a task budget that is too restrictive, it may complete the task less thoroughly, referencing its budget as the constraint.742743 For open-ended agentic tasks where quality matters more than speed, do not set a task budget. Reserve task budgets for workloads where you need the model to scope its work to a token allowance. The minimum value for a task budget is 20k tokens.744745 A task budget is not a hard cap; it's a suggestion that the model is aware of. It differs from `max_tokens`:746747 * **`task_budget`:** an advisory cap across the full agentic loop. The model sees it and uses it to pace itself.748 * **`max_tokens`:** a hard per-request ceiling on generated tokens. It is not passed to the model, so the model is not aware of it.749750 Use `task_budget` when you want the model to self-moderate, and `max_tokens` as a hard ceiling to cap usage.7517524. **Set a large `max_tokens` at `max` or `xhigh` effort:** If you are running Claude Opus 4.7 or a later model at `max` or `xhigh` effort, set a large max output token budget so the model has room to think and act across its subagents and tool calls. Start at 64k tokens and tune from there.7537545. **Downsample images if high resolution is unnecessary:** Claude Opus 4.7 and later models support images up to 2576px / 3.75MP. High-res images use more tokens. If the additional image fidelity is unnecessary, downsample images before sending to Claude to avoid token-usage increases. See [Images and vision](https://platform.claude.com/docs/en/build-with-claude/vision).7557566. **Consider automatic fallbacks:** Claude Opus 5 ships with cybersecurity safety classifiers whose cyber-category refusals can fall back to Claude Opus 4.8. To re-run refused requests on another model automatically, consider the `fallbacks` parameter with the `"default"` mode (`fallbacks: "default"`), which selects a recommended fallback model based on the refusal category instead of a hand-maintained model list. Server-side fallback is in beta; the `"default"` mode requires the `server-side-fallback-2026-07-01` beta header. See [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback).7577587. **Cache shorter prompts:** The minimum cacheable prompt length on Claude Opus 5 is 512 tokens, lower than on earlier Opus models. Prompts that were too short to cache can now create cache entries, with no code changes required. See [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations) for per-model minimums.7597608. **Change tools mid-conversation (beta):** You can add or remove tools between turns of a conversation without invalidating [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits on earlier turns. Send the beta header `mid-conversation-tool-changes-2026-07-01`. This is useful for agentic workloads that expose tools progressively or retire them as a task advances; without it, a changed tool list invalidates the cached prefix.7617629. **Remove carried-over verification instructions and constrain scope:** Claude Opus 5 verifies its own work without being told to, so remove explicit verification or self-check instructions carried over from prompts tuned for earlier models; leaving them in causes over-verification. For narrow tasks, constrain the task scope explicitly. See [Task scope and over-verification](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#task-scope-and-over-verification).763764### Migration checklist765766* Update model name from `claude-opus-4-6` to `claude-opus-5` (or update aliases).767* Remove `temperature`, `top_p`, and `top_k` from request payloads.768* Replace `thinking: {type: "enabled", budget_tokens: N}` with `thinking: {type: "adaptive"}` plus the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort), or remove the `thinking` field entirely; adaptive thinking is on by default on Claude Opus 5.769* Review workloads that ran without a `thinking` field: they run with thinking on Claude Opus 5. Revisit `max_tokens`, which remains a hard limit on total output (thinking plus response text), or pass `thinking: {type: "disabled"}` at effort `high` or below to preserve the old behavior.770* Update response parsing that reads content by position, such as `content[0].text` or a stream handler that assumes the first content block is text: with thinking on, `thinking` blocks arrive before `text` blocks. Select content blocks by `type` instead.771* If you run a tool-use loop, pass `thinking` blocks back complete and unmodified when you return tool results; modified blocks return a 400 error. See [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks).772* Audit requests that disable thinking: `thinking: {type: "disabled"}` with effort `xhigh` or `max` returns a 400 error, enforced on each request. Re-enable thinking or lower the effort to `high` or below.773* Remove any assistant-message prefills.774* If your UI displays thinking content, explicitly opt in to thinking summarization.775* Re-benchmark end-to-end cost and latency under the updated tokenization; thinking tokens are billed as output tokens, so workloads that ran without thinking can also produce more output tokens per request.776* Re-tune `max_tokens` to account for the updated tokenization.777* Re-test any client-side token-count estimations.778* If your application sends images, re-budget for [high-resolution image support](https://platform.claude.com/docs/en/build-with-claude/vision#high-resolution-image-support-on-claude-opus-4-7) (up to approximately 3x more image tokens per full-resolution image). Downsample before sending if you do not need the additional fidelity.779* If you consume pointing or bounding-box coordinates from the model, remove any scale-factor conversion; coordinates are 1:1 with actual image pixels on Claude Opus 4.7 and later models.780* Review prompts for the behavior changes (response length, literalism, tone, progress updates, subagents, effort calibration, tool triggering, cyber safeguards, high-resolution image handling).781* Re-baseline response length with existing length-control prompts removed, then tune explicitly.782* If using `xhigh` or `max` effort, raise `max_tokens` to at least 64k as a starting point.783* Consider adopting task budgets (beta) and mid-conversation tool changes (beta) for agentic workflows.784* Handle `stop_reason: "refusal"`, and consider `fallbacks: "default"` (beta) to re-run refused requests on a recommended fallback model automatically.785* Review prompts near the caching minimum: prompts of 512 tokens or more can now create cache entries on Claude Opus 5.786* If you use [web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool), plan an alternative: it is not available on Claude Opus 5.787* If your organization has a [Priority Tier](https://platform.claude.com/docs/en/api/service-tiers#supported-models) commitment, note that Priority Tier is not supported on Claude Opus 5.788* Remove verification and self-check instructions carried over from prompts tuned for earlier models; they cause over-verification on Claude Opus 5.789* If your product does legitimate security work, apply to the [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet) for access to lower restrictions on cyber content.790791### Migrating from Claude Opus 4.5 or earlier792793If you are migrating from Claude Opus 4.5, Opus 4.1, or an earlier model directly to Claude Opus 5, apply **all of the changes earlier in this section** plus the following cumulative changes, which took effect between Opus 4.5 and Opus 4.7. If you are migrating from Opus 4.6, the changes earlier in this section are all you need.794795#### Update your model name796797```python798# Opus migration799model = "claude-opus-4-5" # Before800model = "claude-opus-5" # After801```802803#### Breaking changes8048051. **Prefill removal** is covered in the [breaking changes for migrating from Claude Opus 4.6](https://platform.claude.com/docs/en/models/opus-5/migration-guide#opus-46-breaking-changes).8068072. **Tool parameter quoting:** Claude Opus 4.6 and later models may produce slightly different JSON string escaping in tool call arguments (for example, different handling of Unicode escapes or forward slash escaping). If you parse tool call `input` as a raw string rather than using a JSON parser, verify your parsing logic. Standard JSON parsers (such as `json.loads()` or `JSON.parse()`) handle these differences automatically.808809#### Recommended changes810811These changes improve your experience on Claude Opus 4.7 and later models. Items marked **(required on Opus 4.7)** were optional recommendations when Opus 4.6 launched but are now mandatory; the rest remain recommended.8128131. **Migrate to adaptive thinking (required on Opus 4.7):** `thinking: {type: "enabled", budget_tokens: N}` returns a 400 error on Claude Opus 4.7 and later models. Switch to `thinking: {type: "adaptive"}` and use the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) to control thinking depth; on Claude Opus 5, `thinking: {type: "adaptive"}` is equivalent to omitting the `thinking` field, which runs with adaptive thinking by default. See [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking).814815 <CodeGroup>816 ```bash cURL817 curl -sS https://api.anthropic.com/v1/messages \818 -H "content-type: application/json" \819 -H "x-api-key: $ANTHROPIC_API_KEY" \820 -H "anthropic-version: 2023-06-01" \821 -d '{822 "model": "claude-opus-5",823 "max_tokens": 16000,824 "thinking": {"type": "adaptive"},825 "output_config": {"effort": "high"},826 "messages": [{"role": "user", "content": "Your prompt here"}]827 }'828 ```829830 ```python Before831 response = client.beta.messages.create(832 model="claude-opus-4-5",833 max_tokens=16000,834 thinking={"type": "enabled", "budget_tokens": 32000},835 betas=["interleaved-thinking-2025-05-14"],836 messages=[{"role": "user", "content": "Your prompt here"}],837 )838 ```839840 ```python After841 response = client.messages.create(842 model="claude-opus-5",843 max_tokens=16000,844 thinking={"type": "adaptive"},845 output_config={"effort": "high"},846 messages=[{"role": "user", "content": "Your prompt here"}],847 )848 ```849850 ```bash CLI851 ant messages create <<'YAML'852 model: claude-opus-5853 max_tokens: 16000854 thinking:855 type: adaptive856 output_config:857 effort: high858 messages:859 - role: user860 content: Your prompt here861 YAML862 ```863864 ```typescript TypeScript865 const client = new Anthropic();866867 const response = await client.messages.create({868 model: "claude-opus-5",869 max_tokens: 16000,870 thinking: { type: "adaptive" },871 output_config: { effort: "high" },872 messages: [{ role: "user", content: "Your prompt here" }]873 });874 ```875876 ```csharp C#877 using Anthropic;878 using Anthropic.Models.Messages;879880 AnthropicClient client = new();881882 var parameters = new MessageCreateParams883 {884 Model = Model.ClaudeOpus5,885 MaxTokens = 16000,886 Thinking = new ThinkingConfigAdaptive(),887 OutputConfig = new OutputConfig { Effort = Effort.High },888 Messages = [new() { Role = Role.User, Content = "Your prompt here" }]889 };890891 var response = await client.Messages.Create(parameters);892 Console.WriteLine(response);893 ```894895 ```go Go896 client := anthropic.NewClient()897898 response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{899 Model: anthropic.ModelClaudeOpus5,900 MaxTokens: 16000,901 Thinking: anthropic.ThinkingConfigParamUnion{902 OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},903 },904 OutputConfig: anthropic.OutputConfigParam{905 Effort: anthropic.OutputConfigEffortHigh,906 },907 Messages: []anthropic.MessageParam{908 anthropic.NewUserMessage(anthropic.NewTextBlock("Your prompt here")),909 },910 })911 if err != nil {912 log.Fatal(err)913 }914 fmt.Println(response)915 ```916917 ```java Java918 import com.anthropic.models.messages.OutputConfig;919 import com.anthropic.models.messages.ThinkingConfigAdaptive;920 // ...921 public class AdaptiveThinkingExample {922 public static void main(String[] args) {923 AnthropicClient client = AnthropicOkHttpClient.fromEnv();924925 MessageCreateParams params = MessageCreateParams.builder()926 .model(Model.CLAUDE_OPUS_5)927 .maxTokens(16000L)928 .thinking(ThinkingConfigAdaptive.builder().build())929 .outputConfig(OutputConfig.builder()930 .effort(OutputConfig.Effort.HIGH)931 .build())932 .addUserMessage("Your prompt here")933 .build();934935 Message response = client.messages().create(params);936 System.out.println(response);937 }938 }939 ```940941 ```php PHP942 $client = new Client();943944 $response = $client->messages->create(945 maxTokens: 16000,946 messages: [['role' => 'user', 'content' => 'Your prompt here']],947 model: 'claude-opus-5',948 thinking: ['type' => 'adaptive'],949 outputConfig: ['effort' => 'high'],950 );951 ```952953 ```ruby Ruby954 client = Anthropic::Client.new955956 response = client.messages.create(957 model: "claude-opus-5",958 max_tokens: 16000,959 thinking: { type: "adaptive" },960 output_config: { effort: "high" },961 messages: [{ role: "user", content: "Your prompt here" }]962 )963 ```964 </CodeGroup>965966 Note that the migration also moves from `client.beta.messages.create` to `client.messages.create`. Adaptive thinking and effort do not require the beta SDK namespace or any beta headers.9679682. **Remove effort beta header:** The effort parameter does not require a beta header. Remove `betas=["effort-2025-11-24"]` from your requests.9699703. **Remove fine-grained tool streaming beta header:** Fine-grained tool streaming does not require a beta header. Remove `betas=["fine-grained-tool-streaming-2025-05-14"]` from your requests.9719724. **Remove interleaved thinking beta header:** Adaptive thinking automatically enables interleaved thinking on Claude Opus 4.7, Opus 4.6, and Sonnet 4.6. Remove `betas=["interleaved-thinking-2025-05-14"]` from your requests. The header is still functional on Sonnet 4.6 with manual extended thinking, but manual mode is deprecated.9739745. **Migrate to output\_config.format:** If using structured outputs, update `output_format={...}` to `output_config={"format": {...}}`. The API still accepts the deprecated `output_format` parameter, but it will be removed in a future model release. The Python SDK (v1.0 and later) does not accept `output_format={...}` on `client.beta.messages.create()` or `count_tokens()`. The `output_format=Model` argument of the `parse()` and `stream()` helpers is unchanged.975976### Migrating from Claude 4.1 or earlier977978If you're migrating from Opus 4.1 or earlier models directly to Claude Opus 5, apply all of the changes earlier in this section, plus the additional changes in this sub-section.979980```python981# From Opus 4.1982model = "claude-opus-4-1-20250805" # Before983model = "claude-opus-5" # After984985# From Sonnet 3.7986model = "claude-3-7-sonnet-20250219" # Before987model = "claude-opus-5" # After988```989990#### Additional breaking changes9919921. **Remove sampling parameters**993994 <Warning>995 This is a breaking change when migrating from Claude 3.x models.996 </Warning>997998 Starting with Claude Opus 4.7, setting `temperature`, `top_p`, or `top_k` to any non-default value returns a 400 error. The Python SDK (v1.0 and later) does not define them, and passing them raises a `TypeError`. The safest migration path is to omit these parameters entirely from requests, and to use prompting to guide the model's behavior. If you were using `temperature = 0` for determinism, note that it never guaranteed identical outputs.9991000 <CodeGroup exclude="shell">1001 ```python Python1002 # Before - This will error in Claude 4+ models1003 response = client.messages.create(1004 model="claude-3-7-sonnet-20250219",1005 temperature=0.7,1006 top_p=0.9, # Non-default sampling params return 400 on Opus 4.71007 # ...1008 )10091010 # After1011 response = client.messages.create(1012 model="claude-opus-5",1013 # ...1014 )1015 ```10161017 ```typescript TypeScript1018 // Before - This will error in Claude 4+ models1019 await client.messages.create({1020 model: "claude-3-7-sonnet-20250219",1021 temperature: 0.7,1022 top_p: 0.9 // Non-default sampling params return 400 on Opus 4.71023 // ...1024 });10251026 // After1027 await client.messages.create({1028 model: "claude-opus-5"1029 // ...1030 });1031 ```10321033 ```csharp C#1034 // Before - This will error in Claude 4+ models1035 await client.Messages.Create(new MessageCreateParams1036 {1037 Model = "claude-3-7-sonnet-20250219",1038 Temperature = 0.7,1039 TopP = 0.9, // Non-default sampling params return 400 on Opus 4.71040 // ...1041 });10421043 // After1044 await client.Messages.Create(new MessageCreateParams1045 {1046 Model = "claude-opus-5",1047 // ...1048 });1049 ```10501051 ```go Go1052 // Before - This will error in Claude 4+ models1053 client.Messages.New(ctx, anthropic.MessageNewParams{1054 Model: "claude-3-7-sonnet-20250219",1055 Temperature: anthropic.Float(0.7),1056 TopP: anthropic.Float(0.9), // Non-default sampling params return 400 on Opus 4.71057 // ...1058 })10591060 // After1061 client.Messages.New(ctx, anthropic.MessageNewParams{1062 Model: "claude-opus-5",1063 // ...1064 })1065 ```10661067 ```java Java1068 // Before - This will error in Claude 4+ models1069 client.messages().create(MessageCreateParams.builder()1070 .model("claude-3-7-sonnet-20250219")1071 .temperature(0.7)1072 .topP(0.9) // Non-default sampling params return 400 on Opus 4.71073 // ...1074 .build());10751076 // After1077 client.messages().create(MessageCreateParams.builder()1078 .model("claude-opus-5")1079 // ...1080 .build());1081 ```10821083 ```php PHP1084 // Before - This will error in Claude 4+ models1085 $client->messages->create(1086 model: 'claude-3-7-sonnet-20250219',1087 temperature: 0.7,1088 topP: 0.9, // Non-default sampling params return 400 on Opus 4.71089 // ...1090 );10911092 // After1093 $client->messages->create(1094 model: 'claude-opus-5',1095 // ...1096 );1097 ```10981099 ```ruby Ruby1100 # Before - This will error in Claude 4+ models1101 client.messages.create(1102 model: "claude-3-7-sonnet-20250219",1103 temperature: 0.7,1104 top_p: 0.9, # Non-default sampling params return 400 on Opus 4.71105 # ...1106 )11071108 # After1109 client.messages.create(1110 model: "claude-opus-5",1111 # ...1112 )1113 ```1114 </CodeGroup>111511162. **Update tool versions**11171118 <Warning>1119 This is a breaking change when migrating from Claude 3.x models.1120 </Warning>11211122 Update to the latest tool versions. Remove any code using the `undo_edit` command.11231124 <CodeGroup exclude="shell">1125 ```python Python1126 # Before1127 tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]11281129 # After1130 tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]1131 ```11321133 ```typescript TypeScript1134 // Before1135 const legacyTools = [{ type: "text_editor_20250124", name: "str_replace_editor" }];11361137 // After1138 const tools = [{ type: "text_editor_20250728", name: "str_replace_based_edit_tool" }];1139 ```11401141 ```csharp C#1142 var parameters = new MessageCreateParams1143 {1144 // Before: {"type": "text_editor_20250124", "name": "str_replace_editor"}1145 // After:1146 Tools = [new ToolTextEditor20250728()],1147 // ...1148 };1149 ```11501151 ```go Go1152 params := anthropic.MessageNewParams{1153 // Before: {"type": "text_editor_20250124", "name": "str_replace_editor"}1154 // After:1155 Tools: []anthropic.ToolUnionParam{1156 {OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},1157 },1158 // ...1159 }1160 ```11611162 ```java Java1163 MessageCreateParams params = MessageCreateParams.builder()1164 // Before: {"type": "text_editor_20250124", "name": "str_replace_editor"}1165 // After:1166 .addTool(ToolTextEditor20250728.builder().build())1167 // ...1168 .build();1169 ```11701171 ```php PHP1172 $message = $client->messages->create(1173 // Before: ['type' => 'text_editor_20250124', 'name' => 'str_replace_editor']1174 // After:1175 tools: [new ToolTextEditor20250728()],1176 // ...1177 );1178 ```11791180 ```ruby Ruby1181 # Before1182 legacy_tools = [{type: "text_editor_20250124", name: "str_replace_editor"}]11831184 # After1185 tools = [{type: "text_editor_20250728", name: "str_replace_based_edit_tool"}]1186 ```1187 </CodeGroup>11881189 * **Text editor:** Use `text_editor_20250728` and `str_replace_based_edit_tool`. See [Text editor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool) documentation for details.1190 * **Code execution:** Upgrade to `code_execution_20260521`. See [Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version) documentation for migration instructions.119111923. **Handle the `refusal` stop reason**11931194 Update your application to [handle `refusal` stop reasons](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals):11951196 <CodeGroup exclude="shell">1197 ```python Python1198 response = client.messages.create(...)11991200 if response.stop_reason == "refusal":1201 # Handle refusal appropriately1202 pass1203 ```12041205 ```typescript TypeScript1206 const response = await client.messages.create(/* ... */);12071208 if (response.stop_reason === "refusal") {1209 // Handle refusal appropriately1210 }1211 ```12121213 ```csharp C#1214 var response = await client.Messages.Create(...);12151216 if (response.StopReason?.Value() == StopReason.Refusal)1217 {1218 // Handle refusal appropriately1219 }1220 ```12211222 ```go Go1223 response, _ := client.Messages.New(ctx, params) // your existing request12241225 if response.StopReason == anthropic.StopReasonRefusal {1226 // Handle refusal appropriately1227 }1228 ```12291230 ```java Java1231 Message response = client.messages().create(...);12321233 StopReason reason = response.stopReason().orElse(StopReason.END_TURN);1234 if (reason.equals(StopReason.REFUSAL)) {1235 // Handle refusal appropriately1236 }1237 ```12381239 ```php PHP1240 $response = $client->messages->create(...);12411242 if ($response->stopReason === 'refusal') {1243 // Handle refusal appropriately1244 }1245 ```12461247 ```ruby Ruby1248 response = client.messages.create(...)12491250 if response.stop_reason == :refusal1251 # Handle refusal appropriately1252 end1253 ```1254 </CodeGroup>125512564. **Handle the `model_context_window_exceeded` stop reason**12571258 Claude 4.5+ models return a `model_context_window_exceeded` stop reason when generation stops because of hitting the context window limit, rather than the requested `max_tokens` limit. Update your application to handle this new stop reason:12591260 <CodeGroup exclude="shell">1261 ```python Python1262 response = client.messages.create(...)12631264 if response.stop_reason == "model_context_window_exceeded":1265 # Handle context window limit appropriately1266 pass1267 ```12681269 ```typescript TypeScript1270 const response = await client.messages.create(/* ... */);12711272 if (response.stop_reason === "model_context_window_exceeded") {1273 // Handle context window limit appropriately1274 }1275 ```12761277 ```csharp C#1278 var response = await client.Messages.Create(...);12791280 if (response.StopReason?.Raw() == "model_context_window_exceeded")1281 {1282 // Handle context window limit appropriately1283 }1284 ```12851286 ```go Go1287 response, _ := client.Messages.New(ctx, params) // your existing request12881289 if response.StopReason == "model_context_window_exceeded" {1290 // Handle context window limit appropriately1291 }1292 ```12931294 ```java Java1295 Message response = client.messages().create(...);12961297 StopReason reason = response.stopReason().orElse(StopReason.END_TURN);1298 if (reason.equals(StopReason.of("model_context_window_exceeded"))) {1299 // Handle context window limit appropriately1300 }1301 ```13021303 ```php PHP1304 $response = $client->messages->create(...);13051306 if ($response->stopReason === 'model_context_window_exceeded') {1307 // Handle context window limit appropriately1308 }1309 ```13101311 ```ruby Ruby1312 response = client.messages.create(...)13131314 if response.stop_reason == :model_context_window_exceeded1315 # Handle context window limit appropriately1316 end1317 ```1318 </CodeGroup>131913205. **Verify tool parameter handling (trailing newlines)**13211322 Claude 4.5+ models preserve trailing newlines in tool call string parameters that were previously stripped. If your tools rely on exact string matching against tool call parameters, verify your logic handles trailing newlines correctly.132313246. **Update your prompts for behavioral changes**13251326 Claude 4+ models have a more concise, direct communication style and require explicit direction. Review [prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) for optimization guidance.13271328#### Additional recommended changes13291330* **Remove legacy beta headers:** Remove `token-efficient-tools-2025-02-19` and `output-128k-2025-02-19`. All Claude 4+ models have built-in token-efficient tool use and these headers have no effect.13311332### Migration checklist (from Claude Opus 4.5 or earlier)13331334* Update model ID to `claude-opus-5`1335* Apply all of the [breaking changes for migrating from Claude Opus 4.6](https://platform.claude.com/docs/en/models/opus-5/migration-guide#opus-46-breaking-changes) (extended thinking removed, thinking on by default, effort cap on disabling thinking, sampling parameters removed, thinking display omitted by default, updated tokenization)1336* **BREAKING:** Remove assistant message prefills (returns 400 error); use structured outputs or `output_config.format` instead1337* **BREAKING on Opus 4.7:** Replace `thinking: {type: "enabled", budget_tokens: N}` with `thinking: {type: "adaptive"}` plus the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) (returns 400 on Opus 4.7)1338* Verify tool call JSON parsing uses a standard JSON parser1339* Remove `effort-2025-11-24` beta header (the effort parameter does not require it)1340* Remove `fine-grained-tool-streaming-2025-05-14` beta header1341* Remove `interleaved-thinking-2025-05-14` beta header (adaptive thinking enables interleaved thinking automatically)1342* Migrate `output_format` to `output_config.format` (if applicable)1343* If migrating from Claude 4.1 or earlier: remove `temperature`, `top_p`, and `top_k` (non-default values return 400 on Opus 4.7)1344* If migrating from Claude 4.1 or earlier: update tool versions (`text_editor_20250728`, `code_execution_20260521`)1345* If migrating from Claude 4.1 or earlier: handle `refusal` stop reason1346* If migrating from Claude 4.1 or earlier: handle `model_context_window_exceeded` stop reason1347* If migrating from Claude 4.1 or earlier: verify tool string parameter handling for trailing newlines1348* If migrating from Claude 4.1 or earlier: remove legacy beta headers (`token-efficient-tools-2025-02-19`, `output-128k-2025-02-19`)1349* Review and update prompts following [prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)1350* Test in development environment before production deployment13511352## Migrating to Claude Opus 5 from Claude Sonnet 513531354Claude Opus 5 and Claude Sonnet 5 share the same API surface: both run with [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) on by default, both default the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) to `high` on the Claude API and Claude Code, both serve a [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) by default with [128k max output tokens](https://platform.claude.com/docs/en/models/overview), and neither supports [Priority Tier](https://platform.claude.com/docs/en/api/service-tiers#supported-models). Manual extended thinking and non-default sampling parameters return a 400 error on both models, as does assistant prefill.13551356### Update your model name13571358```python1359model = "claude-sonnet-5" # Before1360model = "claude-opus-5" # After1361```13621363### What changed136413651. **Pricing:** Claude Opus 5 is priced at $5 USD per million input tokens and $25 USD per million output tokens. Claude Sonnet 5 is priced at $2/$10 USD per million input/output tokens. See [Claude pricing](https://platform.claude.com/docs/en/about-claude/pricing) for complete pricing.136613672. **Disabling thinking is capped at `high` effort:** On Claude Sonnet 5, `thinking: {type: "disabled"}` is accepted at any effort level. On Claude Opus 5, it is accepted only at an [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level of `high` or below; a request that combines `thinking: {type: "disabled"}` with effort `xhigh` or `max` returns a 400 error, enforced on each request. Audit requests that disable thinking before you migrate.136813693. **Mid-conversation system messages:** Claude Opus 5 accepts `role: "system"` messages immediately after a user turn in the `messages` array (subject to [placement rules](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations)). This feature is not available on Claude Sonnet 5. If you maintain code paths that rebuild the full message history to update instructions, you can simplify them and preserve [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits on earlier turns.137013714. **Web fetch is not available:** The [web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) tool is available on Claude Sonnet 5 but not on Claude Opus 5.13721373### Migration checklist13741375* Update the model name from `claude-sonnet-5` to `claude-opus-5`.1376* Audit requests that disable thinking: `thinking: {type: "disabled"}` with effort `xhigh` or `max` returns a 400 error on Claude Opus 5. Re-enable thinking or lower the effort to `high` or below.1377* If you use [web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool), plan an alternative: it is not available on Claude Opus 5.1378* Re-run [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) against Claude Opus 5 rather than reusing counts measured against Claude Sonnet 5, and re-baseline cost and latency on your own workloads; per-token pricing differs.1379