Moving an existing Claude Opus 4.6 application to Opus 4.7 takes more than changing model. A direct Messages API request can fail on its thinking, sampling or speed settings; a successful response can still break the application's parser or tool loop. This guide is for the owner of a text-only, direct Claude Messages API application who can inspect its actual requests, stage permitted task cases and approve a release. The result is a checked 4.7 revision or a documented hold, based on that application's evidence.
The big change
- What changed: Opus 4.7 uses
claude-opus-4-7, rejects manual thinking budgets andspeed: "fast", and uses a different tokenizer. Sampling-key rules also depend on the effective API version. - Why it matters: Request validity, response handling, token thresholds and task outcomes all need checking before the owner changes serving traffic.
- What to watch: API version
2026-10-21rejectstemperature,top_pandtop_keven at default values on every model. An SDK upgrade may change that version, so keep it out of a model-only comparison. Anthropic's migration guide, API versions
1. Capture the request the application actually sends
Pick one owned text call path. From the deployed configuration and a redacted serialized request, record the resolved SDK version, direct Claude API endpoint, effective anthropic-version header, fixed model ID, prompt revision, max_tokens, tools and schema if used, thinking and effort settings, and any sampling or speed fields. Check both source and runtime routing: a source search alone cannot establish what the service sends. Keep credentials and private task data out of the record. Direct HTTP requests set anthropic-version; an SDK sets it for you, so inspect the effective value rather than assuming it from the model name. API versions
Check whether this path sends images, uses computer control or consumes image coordinates. Those paths need their own migration: Opus 4.7 changes image resolution and returned coordinate scale. This procedure does not clear them for release. Record a speed: "fast" branch separately; 4.7 rejects it. Model migration guide
Before changing code, confirm that the account can access claude-opus-4-7, that staging has an approved spend limit, and that each test input and output may be sent to and retained by the provider under the owner's data rules. Keep the currently working 4.6 configuration and its observed behavior available while evaluating. Claude API use and billing are separate from a chat subscription. Model IDs identify fixed versions, but an account's access is an account-specific check. Model IDs, model deprecations
2. Freeze real task cases and a 4.6 baseline
The owner supplies the application, permitted inputs, expected outcomes and acceptance thresholds. Save a versioned case list before changing the prompt or request. It should cover an ordinary successful task, a denied or negative case, an empty or failed upstream result, and a boundary case near the application's output or context limit. Add client-tool and JSON-schema cases only where that application uses them. For each case, record the allowed tool effect or safe stub, expected application result, prohibited side effect and pass rule. This is a case-record shape, not a claim that BIG CHANGE has such an application:
Record field | Owner's actual value |
|---|---|
Case ID and permitted input revision | A private reference, without copied secrets or unnecessary personal data |
Expected result and prohibited effect | The owner's predeclared task rule and authority boundary |
Prompt, tool/schema, code and API-version revisions | Exact values used for both model runs |
Observation | Returned model, typed blocks, stop reason, application outcome, usage, latency, retry/cache activity and redacted error |
Decision | Pass, fail or unable to run, with the reason |
Run the permitted baseline through 4.6 if current access allows it. Capture the actual response and application result, not just an HTTP success. If 4.6 is unavailable or the chosen API version cannot serve both IDs, record the missing comparable baseline. A new SDK or anthropic-version is a separate compatibility change: establish a baseline under that version before attributing any difference to 4.7. API versions
3. Build a separate 4.7 request revision
Keep the prompt, approved cases, tools and effective API version fixed where both models support that version. Change the candidate route's model to claude-opus-4-7, then apply the fields that the inventoried 4.6 request actually uses:
Existing field or behavior | 4.7 candidate change | Check |
|---|---|---|
| Remove the manual budget; if thinking is needed, use | Do not convert the old budget number into an effort level. |
No thinking configuration | Preserve that deliberate route unless the task review chooses to enable thinking. | Opus 4.7 does not require thinking; its API effort default is |
| Omit all three keys from the 4.7 serialized request, including default-valued keys. | On API version |
| Remove or disable it and test whether the resulting latency is acceptable; otherwise leave this path on its prior approved route. | A 4.7 request with |
| Recount and retest against 4.7 usage. | Do not carry over a fixed character-to-token estimate as a count. |
For a JavaScript call path, the field-only candidate can be prepared from an already captured request object before it is sent. The owner still has to inspect the final serialized request and choose effort from real cases:
const candidate = structuredClone(baselineRequest);
candidate.model = "claude-opus-4-7";
delete candidate.temperature;
delete candidate.top_p;
delete candidate.top_k;
if (candidate.thinking?.type === "enabled") {
candidate.thinking = { type: "adaptive" };
candidate.output_config = { ...candidate.output_config, effort: "high" };
}
if (candidate.speed === "fast") delete candidate.speed;This leaves a no-thinking request without a thinking field. high is an explicit starting setting for the formerly manual-thinking branch, not a conversion of its old budget or an accepted production value. A fast path still needs its own latency decision.
Anthropic documents low, medium, high, xhigh and max effort for Opus 4.7 and a high API default. Effort guides allocation; it is not a hard token budget. Choose a value through the owner's case checks. A previous temperature: 0 setting did not guarantee repeatable output, so an exact text match is only appropriate if the application's real acceptance contract requires it. Keep existing supported tool choice and structured-output settings unless the current model/API reference identifies a conflict in that actual combination. Rules for later Opus generations do not establish a 4.7 restriction. Migration guide, thinking, effort, model deprecations
4. Recount and stage the same application cases
For each supported request shape, send the same approved input to /v1/messages/count_tokens under the 4.6 and 4.7 model IDs. Save both returned counts with their request revisions. The 4.7 tokenizer can count text differently; check the application's context threshold, compaction trigger, rate limits and max_tokens headroom against observed usage. Token counting is an estimate before generation, not a bill or an output-quality check. The endpoint rejects some inputs the Messages API accepts, including most server tools, the MCP connector and URL or file sourced image/document blocks. If it rejects an actual request, record the error and use authorized staging response usage; do not manufacture a count. Token counting
Run the frozen cases in staging within the approved budget. Confirm the returned model and inspect every response content block by type. A parser that assumes content[0].text can misread a thinking or tool block. Check stop_reason and handle refusal, API errors, timeout, max_tokens truncation and tool_use continuation as distinct outcomes. An empty displayed thinking string can reflect the default display setting while the block and signature still carry continuation state; it is not by itself a failed response. If the application uses client tools, preserve the complete assistant content, including thinking and tool blocks, in order, then send the matching tool_result blocks first in the next user message. Use safe stubs or separately approved effects, and check that denied cases never cause a write. Validate a used JSON schema and the fields and effects the application consumes. Thinking, tool calls, Messages API
5. Decide from results, then release or hold
Compare the fixed 4.6 baseline and 4.7 candidate case by case: accepted task result, rejected action, parser and tool behavior, schema validity, refusal/error handling, tokens, end-to-end latency and actual cost. Include retries and cache activity when reconciling usage with billing. No vendor benchmark, token ratio or price list can establish that this particular application improves. If a case fails, keep the exact request, error and failing revision; repair one defect under a new revision and rerun its affected and regression cases. A fast-mode route remains unmigrated if latency after disabling speed: "fast" misses the owner's threshold.
The application owner approves an exact code, request, prompt, API-version, model and effort revision only when the predeclared rules pass. Observe the first authorized traffic: confirm its returned model, request revision, application outcome, usage and errors. Then accept it or restore a verified available prior route under the owner's release controls. Check current 4.6 access and its compatible API version before naming 4.6 as rollback; if it is unavailable, hold traffic or use another already approved safe state. Do not make an unapproved production tool write merely to test migration. Model deprecations, API versions
This is a documentation-based procedure checked against Anthropic's current references on 22 October 2026. BIG CHANGE did not receive an application, run either model, make a paid call, observe an output or calculate a reader's bill. The owner's recorded tests determine whether the migration is complete.
Sources & further reading
- Claude Opus migration guide — Its 4.6-to-4.7 section documents the thinking, tokenizer and display changes; its fast-mode note establishes the 4.7 rejection. Other sections concern later target models and are not rules for this task.
- API versions and 2026-10-21 migration — Establish the effective header and the API-wide removal of sampling keys; neither proves the version used by a reader's SDK.
- Model deprecations and model IDs — Distinguish model-specific older-version restrictions and fixed IDs from actual account access.
- Thinking and effort — Document 4.7 thinking modes, display and effort options; they do not supply an equivalent setting for an application's old manual budget.
- Token counting — Documents the counting route and unsupported inputs; actual staging usage and billing remain owner observations.
- Messages API and handling tool calls — Define typed response and client-tool continuation requirements; an application's parser and authority checks still need testing.
