Claude API のベータヘッダーの使い方

Claude API の実験的な機能は、標準の API に入る前にベータとして公開されます。使うには anthropic-beta ヘッダーを付けるか、クライアント SDK の betas パラメータに機能名を渡します。本記事では、基本の指定方法、複数のベータを同時に有効にするときの書き方、エンドポイントごとに決まっているベータヘッダー、そして間違えたときに返る 400 エラーの読み方を日本語で整理します。非公式の解説です。

ベータヘッダーとは

ベータヘッダーは、実験的な機能や新しいモデルの機能を、標準 API に取り込まれる前に使えるようにする仕組みです。リクエストに anthropic-beta ヘッダーを付けると、その機能が有効になります。

送る値（ベータ名）は機能ごとに決まっており、各機能のドキュメントに正確な名前が書かれています。いま何がベータなのかは API の概要ページで一覧できます。

クライアント SDK には beta 名前空間があり、ベータ機能を有効にした呼び出しはそこから行います。SDK は betas パラメータに渡した名前を anthropic-beta ヘッダーへ変換して送ってくれるので、ヘッダーを自分で組み立てる必要があるのは生の HTTP リクエストを書くときだけです。

基本の使い方

生の HTTP では、次のようにヘッダーを1行足すだけです。

POST /v1/messages
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
anthropic-beta: BETA_FEATURE_NAME
content-type: application/json

以下は同じリクエストを cURL と各 SDK で書いたものです。例としてコンテキスト編集（context editing）のベータ context-management-2025-06-27 を有効にしています。

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"}
    ]
  }'

Python SDK では client.beta.messages.create() を呼び、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"],
)

print(response.content)

TypeScript SDK も同じ形です。

const client = new Anthropic();

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

console.log(msg.content);

コマンドラインの ant CLI では --beta フラグで指定します。

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

公式ドキュメントには、これらに加えて C#・Go・Java・PHP・Ruby の例も同じ形で載っています。いずれも beta 名前空間と betas 相当のパラメータを使う点は共通です。

複数のベータを同時に使う

1回のリクエストで複数のベータ機能を使うときは、ヘッダーの値をカンマで区切って並べます。

anthropic-beta: feature1,feature2,feature3

SDK では betas パラメータに配列で列挙します（例: betas=["feature1", "feature2"]）。

CLI で注意が要るのはここです。--beta フラグは1回だけ使い、機能名をカンマで区切ります（例: --beta feature1,feature2）。--beta を複数回書くのは避けてください。現状は最初のフラグの値だけが有効になり、2つ目以降は黙って無視されます。フラグを繰り返す書き方はエラーにならないぶん、気づきにくい失敗です。

エンドポイント専用のベータヘッダー

ベータ 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 リクエストを書くときだけです。

同じエンドポイントに掛かるヘッダーどうしが常に併用できるわけではない点にも注意してください。メモリストアのエンドポイントでは agent-memory-2026-07-22 が managed-agents-2026-04-01 を置き換えます。同じリクエストに両方を送ると 400 エラーになります。SDK はエンドポイントごとに正しいヘッダーを選んで送るので、この衝突は起きません。

ベータ名は 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"
}

このメッセージは名前の誤りと権限不足を区別しません。綴りが正しいと確信できるなら、次に疑うのは組織のアクセス権です。切り分けのために request_id を控えておくと、サポートへの問い合わせがそのまま通ります。

ベータ機能そのものについて、公式ドキュメントは次の点を明記しています。

予告のうえで破壊的変更が入ることがある
非推奨化・削除されることがある
レート制限や価格が通常と異なることがある
すべてのリージョンで使えるとは限らない

つまり、ベータ機能を本番の処理経路に組み込むなら、その機能が使えなくなったときに何が起きるかを先に決めておく必要があります。ベータ名は日付入りなので、コードに直接書くのではなく設定値として外に出しておくと、次のバージョンが出たときの差し替えが1箇所で済みます。

ベータ機能の更新はリリースノートで告知されます。本番で問題が起きた場合はサポートに連絡してください。

本記事は Anthropic の公式ドキュメント Beta headers（2026-09-08 確認）に基づく非公式の日本語解説です。ベータ機能のため、名称や仕様は変更される可能性があります。実装前に公式ドキュメントで最新の内容をご確認ください。