Claude APIをバージョン2026-10-21へ移行する手順 — SDKとant CLIの変更点

移行で何が変わるか

Claude APIの anthropic-version を 2023-06-01 から 2026-10-21 に上げるには、SDKを指定のメジャーバージョンへ更新し、破壊的変更に当たるコードを直します。SDKを使わずに直接APIを呼ぶ場合は、ヘッダーの値を書き換えるだけでは終わりません。リクエストの中身も直す必要があります。

SDKとCLIは、リリースされた時点で最新だったAPIバージョンを送ります。そのため、更新したSDKは自動で 2026-10-21 を送ります。ヘッダーの仕組み自体はanthropic-versionヘッダーの解説にあります。

移行の流れは3段階です。

SDKごとの更新先

更新先は言語ごとに違います。次の表のバージョンが、2026-10-21 を送る最初のバージョンです。

つまずきやすい更新が3つあります。

• PHP: composer update だけでは、現在のバージョン制約の範囲に留まります。composer require "anthropic-ai/sdk" で制約ごと上げます
• Go: メジャーバージョンが変わるとモジュールのimportパスも変わります。.../anthropic-sdk-go と .../option などのパッケージを、すべて .../anthropic-sdk-go/v2 で始まる形に直し、go get を実行します
• TypeScript: Bedrock・Vertex・Foundry・AWS・Google Cloud向けのプラットフォームSDKも、1.0.0に同時に上げます。上げ忘れると、パッケージマネージャーが古い @anthropic-ai/sdk をもう1つ入れます

SDKを使わない場合は、ヘッダーを書き換えます。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_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"}]}'

Messages APIの破壊的変更を直す

Messages API、トークン数のカウント、Message Batchの各リクエストに効く変更が3つあります。どれも該当しなければ、コードの修正は要りません。

assistantメッセージのdocumentブロック

assistant メッセージに document ブロックを直接置くと、400エラーになります。文書は user メッセージで送ります。Claudeが返したweb fetchのツール結果のように、別のブロックの中に入れ子になった文書は、これまでどおり受け付けます。

userメッセージのcitations

user メッセージの text ブロックに、空でない citations 配列を付けると400エラーになります。search_result ブロックの中でも同じです。直し方は、その citations を外すことです。

外さなくてよいものもあります。assistant メッセージとして送り返すClaudeの過去の返答にある citations は、そのまま通ります。文書や検索結果の "citations": {"enabled": true} の設定も有効です。

temperature・top_p・top_k

3つのパラメーターは削除されました。既定値のまま temperature: 1.0 を渡しても、400エラーになります。SDKとCLIの側も、最新のメジャーバージョンからこの3つを持ちません。

直す前に、副作用を見ておく必要があります。パラメーターを外したリクエストは、既定値でサンプリングされます。Claude 4.7以降のように既定値しか受け付けないモデルでは、挙動は変わりません。一方、Claude Sonnet 4.6のように他の値を受け付けるモデルでは、temperature を下げて出力を安定させていた効果が消えます。代わりになる設定はありません。

非既定の値に頼るリクエストが残るなら、選択肢は2つです。パラメーターを諦めるか、そのリクエストだけ 2023-06-01 に残します。

Admin APIのフィールド名変更

Admin APIとClaude Enterprise Analytics APIは、応答から旧名のフィールドを外しました。応答を読むコードがある場合だけ、読み替えます。

最後のAPIキーだけは、名前の変更で済みません。workspace_id の意味が変わっています。旧バージョンでは、Defaultワークスペースに紐づくキーと、全ワークスペース共通のキーの両方で、workspace_id が null でした。新バージョンでは、ワークスペースに紐づくキーはDefaultも含めて scope.workspace_id に実際のIDが入ります。全ワークスペース共通のキーは、scope が {"type": "organization"} になり、workspace_id を持ちません。

null をDefaultワークスペースの目印にしていたコードは、scope.workspace_id とDefaultのIDを比べる形に直します。IDは、List Workspacesを include_default=true で呼び、名前が Default のワークスペースから取れます。一覧取得時の group_type クエリと workspace_id フィルターは、変わりません。

SDKとCLIで直すところ

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

SDKとCLIは、APIキーを X-Api-Key ではなく Authorization: Bearer <key> で送ります。キーを読むプロキシ、ゲートウェイ、ミドルウェア、ログフィルター、テスト用のスタブがあれば、Authorization を読む形へ直します。APIはどちらのヘッダーのキーも受け付けます。

ゲートウェイ側を直せない場合は、クライアント側でヘッダーを戻せます。TypeScriptの例を示します。

const client = new Anthropic({
  apiKey,
  defaultHeaders: { "X-Api-Key": apiKey, Authorization: null }
});

ant には独自のヘッダーを足す手段がありません。プロキシ経由で ant を使っているなら、ゲートウェイを Authorization 対応に直す一択です。プラットフォーム別のクライアントには例外があります。たとえばPythonの AnthropicFoundry は、これまでどおり x-api-key で送ります。

クライアントは認証情報を1つだけ持つ

APIキーと認証トークンが同じヘッダーを使うため、SDKクライアントが持てる認証情報は1つです。以前はAPIキーとトークンを両方持つと、2つのヘッダーで両方送っていました。

Pythonでは api_key と auth_token を同時に渡すと ValueError、TypeScriptでは TypeError になります。ゲートウェイ用のトークンと、その先のAPI用のキーを併用していた構成は、トークンを auth_token で渡し、キーを X-Api-Key のヘッダーとして足す形に直します。ゲートウェイは、転送前に自分の Authorization を外します。APIが期待する認証情報は、1リクエストにつき1つです。

何も渡さない場合の参照順は、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_PROFILE が指すプロファイル、Workload Identity Federationの変数、ディスク上のアクティブなプロファイルです。最初に見つかった1つが使われます。

ant CLI 2.0.0の変更点

CLIは ant 2.0.0に上げます。Homebrewのコマンドとリリースのダウンロードは変わりません。変わるのは次の3点です。

Goのインストールパス。 go install を使っている場合は、パスに /v2 を足します。

# Before
go install 'github.com/anthropics/anthropic-cli/cmd/ant@latest'
 
# After
go install 'github.com/anthropics/anthropic-cli/v2/cmd/ant@latest'

旧パスは、エラーも警告も出さずに、v1の最新リリースを入れ続けます。気づかないまま古い ant を使い続けるおそれがあるので、更新後に ant --version を確かめてください。

--api-key と --auth-token の削除。コマンドラインの値はシェル履歴とプロセス一覧に残るため、2つのフラグはなくなりました。v1.27.0から非推奨の警告が出ていた機能です。まだ使うコマンドは flag provided but not defined で止まります。

--api-key-stdin は標準入力をすべて読むので、同じコマンドのリクエストボディはフラグで渡します。

op read op://vault/anthropic/api-key | ant --api-key-stdin models list

スクリプトから ant を呼ぶ構成は、ant CLIの自動化記事の例を参考に、キーを環境変数か標準入力で渡す形へ点検します。インストールと認証の基本はant CLIのインストール方法にあります。

models の --beta。非betaの ant models から --beta が外れました。ベータヘッダーが要る場合は ant beta:models list --beta "$BETA" を使います。同じ変更は各SDKの models メソッドの betas 引数にも及びます。betaヘッダーを送るなら client.beta.models を呼びます。

言語別の型・API変更

言語ごとに、次の変更があります。該当する言語だけ読み進めれば足ります。

• MessageParam が役割別のユニオンに: UserMessageParam、AssistantMessageParam、SystemMessageParam の3つに分かれました。PythonでもTypeScriptでも、{"role": "user", "content": "Hello"} のような辞書やオブジェクトのリテラルは、そのままです。Pythonで MessageParam(role="user", ...) のようにクラスとして呼ぶと TypeError になるので、辞書で書きます
• C#: Role 列挙型が消え、new UserMessageParam { Content = "..." } のように役割ごとのクラスを使います。IChatClient は ChatOptions.Temperature、TopK、TopP を無視します。関連はC# SDKとIChatClientの記事にあります
• Go: Go 1.25以降が必須です。vertex.DefaultVersion と bedrock.DefaultVersion は削除されました
• Java: AnthropicBackend の apiKey() と authToken() が Optional<String> を返します。インターセプターが anthropic-version を上書きするときは、putHeader ではなく replaceHeaders を使います。putHeader では2つ目の値が追加されます
• PHP: 渡した列挙型のケースは、値として読み戻されます。in_array(AllowedCaller::DIRECT, ...) は AllowedCaller::DIRECT->value との比較に変わります。PHP SDK全般の話はPHP SDKの記事にあります
• Ruby: Anthropic::VertexClient::DEFAULT_VERSION と Anthropic::BedrockClient::DEFAULT_VERSION が削除されました
• TypeScript・Ruby: ツールランナーのクライアント側compactionが削除され、サーバー側compactionに置き換わりました。トークンのしきい値で自動圧縮するには、betas: ["compact-2026-01-12"] と context_management の compact_20260112 を指定します。しきい値は50,000トークン以上です
• Text Completions: TypeScript、Go、Java、RubyのSDKとCLIから削除されました。Messages APIを使います

ライセンスも変わります。新しいバージョンのSDKとCLIは、MITからApache License 2.0になります。コードの変更は要りませんが、依存ライセンスの一覧を管理している場合は、エントリーを更新します。

Claude Codeで影響箇所を洗い出す

破壊的変更の多くは、文字列で探せます。リポジトリを移行前にスキャンしておくと、直す範囲が見えます。

# 削除されたサンプリングパラメーター
rg -n "temperature|top_p|top_k" --glob '!node_modules'
 
# X-Api-Keyを読むプロキシ・ミドルウェア・テスト
rg -n -i "x-api-key" --glob '!node_modules'
 
# ant CLIの削除済みフラグ
rg -n -e "--api-key[ =]" -e "--auth-token[ =]" .
 
# Goのimportパス
rg -n "anthropic-sdk-go\"|anthropic-sdk-go/option"

Claude Codeに任せるなら、Claude Code v2.1.307以降で /claude-api api-version を使えます。コードを新しいAPIバージョンに合わせて更新し、そのうえでリクエストを切り替えるサブコマンドです。詳しくはv2.1.307のリリースノートにあります。

どちらの場合も、プロジェクトの CLAUDE.md に移行のルールを書いておくと、Claudeが旧パラメーターを書き戻すのを防げます。例えば次のような形です。

## Claude API
- anthropic-version は 2026-10-21。temperature / top_p / top_k は送らない
- APIキーは Authorization: Bearer で送られる。X-Api-Key を前提にしない
- ant CLI にキーはフラグで渡さず、ANTHROPIC_API_KEY を使う

Claudeに修正を頼んだあとも、さきほどの rg を再実行して残りを数えます。最後に、2026-10-21 を指定した結合テストで400エラーが出ないことを確かめます。

移行前に決めておくこと

temperature を使うかどうかが、移行の分かれ目です。Claude 4.7以降のモデルだけを使うなら、挙動は変わりません。Sonnet 4.6のようなモデルで出力の安定のために温度を下げている呼び出しは、移行すると効果を失います。その呼び出しだけは、2023-06-01 に残す判断もあります。

もう1つは認証経路です。SDK経由のキーが Authorization に移るので、前段のプロキシが X-Api-Key でルーティングや課金の識別をしていないかを、先に見ます。