Markdown edition

# Move a Claude Opus 4.6 API application to 4.7 and check the result

> Migrate one owned Claude Messages API call path from Opus 4.6 to 4.7 by checking request fields, typed responses, client tools, token counts and real task outcomes before release.

By BIGCHANGE.AI Editorial

Published: 2026-10-22T06:47:37.999Z
Updated: 2026-10-22T06:47:37.999Z
Canonical: https://bigchange.ai/blog/claude-opus-46-47-messages-api-migration-guide

![Conceptual charcoal illustration of an unbranded desktop monitor displaying two columns of abstract code-like marks with restrained orange highlights.](https://bigchange.ai/api/media/file/claude-opus-46-47-request-review-hero-v1.png)
AI-generated conceptual illustration by BIG CHANGE.

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 and `speed: "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-21` rejects `temperature`, `top_p` and `top_k` even 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](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide), [API versions](https://platform.claude.com/docs/en/api/versioning)

## 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](https://platform.claude.com/docs/en/api/versioning)

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](https://platform.claude.com/docs/en/models/opus-5-5/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](https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions), [model deprecations](https://platform.claude.com/docs/en/about-claude/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](https://platform.claude.com/docs/en/api/versioning)

## 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 |
| --- | --- | --- |
| `thinking: {"type":"enabled","budget_tokens":N}` | Remove the manual budget; if thinking is needed, use `thinking: {"type":"adaptive"}` and an explicit, task-tested `output_config: {"effort":"…"}`. | 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 `high`. |
| `temperature`, `top_p`, `top_k` | Omit all three **keys** from the 4.7 serialized request, including default-valued keys. | On API version `2026-10-21`, any included value fails on every model. Earlier versions reject non-default values on 4.7. |
| `speed: "fast"` | 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 `speed: "fast"` fails. |
| `max_tokens`, context or compaction threshold | 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:

```javascript
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](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide), [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking), [effort](https://platform.claude.com/docs/en/build-with-claude/effort), [model deprecations](https://platform.claude.com/docs/en/about-claude/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](https://platform.claude.com/docs/en/build-with-claude/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](https://platform.claude.com/docs/en/build-with-claude/thinking), [tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls), [Messages API](https://platform.claude.com/docs/en/api/messages/create)

## 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](https://platform.claude.com/docs/en/about-claude/model-deprecations), [API versions](https://platform.claude.com/docs/en/api/versioning)

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](https://platform.claude.com/docs/en/models/opus-5-5/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](https://platform.claude.com/docs/en/api/versioning) and [2026-10-21 migration](https://platform.claude.com/docs/en/api/migration-2026-10-21) — Establish the effective header and the API-wide removal of sampling keys; neither proves the version used by a reader's SDK.
- [Model deprecations](https://platform.claude.com/docs/en/about-claude/model-deprecations) and [model IDs](https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions) — Distinguish model-specific older-version restrictions and fixed IDs from actual account access.
- [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) and [effort](https://platform.claude.com/docs/en/build-with-claude/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](https://platform.claude.com/docs/en/build-with-claude/token-counting) — Documents the counting route and unsupported inputs; actual staging usage and billing remain owner observations.
- [Messages API](https://platform.claude.com/docs/en/api/messages/create) and [handling tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls) — Define typed response and client-tool continuation requirements; an application's parser and authority checks still need testing.

## Sources

- [Claude Opus migration guide](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide) — Explicit 4.6-to-4.7 deltas and 4.7 fast-mode rejection; later target-model rules excluded.
- [API versions](https://platform.claude.com/docs/en/api/versioning) — Effective version header and 2026-10-21 all-value sampling-key removal.
- [API-version migration](https://platform.claude.com/docs/en/api/migration-2026-10-21) — SDK/header migration context; compare models only under a held version or separately rebaseline.
- [Model deprecations](https://platform.claude.com/docs/en/about-claude/model-deprecations) — Earlier-version model sampler restriction and current model status; account rollback access still unverified.
- [Model IDs and versions](https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions) — Fixed Claude API IDs; provider-specific IDs differ.
- [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) — 4.7 adaptive/no-thinking modes, omitted display and continuation blocks.
- [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) — 4.7 levels and high API default, without a manual-budget equivalence.
- [Token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) — Count route and unsupported shapes; response usage is an observed fallback.
- [Create a Message](https://platform.claude.com/docs/en/api/messages/create) — Request and response shapes to audit against the actual application.
- [Handle tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls) — Client tool result ordering, matching and error handling.
- [Claude Opus 4.7 release](https://www.anthropic.com/news/claude-opus-4-7) — Vendor release context only; no application performance claim drawn.