Claude APIでanthropic-betaヘッダーを使う方法
anthropic-betaヘッダーの書式、複数ベータの併用ルール、エンドポイント固有ヘッダーの衝突を具体例で解説する。
anthropic-betaヘッダーの書式と複数指定
anthropic-beta ヘッダーは、正式リリース前の実験的機能をClaude APIで先行利用するための識別子です。POST /v1/messages のリクエストヘッダーに機能名を1つ入れるだけで有効になります。
POST /v1/messages
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
anthropic-beta: context-management-2025-06-27
content-type: application/json複数のベータ機能を同時に使う場合はカンマ区切りで並べます。
anthropic-beta: feature1,feature2,feature3SDKでは betas パラメーターに配列で渡すのが正規の書き方です。
client = Anthropic()
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
betas=["context-management-2025-06-27"],
)TypeScriptでも構造は同じで、betas: ["context-management-2025-06-27"] のように配列を渡せばSDK側が anthropic-beta ヘッダーを自動生成します。複数のベータを併用するときは、配列に機能名を追加するだけで済みます(betas: ["context-management-2025-06-27", "fast-mode-2026-02-01"])。生のHTTPリクエストを自前で組むとき以外は、ヘッダーを直接書く必要はありません。
ここでCLIだけ挙動が違います。 ant CLIには --beta フラグがありますが、複数のベータ機能をカンマ区切りの1つの値として渡す必要があります(--beta feature1,feature2)。フラグを繰り返して --beta feature1 --beta feature2 のように書くと、最初のフラグの値しか反映されません。SDKの betas 配列と同じ感覚で書くと機能が片方だけ無効になり、原因が分かりにくいはまりどころです。
ベータ機能名は feature-name-YYYY-MM-DD の形式が基本で、日付部分はベータが公開された時期を示します。存在しない名前や組織にアクセス権がない名前を送ると、次の400エラーが返ります。
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Unexpected value(s) `invalid-beta-name` for the `anthropic-beta` header. Please consult our documentation at platform.claude.com/docs or try again without the header."
},
"request_id": "req_011CcnGfC9fELffo2EALu4Wd"
}エラーメッセージに機能名がそのまま出るので、typoの特定はしやすい部類です。ただしタイプミスではなく「まだ組織に権限が付与されていないベータ」を叩いたときも同じ400が返るため、綴りを何度確認しても直らない場合は権限側を疑う必要があります。
正確な機能名は、各機能のドキュメントページに個別に記載されています。「現在どのベータ機能が公開されているか」を横断で確認したい場合は、Claude APIのAPI概要ページにベータ中のAPI一覧がまとまっています。機能名を推測やコードコメントの古い記述から拾わず、その機能の公式ページで最新の名前を確認する方が、typoと廃止済みベータ名の混同を両方防げます。
エンドポイント固有ベータヘッダーの一覧
ベータ機能の大半は /v1/messages に対するオプトインですが、一部のベータAPIは特定のエンドポイント専用で、そのエンドポイントを叩くたびに機能固有のヘッダーが必須になります。
| エンドポイント | 必須ヘッダー |
|---|---|
/v1/agents、/v1/sessions、/v1/environments | 必須ヘッダーmanaged-agents-2026-04-01 |
/v1/tunnels | 必須ヘッダーmcp-tunnels-2026-06-22 |
/v1/memory_stores とそのサブリソース | 必須ヘッダーagent-memory-2026-07-22 |
SDKの beta 名前空間はこれらのヘッダーを自動で付与します。手動で付ける必要があるのは、生のHTTPリクエストを組むときだけです。Managed Agentsをこれから使い始める場合は、実装パターンがManaged Agentsへの移行にまとまっているので、ヘッダーの扱いだけでなくAPI呼び出し全体の移行手順を先に見ておくと二度手間になりません。
/v1/agents を生のHTTPリクエストで叩く場合、ヘッダーの付け方は次のようになります。
curl https://api.anthropic.com/v1/agents \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json"/v1/messages 向けのベータ機能と混同しやすいのは、この種のヘッダーがリクエストのたびに毎回必須という点です。/v1/messages の一般的なベータは「送れば有効になる」opt-in形式ですが、エンドポイント固有ヘッダーは「送らないとそもそもエンドポイントが機能しない」必須パラメーターに近い性質を持ちます。3種類のヘッダーの性質を並べると次のようになります。
| ヘッダーの種類 | 対象 | 送らなかった場合 |
|---|---|---|
機能単位のベータ(context-management-2025-06-27 等) | 対象/v1/messages | 送らなかった場合ベータ機能が無効なだけで、リクエスト自体は通常どおり成功する |
エンドポイント固有ヘッダー(managed-agents-2026-04-01 等) | 対象/v1/agents 等の専用エンドポイント | 送らなかった場合エンドポイントが機能しない(実質必須) |
パラメーター単位のベータ(thinking-binding-controls-2026-08-01 等) | 対象/v1/messages の特定パラメーター | 送らなかった場合該当パラメーターを送った瞬間に400エラー |
メモリーストアのエンドポイントで併用不可になる理由
エンドポイント固有ヘッダーは、同じエンドポイントに対して常に組み合わせられるわけではありません。とくに /v1/memory_stores 系では注意が必要です。
agent-memory-2026-07-22 はメモリーストアのエンドポイント上で managed-agents-2026-04-01 を置き換えます。両方を同じリクエストに含めて送ると400エラーになります。
anthropic-beta: managed-agents-2026-04-01,agent-memory-2026-07-22このヘッダーの組み合わせでメモリーストアのエンドポイントを叩くと、リクエストは失敗します。Managed AgentsとAgent Memoryの両方を有効化している開発環境で、共通のヘッダー生成ロジックを使い回していると起きやすい事故です。エンドポイントごとにどのベータヘッダーが必要かをハードコードで一覧管理していると、メモリーストア呼び出し用のパスだけ managed-agents-2026-04-01 を明示的に外す分岐が要ります。SDKの beta 名前空間を使っていれば、この分岐はSDK側が正しいヘッダーを自動で選ぶため意識せずに済みます。
thinking.block_bindingで見落としがちな400エラー
エンドポイント固有ヘッダーだけでなく、/v1/messages の個別パラメーターにもベータヘッダーが要求されるケースがあります。代表例が thinking.block_binding です。
thinking.block_binding を thinking-binding-controls-2026-08-01 ベータヘッダーなしで送ると、400 invalid_request_error が返ります。このパラメーターはClaude Fable 5.1で、リプレイした思考ブロックの整合性を制御する用途で使いますが、パラメーター自体はドキュメントに載っていても、対応するベータヘッダーの記載を見落としたまま実装するとこのエラーに行き当たります。
エラーメッセージの末尾にはどのヘッダーが必要かが明示されるため、原因の特定自体は難しくありません。ただし発生源は「機能が使えない」ことではなく「ヘッダーの付け忘れ」であることが多く、機能そのものへの疑いから入ると回り道になります。新しいベータ機能をパラメーターのドキュメントだけを見て実装するときは、そのパラメーターの説明文中に対応するベータヘッダー名がリンクされていないか先に確認する方が早く済みます。
本番運用に組み込む前に確認すべきリスク
ベータ機能は名前のとおり実験段階にあり、正式リリース済みの /v1/messages パラメーターとは前提が異なります。公式ドキュメントは次の4点を明記しています。
- 事前通知のうえで破壊的変更が入ることがある
- 非推奨化・廃止されることがある
- 正式機能とは異なるレート制限や料金が適用されることがある
- 一部リージョンでは利用できないことがある
つまり、ベータ機能名をコードに直接埋め込んだまま本番運用に組み込むと、機能名自体が将来変わったりレスポンス形式が変わったりするリスクを引き受けることになります。実務上の対策は難しくありません。ベータ機能名は環境変数か設定ファイルの1箇所にまとめておき、複数箇所に文字列としてハードコードしないことです。破壊的変更の通知が来たときに直す箇所が1つで済みます。料金・レート制限が正式機能と異なる可能性がある点は、コスト試算の段階で見落としやすいので、ベータ機能を組み込んだ機能の課金テストは正式機能とは別枠で行う方が安全です。
リージョン制限も同様に見落としやすい点です。ある拠点では動いていたベータ機能が、別リージョンのエンドポイントに切り替えた途端に使えなくなるという事象は、機能そのものの不具合ではなく可用性の差に起因することがあります。マルチリージョン構成でベータ機能を使う場合は、リージョンごとに動作確認を別立てで行うのが安全です。
anthropic-versionヘッダーとの違い
anthropic-beta と混同しやすいヘッダーに anthropic-version があります。役割はまったく異なります。anthropic-version はメッセージAPIの安定版フォーマットを指定するヘッダーで、既存の入出力パラメーターの互換性を保証する単位です。一方 anthropic-beta は、まだ正式版に入っていない機能を個別にオプトインする仕組みで、機能ごとに独立したライフサイクルを持ちます。
両者は同じリクエストに同居できます。anthropic-version: 2023-06-01 を送りながら、特定のベータ機能だけを anthropic-beta で追加opt-inする、というのが通常の組み合わせです。バージョン管理の設計思想と現在のバージョン履歴はanthropic-versionヘッダーとClaude APIのバージョン管理方針で扱っています。ベータ機能が正式版に昇格するとヘッダー自体が不要になり、パラメーターがデフォルトの /v1/messages 仕様に統合される流れも、そちらの記事で確認できます。
エラーハンドリングをどう実装するか
anthropic-beta 関連のエラーは、他の400系エラーと同じ invalid_request_error 型で返ってきます。SDKを使っていれば、この型は言語ごとの例外クラスにマッピングされるため、anthropic-beta 特有の分岐を自前で書く必要はほとんどありません。SDK側の例外クラスとエラー型の対応表はClaude APIのエラー形式とSDK例外クラスの言語別対応表にまとめてあります。
生HTTPで実装している場合は、error.type が invalid_request_error で error.message に anthropic-beta という文字列が含まれるかどうかで、ヘッダー起因のエラーを他の400エラーから切り分けられます。
try:
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
betas=["invalid-beta-name"],
)
except anthropic.BadRequestError as e:
if "anthropic-beta" in str(e.body.get("error", {}).get("message", "")):
# ベータヘッダー起因の400。機能名の綴りか権限を確認する
pass
else:
raiseこの切り分けを入れておくと、監視ダッシュボード上で「ベータ機能起因のエラー」と「それ以外の400エラー」を別カウントで集計でき、新しいベータ機能を導入した直後の異常検知がしやすくなります。ベータ機能を段階的にロールアウトしているチームでは、この分離が「ロールアウト対象の一部ユーザーだけでエラー率が上がった」ことに気づく最初の手がかりにもなります。
まとめ
anthropic-beta ヘッダーは、単一機能ならカンマ区切りとSDKの betas 配列で素直に扱えます。つまずきどころは3つに集約できます。CLIの --beta フラグはカンマ区切り1本で渡し、繰り返し指定しないこと。Managed AgentsとAgent Memoryのようにエンドポイント固有ヘッダーが競合する組み合わせを避けること。そしてパラメーター単位でベータヘッダーが要求されるケース(thinking.block_binding など)を、パラメーターのドキュメントとセットで確認すること。SDKの beta 名前空間を使っていれば、この3つのほとんどはSDK側が肩代わりしてくれます。
生のHTTPリクエストで実装する場合だけ、この記事のエンドポイント固有ヘッダーの一覧とヘッダー種類ごとの性質の表を実装前のチェックリストとして見返すと、後から400エラーの原因を1つずつ潰していく手戻りを減らせます。