SPB Git

Repository Public

migration-guide.md 37.7 KB 678 lines markdown

1---2title: Migrating to Claude Sonnet 53url: https://platform.claude.com/docs/en/models/sonnet-5/migration-guide4description: "Migrate to Claude Sonnet 5 from earlier Claude models: model IDs, breaking 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-sonnet-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 Sonnet 5 offers the best combination of speed and intelligence in the Claude model family. It builds on Claude Sonnet 4.6.2223Claude Sonnet 5 is a drop-in upgrade for Claude Sonnet 4.6, priced at $2/$10 USD per million input/output tokens; see [Pricing](https://platform.claude.com/docs/en/about-claude/pricing) for details. There are two breaking API changes for code already running on Claude Sonnet 4.6. First, [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) is on by default and manual extended thinking (`thinking: {type: "enabled", budget_tokens: N}`) returns a 400 error, so requests that ran without thinking can now return `thinking` blocks before the first `text` block and code that reads content by position must select content blocks by `type`. Second, sampling parameters (`temperature`, `top_p`, `top_k`) set to non-default values return a 400 error. Use adaptive thinking with the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) to control thinking depth. Claude Sonnet 5 supports the same set of features as Claude Sonnet 4.6, including the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows), [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 the full set of server-side and client-side [tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview). On the Claude API and Google Cloud, Claude Sonnet 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 Sonnet 4.6 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). [Priority Tier](https://platform.claude.com/docs/en/api/service-tiers#supported-models) is not available on Claude Sonnet 5. Claude Sonnet 5 also uses a new tokenizer.2425## Migrating to Claude Sonnet 5 from Claude Sonnet 4.62627<Note>28  If your code is on Claude Sonnet 4.5 or earlier, also apply [Migrating to Claude Sonnet 5 from Claude Sonnet 4.5 and earlier Sonnet models](https://platform.claude.com/docs/en/models/sonnet-5/migration-guide#migrating-from-sonnet-45). Those steps include breaking changes (assistant message prefilling rejected, tool parameter JSON escaping differences) that this section alone does not cover.29</Note>3031### Update your model name3233```python34# Sonnet migration35model = "claude-sonnet-4-6"  # Before36model = "claude-sonnet-5"  # After37```3839### What changed4041Items 4 and 5 in the following list are breaking changes. `max_tokens` remains a hard limit on total output (thinking plus response text), so revisit it for workloads that ran without thinking on Claude Sonnet 4.6.42431. **New tokenizer:** Claude Sonnet 5 uses a new tokenizer. The same input text produces approximately 30% more tokens than on Claude Sonnet 4.6. The exact increase depends on the content. Requests, responses, and streaming events keep the same shape, and no code changes are required, but anything you measure or budget in tokens shifts: `usage` fields and [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) results for the same text are higher, the 1M token context window holds less text, and a `max_tokens` limit tuned for Claude Sonnet 4.6 may truncate equivalent output. Per-token pricing is lower ($2/$10 USD versus Claude Sonnet 4.6's $3/$15 USD per million input/output tokens), but the cost of an equivalent request does not drop in direct proportion. Re-run token counting against Claude Sonnet 5 rather than reusing counts measured against earlier models.44452. **128k max output tokens (unchanged):** Claude Sonnet 5 supports up to 128k output tokens, the same as Claude Sonnet 4.6. Existing `max_tokens` values remain valid. Account for the new tokenizer when sizing them.46473. **Assistant message prefilling (unchanged):** Prefilling the assistant message returns a `400` error on Claude Sonnet 5, the same as on Claude Sonnet 4.6. If you removed prefill when migrating to Claude Sonnet 4.6, no further changes are needed. Use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs), system prompt instructions, or `output_config.format` instead.48494. **Adaptive thinking on by default:** On Claude Sonnet 4.6, requests without a `thinking` field run without thinking; on Claude Sonnet 5, the same requests run with [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking). To turn thinking off, pass `thinking: {type: "disabled"}`. Manual extended thinking (`thinking: {type: "enabled", budget_tokens: N}`) is not supported and returns a 400 error. Use the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) (default `high`) to control thinking depth.5051   With thinking on, a response can begin with one or more `thinking` blocks before the first `text` block, returned with an empty `thinking` field at the default `display: "omitted"`. Code that reads the reply by position, such as `content[0].text` or a stream handler that treats the first content block as text, must select content blocks by their `type` field instead, and tool-use loops must pass `thinking` blocks back complete and unmodified with their tool results (see [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks)). Thinking tokens are billed as output tokens even when the thinking text is not returned. If you used thinking on Claude Sonnet 4.6 and display the returned thinking text, note that `thinking.display` defaulted to `"summarized"` there and defaults to `"omitted"` on Claude Sonnet 5; set `display: "summarized"`, as the following example does, to keep receiving readable summaries (see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display)).5253   <Tabs>54     <Tab title="Claude Sonnet 5">55       <Note>56         Adaptive thinking is on by default for Claude Sonnet 5. The `thinking` field is shown explicitly here to set `display: "summarized"`; if you omit `thinking`, Claude Sonnet 5 omits thinking content from the response by default. For per-model defaults, see [Configurations each model rejects](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#rejected-configurations).57       </Note>5859       <CodeGroup>60         ```bash cURL61         curl https://api.anthropic.com/v1/messages \62           -H "x-api-key: $ANTHROPIC_API_KEY" \63           -H "anthropic-version: 2023-06-01" \64           -H "content-type: application/json" \65           -d '{66             "model": "claude-sonnet-5",67             "max_tokens": 16000,68             "thinking": {69               "type": "adaptive",70               "display": "summarized"71             },72             "output_config": {73               "effort": "high"74             },75             "messages": [76               {77                 "role": "user",78                 "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"79               }80             ]81           }'82         ```8384         ```bash CLI85         ant messages create --transform content --format yaml <<'YAML'86         model: claude-sonnet-587         max_tokens: 1600088         thinking:89           type: adaptive90           display: summarized91         output_config:92           effort: high93         messages:94           - role: user95             content: Are there an infinite number of prime numbers such that n mod 4 == 3?96         YAML97         ```9899         ```python Python100         client = anthropic.Anthropic()101102         response = client.messages.create(103             model="claude-sonnet-5",104             max_tokens=16000,105             thinking={"type": "adaptive", "display": "summarized"},106             output_config={"effort": "high"},107             messages=[108                 {109                     "role": "user",110                     "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",111                 }112             ],113         )114115         # The response contains summarized thinking blocks and text blocks116         for block in response.content:117             match block.type:118                 case "thinking":119                     print(f"\nThinking summary: {block.thinking}")120                 case "text":121                     print(f"\nResponse: {block.text}")122         ```123124         ```typescript TypeScript125         const client = new Anthropic();126127         const response = await client.messages.create({128           model: "claude-sonnet-5",129           max_tokens: 16000,130           thinking: {131             type: "adaptive",132             display: "summarized"133           },134           output_config: {135             effort: "high"136           },137           messages: [138             {139               role: "user",140               content: "Are there an infinite number of prime numbers such that n mod 4 == 3?"141             }142           ]143         });144145         // The response contains summarized thinking blocks and text blocks146         for (const block of response.content) {147           switch (block.type) {148             case "thinking":149               console.log(`\nThinking summary: ${block.thinking}`);150               break;151             case "text":152               console.log(`\nResponse: ${block.text}`);153               break;154           }155         }156         ```157158         ```csharp C#159         AnthropicClient client = new();160161         var response = await client.Messages.Create(new()162         {163             Model = Model.ClaudeSonnet5,164             MaxTokens = 16000,165             Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized },166             OutputConfig = new OutputConfig { Effort = Effort.High },167             Messages =168             [169                 new()170                 {171                     Role = Role.User,172                     Content = "Are there an infinite number of prime numbers such that n mod 4 == 3?",173                 },174             ],175         });176177         // The response contains summarized thinking blocks and text blocks178         foreach (var block in response.Content)179         {180             if (block.TryPickThinking(out var thinking))181             {182                 Console.WriteLine($"\nThinking summary: {thinking.Thinking}");183             }184             else if (block.TryPickText(out var text))185             {186                 Console.WriteLine($"\nResponse: {text.Text}");187             }188         }189         ```190191         ```go Go192         client := anthropic.NewClient()193194         response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{195         	Model:     anthropic.ModelClaudeSonnet5,196         	MaxTokens: 16000,197         	Thinking: anthropic.ThinkingConfigParamUnion{198         		OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{199         			Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized,200         		},201         	},202         	OutputConfig: anthropic.OutputConfigParam{203         		Effort: anthropic.OutputConfigEffortHigh,204         	},205         	Messages: []anthropic.MessageParam{206         		anthropic.NewUserMessage(anthropic.NewTextBlock("Are there an infinite number of prime numbers such that n mod 4 == 3?")),207         	},208         })209         if err != nil {210         	log.Fatal(err)211         }212213         // The response contains summarized thinking blocks and text blocks214         for _, block := range response.Content {215         	switch block := block.AsAny().(type) {216         	case anthropic.ThinkingBlock:217         		fmt.Printf("\nThinking summary: %s", block.Thinking)218         	case anthropic.TextBlock:219         		fmt.Printf("\nResponse: %s", block.Text)220         	}221         }222         ```223224         ```java Java225         import com.anthropic.client.okhttp.AnthropicOkHttpClient;226         import com.anthropic.models.messages.MessageCreateParams;227         import com.anthropic.models.messages.Model;228         import com.anthropic.models.messages.OutputConfig;229         import com.anthropic.models.messages.ThinkingConfigAdaptive;230231         void main() {232             var client = AnthropicOkHttpClient.fromEnv();233234             var params = MessageCreateParams.builder()235                 .model(Model.CLAUDE_SONNET_5)236                 .maxTokens(16_000)237                 .thinking(ThinkingConfigAdaptive.builder()238                     .display(ThinkingConfigAdaptive.Display.SUMMARIZED)239                     .build())240                 .outputConfig(OutputConfig.builder()241                     .effort(OutputConfig.Effort.HIGH)242                     .build())243                 .addUserMessage("Are there an infinite number of prime numbers such that n mod 4 == 3?")244                 .build();245246             var response = client.messages().create(params);247248             // The response contains summarized thinking blocks and text blocks249             for (var block : response.content()) {250                 block.thinking().ifPresent(thinkingBlock ->251                     IO.println("\nThinking summary: " + thinkingBlock.thinking())252                 );253                 block.text().ifPresent(textBlock ->254                     IO.println("\nResponse: " + textBlock.text())255                 );256             }257         }258         ```259260         ```php PHP261         use Anthropic\Messages\TextBlock;262         use Anthropic\Messages\ThinkingBlock;263264         $client = new Client();265266         $response = $client->messages->create(267             model: 'claude-sonnet-5',268             maxTokens: 16000,269             thinking: ['type' => 'adaptive', 'display' => 'summarized'],270             outputConfig: ['effort' => 'high'],271             messages: [272                 [273                     'role' => 'user',274                     'content' => 'Are there an infinite number of prime numbers such that n mod 4 == 3?',275                 ],276             ],277         );278279         // The response contains summarized thinking blocks and text blocks280         foreach ($response->content as $block) {281             echo match (true) {282                 $block instanceof ThinkingBlock => "\nThinking summary: {$block->thinking}",283                 $block instanceof TextBlock => "\nResponse: {$block->text}",284                 default => '',285             };286         }287         ```288289         ```ruby Ruby290         client = Anthropic::Client.new291292         response = client.messages.create(293           model: "claude-sonnet-5",294           max_tokens: 16_000,295           thinking: {type: :adaptive, display: :summarized},296           output_config: {effort: :high},297           messages: [298             {299               role: :user,300               content: "Are there an infinite number of prime numbers such that n mod 4 == 3?"301             }302           ]303         )304305         # The response contains summarized thinking blocks and text blocks306         response.content.each do |block|307           case block308           when Anthropic::Models::ThinkingBlock309             puts "\nThinking summary: #{block.thinking}"310           when Anthropic::Models::TextBlock311             puts "\nResponse: #{block.text}"312           end313         end314         ```315       </CodeGroup>316     </Tab>317318     <Tab title="Claude Sonnet 4.6">319       <CodeGroup>320         ```bash cURL321         curl https://api.anthropic.com/v1/messages \322           -H "x-api-key: $ANTHROPIC_API_KEY" \323           -H "anthropic-version: 2023-06-01" \324           -H "content-type: application/json" \325           -d '{326             "model": "claude-sonnet-4-6",327             "max_tokens": 16000,328             "thinking": {329               "type": "enabled",330               "budget_tokens": 10000331             },332             "messages": [333               {334                 "role": "user",335                 "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"336               }337             ]338           }'339         ```340341         ```bash CLI342         ant messages create \343           --format yaml <<'YAML'344         model: claude-sonnet-4-6345         max_tokens: 16000346         thinking:347           type: enabled348           budget_tokens: 10000349         messages:350           - role: user351             content: Are there an infinite number of prime numbers such that n mod 4 == 3?352         YAML353         ```354355         ```python Python356         client = anthropic.Anthropic()357358         response = client.messages.create(359             model="claude-sonnet-4-6",360             max_tokens=16000,361             thinking={"type": "enabled", "budget_tokens": 10000},362             messages=[363                 {364                     "role": "user",365                     "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",366                 }367             ],368         )369370         # The response contains summarized thinking blocks and text blocks371         for block in response.content:372             match block.type:373                 case "thinking":374                     print(f"\nThinking summary: {block.thinking}")375                 case "text":376                     print(f"\nResponse: {block.text}")377         ```378379         ```typescript TypeScript380         const client = new Anthropic();381382         const response = await client.messages.create({383           model: "claude-sonnet-4-6",384           max_tokens: 16000,385           thinking: {386             type: "enabled",387             budget_tokens: 10000,388           },389           messages: [390             {391               role: "user",392               content: "Are there an infinite number of prime numbers such that n mod 4 == 3?",393             },394           ],395         });396397         // The response contains summarized thinking blocks and text blocks398         for (const block of response.content) {399           switch (block.type) {400             case "thinking":401               console.log(`\nThinking summary: ${block.thinking}`);402               break;403             case "text":404               console.log(`\nResponse: ${block.text}`);405               break;406           }407         }408         ```409410         ```csharp C#411         AnthropicClient client = new();412413         var response = await client.Messages.Create(new()414         {415             Model = Model.ClaudeSonnet4_6,416             MaxTokens = 16000,417             Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),418             Messages =419             [420                 new()421                 {422                     Role = Role.User,423                     Content = "Are there an infinite number of prime numbers such that n mod 4 == 3?",424                 },425             ],426         });427428         // The response contains summarized thinking blocks and text blocks429         foreach (var block in response.Content)430         {431             if (block.TryPickThinking(out var thinking))432             {433                 Console.WriteLine($"\nThinking summary: {thinking.Thinking}");434             }435             else if (block.TryPickText(out var text))436             {437                 Console.WriteLine($"\nResponse: {text.Text}");438             }439         }440         ```441442         ```go Go443         client := anthropic.NewClient()444445         response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{446         	Model:     anthropic.ModelClaudeSonnet4_6,447         	MaxTokens: 16000,448         	Thinking:  anthropic.ThinkingConfigParamOfEnabled(10000),449         	Messages: []anthropic.MessageParam{450         		anthropic.NewUserMessage(anthropic.NewTextBlock("Are there an infinite number of prime numbers such that n mod 4 == 3?")),451         	},452         })453         if err != nil {454         	log.Fatal(err)455         }456457         // The response contains summarized thinking blocks and text blocks458         for _, block := range response.Content {459         	switch block := block.AsAny().(type) {460         	case anthropic.ThinkingBlock:461         		fmt.Printf("\nThinking summary: %s", block.Thinking)462         	case anthropic.TextBlock:463         		fmt.Printf("\nResponse: %s", block.Text)464         	}465         }466         ```467468         ```java Java469         import com.anthropic.client.okhttp.AnthropicOkHttpClient;470         import com.anthropic.models.messages.MessageCreateParams;471         import com.anthropic.models.messages.Model;472473         void main() {474             var client = AnthropicOkHttpClient.fromEnv();475476             var params = MessageCreateParams.builder()477                 .model(Model.CLAUDE_SONNET_4_6)478                 .maxTokens(16_000)479                 .enabledThinking(10_000)480                 .addUserMessage("Are there an infinite number of prime numbers such that n mod 4 == 3?")481                 .build();482483             var response = client.messages().create(params);484485             // The response contains summarized thinking blocks and text blocks486             for (var block : response.content()) {487                 block.thinking().ifPresent(thinkingBlock ->488                     IO.println("\nThinking summary: " + thinkingBlock.thinking())489                 );490                 block.text().ifPresent(textBlock ->491                     IO.println("\nResponse: " + textBlock.text())492                 );493             }494         }495         ```496497         ```php PHP498         $client = new Client();499500         $response = $client->messages->create(501             model: 'claude-sonnet-4-6',502             maxTokens: 16000,503             thinking: ['type' => 'enabled', 'budget_tokens' => 10000],504             messages: [505                 [506                     'role' => 'user',507                     'content' => 'Are there an infinite number of prime numbers such that n mod 4 == 3?',508                 ],509             ],510         );511512         // The response contains summarized thinking blocks and text blocks513         foreach ($response->content as $block) {514             echo match (true) {515                 $block instanceof \Anthropic\Messages\ThinkingBlock => "\nThinking summary: {$block->thinking}",516                 $block instanceof \Anthropic\Messages\TextBlock => "\nResponse: {$block->text}",517                 default => '',518             };519         }520         ```521522         ```ruby Ruby523         client = Anthropic::Client.new524525         response = client.messages.create(526           model: "claude-sonnet-4-6",527           max_tokens: 16_000,528           thinking: {529             type: :enabled,530             budget_tokens: 10_000531           },532           messages: [533             {534               role: :user,535               content: "Are there an infinite number of prime numbers such that n mod 4 == 3?"536             }537           ]538         )539540         # The response contains summarized thinking blocks and text blocks541         response.content.each do |block|542           case block543           when Anthropic::Models::ThinkingBlock544             puts "\nThinking summary: #{block.thinking}"545           when Anthropic::Models::TextBlock546             puts "\nResponse: #{block.text}"547           end548         end549         ```550       </CodeGroup>551     </Tab>552   </Tabs>5535545. **Sampling parameters removed:** Sampling parameters (`temperature`, `top_p`, `top_k`) set to a non-default value are not accepted and return a 400 error.5555566. **Cybersecurity safeguards:** Claude Sonnet 5 is the first Sonnet-tier model with real-time cybersecurity safeguards. Requests that involve prohibited or high-risk cybersecurity topics may be refused. Refusals return as a successful HTTP 200 response with `stop_reason: "refusal"`, not an error. See [Real-time cyber safeguards on Claude Opus and Sonnet](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet) for what the safeguards block and how legitimate security work can apply to the Cyber Verification Program.557558### Migration checklist559560* Update model name from `claude-sonnet-4-6` to `claude-sonnet-5`.561* Re-run [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) against Claude Sonnet 5. The new tokenizer produces approximately 30% more tokens for the same text, which can change per-request cost even though per-token pricing is lower. The exact increase depends on the content and workload shape.562* Revisit `max_tokens` limits sized close to your expected output length, and raise them up to the 128k maximum (unchanged from Claude Sonnet 4.6) where useful.563* Remove `thinking: {type: "enabled", budget_tokens: N}` configuration (returns a 400 error). Adaptive thinking is on by default; pass `{type: "disabled"}` to turn it off, or use the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) to control depth.564* Update response parsing that reads content by position, such as `content[0].text`: with thinking on, `thinking` blocks arrive before `text` blocks. Select content blocks by `type` instead, and pass `thinking` blocks back unmodified in tool-use loops; modified blocks return a 400 error.565* Verify any code that parses the `thinking` field treats it as display text only. `thinking.display` defaults to `"omitted"` on Claude Sonnet 5 (it defaulted to `"summarized"` on Claude Sonnet 4.6), 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).566* Remove `temperature`, `top_p`, and `top_k` parameters set to non-default values (they return a 400 error on Claude Sonnet 5).567* Add handling for `stop_reason: "refusal"` if your workload may touch cybersecurity topics.568* Re-baseline cost on your typical workload before production deployment.569* Review `max_tokens` for workloads that previously ran without thinking.570571## Migrating to Claude Sonnet 5 from Claude Sonnet 4.5 and earlier Sonnet models572573If you are migrating from Claude Sonnet 4.5 or an earlier Sonnet model directly to Claude Sonnet 5, apply the [Migrating to Claude Sonnet 5 from Claude Sonnet 4.6](https://platform.claude.com/docs/en/models/sonnet-5/migration-guide#migrating-from-claude-sonnet-4-6-to-claude-sonnet-5) changes plus the changes in this section.574575<Warning>576  Claude Sonnet 5 defaults to an effort level of `high`, in contrast to Sonnet 4.5 which had no effort parameter. Consider adjusting the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) as you migrate. If not explicitly set, you may experience higher latency with the default effort level.577</Warning>578579### Breaking changes580581#### When migrating from Sonnet 4.55825831. **Prefilling assistant messages is no longer supported**584585   <Warning>586     This is a breaking change when migrating from Sonnet 4.5 or earlier.587   </Warning>588589   Prefilling assistant messages returns a `400` error on Claude Sonnet 4.6 and later models, including Claude Sonnet 5. Use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs), system prompt instructions, or `output_config.format` instead.590591   **Common prefill use cases and migrations:**592593   * **Controlling output formatting** (forcing JSON/YAML output): Use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) or tools with enum fields for classification tasks.594595   * **Eliminating preambles** (removing "Here is..." phrases): Add direct instructions in the system prompt: "Respond directly without preamble. Do not start with phrases like 'Here is...', 'Based on...', etc."596597   * **Avoiding bad refusals:** Claude is much better at appropriate refusals now. Clear prompting in the user message without prefill should be sufficient.598599   * **Continuations** (resuming interrupted responses): Move the continuation to the user message: "Your previous response was interrupted and ended with `[previous_response]`. Continue from where you left off."600601   * **Context hydration / role consistency** (refreshing context in long conversations): Inject what were previously prefilled-assistant reminders into the user turn instead.6026032. **Tool parameter JSON escaping may differ**604605   <Warning>606     This is a breaking change when migrating from Sonnet 4.5 or earlier.607   </Warning>608609   JSON string escaping in tool parameters may differ from previous models. Standard JSON parsers handle this automatically, but custom string-based parsing may need updates.610611**Extended thinking changes:** `budget_tokens` configurations from Claude Sonnet 4.5 (`thinking: {type: "enabled", budget_tokens: N}`) are not supported on Claude Sonnet 5 and return a 400 error. Adaptive thinking is on by default, so most workloads need no `thinking` configuration at all; use the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) to control thinking depth. If you ran Claude Sonnet 4.5 without extended thinking, pass `thinking: {type: "disabled"}` to preserve that behavior.612613#### When migrating from Claude 3.x6146153. **Remove sampling parameters**616617   <Warning>618     This is a breaking change when migrating from Claude 3.x models.619   </Warning>620621   Sampling parameters (`temperature`, `top_p`, `top_k`) set to a non-default value return a 400 error on Claude Sonnet 5. Remove them from requests, and use prompting to guide the model's behavior instead.6226234. **Update tool versions**624625   <Warning>626     This is a breaking change when migrating from Claude 3.x models.627   </Warning>628629   Update to the latest tool versions (`text_editor_20250728`, `code_execution_20260521`). Remove any code using the `undo_edit` command.6306315. **Handle the `refusal` stop reason**632633   Update your application to [handle `refusal` stop reasons](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals).6346356. **Update your prompts for behavioral changes**636637   Claude 4 models have a more concise, direct communication style. Review [prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) for optimization guidance.638639## Migrating to Claude Sonnet 5 from Claude Haiku 4.5640641Claude Haiku 4.5 and Claude Sonnet 5 differ more at the API level than adjacent models within one class: Claude Haiku 4.5 uses manual [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) (off by default), a 200k token context window, and up to 64k output tokens, while Claude Sonnet 5 runs with [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) on by default, serves a [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) by default, and supports up to [128k output tokens](https://platform.claude.com/docs/en/models/overview).642643### Update your model name644645```python646model = "claude-haiku-4-5-20251001"  # Before647model = "claude-sonnet-5"  # After648```649650### What changed6516521. **Thinking configuration:** Claude Haiku 4.5 supports manual extended thinking (`thinking: {type: "enabled", budget_tokens: N}`) and rejects `thinking: {type: "adaptive"}`. On Claude Sonnet 5, the support is reversed: adaptive thinking is on by default, and manual extended thinking returns a 400 error. Remove `thinking: {type: "enabled", budget_tokens: N}` configurations and rely on the default, or pass `thinking: {type: "disabled"}` to turn thinking off. `budget_tokens` has no direct replacement; use the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) to control thinking depth. Effort is not available on Claude Haiku 4.5 and defaults to `high` on Claude Sonnet 5.653654   The response shape changes for both kinds of Claude Haiku 4.5 request. Requests that ran without extended thinking can now return one or more `thinking` blocks before the first `text` block, so code that reads the reply by position, such as `content[0].text`, must select content blocks by their `type` field instead, and tool-use loops must pass `thinking` blocks back complete and unmodified with their tool results (see [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks)). Requests that used extended thinking keep receiving `thinking` blocks, but `thinking.display` defaults to `"omitted"` on Claude Sonnet 5 rather than `"summarized"`, so those blocks arrive with an empty `thinking` field; set `display: "summarized"` to keep receiving readable summaries (see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display)). Thinking tokens are billed as output tokens even when the thinking text is not returned.6556562. **Sampling parameters removed:** `temperature` and `top_p` work on Claude Haiku 4.5 (one at a time, not both). On Claude Sonnet 5, setting `temperature`, `top_p`, or `top_k` to a non-default value returns a 400 error. Remove these parameters and use prompting to guide the model's behavior.6576583. **Assistant prefill removed:** Prefilling the assistant message works on Claude Haiku 4.5 but returns a 400 error on Claude Sonnet 5. Use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs), system prompt instructions, or `output_config.format` instead.6596604. **Larger context window and output:** Claude Sonnet 5 serves a 1M token context window by default, up from 200k tokens on Claude Haiku 4.5, and supports up to 128k output tokens, up from 64k. Claude Sonnet 5 also uses a different tokenizer, so re-run [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) rather than reusing counts measured against Claude Haiku 4.5.6616625. **Pricing:** Claude Haiku 4.5 is priced at $1/$5 USD per million input/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).6636646. **Cybersecurity safeguards:** Claude Sonnet 5 has real-time cybersecurity safeguards. Requests that involve prohibited or high-risk cybersecurity topics may be refused, returned as a successful HTTP 200 response with `stop_reason: "refusal"`. See [Real-time cyber safeguards on Claude Opus and Sonnet](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet) for what the safeguards block and how legitimate security work can apply to the Cyber Verification Program.665666### Migration checklist667668* Update the model name from `claude-haiku-4-5-20251001` (or the `claude-haiku-4-5` alias) to `claude-sonnet-5`.669* Remove `thinking: {type: "enabled", budget_tokens: N}` configuration (returns a 400 error). Adaptive thinking is on by default; pass `thinking: {type: "disabled"}` to preserve no-thinking behavior, and revisit `max_tokens` for workloads that ran without thinking.670* Update response parsing that reads content by position, such as `content[0].text`: with thinking on, `thinking` blocks arrive before `text` blocks. Select content blocks by `type` instead, and pass `thinking` blocks back unmodified in tool-use loops; modified blocks return a 400 error.671* If your UI displays thinking content, set `display: "summarized"`. `thinking.display` defaults to `"omitted"` on Claude Sonnet 5, so thinking blocks otherwise arrive with an empty `thinking` field. See [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).672* Use the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) (default `high`) to control thinking depth and token spend; it is not available on Claude Haiku 4.5, so no existing setting carries over.673* Remove `temperature` and `top_p` settings (non-default values return a 400 error on Claude Sonnet 5).674* Remove any assistant-message prefills (they return a 400 error on Claude Sonnet 5).675* Re-run [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) against Claude Sonnet 5, and revisit `max_tokens` limits, which you can raise up to the 128k maximum.676* Add handling for `stop_reason: "refusal"` if your workload may touch cybersecurity topics.677* Re-baseline cost on your typical workload before production deployment; per-token pricing differs.678
Files main
Menu

Theme