Claude APIでanthropic-betaヘッダーを使う方法

anthropic-betaヘッダーの書式と複数指定

anthropic-beta ヘッダーは、正式リリース前の実験的機能をClaude APIで先行利用するための識別子です。POST /v1/messages のリクエストヘッダーに機能名を入れると有効になります。

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,feature3

ヘッダーを行ごとに分けて繰り返し送っても、同じ意味になります。Claude APIは同名のヘッダーをすべて読むためです。

anthropic-beta: feature1
anthropic-beta: feature2
anthropic-beta: feature3

SDKでは betas パラメーターに配列で渡すのが正規の書き方で、anthropic-beta ヘッダーはSDKが生成します。

client = Anthropic()
 
response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    betas=["context-management-2025-06-27"],
)

TypeScriptでも構造は同じで、betas: ["context-management-2025-06-27"] のように配列を渡します。ベータを併用するなら、配列に機能名を足すだけです(betas: ["context-management-2025-06-27", "fast-mode-2026-02-01"])。ヘッダーを直接書くのは、生のHTTPリクエストを自前で組むときだけです。

ant CLIには --beta フラグがあり、複数のベータはカンマ区切りの1つの値でも、フラグの繰り返しでも渡せます。

ant beta:messages create \
  --beta context-management-2025-06-27,fast-mode-2026-02-01 \
  --model claude-opus-5-5 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

--beta context-management-2025-06-27 --beta fast-mode-2026-02-01 と書いても、結果は同じです。

ベータ機能名は 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が返ります。綴りを何度見直しても直らない場合は、権限側を疑う必要があります。

アクセス権が必要なベータの代表が fast-mode-2026-02-01 です。fast modeはリサーチプレビューで、speed: "fast" をこのヘッダーとセットで送ります。利用にはアカウント担当者への依頼かウェイトリスト登録が前提です。同じ機能名で世代が3つに分かれる例はClaude APIのUser Profilesでエンドユーザーを識別する手順にあります。

正確な機能名は、各機能のドキュメントページに個別に記載されています。いまベータ中のAPIを横断で見たいときは、Claude APIのAPI概要ページに一覧があります。機能名をコードコメントの古い記述から拾わず、その機能の公式ページで名前を取り直す方が、typoと廃止済みベータ名の混同を両方防げます。

エンドポイント固有ベータヘッダーの一覧

ベータ機能の大半は /v1/messages に対するオプトインですが、一部のベータAPIは特定のエンドポイント専用で、そのエンドポイントを叩くたびに機能固有のヘッダーが必須になります。

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"

ヘッダーの役割は、大きく3つに分かれます。

メモリーストアのエンドポイントで併用不可になる理由

エンドポイント固有ヘッダーは、同じエンドポイントに対して常に組み合わせられるわけではありません。とくに /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 です。

このフィールドは、再送した思考ブロックが前の履歴と食い違ったときの扱いを prefix_mismatch_behavior で選ぶ用途です。値は "error"(既定)と "drop_block" で、後者は食い違ったブロックを捨ててリクエストを通します。Claude Fable 5.1、Claude Opus 5.5、Claude Sonnet 5.5が対象です。

thinking-binding-controls-2026-08-01 なしでこのフィールドを送ると、400 invalid_request_error が返ります。メッセージの末尾は次の1行です。

block_binding: Extra inputs are not permitted

この文面にはヘッダー名が出ません。「フィールドが認識されない」という意味に読めるので、パラメーター名の綴りやモデル側の対応を疑って遠回りしがちです。対処はヘッダーを足すか、フィールドを外すかの二択です。

ヘッダーには別の効果もあります。2026年8月31日より前に作られたアカウントでは、prefix_mismatch_behavior を指定しない限り、履歴の食い違いは検査されません。そこでこのヘッダーを付けると、検査に引っかかるブロックがレスポンスの input_transformations に載ります。新しいアカウントの利用者が受ける400に当たるブロックを、自分のキーで先に見つけられます。

本番運用に組み込む前に確認すべきリスク

ベータ機能は名前のとおり実験段階にあり、正式リリース済みの /v1/messages パラメーターとは前提が異なります。公式ドキュメントは次の4点を明記しています。

• 事前通知のうえで破壊的変更が入ることがある
• 非推奨化・廃止されることがある
• 正式機能とは異なるレート制限や料金が適用されることがある
• 一部リージョンでは利用できないことがある

ベータ機能名をコードに直接埋め込んだまま本番へ載せると、機能名やレスポンス形式が将来変わるリスクを引き受けることになります。対策は単純で、機能名を環境変数か設定ファイルの1箇所にまとめ、文字列のハードコードを避けます。破壊的変更の通知が来たときに、直す箇所が1つで済みます。

料金やレート制限が正式機能と異なる可能性は、コスト試算で見落としやすい点です。ベータを組み込んだ機能の課金テストは、正式機能とは別枠で行う方が安全です。

リージョン制限も同様です。ある拠点で動いていたベータ機能が、別リージョンのエンドポイントへ切り替えた途端に使えなくなっても、機能の不具合とは限りません。可用性の差が原因のこともあるため、マルチリージョン構成ではリージョンごとに動作確認を別立てにします。

anthropic-versionヘッダーとの違い

anthropic-beta と混同しやすいヘッダーに anthropic-version があります。両者は同じリクエストに同居でき、通常は anthropic-version: 2023-06-01 を送りながら、特定のベータだけを追加でオプトインします。

バージョン管理の設計思想と現在のバージョン履歴は、anthropic-versionヘッダーとClaude APIのバージョン管理方針で扱っています。

400が返ったときの切り分けとエラーハンドリング

anthropic-beta 関連のエラーは、他の400系エラーと同じ invalid_request_error 型で返ります。SDKを使っていれば、この型は言語ごとの例外クラスに対応づけられ、ベータ専用の分岐を自前で書く必要はほとんどありません。例外クラスとエラー型の対応はClaude APIのエラー形式とSDK例外クラスの言語別対応表にあります。

原因の見当をつける順序は、メッセージの文面で決まります。

BadRequestError の文字列表現に anthropic-beta が含まれるかどうかで、ヘッダー起因のエラーを切り分けられます。生HTTPで実装している場合は、レスポンスの error.message に同じ文字列があるかを見ます。

try:
    response = client.beta.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello"}],
        betas=["invalid-beta-name"],
    )
except anthropic.BadRequestError as e:
    if "anthropic-beta" in str(e):
        # ベータヘッダー起因の400。機能名の綴りか権限を確認する
        pass
    else:
        raise

この切り分けを入れると、監視ダッシュボードで「ベータ機能起因のエラー」と「それ以外の400」を別カウントにできます。新しいベータを段階的にロールアウトするチームなら、一部の利用者だけエラー率が上がったことに気づく最初の手がかりになります。

エラー本文の request_id は、サポートへ問い合わせるときの識別子になります。同じ値はレスポンスの request-id ヘッダーにも入っているので、ログに残しておくと原因調査が早く進みます。

まとめ

ベータ名は機能のドキュメントで取り直し、複数あればカンマ区切りか配列で並べれば足ります。つまずくのは、エンドポイント固有ヘッダーの併用と、パラメーターを解禁するヘッダーの付け忘れの2点です。SDKの beta 名前空間を使えば、前者はSDKが肩代わりします。

生のHTTPで実装するなら、この記事のエンドポイント別ヘッダーの表と400の切り分け順序を、実装前のチェックリストとして使えます。