Claude API に新しい API バージョン 2026-10-21 が追加されました。これまで anthropic-version ヘッダーには何年も 2023-06-01 を送り続けてきましたが、ようやく次のバージョンが出たことになります。
ヘッダーの値を書き換えるだけなら一瞬ですが、今回は API 側の破壊的変更と、SDK / CLI のメジャーアップデートに伴う破壊的変更が同時に来ます。特に後者は、API キーを送るヘッダーが変わるので、API の前段にプロキシやゲートウェイを置いている構成は SDK を上げた瞬間に壊れる可能性があります。
本記事では、公式の移行ガイド(Migrating to API version 2026-10-21)をもとに、どこが壊れるか、どう見つけてどう直すかを整理します。前回の Fable 5.2 の記事で触れた「temperature を送ると 400」の詳細編でもあります。
到達点
2026-10-21で API が 400 を返すようになる 3 つのリクエストを把握する- Admin API / Enterprise Analytics API のフィールド名変更に備える
- SDK v2 系の 認証ヘッダーの Bearer 化と認証情報 1 つ制限で、プロキシ構成が壊れないようにする
MessageParamの型変更、tool runner の compaction、antCLI のフラグ削除に対応する
移行の進め方
公式の手順は 3 ステップです。
2026-10-21に切り替える。SDK を使っているなら、2026-10-21を送る最初の SDK バージョンに上げます(Python はanthropic2.0.0)。SDK を使わず HTTP で直接呼んでいるなら、anthropic-versionヘッダーを2026-10-21にします。- 破壊的変更に合わせてコードを直す。SDK / CLI の新バージョンで必要になる修正もここに含みます。
2026-10-21に対してテストしてからリリースする。
ポイントは、1 と 2 を同じリリースに入れることです。ガイドも、バージョンの切り替えはコード修正と一緒にリリースするよう求めています。ヘッダーだけ先に変えると、後述の 400 エラーが本番で出ます。
Amazon Bedrock の注意
Bedrock では、2026-10-21 を使えるのは Claude 4.7 以降のモデルだけです。4.6 以下のモデルを呼んでいる処理は、4.7 以降のモデルに移すまで現在の API バージョンのままにしておく必要があります。Bedrock で古いモデルと新しいモデルを混在させているなら、モデルごとにバージョンを分ける前提で計画してください。
API 側の破壊的変更(Messages API)
対象は POST /v1/messages、トークンカウント、そして 2026-10-21 で作った Message Batch の各リクエストです。
1. temperature / top_p / top_k が 400 になる
既定値を送っても 400 です。値を変えていなくても、パラメーターが入っているだけでエラーになります。
{
"model": "claude-opus-5-5",
"max_tokens": 4096,
- "temperature": 0.2,
"messages": [{ "role": "user", "content": "..." }]
}
削除後のリクエストは、temperature 1.0 を含む既定値でサンプリングされます。
影響の大きさはモデルによって違います。
- Claude 4.7 以降のように、もともと既定値しか受け付けないモデルは影響なし。
- Claude Sonnet 4.6 など、既定値以外を受け付けるモデルでは、出力を安定させるために
temperatureを下げていた効果がなくなります。代わりになる設定はありません。パラメーターを送るのをやめるか、そのリクエストだけ2023-06-01に残すかの二択です。
「抽出系の処理は temperature: 0 で安定させている」というコードは珍しくないので、ここが一番の要注意ポイントです。古いモデルで再現性に依存している処理があるなら、2023-06-01 に残すか、structured outputs やツールで出力形式を固定する方向に寄せるのが現実的です。
見つけ方:
# リポジトリ内で sampling パラメーターを送っている箇所を洗い出す
rg -n --type-add 'src:*.{ts,tsx,js,py,go,rb,java,cs,php}' -t src \
'\b(temperature|top_p|top_k|topP|topK)\b'
2. assistant メッセージに直接置いた document ブロックが 400 になる
assistant メッセージの中に直接 document ブロックを置くと 400 になります。ドキュメントは user メッセージで送ってください。
ただし、別のブロックの中に入っている document は引き続き受け付けられます。たとえば Claude が返した web fetch ツールの結果に含まれる document は、会話履歴にそのまま残して問題ありません。会話履歴を自前で組み立てて「前に読ませた資料」を assistant 側に詰めているような実装が対象です。
3. user メッセージ内の citations が 400 になる
user メッセージの text ブロックに空でない citations 配列があると 400 です(search_result ブロックの中も含む)。該当ブロックから citations を外してください。
引き続き使えるもの:
assistantメッセージのtextブロックに付いた citations- document や search result に付ける
"citations": {"enabled": true}
ありがちなのは、Claude の回答(citations 付き)を加工して user ターンに貼り直すケースです。たとえば「前回の回答をもとに続きを書いて」と回答テキストを user メッセージに流し込むとき、ブロックをそのままコピーしていると citations ごと入ってしまいます。user 側に入れるときはテキストだけを取り出すようにします。
Admin API / Enterprise Analytics API のフィールド名変更
改名されたフィールドの旧名がレスポンスから消えます。新しい名前で読むように直してください。
Admin API
| エンドポイント | 旧名 | 新名 |
|---|---|---|
| RBAC グループ(作成・一覧・取得・更新) | roles |
role_ids |
| RBAC グループメンバー(一覧・追加・削除のレスポンス) | group_id |
rbac_group_id |
| RBAC ロール(一覧・取得) | name |
display_name |
| 組織・ワークスペースのレート制限(一覧、ワークスペースのレート制限設定のレスポンス) | group_type |
group.type |
| API キー(一覧・取得・更新) | workspace_id |
scope(値の形が違う。後述) |
Claude Enterprise Analytics API
| エンドポイント | 旧名 | 新名 |
|---|---|---|
| ユーザー別の利用量・コストレポート | actor.email |
actor.email_address |
| アクティビティサマリー | summaries |
data |
なお、レート制限一覧エンドポイントの group_type クエリパラメーターと、API キー一覧エンドポイントの workspace_id フィルターは変わりません。変わるのはレスポンスのフィールドだけです。
API キーの workspace_id → scope は意味も変わる
ここは単純な改名ではないので注意が必要です。
2023-06-01のworkspace_idは、紐づくワークスペースの ID。ただし Default Workspace のキーと、全ワークスペース対象のキーはどちらもnullでした。2026-10-21ではworkspace_idが消え、scopeを読みます。- ワークスペースに紐づくキー(Default Workspace を含む)は、
scope.workspace_idにそのワークスペースの実際の ID が入ります。 - 全ワークスペース対象のキーは
scopeが{"type": "organization"}で、workspace_idを持ちません。
- ワークスペースに紐づくキー(Default Workspace を含む)は、
つまり、「workspace_id が null なら Default Workspace」と判定していたコードは、新バージョンでは誤判定になります。Default Workspace かどうかは、scope.workspace_id を Default Workspace の ID と比べて判定します。その ID は、List Workspaces を include_default=true で呼び、名前が "Default" のワークスペースから取ります。
// API キーがどこを対象にしているかを判定する(2026-10-21)
type KeyScope = { type: "organization" } | { workspace_id: string };
export function describeKeyScope(scope: KeyScope, defaultWorkspaceId: string): string {
if (!("workspace_id" in scope)) return "全ワークスペース";
return scope.workspace_id === defaultWorkspaceId ? "Default Workspace" : scope.workspace_id;
}
scope のうちワークスペースに紐づく場合の正確な形(workspace_id 以外のキーの有無など)は、ガイドに記載がないため、上の型は判定に必要な部分だけを書いています。実際のレスポンスで確かめてから型を固めてください。
SDK / CLI の破壊的変更
旧バージョンの SDK と CLI は anthropic-version: 2023-06-01 を送っていました。新バージョン(Bedrock / Google Cloud 用のクライアントを含む)は 2026-10-21 を送ります。SDK を上げる = API バージョンが変わるので、上の API 側の修正も同時に必要です。削除されたパラメーターや旧フィールド名は、SDK の型や CLI のフラグ・出力からも消えています。
1. API キーが Authorization: Bearer で送られる(最重要)
SDK と CLI は、API キーを X-Api-Key ではなく Authorization ヘッダーで送るようになりました。
# 旧
X-Api-Key: <key>
# 新
Authorization: Bearer <key>
Claude API 自体はどちらのヘッダーでも受け付けます。壊れるのは、間に挟まっているものです。
X-Api-Keyを読んだり付けたりしているプロキシ、ゲートウェイ、ミドルウェア、ログのマスキングフィルター、テスト用スタブはすべて見直しが必要です。- 特にログのマスキングは見落としやすいところです。
X-Api-Keyだけを伏せ字にしていると、新しい SDK ではAuthorizationヘッダー経由でキーが平文でログに出ます。
対象は、Anthropic / AsyncAnthropic の api_key と ANTHROPIC_API_KEY、AnthropicAWS の api_key と ANTHROPIC_AWS_API_KEY です。AnthropicFoundry は引き続き x-api-key を送り、AnthropicBedrockMantle はもともと bearer token を送っていました。
プロキシが X-Api-Key を読む構成で、すぐにはプロキシを直せない場合(Python)は、HTTP クライアントの auth 関数でキーを X-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))
AsyncAnthropic なら http_client=DefaultAsyncHttpxClient(auth=send_x_api_key) を使います。これはあくまでつなぎで、本筋はプロキシ側を Authorization 対応に直すことです。
リクエスト単位で X-Api-Key を操作していたコード(Python / TypeScript / Go / PHP / Ruby)も挙動が変わります。
- トークンだけを送るために
X-Api-Keyを消していたコードは削除します。Authorizationを消すとトークンまで消えます。 extra_headers={"X-Api-Key": omit}ではキーを外せなくなりました。extra_headers={"Authorization": omit}を使います。extra_headers={"X-Api-Key": other_key}で別キーに差し替えていたコードは、両方のキーが送られるようになります。1 リクエストだけ別キーを使うならextra_headers={"Authorization": f"Bearer {other_key}"}にします。
2. クライアントが持てる認証情報は 1 つだけ
API キーと認証トークンが同じ Authorization ヘッダーを使うため、1 つのクライアントが持てる認証情報は 1 つになりました。
api_key/auth_token/credentials/config/profileのうち、渡せるのは最大 1 つ。2 つ以上渡すとValueErrorです(v1 では一部の組み合わせだけTypeErrorでした)。- 渡したものだけが使われます。環境変数やディスク上の設定を探しにいきません。
- 何も渡さない場合は、
ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_PROFILEで指定したプロファイル、workload identity federation の環境変数、ディスク上のアクティブなプロファイルの順で、最初に見つかったものを使います。ANTHROPIC_API_KEYとANTHROPIC_AUTH_TOKENの両方があると、警告が 1 回ログに出ます。 copy()とwith_options()は認証情報を置き換えます。古い認証情報の設定やプロファイルに由来するベース URL とヘッダーは捨てられ、新しいほうのものが使われます(自分で渡したベース URL は残ります)。
client = Anthropic(api_key=key, auth_token=token)
# 旧: X-Api-Key: <key> と Authorization: Bearer <token> の両方を送っていた
# 新: ValueError
ゲートウェイ用のトークンと、その先の API 用のキーを両方送っていた構成は、この変更で正面から壊れます。ガイドの対処は、トークンを auth_token で渡し、キーを default_headers の X-Api-Key に入れ、ゲートウェイ側で転送前に Authorization ヘッダーを外す、というものです。社内 LLM ゲートウェイを運用しているチームは、SDK を上げる前にゲートウェイ側の対応を済ませておく必要があります。
なお、AnthropicAWS は api_key と auth_token を同時に渡してもエラーにならず、キーのほうを送ります。
3. MessageParam がロール別の union になった
MessageParam は UserMessageParam / AssistantMessageParam / SystemMessageParam の union になりました。BetaMessageParam も同様に分かれています。
{"role": "user", "content": "Hello"} のような辞書リテラルはそのまま使えます。困るのは次の 2 パターンです。
MessageParam(...) をコンストラクタとして呼んでいる: TypeError になります(サブクラス化しても TypeError)。辞書リテラルに直します。
# 旧
message = MessageParam(role="user", content="Hello")
# 新
message: MessageParam = {"role": "user", "content": "Hello"}
ロールを変数で受け取って辞書を組み立てている: role が複数の値を取りうる辞書は union のどのメンバーにも合わないので、型チェックで落ちます。ロールごとに分岐して組み立てます。
# 新
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
if role == "user":
return {"role": "user", "content": text}
return {"role": "assistant", "content": text}
BetaMessageParam では、clear_at と output_config は BetaSystemMessageParam だけのキーになり、BetaSystemMessageParam の content は省略可能になりました。message["content"] と直接読んでいる箇所は、message.get("content") にするか、先に role が "system" でないことを確かめます。
4. tool runner のクライアント側 compaction が削除(TypeScript / Ruby)
TypeScript では compactionControl オプションと @anthropic-ai/sdk/lib/tools/CompactionControl モジュールが削除されました。このオプションは v0.129.0 の時点で、渡すと AnthropicError を投げるようになっていました。サーバー側 compaction に移行します。
// 旧
const runner = client.beta.messages.toolRunner({
// ...
compactionControl: { enabled: true, contextTokenThreshold: 100_000 }
});
// 新
const runner = client.beta.messages.toolRunner({
// ...
betas: ["compact-2026-01-12"],
context_management: {
edits: [{ type: "compact_20260112", trigger: { type: "input_tokens", value: 100_000 } }]
}
});
- 発動の閾値は 50,000 トークン以上にする必要があります。
- compaction のタイミングを自分で決めたい場合は
runner.compactBeforeNextTurn()を呼びます。
5. その他の削除
- Text Completions API が TypeScript / Go / Java / Ruby の SDK と CLI から削除されました。Messages API を使います。
- 非 beta の Models メソッドから
betasが削除されました。ant modelsも--betaを受け付けません。client.beta.models(CLI はant beta:models)を使います。こちらはModelInfoではなくBetaModelInfoを返します。Python でclient.models.list()/retrieve()にbetasを渡すとTypeErrorです。
# 旧
page = client.models.list(betas=[beta])
# 新
page = client.beta.models.list(betas=[beta])
- C# / Go / Java / PHP / Ruby の SDK では、値が 1 つしかない enum 型が定数に置き換わりました(JSON は変わりません)。
6. ant CLI の --api-key / --auth-token が削除
v1.27.0 から非推奨の警告が出ていた 2 つのフラグが削除されました。使っているコマンドは flag provided but not defined で失敗します。CI のスクリプトに残っていないか確認してください。
| 削除 | 代わり |
|---|---|
--api-key <key> |
ANTHROPIC_API_KEY、--api-key-stdin、ant auth login |
--auth-token <token> |
ANTHROPIC_AUTH_TOKEN、--auth-token-stdin |
# 環境変数から
export ANTHROPIC_API_KEY="$KEY"
ant models list
# シークレットマネージャーから
op read op://vault/anthropic/api-key | ant --api-key-stdin models list
--api-key-stdin / --auth-token-stdin は標準入力をすべて読むので、これを使うコマンドではリクエストボディをフラグで渡すことになります。
7. ライセンスが Apache 2.0 に
新しいバージョンの SDK と CLI は Apache License 2.0 になりました(以前のバージョンは MIT のまま)。コードの変更は不要ですが、依存ライブラリのライセンス台帳を管理しているなら更新が必要です。TypeScript の @anthropic-ai/bedrock-sdk などのプラットフォーム別パッケージと C# の Anthropic.Bedrock などは、それぞれの 1.0.0 で切り替わります。Java は com.anthropic の全アーティファクトが対象です。
移行チェックリスト
-
temperature/top_p/top_kを送っている箇所を消す。古いモデルで出力の安定に頼っている処理は、2023-06-01に残すか設計を見直す -
assistantメッセージに直接置いたdocumentブロックをuser側へ移す -
userメッセージのtextブロック(search_result内を含む)からcitationsを外す - Bedrock で 4.6 以下のモデルを呼ぶ処理は、旧バージョンのまま残す
- Admin API / Enterprise Analytics API の旧フィールド名を新名に置き換える
- API キーの「
workspace_idがnullなら Default Workspace」判定をscopeベースに直す - プロキシ、ゲートウェイ、ログのマスキング、テストスタブを
Authorization: Bearerに対応させる - クライアントに渡す認証情報を 1 つにする(
api_keyとauth_tokenの同時指定をやめる) -
MessageParam(...)の呼び出しと、ロールを変数で受ける辞書の組み立てを直す - TypeScript / Ruby の tool runner でクライアント側 compaction を使っていたら、サーバー側 compaction に移す
-
ant --api-key/--auth-tokenを CI スクリプトから消す - 依存ライブラリのライセンス記録を Apache 2.0 に更新する
- SDK の更新と上記の修正を同じリリースに入れ、
2026-10-21でテストしてから出す
まとめ
API 側の変更は、sampling パラメーターの廃止と、メッセージのロールに合わない使い方(assistant 側の document、user 側の citations)の禁止が中心です。どちらも「コードを grep すれば見つかる」種類の変更なので、対応自体は難しくありません。
本当に注意すべきなのは SDK 側で、API キーのヘッダーが X-Api-Key から Authorization: Bearer に変わることと、認証情報が 1 クライアント 1 つに限られることです。Claude API そのものは両方のヘッダーを受け付けるので、直接呼んでいるだけなら何も起きません。壊れるのは間に挟まったプロキシやゲートウェイ、ログのマスキングです。SDK を上げる前に、自分の構成で API キーがどこを通っているかを一度確認しておくことをおすすめします。