Anthropic API キーを直接使って Claude Code を動かしてる開発者向け
Anthropic が新しく発表した推論機能（interleaved-thinking など）や新しい Files API を GA より早く Claude Code 経由で触りたいときに、ANTHROPIC_API_KEY を使って動かしてるセッションの起動コマンドに付けて立ち上げる。1セッションの間ずっと指定したベータ機能が有効になり、終了するまで同じ機能名で API リクエストが飛び続けます。
--betas は claude コマンドを叩いて Claude Code を起動するとき、Anthropic API がまだ実験段階で出している新機能を「このセッションでは試したいです」と宣言するためのスイッチです。普段は GA になった機能しか使えないところに、日付付きの機能名を渡すことで、API リクエストに anthropic-beta ヘッダーが自動で乗ります。
条件が1つあります。Anthropic API キーを直接使ってる人だけ効きます。Claude.ai の Pro/Max の月額契約でログインしてる人が同じことをしても、効きません。
噛み砕くと
Anthropic は新機能をいきなり本番に出さず、まず「ベータ版」として一部のユーザーに開放します。これを使いたい人は、API リクエストに「私はこのベータ機能を使う前提で話します」という一言を添えて投げる必要があります。その「一言」が anthropic-beta ヘッダーです。
家電量販店で「先行体験コーナーの新型レンジを試したい」と申告して入る感じに近いです。何も言わなければ普通の売り場の通常品しか触れません。--betas は、Claude Code 経由でその先行体験コーナーに入るためのチケット名を渡す場所です。
大事な前提：Anthropic API キーで動かしてる人だけ効く
これは --betas を覚える前に必ず押さえてほしい部分です。Claude Code には2つの認証方式があり、--betas が効くのは片方だけです。
Anthropic の公式表にも「API key users only」と明記されています。Claude.ai の Pro/Max/Team/Enterprise 契約で OAuth ログインしてる場合、--betas を付けて起動しても無視されます。逆に ANTHROPIC_API_KEY に API キーを入れて使ってる場合だけ、ヘッダーが API に届きます。
確認は黒い画面で次の1行を打つだけで済みます。
$ echo $ANTHROPIC_API_KEY何か長い文字列が返ってくれば API キー利用者です。空っぽで何も返ってこない場合は Subscription 側の可能性が高いので、--betas を試しても何も起きません。
「interleaved-thinking を試したい」場面を例に、実際の手順を見る
題材として、Anthropic が新しく公開した interleaved-thinking という実験機能を、Claude Code 経由で試したい場面を想定します。
ステップ1: API キー利用者であることを確認する
まず黒い画面を開いて、次の1行を打ちます。Mac なら「ターミナル」アプリ、Windows なら「PowerShell」が該当します。
$ echo $ANTHROPIC_API_KEY長い文字列が返ってきたら準備完了。空っぽなら、Anthropic Console から API キーを発行して環境設定値に入れる作業が先に必要です。
ステップ2: 通常起動で claude を立ち上げて挙動を見ておく
比較のために、まず --betas なしで起動します。
$ claude適当なコード書き換え依頼を投げて、応答の流れを覚えておきます。たとえば「この関数を3つに分割して」みたいな依頼を投げると、Claude は一気に考えて一気に書き換え案を返してきます。
ステップ3: --betas 付きで起動し直して同じ依頼を投げる
一旦 /exit で終了して、今度はベータ機能名を渡して起動します。
$ claude --betas interleaved-thinking-2025-05-14機能名は 機能名-YYYY-MM-DD の命名規則になっています。日付部分はその beta バージョンが公開された日付。Anthropic の API ドキュメントに正確な名前と日付が載っているので、ここからコピペするのが一番安全です。
同じコード書き換え依頼を投げると、Claude が「考える→ツール呼ぶ→また考える→またツール呼ぶ」を交互に挟みながら進む挙動が観察できます。通常モードとの応答の質や所要時間を比べる、というのがここでの目的です。
ステップ4: 複数のベータ機能を同時に有効化する
1つしか使えないわけではなく、カンマ区切りで何個でも並べられます。たとえば思考の interleave に加えて、長い CLAUDE.md の読み込みコストを抑える prompt-caching も同時に効かせたい場合はこうです。
$ claude --betas "interleaved-thinking-2025-05-14,prompt-caching-2024-07-31"区切りは半角カンマだけです。スペースを入れて "a, b" みたいに書くと、機能名の先頭にスペースが入った状態で API に渡って、機能名が一致せず弾かれます。これは初心者がやりがちな勘違いポイントの1つです。
ステップ5: わざとタイポして拒否される様子を見る
正しく機能してるか確認するために、一度わざとタイポして起動してみます。
$ claude --betas interleaved-think最後の ing を抜いた状態です。この状態で何か依頼を投げると、API から下記のようなエラー JSON が返ってきて止まります。
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Unsupported beta header: invalid-beta-name"
}
}日付部分の typo でも同じく拒否されます。2025-05-14 を 2025-05-15 と書くと、Anthropic 側にその日付の beta バージョンが存在しないため、同じエラーになります。
ステップ6: 公式ドキュメントで機能名を確認する習慣をつける
使いたいベータ機能の名前と日付は、必ず Anthropic 公式の beta-headers ドキュメントで確認します。記憶や昔のメモから書くと、上記の typo パターンを踏みます。GA に昇格してすでに不要になってる機能名を渡しっぱなしになるのも、ここで気づけます。
つまり --betas は何をしてくれるのか
- やってくれる: 渡した機能名を
anthropic-betaヘッダーに展開して、Claude Code から Anthropic API へのリクエストに自動で乗せる。これで実験段階の新機能が起動中ずっと有効になる - やってくれない: Subscription ログイン中のユーザーへの機能解放。GA 済み機能を「もう一度ベータ扱いに戻す」こと。料金体系の説明そのもの
- 意味が薄い場面: そもそも実験機能を使う予定がない普通のコーディング作業。GA に昇格した古い機能名を渡し続けてるケース（無害だが意味なし）
使いどころ3シナリオ（具体題材で再現）
シナリオ1: Anthropic が発表したばかりの推論機能を Claude Code で早めに試す
題材: interleaved-thinking を使って、自社の TypeScript プロジェクトの大規模リファクタ作業（300行クラスの分割）を回す。通常モードと比較して「考えながらツールを取り直す」挙動が応答の質にどう効くかを観察したい場面です。claude --betas interleaved-thinking-2025-05-14 で起動して、同じ依頼を通常モードと交互に投げて応答ログを比べます。
シナリオ2: 長い CLAUDE.md を持つ社内ツールでプロンプト前半の使い回し機能を試す
題材: 数千行ある CLAUDE.md を読ませた状態で何度もコード生成依頼を投げると、2回目以降の応答時間が体感で気になる。--betas prompt-caching-2024-07-31 を付けて起動し直すと、同じ CLAUDE.md 部分が一時保存されて使い回され、2回目以降が速くなるはず、という仮説検証ができます。なお prompt caching は GA 済みなので、現実には --betas を渡さなくても動きます。古いスクリプトに残ってるパターンの説明用です。
シナリオ3: Files API を Claude Code 経由でテストする
題材: 大量の PDF（決算資料・契約書など）を Claude に読ませて要約させたい。claude --betas files-api-2025-04-14 を付けて起動すると、API レベルのファイルアップロード機能が有効化された状態で対話できます。Claude Code が標準で持ってる Read ツールでは扱いにくい、API 経由でしか触れない実験機能を試したいときの定番形です。
初心者が踏みやすい落とし穴
- Subscription ログイン中は完全に無視される。Claude.ai の Pro/Max 契約で OAuth ログインして使ってる人が
--betas interleaved-thinking-2025-05-14を付けても、ヘッダーは API に届きません。事前にecho $ANTHROPIC_API_KEYで API キー利用者かを確認します - タイポすると Unsupported beta header エラーで止まる。日付部分のミスでも同じ扱いです。Anthropic 公式の beta-headers ドキュメントから正確な機能名をコピペするのが安全
- 複数指定はカンマ区切り、スペース禁止。
"a,b,c"は OK、"a, b, c"はスペースごと機能名扱いされて全部弾かれます。コマンドを囲むダブルクォートも忘れずに - ベータ機能は予告なく削除されたり仕様変更される。Anthropic 公式ドキュメントの原文では「breaking changes with notice / be deprecated or removed」と書かれています。本番システムに beta 機能名を埋め込むと、ある日突然動かなくなることがあります
- GA 昇格後に渡し続けると無意味、場合によっては警告。実験段階を抜けて正式機能になった後は、
--betasで指定しなくても普通に使えます。古い CI スクリプトや起動用の小さなスクリプトに昔の beta 名が残ってないか定期的に見直す習慣をつけます - 料金が標準と違う場合がある。Anthropic 公式は「Have different rate limits or pricing」と明記しています。ベータ機能を使ってる間のリクエストは標準と従量課金が異なる可能性があるので、月次の請求書は必ず見ます
- リージョン制限あり。同じく公式に「Not be available in all regions」と書かれていて、一部の地域からでは特定のベータ機能が動かないことがあります。日本から触ったときに「タイポしてないのに使えない」場合はこれを疑います
- 機能名をプロジェクトの覚え書きに直書きすると古びる。日付付きの機能名は短期間で更新されたり GA に昇格します。CLAUDE.md や README に
--betas interleaved-thinking-2025-05-14をそのまま書くと、半年後に同じプロジェクトを触る人が古い名前を渡し続ける羽目になります
書き方
claude --betas "<機能名1>,<機能名2>,..."やってみるとこうなる
入力
claude --betas "interleaved-thinking-2025-05-14"出力例
通常通り対話画面が立ち上がり、内部では API リクエストに anthropic-beta: interleaved-thinking-2025-05-14 ヘッダーが含まれた状態で送信され、対応した実験機能が有効になります。機能名をタイポしたり日付を間違えると、Unsupported beta header: invalid-beta-name という API エラーがプロンプト画面に出て止まります。このページに出てきた言葉
- anthropic-beta ヘッダー
- Anthropic API へのリクエストに添える HTTP ヘッダー。<code>anthropic-beta: 機能名-日付</code> の形で「このリクエストは実験中の機能を使います」と伝える
- GA（General Availability）
- 実験段階を抜けて「正式機能」として誰でも普通に使える状態。GA 昇格後はベータヘッダーを付けなくても動く
- Subscription / API キー
- Claude Code には Claude.ai 月額契約（Pro/Max/Team/Enterprise）でログインする方式と、Anthropic API キーを <code>ANTHROPIC_API_KEY</code> に入れて使う方式がある。<code>--betas</code> は後者でだけ効く
- rate limit
- 単位時間あたりに何回 API リクエストを送れるかの上限。ベータ機能は標準とは別の rate limit が設定されることがある
- interleaved-thinking
- モデルが「思考」と「ツール呼び出し」を1ターン内で交互に挟みながら推論を進める実験機能。思考の途中で道具を取り、結果を見てまた思考を続けられる