Claude CodeプロンプトキャッシュTTL完全解説：5分と1時間、どちらを選ぶべきか？3プラットフォームの料金比較付き

作者注：Claude Code のプロンプトキャッシュにおける TTL（生存時間）メカニズム、5分と1時間の違い、Anthropic API と AWS Bedrock のキャッシュ料金比較、そしてコスト削減のための設定アドバイスを詳しく解説します。

「Claude Code のプロンプトキャッシュの TTL は変更できるの？5分と1時間で何が違うの？結局どっちがお得？」——これは、Claude Code を利用する多くのユーザーがコスト管理の際に抱く最も一般的な疑問です。

結論から言うと、Claude Code のキャッシュ TTL は、現時点ではユーザーが直接変更することはできません。これはご契約中のサブスクリプションプランによって決まります。Max プランのユーザーは自動的に 1 時間の TTL が付与され、Pro プランおよび API キー利用者はデフォルトで 5 分の TTL となります。ただし、Claude API を直接呼び出す場合は、cache_control パラメータを使用して 5 分または 1 時間を自由に選択可能です。

核心的な価値: 本記事を読めば、Claude のプロンプトキャッシュの TTL メカニズムを完全に理解し、Anthropic 公式 API と AWS Bedrock のキャッシュ料金の違いを把握した上で、利用シーンに応じた最もお得なキャッシュ戦略を選択できるようになります。

Claude プロンプトキャッシュ TTL の重要ポイント

プロンプトキャッシュは、Claude シリーズのモデルにおいて最も重要なコスト削減メカニズムの一つです。以前送信したプロンプトのプレフィックス（システムプロンプト、ツール定義、会話履歴など）をサーバー側に保存し、次回の要求でプレフィックスが一致すればキャッシュから直接読み込むため、通常の入力料金の 10% の支払いで済みます。

Claude Code で TTL は変更できるのか？

これはユーザーが最も気にしている点です。答えは状況によって異なります。

Claude Code（インタラクティブ CLI ツール）：手動変更は不可。 Claude Code のキャッシュはサーバー側で制御されています。Max プランユーザーには 1 時間の TTL が付与され（サーバー側の機能フラグ tengu_prompt_cache_1h_config で制御）、Pro プランおよび API キー利用者は 5 分の TTL となります。環境変数 DISABLE_PROMPT_CACHING=1 を設定してキャッシュを完全に無効化することはできますが、TTL の段階を切り替えることはできません。

Claude API（直接呼び出し）：自由に選択可能。 API 経由で呼び出す場合、cache_control パラメータで TTL を指定できます。

// 5分キャッシュ（デフォルト）
{ "cache_control": { "type": "ephemeral" } }

// 1時間キャッシュ
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }

🎯 選択のアドバイス: 主に Claude Code CLI を使用している場合、TTL はサブスクリプションプランに依存します。API 経由で呼び出す場合（APIYI apiyi.com などを使用する場合）は、利用シーンに応じて 5 分または 1 時間の TTL を柔軟に選択し、より詳細なコスト制御を実現してください。

Claude プロンプトキャッシュのTTL課金ルールを徹底解説

5分 vs 1時間：課金比較

2つのTTLの決定的な違いは「書き込みコスト」にあります。読み込みコストはどちらも同じで、基本入力価格の0.1倍です。

各モデルのプロンプトキャッシュ価格

Anthropic公式APIにおける各モデルのキャッシュ課金表（2026年3月時点）です。

重要な発見：キャッシュ読み込みの割引率は驚異的です。 Claude Opus 4.6を例に挙げると：

• 通常入力 100万トークン = $5.00
• キャッシュ読み込み 100万トークン = $0.50（$4.50節約、90%オフ）
• これがClaude Code Proの月額$20が経済的に成り立つ理由です。キャッシュなしでOpusを100回対話すると$50〜$100かかるところ、キャッシュを使えば$10〜$19で済みます。

キャッシュ可能な最低トークン数

すべての内容がキャッシュできるわけではありません。各モデルには最低トークン数の制限があり、これに満たない場合はキャッシュがトリガーされません。

🎯 実用的なヒント: システムプロンプトが短い（2,048トークン未満など）場合、Claude Sonnet 4.6ではキャッシュがトリガーされません。システムプロンプトを充実させるか、ツール定義を統合して最低しきい値を超えるようにしましょう。APIYI (apiyi.com) を経由して呼び出す場合もキャッシュをサポートしており、よりお得なレートで利用可能です。

Anthropic API vs AWS Bedrock：キャッシュ課金比較

3大プラットフォームのキャッシュ対応状況

Claudeのプロンプトキャッシュは、Anthropic公式API、AWS Bedrock、Google Vertex AIの3つのプラットフォームでサポートされていますが、詳細には違いがあります。

各プラットフォームの重要な違い

Anthropic 公式API: キャッシュ機能が最も充実しており、全モデルで5分と1時間のTTLを選択可能です。2026年2月5日より、キャッシュの分離単位が組織レベルからワークスペースレベルに変更され、同一組織内でもワークスペースごとにキャッシュが独立するようになりました。

AWS Bedrock: 2026年1月に1時間TTLのサポートが発表されましたが、Claude Opus 4.5、Sonnet 4.5、Haiku 4.5など一部のモデルに限られます。最新のClaude Sonnet 4.6やOpus 4.6での1時間TTL対応については確認が必要です。Claude CodeからBedrockに接続する場合、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 の互換性設定にも注意してください。

Google Vertex AI: キャッシュ機能は公式APIとほぼ同じですが、Google Cloudプロジェクトを通じた認証と課金が必要です。

🎯 プラットフォーム選択のアドバイス: プラットフォームごとの違いや複雑な設定に悩まされたくない場合は、APIYI (apiyi.com) の統合インターフェース経由での呼び出しが最も簡単です。完全なキャッシュ機能をサポートしており、AWS IAMやGoogle Cloudの個別の認証設定は不要です。

Claude Code プロンプトキャッシュのクイックスタート

シンプルな例：1時間 TTL キャッシュの設定

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://vip.apiyi.com/v1"
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "あなたはプロの物理教師アシスタントです。高校物理の問題を解説する役割を担っています...(ここに長いシステムプロンプト)",
        "cache_control": {"type": "ephemeral", "ttl": "1h"}
    }],
    messages=[{"role": "user", "content": "ニュートンの第3法則を説明して"}]
)
print(f"キャッシュ読み取りトークン数: {response.usage.cache_read_input_tokens}")
print(f"キャッシュ書き込みトークン数: {response.usage.cache_creation_input_tokens}")

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://vip.apiyi.com/v1"
)

# TTLの混在：システムプロンプトは1時間（変更頻度が低い）、会話コンテキストは5分（頻繁に変更）
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": "あなたはプロのAI技術コンサルタントです...(長いシステムプロンプト、2000+ トークン)",
            "cache_control": {"type": "ephemeral", "ttl": "1h"}  # システムプロンプトは1時間
        },
        {
            "type": "text",
            "text": "以下はユーザーの過去の会話コンテキストです...(会話履歴)",
            "cache_control": {"type": "ephemeral"}  # 会話コンテキストは5分（デフォルト）
        }
    ],
    messages=[{"role": "user", "content": "ClaudeとGPTの推論能力を比較して"}]
)

# キャッシュの使用状況を確認
usage = response.usage
print(f"通常入力トークン数: {usage.input_tokens}")
print(f"キャッシュ読み取りトークン数: {usage.cache_read_input_tokens}")
print(f"キャッシュ書き込みトークン数: {usage.cache_creation_input_tokens}")

# 節約額を計算（Sonnet 4.6を例とする）
base_cost = (usage.input_tokens / 1_000_000) * 3
cache_cost = (usage.cache_read_input_tokens / 1_000_000) * 0.3
saved = (usage.cache_read_input_tokens / 1_000_000) * 2.7
print(f"今回の節約額: ${saved:.4f}")

重要な制約: 1つのリクエスト内で2種類の TTL を混在させる場合、1時間のキャッシュ内容を5分のキャッシュ内容よりも先に配置する必要があります。そうしないとエラーが返されます。

アドバイス: APIYI (apiyi.com) を通じて Claude API を呼び出す場合、cache_control パラメータ設定が完全にサポートされており、5分および1時間の TTL を自由に選択可能です。

5分 vs 1時間 TTL：どちらを選ぶべきか？

選択の判断基準

コスト計算式

キャッシュが割に合うかを判断する核心的な計算式です：

5分 TTL で元を取る条件: キャッシュ内容が5分以内に少なくとも1回読み取られる

• 書き込みコスト：1.25倍 → 追加で 0.25倍
• 読み取り節約：1回につき 0.9倍節約
• 1回の読み取りで元が取れる（0.9 > 0.25）

1時間 TTL で元を取る条件: キャッシュ内容が1時間以内に少なくとも2回読み取られる

• 書き込みコスト：2.0倍 → 追加で 1.0倍
• 読み取り節約：1回につき 0.9倍節約
• 2回の読み取りで元が取れる（0.9 × 2 = 1.8 > 1.0）

よくある質問

まとめ

Claude プロンプトキャッシュの TTL に関する重要なポイント：

1. 2 種類の TTL を選択可能: 5 分（書き込み 1.25 倍、1 回の読み取りで元が取れる）と 1 時間（書き込み 2 倍、2 回の読み取りで元が取れる）。読み取り料金はいずれも 0.1 倍です。
2. Claude Code CLI では TTL を変更不可: Max サブスクリプションは自動的に 1 時間、Pro/API キーは 5 分に固定されており、変更はできません。
3. Claude API では自由に選択可能: cache_control.ttl パラメータで設定でき、同一リクエスト内で異なる TTL を混在させることも可能です。
4. 高頻度の対話には 5 分を選択: ヒットするたびに自動更新されるため、書き込みコストを抑えられます。間欠的に使用する場合は、期限切れを防ぐために 1 時間を選択してください。

キャッシュヒット＝入力コストが 1/10 になる、これが Claude の最も重要な節約メカニズムです。APIYI (apiyi.com) の統合インターフェース経由での呼び出しを推奨します。キャッシュ設定を完全にサポートしており、1 つの API キーで異なる TTL 戦略の実際のコスト差をテストできます。

📚 参考資料

1. Anthropic 公式ドキュメント – プロンプトキャッシング: TTL 設定、課金ルール、cache_control 構文に関する信頼できる情報源

   • リンク: platform.claude.com/docs/en/build-with-claude/prompt-caching
   • 説明: 5分/1時間のTTLに関する詳細な課金計算式とコード例

2. Anthropic 公式ドキュメント – 料金: 各モデルの基本料金およびキャッシュ料金

   • リンク: platform.claude.com/docs/en/about-claude/pricing
   • 説明: Opus/Sonnet/Haiku 各モデルのキャッシュ書き込みおよび読み取り料金

3. AWS 公式ドキュメント – Bedrock プロンプトキャッシング: Bedrock プラットフォームにおけるキャッシュサポートの詳細

   • リンク: docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
   • 説明: Bedrock 上での各モデルのTTLサポート範囲と課金基準

4. Claude Code Camp – プロンプトキャッシングの仕組み: Claude Code におけるキャッシュ実装の深掘り解説

   • リンク: claudecodecamp.com/p/how-prompt-caching-actually-works-in-claude-code
   • 説明: Claude Code がどのようにキャッシュのブレークポイントを自動管理しているかを理解する

5. GitHub Issue #19436 – 多層キャッシュTTL機能のリクエスト: より柔軟なTTL設定に関するコミュニティでの議論

   • リンク: github.com/anthropics/claude-code/issues/19436
   • 説明: コンテンツの更新頻度に基づいた多層TTLスキームに関するコミュニティからの提案

著者: APIYI 技術チーム
技術交流: Claude のキャッシュ設定に関する経験談をぜひコメント欄でお聞かせください。その他のモデル呼び出しに関するチュートリアルは、APIYI ドキュメントセンター（docs.apiyi.com）をご覧ください。