約 3 分で読めます

Claude API 2026-10-21移行のゲートウェイ設計

2026年10月21日、Claude APIに新しいAPIバージョン 2026-10-21 が加わった。2023-06-01 以来の更新で、temperature を送るだけで400エラーになる。複数チームがSDKを使い、社内ゲートウェイや監視基盤がヘッダーを読んでいるエンタープライズでは、各チームが個別にSDKを上げるだけでは安全に移行できない。本稿は公式の移行ガイドに沿って、基盤チームが先に押さえる変更点と段階移行の設計を整理する。

2026-10-21でMessages APIの何が壊れるのか

2026-10-21ではtemperature等の送信と、assistantへのdocument配置が400エラーになります。

Messages API(POST /v1/messages)、トークンカウント、Message Batchの各リクエストに次の3つが適用される。

  • サンプリングパラメータの除去: temperature、top_p、top_k は既定値でも400になる。最新メジャーのSDKとCLIからはこの3つの引数自体がなくなった
  • assistantメッセージ内のdocumentブロック: 400になる。documentはuserメッセージで送る。web fetchツール結果のようにブロックの内側にあるdocumentは従来どおり受理される
  • userメッセージのtextブロックに付けたcitations: 空でない citations 配列は400になる。assistant側の citations と、documentや検索結果の "citations": {"enabled": true} は有効なまま

注意すべきは挙動の変化だ。送信をやめた場合の値は既定値(temperature は1.0)になる。Claude 4.7以降のように既定値しか受け付けないモデルは変わらないが、Claude Sonnet 4.6のように別の値を受け付けるモデルで出力の安定化のために temperature を下げていた呼び出しは、その効果を失う。代替設定は用意されていない。

APIキーのヘッダー変更でゲートウェイは何を直すのか

新SDKはAPIキーをAuthorization: Bearerで送るため、X-Api-Keyを読むゲートウェイは修正が必要です。

SDKとCLIは、キーを Authorization: Bearer <key> で送る。Claude API側はどちらのヘッダーのキーも受理するため、API自体は止まらない。壊れるのは自社側の層だ。

  • X-Api-Key を読んでチーム識別や課金按分をしているプロキシ・LLMゲートウェイ
  • X-Api-Key をマスクしているログフィルタ、監視、テストスタブ
  • リクエスト単位で X-Api-Key を上書き・削除していたコード。新SDKでは上書きしても両方のキーが送られ、削除しても効かない

一方、SDKクライアントが保持する資格情報は1つになった。APIキーと認証トークンが同じヘッダーを使うためで、Python SDKではコンストラクタに2つ以上渡すと ValueError になる。ゲートウェイ側は Authorization と X-Api-Key の両方を読む期間を設けてから、X-Api-Key 依存を外す順序が安全だ。構成の考え方はLLMゲートウェイの設計も参考になる。

Admin APIのフィールド名変更はどこに影響するのか

Admin APIの応答からrolesなど旧フィールド名が消えるため、棚卸しや集計コードの修正が必要です。

2026-10-21の応答からは旧名が消える。基盤チームのメンバー管理・コスト配賦の自動化に直撃する。

対象旧名新名
RBACグループrolesrole_ids
RBACグループメンバーgroup_idrbac_group_id
RBACロールnamedisplay_name
レート制限group_typegroup.type
APIキーworkspace_idscope
Analytics(ユーザー別)actor.emailactor.email_address
Analytics(サマリー)summariesdata

最も落とし穴が大きいのはAPIキーだ。旧版の workspace_id が null だったキーは「Defaultワークスペース」か「全ワークスペース共通」かの区別がつかなかった。新版では scope.workspace_id に実IDが入り、全ワークスペース共通キーは scope が {"type": "organization"} になる。null をDefault扱いしていた棚卸しスクリプトは、scope.workspace_id をDefaultワークスペースのIDと比較する形に書き換える。ワークスペース統制の全体像はワークスペース管理とWIFで扱っている。

どう段階移行を設計するべきか

移行は基盤層の先行修正、SDK更新、チーム別検証の順に進め、旧版に残す例外を管理します。

APIバージョンはSDKのメジャーバージョンと連動する。Python 2.0.0、TypeScript 1.0.0、Go 2.0.0(モジュールパスは /v2)、Java 3.0.0、ant CLI 2.0.0 などが初めて 2026-10-21 を既定で送る。SDKを使わない場合は anthropic-version ヘッダーを自分で指定する。

  1. インベントリ: SDKのバージョン、temperature 系の送信箇所、X-Api-Key 依存、Admin API利用スクリプトを全チームから洗い出す
  2. 基盤層の先行対応: ゲートウェイとログ基盤を両ヘッダー対応にし、Admin API連携を新フィールド名に切り替える
  3. 例外の明示: 非既定の temperature が必須の呼び出しは、そのリクエストだけ 2023-06-01 に残せる。例外はチケットと期限で管理する
  4. Amazon Bedrockの扱い: 2026-10-21 はClaude 4.7以降のモデルでのみ利用できる。旧モデルを呼ぶ経路は現行のSDKとバージョンを維持し、先にモデルを移す
  5. テスト: 本番切替前に 2026-10-21 で統合テストを回す

旧版の廃止期限は、確認した公式資料に記載がなかった。期限が公表されるまでは、例外を放置せず棚卸しを続ける運用が妥当だ。全社規模のAI基盤変更管理は、Kuuの大企業向けAI変革プログラムRDEでも支援している。

参考

まとめ

壊れるのは、サンプリング引数の送信、X-Api-Key 依存、Admin APIの旧フィールド名の3点に集約できる。基盤チームが先に両ヘッダー対応と新フィールド対応を済ませ、各チームのSDK更新を安全に受け止める順序を取れば、全社移行の手戻りは小さくなる。移行計画の設計や統制の整備は、RDEからお問い合わせください。

関連記事

Claude APIの処理地域をinference_geoで固定Managed Agentsのwebhook設計と配信保証Managed Agentsのセルフホストサンドボックス実装GPU推論キャパシティ調達戦略——予約とスポットの使い分け