Claude API バージョン 2026-10-21 移行ガイド — temperature 廃止、認証ヘッダーの Bearer 化、SDK v2 の破壊的変更を実装目線で整理

Claude API に新しいバージョン 2026-10-21 が登場し、2023-06-01 から約 3 年ぶりにバージョンヘッダーが変わります。temperature / top_p / top_k は既定値でも 400、assistant メッセージ内の document ブロックと user メッセージ内の citations も 400 になります。さらに SDK と ant CLI は API キーを X-Api-Key ではなく Authorization: Bearer で送るようになり、クライアントが保持する認証情報は 1 つに限定されます。本記事では公式の移行ガイドをもとに、壊れる箇所の見つけ方と直し方を、API・Admin API・SDK・CLI の順に整理します。

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、ant CLI のフラグ削除に対応する

移行の進め方

公式の手順は 3 ステップです。

  1. 2026-10-21 に切り替える。SDK を使っているなら、2026-10-21 を送る最初の SDK バージョンに上げます(Python は anthropic 2.0.0)。SDK を使わず HTTP で直接呼んでいるなら、anthropic-version ヘッダーを 2026-10-21 にします。
  2. 破壊的変更に合わせてコードを直す。SDK / CLI の新バージョンで必要になる修正もここに含みます。
  3. 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 を持ちません。

つまり、「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 キーがどこを通っているかを一度確認しておくことをおすすめします。

参考