Claude API 2026-10-21 移行ガイド｜temperature で400・SDK 2.0 の変更点と対処【2026年10月】

2026年10月21日、Anthropic は Claude API の新しい API バージョン 2026-10-21 と、それを既定で使う新しい SDK（Python 2.0.0、TypeScript 1.0.0 など）を公開しました。 新バージョンでは temperature・top_p・top_k を送ると既定値でも 400 エラーになるなど、2023-06-01 以来の破壊的変更が入っています。Claude API を使っている人がやることは、SDK を上げる前に自分のコードが影響を受けるかを確かめ、直してから SDK と一緒にリリースすることです。Claude Code を使っているなら、10月21日（UTC）公開の v2.1.307 で追加された /claude-api api-version を移行作業に使うこともできます。

本記事では、2026年10月22日に取得した公式ドキュメント（リリースノート、移行ガイド、バージョンの説明ページ）と、手元の隔離環境で実行した Python SDK 1.17.0・2.0.0、TypeScript SDK 1.1.0、Claude Code 2.1.307 の結果をもとに、移行に必要な情報をまとめます。手元で実行して確かめたことと、ドキュメントに書かれていることは分けて書いています。

結論：2026-10-21 への移行で押さえる5点

API バージョン 2026-10-21 は、Claude API の挙動を決める anthropic-version ヘッダの新しい値です。2023-06-01 版から、一部のリクエストが 400 エラーになる変更と、管理系 API のフィールド名の変更が入りました。 2026年10月22日時点で押さえるべき点は次の5つです。

1. SDK のメジャー版を上げると、自動で新バージョンに切り替わる：SDK は、そのメジャー版が出た時点の API バージョンを送ります。Python は 2.0.0、TypeScript は 1.0.0 から 2026-10-21 を送ります
2. temperature・top_p・top_k は送るだけで 400：既定値（temperature: 1.0 など）を明示しても、どのモデルでもエラーになります。削除するしかありません
3. 認証ヘッダが X-Api-Key から Authorization: Bearer に変わる：Claude API 自体はどちらも受け付けますが、X-Api-Key を見ているプロキシやゲートウェイは直す必要があります
4. 旧バージョン 2023-06-01 は引き続き使える：移行ガイドは、既定以外の temperature に頼るリクエストは 2023-06-01 にとどめてよいと案内しています。2026年10月22日時点で、公式ページに終了日は書かれていません
5. Bedrock では Claude 4.7 以降のモデルだけ：Amazon Bedrock で Opus 4.6 以前のモデルを呼んでいるなら、今の SDK のまま据え置くよう案内されています

Claude API そのものの使い方はAnthropic API（Claude API）の使い方ガイドで扱っています。本記事は、すでに Claude API を使っている人が新バージョンへ移るための手順に絞ります。

API バージョン 2026-10-21 とは

Claude API では、リクエストごとに anthropic-version ヘッダで API の版を指定します。2026-10-21 は、2023年6月1日の 2023-06-01 以来、約3年4か月ぶりに追加された版です。 バージョンの説明ページによると、Anthropic は同じ版の中では既存の入力・出力パラメータを維持するとしています。一方で、任意の入力や出力値の追加、特定のエラーが起きる条件の変更などは同じ版の中でもあり得るとしています。今回のように、既存のパラメータを受け付けなくしたりフィールドを消したりする変更は、新しい版として出されました。

そのため、新しい版が出ても、今のコードが今回の変更で壊れることはありません。今回の変更の影響を受けるのは、anthropic-version が 2026-10-21 に変わったときです。SDK を使っている場合は、ヘッダを自分で書いていなくても SDK のメジャー版を上げた時点で版が切り替わります。リリースノートで「新バージョンを既定で送る」とされた SDK と、Anthropic 公式のコマンドラインツールである ant CLI は次のとおりです。

出典：Claude Platform release notes（2026年10月22日取得）

2026年10月22日時点では、PyPI の anthropic は 2.1.0、npm の @anthropic-ai/sdk は 1.1.0 まで出ていました。pip install -U anthropic や npm install @anthropic-ai/sdk@latest を実行すると、この境目を越えます。依存関係を anthropic>=1 のように上限なしで書いている場合も、次のインストールで新しいメジャー版が入る可能性があります。移行を終えるまでは anthropic>=1,<2 のようにメジャー版の上限を付けておくのが安全です。

SDK を使わずに HTTP で直接呼んでいる場合は、anthropic-version: 2026-10-21 を送るように書き換えたときに切り替わります。書き換えない限り、これまでどおり 2023-06-01 で動きます。

自分のコードが影響を受けるかを確かめる

影響があるのは、移行ガイドの「破壊的変更」と「SDK・CLI の変更」に当てはまる書き方をしているコードだけです。 Messages API に model・max_tokens・messages・system・tools などを渡しているだけのアプリなら、SDK を上げて動作を確かめるだけで済むことが多いでしょう。次の表で、自分のコードが当てはまるかを確かめてください。

出典：Migrating to API version 2026-10-21（2026年10月22日取得）

コードベースが大きい場合は、まず文字列で当たりを付けると早く済みます。次のコマンドは、上の表のうち検索しやすいものを洗い出す例です。

# サンプリングのパラメータ（Message Batches の params や extra_body も含めて探す）
grep -rnE "temperature|top_p|top_k" --include="*.py" --include="*.ts" --include="*.js" .

# X-Api-Key を自分で扱っている箇所（プロキシ設定やヘッダの付け替え）
grep -rni "x-api-key" .

# Admin API の旧フィールド名
grep -rnE "workspace_id|\"roles\"|group_type|actor\.email\b|summaries" .

ヒットした箇所がすべて直す対象とは限りません。OpenAI など別の API 向けの temperature も拾います。また、API キー一覧を絞り込む workspace_id のクエリパラメータと、レート制限一覧の group_type のクエリパラメータは変更されていません。直す必要があるのは、レスポンスのフィールドとして読んでいる箇所です。

temperature・top_p・top_k の廃止

2026-10-21 では、Messages API、トークンカウント、メッセージバッチのリクエストに temperature・top_p・top_k を含めると、値に関係なく 400 エラーになります。 新バージョンで送る場合、移行ガイドの指示は「3つとも削除する」で、代わりになる設定はありません。

削除したリクエストは、各パラメータの既定値（temperature は 1.0）でサンプリングされます。これは、2023-06-01 で3つを省略したときと同じ動きです。影響の大きさはモデルによって変わります。

ここで知っておきたいのは、Python SDK ではこの変化が2段階で来ていることです。SDK の移行ドキュメント（MIGRATION.md）によると、Python SDK は v1 の時点で messages.create() などから3つの引数を削除しており、渡すと TypeError になります。そのうえで、まだ使う古いモデル向けには extra_body={"temperature": 0.2} のようにリクエスト本文へ直接入れる回避策が案内されていました。また、messages.batches.create() の各リクエストの params に書いた temperature は、型チェックでは指摘されるものの、実行時にはそのまま送られるとされています。

# Python SDK v1：引数としては渡せないが、extra_body なら API に届く
client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "..."}],
    extra_body={"temperature": 0.2},  # 2023-06-01 なら受け付けられる
)

2026-10-21 では、この extra_body の回避策も、バッチの params に残った temperature も、API 側で 400 になります。手元で確かめたところ、Python SDK 2.0.0（ヘッダは既定の 2026-10-21）も、extra_body の temperature をそのままリクエスト本文に載せて送りました。SDK が止めてくれないので、実行して初めてエラーに気づくことになります。v1 で extra_body やバッチの params を使って temperature を送っていたコードは、SDK を上げる前に必ず探してください。

既定以外の temperature が必要な処理はどうするか

移行ガイドは、既定以外の値に頼るリクエストについて「パラメータを送るのをやめるか、そのリクエストを 2023-06-01 にとどめる」と案内しています。どうやってとどめるかまでは書かれていないので、ここからは本記事としての提案です。

• モデルを Claude 4.7 以降に上げられる処理：前の表のとおり、パラメータを削除するだけで済みます
• 古いモデルで出力の揺れを抑えたい処理：プロンプトで出力形式を厳密に指定する、構造化出力（Structured Outputs）で形を固定するなど、パラメータ以外の方法で安定させられないかを先に試します
• それでも 2023-06-01 にとどめる処理：方法は2つあります。1つは、その処理を旧 SDK（Python なら 1.x）のまま動かすことです。ただし Python では 1.x と 2.x を同じ環境に同時に入れられないため、別のサービスや別の仮想環境に分ける必要があります。もう1つは、新しい SDK のままヘッダで版を指定することです

手元の Python SDK 2.0.0 では、クライアント作成時に default_headers={"anthropic-version": "2023-06-01"} を渡すと、送信されるヘッダが 2023-06-01 になることを確かめました。ただし、SDK 2.0.0 の型やメソッドは 2026-10-21 を前提に作られており、temperature は extra_body で渡すしかありません。この方法は一時的な逃げ道と考え、移行の本筋にはしないほうがよいでしょう。

document ブロック・citations と Admin API の変更

Messages API では、サンプリングのパラメータ以外に、メッセージの組み立て方に関する400エラーが2つ追加されました。 どちらも、会話の履歴を自前で組み立て直しているアプリで当たりやすい変更です。

• assistant メッセージに直接置いた document ブロック：400 になります。ドキュメントは user メッセージに入れて送ります。Claude が返した web fetch ツールの結果のように、別のブロックの中に入っている document は引き続き受け付けられます
• user メッセージの text ブロックに付けた citations：空でない citations 配列を付けると 400 になります。search_result ブロック内の text ブロックも対象です。Claude の過去の回答を assistant メッセージとして送り返す場合の citations や、document・search_result 側の "citations": {"enabled": true} 設定は、これまでどおり使えます

管理系の API では、名前が変わったフィールドの旧名が返らなくなります。社内の利用状況ダッシュボードや、API キーの棚卸しスクリプトを作っている場合に影響します。

出典：Migrating to API version 2026-10-21（2026年10月22日取得）

API キーの workspace_id は、名前だけでなく意味も変わります。2023-06-01 では、既定のワークスペース（Default Workspace）に属するキーも、全ワークスペースで使えるキーも null でした。2026-10-21 では scope.workspace_id に既定のワークスペースの実際の ID が入り、全ワークスペースのキーは {"type": "organization"} になります。workspace_id が null なら既定のワークスペース、と判定していたコードは、既定のワークスペースの ID と比べる形に書き換える必要があります。 既定のワークスペースの ID は、ワークスペース一覧の API を include_default=true 付きで呼び、名前が "Default" のものから取れます。

新しい SDK・CLI で変わること

新しい SDK と CLI には、API バージョンとは別に、SDK 自体の破壊的変更も入っています。 移行ガイドは「SDK を上げるときは、API の破壊的変更と一緒にこちらも直す」としています。影響の大きいものから順に挙げます。

API キーが Authorization: Bearer で送られる

旧 SDK は API キーを X-Api-Key ヘッダで送っていましたが、新しい SDK と CLI は Authorization: Bearer <キー> で送ります。Claude API はどちらのヘッダも受け付けるため、API に直接つないでいるアプリは何も変える必要がありません。困るのは、社内のプロキシや LLM ゲートウェイが X-Api-Key を読んで認証や振り分けをしている場合です。プロキシ側を Authorization に対応させるか、SDK 側で X-Api-Key に付け替えます。Python では、移行ガイドに次のような付け替えの例が載っています（api_key は定義済みの前提です）。

import httpx2
from anthropic import Anthropic, DefaultHttpxClient

def send_x_api_key(request: httpx2.Request) -> httpx2.Request:
    if request.headers.get("Authorization") == f"Bearer {api_key}":
        del request.headers["Authorization"]
        request.headers["X-Api-Key"] = api_key
    return request

client = Anthropic(api_key=api_key, http_client=DefaultHttpxClient(auth=send_x_api_key))

なお、Python SDK の AnthropicFoundry（Microsoft Foundry 向け）は引き続き x-api-key で鍵を送ります。

1つのクライアントが持てる資格情報は1つ

API キーと認証トークンが同じヘッダを使うようになったため、SDK のクライアントは資格情報を1つしか持てなくなりました。Python では、api_key・auth_token・credentials・config・profile のうち2つ以上を渡すと ValueError になります。コードで何も渡さない場合は、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_PROFILE の指すプロファイル…の順に、最初に見つかったものだけを使います。環境変数に ANTHROPIC_API_KEY と ANTHROPIC_AUTH_TOKEN の両方が入っている場合は API キーが使われ、警告が1回出ます。 ゲートウェイ用のトークンと API 用のキーを両方送っていた構成は、移行ガイドの案内に沿って組み直す必要があります。

型の変更（MessageParam）

各言語の SDK で、MessageParam がロールごとの型（UserMessageParam・AssistantMessageParam・SystemMessageParam）に分かれました。送信されるリクエストの中身は変わりません。Python の場合、{"role": "user", "content": "Hello"} のように辞書で書いているコードは変更不要です。一方、MessageParam(role="user", content="Hello") のように呼び出していると TypeError になるので、辞書の書き方に直します。ほかの言語での書き換え方は、移行ガイドの言語別のタブを参照してください。

そのほかの変更

出典：Migrating to API version 2026-10-21（2026年10月22日取得）

ライセンスの変更は、コードには影響しませんが、受託開発や社内の監査でライセンス一覧を納品・提出している場合は見落としやすい点です。旧版は MIT のままで、新しい版から Apache 2.0 になります。

手元で確かめた結果

2026年10月22日に、API キーを設定していない隔離環境で、各 SDK が実際に送るリクエストを確かめました。 通信先はモックに差し替えており、Claude API には送信していません。そのため、API が返す 400 エラーそのものは確認していません（エラーになることはドキュメントの記載です）。

実測でわかったのは、Python SDK は v1 の時点ですでに temperature を引数で受け付けていないという点です。v1 で引数を削除済みのコードでも、temperature が残りうるのは前述の extra_body とバッチの params です。また、Python SDK を 0.x から一気に 2.x へ上げる場合は、v1 の変更（Python 3.10 以上が必要、HTTP ライブラリが httpx2 に変更など）もまとめて受けることになるので、Python SDK の MIGRATION.md の v1 の項も合わせて確認してください。

あわせて、Claude Code 2.1.307 を同じ隔離環境に入れ、claude --version で 2.1.307 (Claude Code) と表示されることを確認しました。/claude-api api-version はログインしたセッションで使うコマンドのため、実行はしていません。

移行の手順

移行ガイドが示す手順は、「新バージョンに切り替える」「破壊的変更に合わせてコードを直す」「新バージョンで試験してからリリースする」の3段階です。 切り替えと修正は、同じリリースに含めるよう案内されています。実際の作業は次の順で進めると手戻りが少なくなります。

1. 影響の確認：「自分のコードが影響を受けるかを確かめる」の表と検索コマンドで、該当する箇所を一覧にする
2. 依存関係の上限を付ける：anthropic>=1,<2 のように、移行が終わるまでメジャー版を固定する
3. ブランチで SDK を上げる：Python なら pip install "anthropic>=2,<3"、TypeScript なら npm install @anthropic-ai/sdk@^1。TypeScript で @anthropic-ai/bedrock-sdk・@anthropic-ai/vertex-sdk などのクラウド向けパッケージも使っている場合は、同じ更新でそれぞれの 1.0.0 以降に上げる
4. 型チェックとテストを流す：MessageParam や削除された引数は、型チェック（pyright・mypy・tsc）で多くが見つかる
5. 該当箇所を直す：サンプリングのパラメータの削除、document と citations の置き場所、Admin API のフィールド名、認証ヘッダ
6. 出力の変化を確かめる：temperature を下げていた処理は、削除後の出力を何件か比べて、許容できるかを確かめる
7. SDK の更新と修正を一緒にリリースする

Claude Code の /claude-api api-version を使う

Claude Code を使っているなら、2026年10月21日（UTC）公開の v2.1.307 で追加された /claude-api api-version を、手順5のコード修正に使えます。CHANGELOG には「Claude API のコードを API version 2026-10-21 に移すための /claude-api api-version を追加」と書かれています。どこまでを自動で行うかは、2026年10月22日時点で公式ドキュメントに説明がありません。/claude-api は Claude Code に同梱されている claude-api スキルで、プロジェクトの言語を判定して、その言語の SDK の資料を読み込んでから作業します。

# Claude Code 2.1.307 以降で、移行したいリポジトリを開いて実行
/claude-api api-version

使う前に claude --version で 2.1.307 以降であることを確かめてください。2026年10月22日時点では、npm で latest は 2.1.307 ですが、更新の遅い stable チャネルはまだ 2.1.306 です。stable チャネルで使っている場合は、このサブコマンドがまだ入っていない可能性があります。スキルの使い方はClaude Code のスキル（Skills）ガイド、スラッシュコマンドの仕組みはClaude Code のカスタムスラッシュコマンドの作り方で扱っています。

AI に移行を任せた場合でも、変更の差分は必ず人が読んでください。特に temperature の削除は、コードとしては1行消すだけですが、古いモデルを使っている処理では出力の性質が変わります。差分が正しくても、業務として許容できるかは手順6で確かめる必要があります。

Amazon Bedrock・クラウド経由で使う場合の注意

Amazon Bedrock では、2026-10-21 は Claude 4.7 以降のモデルでしか使えません。 Bedrock で Opus 4.6 以前のモデルを呼んでいる場合、移行ガイドは「今の SDK のまま据え置くか、API バージョンを自分で指定しているなら今送っている版を送り続ける」よう案内しています。新バージョンに移すには、先にその呼び出しのモデルを Claude 4.7 以降に切り替えます。

新しい SDK の Amazon Bedrock 向け・Google Cloud 向けのクライアントも 2026-10-21 を送ります。1つのアプリの中で、Claude API 直接の呼び出しと Bedrock 経由の呼び出しが混在している場合は、SDK を上げる前に Bedrock 側で使っているモデルを確認してください。

よくある質問

まとめ

• 2026-10-21 では、temperature・top_p・top_k を送ると既定値でも 400 になる。extra_body やバッチの params に残ったものも対象
• assistant メッセージ内の document と、user メッセージ内の citations も 400 になる。Admin API はフィールド名が変わる
• 新しい SDK では、認証ヘッダが Authorization: Bearer になり、資格情報は1つだけ、ライセンスは Apache 2.0 になる
• SDK のメジャー版を上げた時点で新バージョンに切り替わるので、移行を終えるまでは依存関係に上限を付ける
• 旧バージョン 2023-06-01 は引き続き使え、2026年10月22日時点で終了日は公表されていない
• Claude Code 2.1.307 以降の /claude-api api-version を移行作業に使い、差分の確認と出力の検証は人が行う

出典（2026年10月22日取得）

• Claude Platform release notes
• Migrating to API version 2026-10-21
• Versions（API バージョンの説明）
• Claude API skill
• anthropic-sdk-python MIGRATION.md
• Claude Code CHANGELOG（2.1.307）