Anthropic 平台文档（英文全量）

Migrating to Claude Opus 5 from Claude Opus 4.6 and earlier Opus models

Claude 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:

1M token context window at standard API pricing with no long-context premium
128k max output tokens
Adaptive thinking
Prompt caching
Batch processing
Files API
PDF support
Vision
Server-side and client-side tools (bash, code execution, computer use, text editor, web search, MCP connector, memory)

Two exceptions: web fetch is not available on Claude Opus 5, and Priority Tier is not supported on Claude Opus 5. On the Claude API and Google Cloud, Claude Opus 5 also supports computer use as the stable computer_toolset_20260801 toolset and the 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.

Update your model name

python

# Opus migration
model = "claude-opus-4-6"  # Before
model = "claude-opus-5"  # After

Breaking changes

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 (thinking: \{type: "adaptive"\}) and use the effort parameter 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).

Before (Claude Opus 4.6):

bash

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 16000,
    "thinking": {
      "type": "enabled",
      "budget_tokens": 10000
    },
    "messages": [
      {
        "role": "user",
        "content": "..."
      }
    ]
  }'

bash

ant messages create <<'YAML'
model: claude-opus-4-6
max_tokens: 16000
thinking:
  type: enabled
  budget_tokens: 10000
messages:
  - role: user
    content: "..."
YAML

python

client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "..."}],
)

typescript

await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 16000,
  thinking: { type: "enabled", budget_tokens: 10000 },
  messages: [{ role: "user", content: "..." }]
});

csharp

using Anthropic;
using Anthropic.Models.Messages;

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = "claude-opus-4-6",
    MaxTokens = 16000,
    Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
    Messages = [new() { Role = Role.User, Content = "..." }]
};

var response = await client.Messages.Create(parameters);
Console.WriteLine(response);

client := anthropic.NewClient()

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	Model:     "claude-opus-4-6",
	MaxTokens: 16000,
	Thinking:  anthropic.ThinkingConfigParamOfEnabled(10000),
	Messages: []anthropic.MessageParam{
		anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(response)

java

AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
    .model("claude-opus-4-6")
    .maxTokens(16000L)
    .enabledThinking(10000L)
    .addUserMessage("...")
    .build();

Message response = client.messages().create(params);
IO.println(response);

php

$client = new Client();

$message = $client->messages->create(
    maxTokens: 16000,
    messages: [['role' => 'user', 'content' => '...']],
    model: 'claude-opus-4-6',
    thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
);

ruby

client = Anthropic::Client.new

message = client.messages.create(
  model: "claude-opus-4-6",
  max_tokens: 16000,
  thinking: \{
    type: "enabled",
    budget_tokens: 10000
  \},
  messages: [
    \{ role: "user", content: "..." \}
  ]
)

After (Claude Opus 5):

bash

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 16000,
    "thinking": {
      "type": "adaptive"
    },
    "output_config": {
      "effort": "high"
    },
    "messages": [
      {
        "role": "user",
        "content": "..."
      }
    ]
  }'

bash

ant messages create <<'YAML'
model: claude-opus-5
max_tokens: 16000
thinking:
  type: adaptive
output_config:
  effort: high
messages:
  - role: user
    content: "..."
YAML

python

client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

typescript

await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" }, // or "max", "xhigh", "medium", "low"
  messages: [{ role: "user", content: "..." }]
});

csharp

using Anthropic;
using Anthropic.Models.Messages;

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = "claude-opus-5",
    MaxTokens = 16000,
    Thinking = new ThinkingConfigAdaptive(),
    OutputConfig = new OutputConfig { Effort = Effort.High }, // or Max, Xhigh, Medium, Low
    Messages = [new() { Role = Role.User, Content = "..." }]
};

var response = await client.Messages.Create(parameters);
Console.WriteLine(response);

client := anthropic.NewClient()

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	Model:     "claude-opus-5",
	MaxTokens: 16000,
	Thinking: anthropic.ThinkingConfigParamUnion{
		OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
	},
	OutputConfig: anthropic.OutputConfigParam{
		Effort: anthropic.OutputConfigEffortHigh, // or Max, Xhigh, Medium, Low
	},
	Messages: []anthropic.MessageParam{
		anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(response)

java

AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
    .model("claude-opus-5")
    .maxTokens(16000L)
    .thinking(ThinkingConfigAdaptive.builder().build())
    .outputConfig(OutputConfig.builder()
        .effort(OutputConfig.Effort.HIGH) // or MAX, XHIGH, MEDIUM, LOW
        .build())
    .addUserMessage("...")
    .build();

Message response = client.messages().create(params);
IO.println(response);

php

$client = new Client();

$message = $client->messages->create(
    maxTokens: 16000,
    messages: [['role' => 'user', 'content' => '...']],
    model: 'claude-opus-5',
    thinking: ['type' => 'adaptive'],
    outputConfig: ['effort' => 'high'], // or 'max', 'xhigh', 'medium', 'low'
);

ruby

client = Anthropic::Client.new

message = client.messages.create(
  model: "claude-opus-5",
  max_tokens: 16000,
  thinking: \{
    type: "adaptive"
  \},
  output_config: \{
    effort: "high" # or "max", "xhigh", "medium", "low"
  \},
  messages: [
    \{ role: "user", content: "..." \}
  ]
)

Adaptive thinking is steerable through prompting and the effort parameter; see Choosing an effort level.

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. 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. 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 for mitigations where you can't.
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.
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.
Disabling thinking is capped at high effort: You can turn thinking off with thinking: \{type: "disabled"\}, but only at an 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.
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.

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":

python

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

typescript

const thinking = \{
  type: "adaptive",
  display: "summarized"
\};

csharp

var thinking = new ThinkingConfigAdaptive \{ Display = Display.Summarized \};

thinking := anthropic.ThinkingConfigParamUnion\{
	OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam\{
		Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized,
	\},
\}

java

ThinkingConfigAdaptive thinking = ThinkingConfigAdaptive.builder()
    .display(ThinkingConfigAdaptive.Display.SUMMARIZED)
    .build();

php

$thinking = ['type' => 'adaptive', 'display' => 'summarized'];

ruby

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

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 for details.

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).
/v1/messages/count_tokens 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.
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.
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, system prompt instructions, or output_config.format instead.

Choosing an effort level

The effort parameter 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:

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.
xhigh: Extended capability for long-running agentic and coding work that needs more depth than the default.
high: The default. Balances token usage and intelligence for most tasks.
medium: Cost-saving step-down from the default, worth testing as a cost and latency control.
low: Most efficient. Reserve for short, scoped tasks and latency-sensitive workloads.

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. Effort is more important for this model than for any prior Opus. Experiment with it actively when you upgrade.

Behavior changes

Claude 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.

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.
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.
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.
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.
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.
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.
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.
Stricter effort calibration: Meaningfully changing from Claude Opus 4.6, Claude Opus 4.7 respects effort levels 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.
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.
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.
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.
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.
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 to request reduced restrictions. The application route depends on how you access Claude.
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.
High-resolution support is automatic and requires no beta header or client-side opt-in. Two things to plan for:
- 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.
- 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.
See High-resolution image support on Claude Opus 4.7 for details.

Recommended changes

These are not required but will improve your experience:

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, and effort can help control costs and ensure appropriate token usage.
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 to verify.
Adopt 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:
python
```
output_config = {
    "effort": "high",
    "task_budget": {"type": "tokens", "total": 128000},
}
```
typescript
```
const output_config = {
  effort: "high",
  task_budget: { type: "tokens", total: 128000 }
};
```
csharp
```
var outputConfig = new BetaOutputConfig
{
    Effort = Effort.High,
    TaskBudget = new BetaTokenTaskBudget
    {
        Total = 128000,
    },
};
```
go
```
outputConfig := anthropic.BetaOutputConfigParam{
	Effort: anthropic.BetaOutputConfigEffortHigh,
	TaskBudget: anthropic.BetaTokenTaskBudgetParam{
		Total: 128000,
	},
}
```
java
```
BetaOutputConfig outputConfig = BetaOutputConfig.builder()
    .effort(BetaOutputConfig.Effort.HIGH)
    .taskBudget(BetaTokenTaskBudget.builder()
        .total(128000L)
        .build())
    .build();
```
php
```
$outputConfig = [
    'effort' => 'high',
    'taskBudget' => [
        'type' => 'tokens',
        'total' => 128000,
    ],
];
```
ruby
```
output_config = \{
  effort: :high,
  task_budget: \{
    type: :tokens,
    total: 128_000
  \}
\}
```
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.
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.
A task budget is not a hard cap; it's a suggestion that the model is aware of. It differs from max_tokens:
- task_budget: an advisory cap across the full agentic loop. The model sees it and uses it to pace itself.
- 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.
Use task_budget when you want the model to self-moderate, and max_tokens as a hard ceiling to cap usage.
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.
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.
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.
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 for per-model minimums.
Change tools mid-conversation (beta): You can add or remove tools between turns of a conversation without invalidating prompt cache 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.
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.

Migration checklist

Update model name from claude-opus-4-6 to claude-opus-5 (or update aliases).
Remove temperature, top_p, and top_k from request payloads.
Replace thinking: \{type: "enabled", budget_tokens: N\} with thinking: \{type: "adaptive"\} plus the effort parameter, or remove the thinking field entirely; adaptive thinking is on by default on Claude Opus 5.
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.
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.
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.
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.
Remove any assistant-message prefills.
If your UI displays thinking content, explicitly opt in to thinking summarization.
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.
Re-tune max_tokens to account for the updated tokenization.
Re-test any client-side token-count estimations.
If your application sends images, re-budget for high-resolution image support (up to approximately 3x more image tokens per full-resolution image). Downsample before sending if you do not need the additional fidelity.
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.
Review prompts for the behavior changes (response length, literalism, tone, progress updates, subagents, effort calibration, tool triggering, cyber safeguards, high-resolution image handling).
Re-baseline response length with existing length-control prompts removed, then tune explicitly.
If using xhigh or max effort, raise max_tokens to at least 64k as a starting point.
Consider adopting task budgets (beta) and mid-conversation tool changes (beta) for agentic workflows.
Handle stop_reason: "refusal", and consider fallbacks: "default" (beta) to re-run refused requests on a recommended fallback model automatically.
Review prompts near the caching minimum: prompts of 512 tokens or more can now create cache entries on Claude Opus 5.
If you use web fetch, plan an alternative: it is not available on Claude Opus 5.
If your organization has a Priority Tier commitment, note that Priority Tier is not supported on Claude Opus 5.
Remove verification and self-check instructions carried over from prompts tuned for earlier models; they cause over-verification on Claude Opus 5.
If your product does legitimate security work, apply to the Cyber Verification Program for access to lower restrictions on cyber content.

Migrating from Claude Opus 4.5 or earlier

If 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.

Update your model name

python

# Opus migration
model = "claude-opus-4-5"  # Before
model = "claude-opus-5"  # After

Breaking changes

Prefill removal is covered in the breaking changes for migrating from Claude Opus 4.6.
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.

Recommended changes

These 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.

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 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.

bash

curl -sS https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 16000,
    "thinking": {"type": "adaptive"},
    "output_config": {"effort": "high"},
    "messages": [{"role": "user", "content": "Your prompt here"}]
  }'

python

response = client.beta.messages.create(
    model="claude-opus-4-5",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)

python

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "Your prompt here"}],
)

bash

ant messages create <<'YAML'
model: claude-opus-5
max_tokens: 16000
thinking:
  type: adaptive
output_config:
  effort: high
messages:
  - role: user
    content: Your prompt here
YAML

typescript

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" },
  messages: [{ role: "user", content: "Your prompt here" }]
});

csharp

using Anthropic;
using Anthropic.Models.Messages;

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus5,
    MaxTokens = 16000,
    Thinking = new ThinkingConfigAdaptive(),
    OutputConfig = new OutputConfig { Effort = Effort.High },
    Messages = [new() { Role = Role.User, Content = "Your prompt here" }]
};

var response = await client.Messages.Create(parameters);
Console.WriteLine(response);

client := anthropic.NewClient()

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	Model:     anthropic.ModelClaudeOpus5,
	MaxTokens: 16000,
	Thinking: anthropic.ThinkingConfigParamUnion{
		OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
	},
	OutputConfig: anthropic.OutputConfigParam{
		Effort: anthropic.OutputConfigEffortHigh,
	},
	Messages: []anthropic.MessageParam{
		anthropic.NewUserMessage(anthropic.NewTextBlock("Your prompt here")),
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(response)

java

import com.anthropic.models.messages.OutputConfig;
import com.anthropic.models.messages.ThinkingConfigAdaptive;
// ...
public class AdaptiveThinkingExample {
    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
            .model(Model.CLAUDE_OPUS_5)
            .maxTokens(16000L)
            .thinking(ThinkingConfigAdaptive.builder().build())
            .outputConfig(OutputConfig.builder()
                .effort(OutputConfig.Effort.HIGH)
                .build())
            .addUserMessage("Your prompt here")
            .build();

        Message response = client.messages().create(params);
        System.out.println(response);
    }
}

php

$client = new Client();

$response = $client->messages->create(
    maxTokens: 16000,
    messages: [['role' => 'user', 'content' => 'Your prompt here']],
    model: 'claude-opus-5',
    thinking: ['type' => 'adaptive'],
    outputConfig: ['effort' => 'high'],
);

ruby

client = Anthropic::Client.new

response = client.messages.create(
  model: "claude-opus-5",
  max_tokens: 16000,
  thinking: \{ type: "adaptive" \},
  output_config: \{ effort: "high" \},
  messages: [\{ role: "user", content: "Your prompt here" \}]
)

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.

Remove effort beta header: The effort parameter does not require a beta header. Remove betas=["effort-2025-11-24"] from your requests.
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.
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.
Migrate to output_config.format: If using structured outputs, update output_format=\{...\} to <code v-pre>output_config={"format": {...}}</code>. 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.

Migrating from Claude 4.1 or earlier

If 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.

python

# From Opus 4.1
model = "claude-opus-4-1-20250805"  # Before
model = "claude-opus-5"  # After

# From Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # Before
model = "claude-opus-5"  # After

Additional breaking changes

Remove sampling parameters

This is a breaking change when migrating from Claude 3.x models.

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.

python

# Before - This will error in Claude 4+ models
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    temperature=0.7,
    top_p=0.9,  # Non-default sampling params return 400 on Opus 4.7
    # ...
)

# After
response = client.messages.create(
    model="claude-opus-5",
    # ...
)

typescript

// Before - This will error in Claude 4+ models
await client.messages.create(\{
  model: "claude-3-7-sonnet-20250219",
  temperature: 0.7,
  top_p: 0.9 // Non-default sampling params return 400 on Opus 4.7
  // ...
\});

// After
await client.messages.create(\{
  model: "claude-opus-5"
  // ...
\});

csharp

// Before - This will error in Claude 4+ models
await client.Messages.Create(new MessageCreateParams
\{
    Model = "claude-3-7-sonnet-20250219",
    Temperature = 0.7,
    TopP = 0.9, // Non-default sampling params return 400 on Opus 4.7
    // ...
\});

// After
await client.Messages.Create(new MessageCreateParams
\{
    Model = "claude-opus-5",
    // ...
\});

// Before - This will error in Claude 4+ models
client.Messages.New(ctx, anthropic.MessageNewParams\{
	Model:       "claude-3-7-sonnet-20250219",
	Temperature: anthropic.Float(0.7),
	TopP:        anthropic.Float(0.9), // Non-default sampling params return 400 on Opus 4.7
	// ...
\})

// After
client.Messages.New(ctx, anthropic.MessageNewParams\{
	Model: "claude-opus-5",
	// ...
\})

java

// Before - This will error in Claude 4+ models
client.messages().create(MessageCreateParams.builder()
    .model("claude-3-7-sonnet-20250219")
    .temperature(0.7)
    .topP(0.9) // Non-default sampling params return 400 on Opus 4.7
    // ...
    .build());

// After
client.messages().create(MessageCreateParams.builder()
    .model("claude-opus-5")
    // ...
    .build());

php

// Before - This will error in Claude 4+ models
$client->messages->create(
    model: 'claude-3-7-sonnet-20250219',
    temperature: 0.7,
    topP: 0.9, // Non-default sampling params return 400 on Opus 4.7
    // ...
);

// After
$client->messages->create(
    model: 'claude-opus-5',
    // ...
);

ruby

# Before - This will error in Claude 4+ models
client.messages.create(
  model: "claude-3-7-sonnet-20250219",
  temperature: 0.7,
  top_p: 0.9, # Non-default sampling params return 400 on Opus 4.7
  # ...
)

# After
client.messages.create(
  model: "claude-opus-5",
  # ...
)

Update tool versions

This is a breaking change when migrating from Claude 3.x models.

Update to the latest tool versions. Remove any code using the undo_edit command.

python

# Before
tools = [\{"type": "text_editor_20250124", "name": "str_replace_editor"\}]

# After
tools = [\{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"\}]

typescript

// Before
const legacyTools = [\{ type: "text_editor_20250124", name: "str_replace_editor" \}];

// After
const tools = [\{ type: "text_editor_20250728", name: "str_replace_based_edit_tool" \}];

csharp

var parameters = new MessageCreateParams
\{
    // Before: \{"type": "text_editor_20250124", "name": "str_replace_editor"\}
    // After:
    Tools = [new ToolTextEditor20250728()],
    // ...
\};

params := anthropic.MessageNewParams\{
	// Before: \{"type": "text_editor_20250124", "name": "str_replace_editor"\}
	// After:
	Tools: []anthropic.ToolUnionParam\{
		\{OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param\{&#125;&#125;,
	\},
	// ...
\}

java

MessageCreateParams params = MessageCreateParams.builder()
    // Before: \{"type": "text_editor_20250124", "name": "str_replace_editor"\}
    // After:
    .addTool(ToolTextEditor20250728.builder().build())
    // ...
    .build();

php

$message = $client->messages->create(
    // Before: ['type' => 'text_editor_20250124', 'name' => 'str_replace_editor']
    // After:
    tools: [new ToolTextEditor20250728()],
    // ...
);

ruby

# Before
legacy_tools = [\{type: "text_editor_20250124", name: "str_replace_editor"\}]

# After
tools = [\{type: "text_editor_20250728", name: "str_replace_based_edit_tool"\}]

Text editor: Use text_editor_20250728 and str_replace_based_edit_tool. See Text editor tool documentation for details.
Code execution: Upgrade to code_execution_20260521. See Code execution tool documentation for migration instructions.

Handle the refusal stop reason

Update your application to handle refusal stop reasons:

python

response = client.messages.create(...)

if response.stop_reason == "refusal":
    # Handle refusal appropriately
    pass

typescript

const response = await client.messages.create(/* ... */);

if (response.stop_reason === "refusal") \{
  // Handle refusal appropriately
\}

csharp

var response = await client.Messages.Create(...);

if (response.StopReason?.Value() == StopReason.Refusal)
\{
    // Handle refusal appropriately
\}

response, _ := client.Messages.New(ctx, params) // your existing request

if response.StopReason == anthropic.StopReasonRefusal \{
	// Handle refusal appropriately
\}

java

Message response = client.messages().create(...);

StopReason reason = response.stopReason().orElse(StopReason.END_TURN);
if (reason.equals(StopReason.REFUSAL)) \{
    // Handle refusal appropriately
\}

php

$response = $client->messages->create(...);

if ($response->stopReason === 'refusal') {
    // Handle refusal appropriately
}

ruby

response = client.messages.create(...)

if response.stop_reason == :refusal
  # Handle refusal appropriately
end

Handle the model_context_window_exceeded stop reason

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:

python

response = client.messages.create(...)

if response.stop_reason == "model_context_window_exceeded":
    # Handle context window limit appropriately
    pass

typescript

const response = await client.messages.create(/* ... */);

if (response.stop_reason === "model_context_window_exceeded") {
  // Handle context window limit appropriately
}

csharp

var response = await client.Messages.Create(...);

if (response.StopReason?.Raw() == "model_context_window_exceeded")
{
    // Handle context window limit appropriately
}

response, _ := client.Messages.New(ctx, params) // your existing request

if response.StopReason == "model_context_window_exceeded" {
	// Handle context window limit appropriately
}

java

Message response = client.messages().create(...);

StopReason reason = response.stopReason().orElse(StopReason.END_TURN);
if (reason.equals(StopReason.of("model_context_window_exceeded"))) {
    // Handle context window limit appropriately
}

php

$response = $client->messages->create(...);

if ($response->stopReason === 'model_context_window_exceeded') \{
    // Handle context window limit appropriately
\}

ruby

response = client.messages.create(...)

if response.stop_reason == :model_context_window_exceeded
  # Handle context window limit appropriately
end

Verify tool parameter handling (trailing newlines)
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.
Update your prompts for behavioral changes
Claude 4+ models have a more concise, direct communication style and require explicit direction. Review prompting best practices for optimization guidance.

Additional recommended changes

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.

Migration checklist (from Claude Opus 4.5 or earlier)

Update model ID to claude-opus-5
Apply all of the breaking changes for migrating from Claude Opus 4.6 (extended thinking removed, thinking on by default, effort cap on disabling thinking, sampling parameters removed, thinking display omitted by default, updated tokenization)
BREAKING: Remove assistant message prefills (returns 400 error); use structured outputs or output_config.format instead
BREAKING on Opus 4.7: Replace thinking: \{type: "enabled", budget_tokens: N\} with thinking: \{type: "adaptive"\} plus the effort parameter (returns 400 on Opus 4.7)
Verify tool call JSON parsing uses a standard JSON parser
Remove effort-2025-11-24 beta header (the effort parameter does not require it)
Remove fine-grained-tool-streaming-2025-05-14 beta header
Remove interleaved-thinking-2025-05-14 beta header (adaptive thinking enables interleaved thinking automatically)
Migrate output_format to output_config.format (if applicable)
If migrating from Claude 4.1 or earlier: remove temperature, top_p, and top_k (non-default values return 400 on Opus 4.7)
If migrating from Claude 4.1 or earlier: update tool versions (text_editor_20250728, code_execution_20260521)
If migrating from Claude 4.1 or earlier: handle refusal stop reason
If migrating from Claude 4.1 or earlier: handle model_context_window_exceeded stop reason
If migrating from Claude 4.1 or earlier: verify tool string parameter handling for trailing newlines
If migrating from Claude 4.1 or earlier: remove legacy beta headers (token-efficient-tools-2025-02-19, output-128k-2025-02-19)
Review and update prompts following prompting best practices
Test in development environment before production deployment

messages

batches

organization

federation

sessions

events

threads

vaults

activities

batches

Migrating to Claude Opus 5 from Claude Opus 4.6 and earlier Opus models ​

Update your model name ​

Breaking changes ​

Choosing an effort level ​

Behavior changes ​

Recommended changes ​

Migration checklist ​

Migrating from Claude Opus 4.5 or earlier ​

Update your model name ​

Breaking changes ​

Recommended changes ​

Migrating from Claude 4.1 or earlier ​

Additional breaking changes ​

Additional recommended changes ​

Migration checklist (from Claude Opus 4.5 or earlier) ​

Migrating to Claude Opus 5 from Claude Opus 4.6 and earlier Opus models

Update your model name

Breaking changes

Choosing an effort level

Behavior changes

Recommended changes

Migration checklist

Migrating from Claude Opus 4.5 or earlier

Update your model name

Breaking changes

Recommended changes

Migrating from Claude 4.1 or earlier

Additional breaking changes

Additional recommended changes

Migration checklist (from Claude Opus 4.5 or earlier)