DEV Community

Cover image for Claude API バージョン 2026-10-21 の変更点と安全なアップグレード方法
Akira
Akira

Posted on Originally published at apidog.com

Claude API バージョン 2026-10-21 の変更点と安全なアップグレード方法

#ai #api #claude #softwaredevelopment

Claude API バージョン 2026-10-21 の変更点と安全なアップグレード方法

Claude API version 2026-10-21

Claude API バージョン 2026-10-21 は、2023-06-01 以来初となる新しい anthropic-version の値です。Messages API に 3 つの破壊的変更を加えます。temperature、top_p、top_k は 400 エラーを返すようになり、assistant メッセージ内の document ブロックは 400 を返し、user メッセージ内の text ブロックの citations も 400 を返します。さらに、Admin API と Enterprise Analytics API のいくつかのフィールド名が変更されます。anthropic-version: 2026-10-21 を送信するか、新しい SDK のメジャーバージョン（Python 2.0.0、TypeScript 1.0.0、Go 2.0.0 など）にアップグレードすることでオプトインできます。

今すぐ Apidog を試す

ただし落とし穴があります。ほとんどのチームは SDK のアップグレードによって「うっかり」新バージョンへ移行することになるのです。メジャーバージョンをまたぐ日常的な pip install -U anthropic や npm update は、すべてのリクエストを一斉に 2026-10-21 へ切り替えてしまいます。このガイドでは、Anthropic が文書化しているすべての変更を一覧にし、実際のコードで影響が出るものはどれかを示し、安全にアップグレードする順序を説明します。

anthropic-version ヘッダーとは？

anthropic-version ヘッダーは、受け取る Claude API の形を固定する必須のリクエストヘッダーです。ひとつのバージョン内では、Anthropic は既存の入力パラメータと出力パラメータを安定して維持しますが、任意の入力、新しい出力値、ストリーミングイベント型のような新しい enum のバリアント、および新しいエラー条件を追加することがあります。破壊的変更は、新しいバージョン日付が登場したときにのみ行われます。

バージョニングのページによると、3 つのバージョンが存在します。

バージョン 導入された内容
2023-01-01 初回リリース
2023-06-01 ストリーミング向けのインクリメンタルで名前付きの server-sent events。data: [DONE] イベント、およびレガシーの exception と truncated の値を削除
2026-10-21 サンプリングパラメータの削除、メッセージコンテンツのルールの厳格化、Admin および Analytics フィールドの名称変更

公式 SDK を使用している場合、このヘッダーを自分で設定することはありません。各 SDK のメジャーバージョンは、そのメジャーが出荷された時点で最新だったバージョンを送信します。だからこそ、ほとんどのコードベースにとって SDK のアップグレードと API バージョンのアップグレードは同じ出来事なのです。

Claude API 2026-10-21 の破壊的変更

これらの変更は POST /v1/messages、トークンカウント、そして 2026-10-21 で作成された Message Batch 内のすべてのリクエストに適用されます。

1. temperature、top_p、top_k が削除されました

これが最も多くの人が遭遇する変更です。temperature、top_p、top_k を送信するリクエストは、すべてのモデルで、たとえデフォルト値を送信したとしても 400 エラーを返します。設定ファイルに残った temperature: 1.0 だけで呼び出しが壊れます。

出力品質がどうなるかはモデルによります。

  • Claude 4.7 以降はすでにデフォルトのサンプリング値しか受け付けないため、パラメータを削除してもサンプリングの方法は何も変わりません。
  • 他の値を受け付ける古いモデル（Claude Sonnet 4.6 など）では、temperature を下げることで得ていた効果が失われます。移行ガイドははっきりと述べています。これを置き換える設定は他にありません。

リクエストが本当にデフォルト以外の値に依存している場合、Anthropic は 2 つの選択肢を用意しています。送信をやめるか、その特定のリクエストを 2023-06-01 に留めておくかです。

2. assistant メッセージ内の document ブロックは 400 を返します

一部のアプリは、assistant のターンに直接 document ブロックを置いた会話履歴を再生します。2026-10-21 ではこれは拒否されます。ドキュメントは user メッセージへ移動してください。Claude が返した web fetch ツール結果のように、別のブロックの中に入れ子になったドキュメントは引き続き受け付けられます。

3. user メッセージ内の citations は 400 を返します

user メッセージ内で空でない citations 配列を持つ text ブロックは失敗するようになり、これには search_result ブロック内のテキストも含まれます。これらのブロックから citations を削除してください。送り返す Claude 自身の assistant 応答にある citations は引き続き問題なく、ドキュメントや検索結果に対する "citations": {"enabled": true} も同様に問題ありません。

4. Admin API および Enterprise Analytics のフィールド名の変更

レスポンスには古いフィールド名が含まれなくなります。

エンドポイント 旧フィールド 新フィールド
RBAC グループ roles role_ids
RBAC グループメンバー group_id rbac_group_id
RBAC ロール name display_name
組織およびワークスペースのレート制限 group_type group.type
API キー workspace_id scope.workspace_id
Analytics のユーザー別使用量およびコストレポート actor.email actor.email_address
Analytics のアクティビティサマリー summaries data

API キーの変更は気づきにくいものです。2023-06-01 では、Default Workspace に紐づくキーでも全ワークスペースのキーでも workspace_id は null でした。2026-10-21 では、scope.workspace_id に Default Workspace の実際の ID が入り、全ワークスペースのキーは scope: {"type": "organization"} を持ち workspace_id はありません。ダッシュボードが null を「Default Workspace」として扱っていた場合、アップグレード後にキーを誤ってラベル付けすることになります。

Diagram of the upgrade path from anthropic-version 2023-06-01 to 2026-10-21 in three steps: upgrade the SDK, fix breaking changes, test both versions, with temperature, top_p and top_k marked as removed

2026-10-21 を送信する SDK バージョン

Anthropic は 2026 年 10 月 21 日に新しい SDK のメジャーバージョンをリリースし、リリースノートによると、それぞれがデフォルトで 2026-10-21 を送信します。

SDK 2026-10-21 に対応した最初のバージョン
Python (anthropic) 2.0.0
TypeScript (@anthropic-ai/sdk) 1.0.0
Go (anthropic-sdk-go/v2) 2.0.0
Java (anthropic-java) 3.0.0
C# (Anthropic) 13.0.0
PHP (anthropic-ai/sdk) 1.0.0
Ruby (anthropic) 2.0.0
ant CLI 2.0.0

新しいメジャーバージョンには、API バージョンにまったく依存しない変更もあります。

  • API キーは X-Api-Key ではなく Authorization: Bearer <key> として送信されます。 Claude API はどちらも受け付けますが、X-Api-Key を読み取るプロキシ、ゲートウェイ、ログフィルター、テストスタブはキーを見つけられなくなります。
  • Text Completions が削除されました。 TypeScript、Go、Java、Ruby の SDK および CLI から削除されています。Messages API を使用してください。
  • 非ベータの Models メソッドから betas がなくなりました。 代わりに client.beta.models を呼び出してください。
  • 型付き SDK では MessageParam がロールごとに 1 つの型を持つユニオンになりました。 そのため一部の型アノテーションを更新する必要があります。
  • Go では /v2 で終わる新しいインポートパスが必要です。 また、Bedrock、Vertex、Foundry、AWS、Google Cloud の各パッケージを使っている TypeScript ユーザーは、同じアップグレードの中でそれらを v1 に移行する必要があります。そうしないと、パッケージマネージャーがコア SDK の古いコピーをもう 1 つインストールしてしまいます。
  • ライセンスが変更されました。 MIT から Apache 2.0 になりました。

何よりも先に、現在のメジャーバージョンを固定してください。そうすれば依存関係ボットがスプリントの途中でアップグレードしてしまうのを防げます。

Amazon Bedrock の例外

Amazon Bedrock では、2026-10-21 は Claude 4.7 以降のモデルでのみ動作します。そこでまだ Opus 4.6 やそれ以前のモデルを呼び出している場合は、現在の SDK バージョンを使い続けるか、現在のヘッダーを送信し続けて、先にモデルを切り替えてください。

Claude API バージョン 2026-10-21 へ安全にアップグレードする方法

移行ガイドが示す順序は、バージョンを切り替え、破壊的変更を修正し、リリース前にテストする、というものです。実際には次のようになります。

  1. 古い SDK のメジャーバージョンを固定します。 たとえば Python なら anthropic<2、npm なら "@anthropic-ai/sdk": "^0" です。
  2. コードと設定を検索します。 temperature、top_p、top_k、X-Api-Key、completions.create、および上の表にある Admin API のフィールドを探します。
  3. サンプリングの扱いを決めます。 Claude 4.7 以降ではパラメータを削除します。古いモデルでは、デフォルトのサンプリングを受け入れるか、それらの呼び出しを 2023-06-01 に留めます。
  4. メッセージの構築を修正します。 assistant 側のドキュメントを user ターンへ移動し、user のテキストブロックから citations を削除します。
  5. 同じペイロードを両方のバージョンでテストし、 ステータスコードとレスポンスの形を比較します。
  6. SDK のアップグレードとコード修正をまとめて出荷します。 Anthropic は、修正より先にアップグレードをリリースしないよう述べています。

SDK を使わない場合、切り替えはヘッダー 1 つです。

curl https://api.anthropic.com/v1/messages \
  -H "x-[REDACTED CREDENTIAL]_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'
Enter fullscreen mode Exit fullscreen mode

このボディに "temperature": 0.2 を追加すると 400 になります。同じボディを anthropic-version: 2023-06-01 で送信すれば成功します。この 2 つの結果の対比こそ、ステップ 5 が本番で送信するすべてのペイロードについて検出すべきものです。

Claude Code に Apidog CLI で両バージョンをテストさせる

ステップ 5 は手作業では退屈です。何十ものペイロード形状があり、それぞれを 2 回実行する必要があります。代わりにコーディングエージェントに任せましょう。Apidog CLIは、Claude Code（または Codex、Cursor、OpenCode）にテストケースを作成して実行するコマンドを提供するので、エージェントが比較を行い、あなたはサマリーを読むだけです。

一度だけセットアップします。

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick Claude Code when prompted
Enter fullscreen mode Exit fullscreen mode

次に Claude Code に 1 つのプロンプトを与えます。

In Apidog project <id>, create an environment "claude-api" with base URL
https://api.anthropic.com. For each JSON payload in ./fixtures/claude/, add a
POST /v1/messages test case that sends the header anthropic-version: {{anthropic_version}}
and asserts status 200 and a non-empty content array. Run every case twice, once with
anthropic_version=2023-06-01 and once with 2026-10-21, and list each case that passes
on the old version but fails on the new one, with the error message.
Enter fullscreen mode Exit fullscreen mode

エージェントは何かを書き込む前に各ペイロードのスキーマを確認し、それからケースを実行します。

apidog environment create claude-api --project <id> --base-url https://api.anthropic.com
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "anthropic_version=2023-06-01" -r cli,json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "anthropic_version=2026-10-21" -r cli,json
Enter fullscreen mode Exit fullscreen mode

--env-var フラグはテストケースに触れずにヘッダーの値を差し替えるので、差分は変数 1 つだけになります。両方の実行を Apidog アプリで確認するには --upload-report を追加し、依存関係の更新が temperature フィールドを本番へ出荷できないようにするには、2026-10-21 の実行を -r junit で CI に入ります。Claude Code での Apidog CLI ガイドでセットアップをより詳しく説明しており、apidog run リファレンスにはすべてのフラグが掲載されています。Apidog の Free プランは最大 4 ユーザーまで利用できます。

Diagram of one POST /v1/messages request run under two API versions: 2023-06-01 returns 200 OK, 2026-10-21 returns a 400 error, and a diff compares the two results

2023-06-01 は非推奨ですか？

いいえ、廃止日は公表されていません。バージョニングのページには 2023-06-01 が非推奨の通知なしで掲載されており、移行ガイド自体も、デフォルト以外の temperature を必要とするリクエストは 2023-06-01 に留めておくよう述べています。Anthropic は依然として「可能な限り」最新バージョンを推奨しています。

これは計画を立てるうえで重要です。今回のアップグレードは任意ですが、2026-10-21 は 3 年以上ぶりの新しいバージョンであり、今後の破壊的変更も同じ形でやってきます。そのため、バージョンテストを今のうちに日常的な CI ジョブとして扱っておくほうが、後で慌てて移行するより安く済みます。すでに Claude API のレート制限や Claude API のコストを調整しているなら、同じパイプラインにバージョンチェックを追加しましょう。API バージョニングのベストプラクティスに関するガイドでは、このような日付ベースのバージョンがなぜそれを容易にするのかを説明しています。

FAQ

今すぐ Claude API バージョン 2026-10-21 にアップグレードする必要がありますか？

いいえ。2023-06-01 は今も動作しており、公表された廃止日もありません。新しいヘッダーを送信するか、それをデフォルトとする SDK のメジャーバージョンをインストールしたときにアップグレードすることになります。

SDK をアップグレードしたらリクエストが 400 を返すのはなぜですか？

新しい SDK のメジャーバージョンは 2026-10-21 を送信し、これが temperature、top_p、top_k、assistant 側の document ブロック、および user のテキストブロックの citations を拒否します。まずペイロードにこれらがないか確認してください。

一部のリクエストで temperature を使い続けられますか？

はい、それらの特定のリクエストを 2023-06-01 に留めておくことで可能です。2026-10-21 には代替となる設定はなく、Claude 4.7 以降のモデルはそもそもデフォルトでのみサンプリングします。

2026-10-21 は Amazon Bedrock で動作しますか？

Claude 4.7 以降のモデルでのみ動作します。古い Bedrock モデルは、モデルを切り替えるまで現在の SDK バージョンまたはヘッダーが必要です。

プロキシは今も API キーを認識しますか？

X-Api-Key を読み取っている場合は認識しません。新しい SDK はキーを [REDACTED CREDENTIAL] として送信します。プロキシをAuthorizationを読み取るように更新するか、SDK がX-Api-Key` を送信するよう自分で設定してください。

新バージョンでストリーミングイベントは変わりますか？

Anthropic は 2026-10-21 におけるストリーミング形式の変更を挙げていません。現在使用しているストリーミング形式は 2023-06-01 で導入されたものです。

Top comments (0)