anthropic-versionヘッダーとClaude APIのバージョン管理方針
Claude APIの必須ヘッダーanthropic-versionは、2023年から実質2種類しか存在しない。後方互換ポリシーと実務上の扱い方を整理する。
anthropic-versionヘッダーとは何か
Claude APIへのリクエストには、anthropic-version というリクエストヘッダーを必ず付ける必要があります。値は anthropic-version: 2023-06-01 のように日付形式です。curlや素のHTTPクライアントで直接APIを叩く場合はこのヘッダーを自分で指定しなければなりません。公式クライアントSDK(Python / TypeScript等)を使っていれば、SDK側が自動でセットするため意識する場面はほとんどありません。
このヘッダーが指すのは「APIの入出力フォーマットのバージョン」です。モデル自体のバージョン(Opus / Sonnet / Haikuの世代)とは別軸の概念で、混同すると設定ミスにつながります。anthropic-versionはAPIの通信仕様、モデル名はAIの世代と分けて覚えておく必要があります。
Anthropicの後方互換ポリシー
公式ドキュメントは、あるバージョンに対して次の2点を「保持する」と明言しています。
- 既存の入力パラメータ
- 既存の出力パラメータ
一方で、同じバージョン番号のまま次の変更は行われる余地があります。
- 追加の入力パラメータ(オプション)を増やす
- 出力に追加の値を増やす
- 特定のエラー種別の発生条件を変える
- enum的な出力値に新しいバリアントを追加する(ストリーミングのイベント種別など)
つまり 2023-06-01 は「凍結されたスキーマ」ではありません。既存のキーが消えたり型が変わったりしない、という破壊的変更をしないという約束であって、フィールドの追加やエラー条件の調整は同一バージョン内で起こり得ます。ドキュメント通りの使い方をしている限り、既存の実装が壊れることはないというのが公式の立場です。
バージョン履歴は実質2つしかない
anthropic-version の値として存在するのは、次の2つだけです。
| バージョン | 内容 |
|---|---|
2023-01-01 | 内容初回リリース |
2023-06-01 | 内容ストリーミングのSSE形式を刷新 |
2023-01-01の初回リリース以降、バージョン識別子が切り替わったのは2023-06-01の1回だけです。多くのSaaS APIが v1 v2 v3 と頻繁にメジャーバージョンを切るのに対し、Claude APIは後方互換な変更を同一バージョン内に押し込む方針を徹底しています。読者が実務で気にすべきは「次のバージョンに備える」ことではなく、「今のバージョンで何が保証されているか」です。
2023-06-01で何が変わったか
2023-06-01 はストリーミングのレスポンス形式を作り直したバージョンです。変更点は3つに整理できます。
- 補完テキストが増分(delta)方式になった。以前は
" Hello"→" Hello my"→" Hello my name"のように毎回それまでの全文が返っていたのに対し、" Hello"→" my"→" name"と差分だけが送られるようになりました - すべてのイベントに名前が付くようになった(named events)。以前はデータのみのイベント(data-only events)でした
- 不要になった
data: [DONE]イベントを廃止し、レスポンスに含まれていた古いexception/truncatedフィールドも削除
ストリーミングを自前でパースしている実装ほど影響が大きい変更です。SDKを使っていれば吸収されますが、SSEを直接受信してテキストを結合している自作コードでは、旧方式(全文送信)を前提に書かれたロジックが 2023-06-01 では動きません。
2023-01-01のまま使い続けるとどうなるか
公式は「最新バージョンの使用を推奨し、古いバージョンは非推奨(deprecated)扱いで、新規ユーザーには利用できなくなることがある」と説明しています。つまり 2023-01-01 を明示指定した既存のリクエストがすぐに止まるわけではありませんが、新規にAPIキーを発行したアカウントでは選べなくなる可能性があるという含みです。既存実装で古いバージョンを指定したままにしている場合、いつまで動くかの保証はドキュメント上に明記されておらず、早めに 2023-06-01 へ揃えておくのが無難です。
anthropic-versionとツールバージョンは別物
紛らわしいのが、Web検索ツールやコード実行ツールの web_search_20250305 のようなツール名末尾の日付です。こちらは個々のツール定義のバージョンで、anthropic-version ヘッダーとは管理の階層が異なります。ツールのバージョニングの詳細はClaude APIツールのバージョン管理ガイドにまとめていますが、要点だけ言うと次のように役割が分かれています。
anthropic-versionヘッダー: リクエスト全体の通信フォーマット(現状2種類)- ツール名の
_YYYYMMDDサフィックス: そのツール固有の入出力スキーマ(ツールごとに独立して増える)
片方を更新してももう片方には影響しません。エラーログに両方の日付表記が混在すると混同しやすいので、どちらのバージョンを指しているかをコードコメントで明示しておくと保守がしやすくなります。
anthropic-versionとanthropic-betaは別ヘッダー
もう1つ混同しやすいのが anthropic-beta ヘッダーです。役割がまったく違います。
anthropic-version: 必須。API全体の通信フォーマットを指定する。値は実質2種類だけanthropic-beta: 任意。個別の実験的機能を有効にするためのオプトインで、機能ごとに異なる値を持つ。正式リリース前の新機能やモデル能力を試すためのフラグで、機能の数だけベータ名が存在する
両方を同時に送るリクエストは珍しくありません。たとえばコンテキスト編集機能を試す場合は次のようになります。
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: context-management-2025-06-27" \
-H "content-type: application/json" \
-d '{"model":"claude-opus-5","max_tokens":1024,"messages":[{"role":"user","content":"Hello, Claude"}]}'anthropic-version は「今使っている通信フォーマットが何か」を固定する軸、anthropic-beta は「正式版になる前の機能を先取りするか」を選ぶ軸です。SDKでは前者を意識する必要がほぼない一方、後者は betas パラメータとして明示的に指定するのが一般的です。この2つのヘッダー名は文字列が似ているため、ログを読むときに取り違えないよう注意してください。
ヘッダーを間違えるとどうなるか
anthropic-version を省略したり、存在しない値(たとえば未来の日付や誤字)を指定したりした場合、公式ドキュメントはこのヘッダー専用のエラーコードを定義していません。Claude APIのエラー体系では、リクエストの形式や内容に問題がある場合は一律で 400 invalid_request_error が返る設計になっており、ヘッダー不備もこの一般的なエラー種別に含まれると考えられます。原因が分からないエラーに遭遇したら、まず anthropic-version ヘッダーの有無・値を確認してから、他のリクエスト内容を疑う順序が効率的です。
新しいモデルが出てもヘッダーは変わらない
Opus 5のような新しいモデル世代がリリースされても、anthropic-version の値自体は変わりません。新モデルで追加された機能(新しいコンテンツブロックの種類や、拡張された stop_reason の値など)は、後方互換ポリシーが許容する「enum的な出力値への新しいバリアント追加」の枠組みで、既存バージョンのまま提供されるのが基本パターンです。モデルのアップグレードとAPIバージョンの更新は別々のタイミングで動く、独立した2つの軸だと理解しておくと、リリースノートを読むときの混乱が減ります。
実装で気を付けること
curlのように自分でHTTPリクエストを組み立てるツールでは、ヘッダーの記述漏れがそのまま障害につながります。実装レビューのチェック項目に「anthropic-version を静的な文字列でハードコードしていないか(将来のバージョン更新時に1か所で直せるか)」を加えておくと、後々の切り替え作業が楽になります。curlで直接叩く例は次の形です。
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-opus-5","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'anthropic-version を省略したり無効な値を渡したりした場合の具体的なエラーメッセージは公式ドキュメントに明記がありません。ヘッダー自体は「必ず送る」ものと定義されているため、リクエストが失敗した際は最初に確認すべき項目の1つです。Claude APIのエラーハンドリング設計ではヘッダー起因を含むエラー種別ごとの対処をまとめています。
このバージョン管理方針をどう読むか
日付ベースのバージョニングは、SemVerのような 1.0.0 2.0.0 に比べて「いつ時点の仕様か」が一目で分かる利点があります。Anthropicの場合はそこからさらに一歩進み、2023-06-01以降はバージョン識別子を一度も切っていないという運用実績自体が特徴です。API利用者にとっては、バージョン追従のためのメンテナンスコストがほぼ発生しない設計だと言えます。
裏を返せば、次に anthropic-version が更新されるとしたら、それは既存の入出力フォーマットを壊さない範囲では収まらない、比較的大きな仕様変更だと推測できます。Messages API自体の互換性を保ったままモデルや機能を拡張してきたAnthropicの姿勢からすると、次のバージョン更新は当面先になりそうです。ただしこれは運用実績からの推測であり、公式が今後の予定を明言しているわけではありません。
まとめ
anthropic-version はClaude APIの通信フォーマットを指定する必須ヘッダーで、実在するバージョンは 2023-01-01 と 2023-06-01 の2つだけです。後方互換ポリシーにより既存の入出力パラメータは保持されつつ、オプション項目やエラー条件は同一バージョン内で追加され得ます。SDK利用者は意識する必要がほぼありませんが、curl等で直接APIを叩く実装や、ストリーミングを自前でパースしているコードは、2023-06-01 の増分方式を前提にしているか確認しておくと安全です。