Migrating from Claude Opus 4.6 to Opus 4.7: the breaking changes

Claude Opus 4.7 launched April 16, 2026. Migrating from Opus 4.6 is mostly a model name swap — but there are five API breaking changes that will return 400 errors if you don't address them first.

This article covers each change and what to replace it with, followed by a complete checklist.

Breaking change 1: Extended thinking removed

Before (Opus 4.6):

client.messages.create(
    model="claude-opus-4-6",
    max_tokens=64000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    messages=[...],
)

After (Opus 4.7):

client.messages.create(
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},
    messages=[...],
)

thinking: {type: "enabled", budget_tokens: N} returns a 400 error on Opus 4.7. Switch to adaptive thinking and use the effort parameter to control thinking depth.

Adaptive thinking is off by default — requests without a thinking field run without thinking, matching Opus 4.6 behavior. Set thinking: {type: "adaptive"} explicitly to enable it.

Available effort levels: low, medium, high, xhigh (new), max. For most coding and agentic work, start with xhigh.

Breaking change 2: Sampling parameters removed

Setting temperature, top_p, or top_k to any non-default value returns a 400 error. Remove these parameters entirely:

# Remove these from Opus 4.7 requests:
# temperature=0.7
# top_p=0.9
# top_k=40

If you were using temperature=0 for determinism: note that it never guaranteed identical outputs on prior models. Use structured outputs or explicit formatting instructions in your system prompt instead.

Breaking change 3: Thinking content omitted by default

Thinking blocks still appear in the response, but their thinking field is empty on Opus 4.7 unless you explicitly opt in. This is a silent change from Opus 4.6.

If your product streams reasoning to users or displays thinking progress, add display: "summarized":

thinking = {
    "type": "adaptive",
    "display": "summarized",  # add this to restore visible thinking
}

Without this, users will see a pause before output begins instead of reasoning progress. The default on Opus 4.7 is "omitted".

Breaking change 4: New tokenizer

Opus 4.7 uses a new tokenizer that consumes 1.0–1.35x as many input tokens as Opus 4.6, depending on content type. This isn't a breaking change in the API sense — requests won't error — but it will affect costs and may cause failures if your code assumes specific token counts or has tight max_tokens budgets.

What to do:

• Increase max_tokens to give headroom (Anthropic recommends starting at 64k for xhigh/max effort)
• Re-test any client-side token-counting code or character-to-token ratio assumptions
• Use the Token Counting endpoint (/v1/messages/count_tokens) to verify against Opus 4.7 specifically

Breaking change 5: Prefill removal (carried from Opus 4.6)

Prefilling assistant messages (starting the assistant turn with your own text) returns a 400 error. This was introduced in Opus 4.6 and still applies.

Replace prefills with structured outputs or system prompt instructions:

# Before (breaks on 4.6+):
messages=[
    {"role": "user", "content": "List the items"},
    {"role": "assistant", "content": "["},  # prefill
]

# After:
# Use output_config.format for structured JSON
output_config={"format": {"type": "json_schema", "json_schema": {...}}}

Migration checklist

• Update model name: claude-opus-4-6 → claude-opus-4-7
• Remove temperature, top_p, top_k from all request payloads
• Replace thinking: {type: "enabled", budget_tokens: N} with thinking: {type: "adaptive"} + output_config: {effort: "xhigh"}
• Remove any assistant-message prefills; replace with structured outputs or prompt instructions
• If your UI displays thinking content: add thinking.display: "summarized"
• Re-benchmark end-to-end cost and latency under the new tokenizer
• Raise max_tokens to 64k+ if using xhigh or max effort
• Re-test any client-side token-count estimations
• If you send images: re-budget for high-resolution support (up to 3x more tokens per image); downsample if you don't need the full resolution
• Review prompts for behavioral changes: response length calibration, more literal instruction following, fewer subagents
• If your product does legitimate security work: apply to the Cyber Verification Program

Automated migration via Claude Code

In Claude Code, run /claude-api migrate to invoke the bundled Claude API skill:

/claude-api migrate this project to claude-opus-4-7

The skill applies the model ID swap, parameter removals, prefill replacement, and effort calibration across your codebase, then produces a checklist of items to verify manually.

Sonnet 4 and Opus 4 retire June 15, 2026

Alongside the Opus 4.7 launch, Anthropic announced that the original Sonnet 4 and Opus 4 models are retiring:

• claude-sonnet-4-20250514 → retire June 15, 2026 → migrate to claude-sonnet-4-6
• claude-opus-4-20250514 → retire June 15, 2026 → migrate to claude-opus-4-7

If you are still on the original Sonnet 4 model ID, the migration to Sonnet 4.6 is a model name swap with no breaking changes. Sonnet 4.6 supports extended thinking, the 1M token context window, and all tools.

Check your codebase for hardcoded model IDs with the -20250514 suffix and update them before June 15.

Full migration guide

platform.claude.com/docs/en/about-claude/models/migration-guide