Prompt Caching の使用と課金

1折AI で Claude Prompt Caching を使う方法：有効化の手順、最小長、ヒットの確認方法、ヒット後の課金、および Claude Code のキャッシュ挙動。

Prompt Caching により、繰り返し送信される長いプレフィックス（システムプロンプト、ツール定義、長いドキュメント、会話履歴）は、初回のみ書き込みとして課金され、以降は読み取りとして課金されます。当サイトのキャッシュ読み取りとキャッシュ書き込みは公式定価で課金され、入出力割引は適用されません。各モデルのキャッシュ単価はモデルと価格を参照してください。

結論を先に

Claude Code はデフォルトでキャッシュが有効です。接続すれば即座に機能します。
自分でコードを書いて呼び出す場合は、キャッシュしたいコンテンツブロックに cache_control を追加し、ネイティブの /v1/messages を使用します。OpenAI 互換インターフェースは現時点でキャッシュされません。
ヒットしたかどうかは、レスポンスの usage.cache_read_input_tokens が 0 より大きいかどうかだけを見ます。
キャッシュはデフォルトで 5 分間有効で、ヒットするたびにタイマーがリセットされます。"ttl": "1h" を使用して 1 時間キャッシュを書き込むこともできますが、書き込み価格は高くなります。

有効化の方法

system、tools、または messages のコンテンツブロックに "cache_control": {"type": "ephemeral"} を追加すると、そのブロックとそれ以前の内容がキャッシュされます。1 リクエストあたり最大 4 個のキャッシュブレークポイントを設定できます。

1
curl https://1zheai.com/v1/messages \
2
  -H "x-api-key: $ONEZHE_API_KEY" \
3
  -H "anthropic-version: 2023-06-01" \
4
  -H "content-type: application/json" \
5
  -d '{
6
    "model": "claude-sonnet-5-5",
7
    "max_tokens": 256,
8
    "system": [
9
      {
10
        "type": "text",
11
        "text": "这里放一段很长、每次都一样的内容：项目说明、代码规范、参考文档……",
12
        "cache_control": {"type": "ephemeral"}
13
      }
14
    ],
15
    "messages": [{"role": "user", "content": "根据上面的规范，审查这段代码：..."}]
16
  }'

キャッシュされるプレフィックスが短すぎる場合、リクエストは通常どおり処理されますが、キャッシュされず、エラーも発生しません。最小長はモデルによって異なり、下の表を参照してください。

最小キャッシュ可能長

以下は Anthropic 公式ドキュメント（2026-10-14）より：

最小トークン数	モデル
512	Fable 5.1、Fable 5、Opus 5.5、Opus 5、Sonnet 5.5、Haiku 5.5
1,024	Opus 4.8、Sonnet 5、Sonnet 4.6、Sonnet 4.5
2,048	Opus 4.7
4,096	Opus 4.6、Opus 4.5、Haiku 4.5

ヒットの確認

同じリクエストを 2 回連続で送信し（間隔 5 分以内）、2 回の usage を比較します。以下は 2026-10-15 に claude-sonnet-5-5 で実測した結果で、system に約 1.8 万トークンの固定テキストを入れた場合です：

第一次：写入缓存
第二次：命中缓存

{
  "input_tokens": 23,
  "cache_creation_input_tokens": 17920,
  "cache_read_input_tokens": 0,
  "cache_creation": {"ephemeral_5m_input_tokens": 17920, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}

{
  "input_tokens": 23,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 17920,
  "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}

2 回目の cache_read_input_tokens が 0 より大きい場合、キャッシュが読み取られていることを意味します。各リクエストのキャッシュ書き込み・読み取りトークンは呼び出しログのトークン列にも表示され、読み取りは「キャッシュ↓」、書き込みは「↑」と記録されます。

課金方法

種類	公式単価	1折AI 単価
キャッシュ書き込み（5 分）	入力価格 × 1.25	公式定価、割引なし
キャッシュ書き込み（1 時間）	入力価格 × 2	公式定価、割引なし
キャッシュ読み取り	入力価格 × 0.1（Opus 5.5、Sonnet 5.5 は 0.05、Fable 5.1 は 0.025）	公式定価、割引なし

5 分キャッシュ書き込みの公式価格は通常、公式入力価格の 1.25 倍です。当サイトは入力に割引があり、キャッシュは割引なしのため、公式倍数だけで 1 回のキャッシュ読み取りで元が取れると判断することはできません。モデル割引、書き込みコスト、繰り返し読み取り回数を組み合わせて比較する必要があります。完全な計算例は価格と課金を参照してください。

1 時間キャッシュ

cache_control に "ttl": "1h" を追加すると、キャッシュが 1 時間保持されます。間隔が 5 分を超えるが、繰り返し使用されるプレフィックスに適しています：

1
"cache_control": {"type": "ephemeral", "ttl": "1h"}

書き込みは公式入力価格の 2 倍で課金され、割引後の入力価格は使用されません。読み取りは 5 分キャッシュと同じです。レスポンス内の書き込みトークンは cache_creation.ephemeral_1h_input_tokens に表示されます。1 時間キャッシュを選択するかどうかは、2 つのリクエストの間隔、書き込みコスト、繰り返し読み取り回数を考慮して判断する必要があります。

Claude Code のキャッシュ

Claude Code はシステムプロンプト、ツール定義、会話履歴に自動的にキャッシュブレークポイントを設定します。公式の説明はこちら。ヒット率を高めるには：

1 つのセッション内で連続して作業し、途中で長時間停止しないでください。キャッシュは 5 分間使用されないと期限切れになります。
同じセッション内の後続リクエストはキャッシュを読み取ります。2026-10-15 の実測では、2 ラウンドの Claude Code タスクで、2 ラウンド目のキャッシュ読み取りは 31,440 トークン、書き込みは 115 トークンでした。新しいセッションを開始すると、最初のラウンドはプレフィックス全体を再書き込みする必要がある場合があります（実測で約 3 万トークン）。このリクエストは後続のものより高額になります。
セッションの途中で CLAUDE.md の変更、MCP サーバーの切り替え、モデルの変更を減らしてください。これらはすべてプレフィックスの変化を招きます。
DISABLE_PROMPT_CACHING=1 を設定しないでください。この環境変数はすべてのモデルのキャッシュを無効にします。

OpenAI 互換インターフェースでキャッシュは使えますか

現時点では使えません。2026-10-15 の実測では、/v1/chat/completions の system メッセージに約 3,100 トークンの固定テキストを入れて 2 回連続で送信し、コンテンツブロックに cache_control を追加するかどうかに関わらず、2 回の usage はいずれも次のとおりでした：

1
{"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171}

prompt_tokens_details.cached_tokens が存在せず、呼び出しログのキャッシュ読み取り・書き込みもいずれも 0 で、全段が入力価格で課金されます。キャッシュが必要な場合は /v1/messages（Anthropic SDK または Claude Code）を使用してください。

よくある質問

なぜ常に cache_creation のみで、cache_read が発生しないのですか？

キャッシュは書き込まれたが、次回読み取られなかった。順に確認してください：2 つのリクエストの間隔が 5 分を超えているか；ブレークポイント前の内容が一字一句同じか（タイムスタンプやランダム ID を system に入れると毎回異なります）；モデルを変更していないか；プレフィックスが上記の最小長に達しているか。

キャッシュヒット率は確認できますか？

各リクエストのキャッシュ読み取り・キャッシュ書き込みトークンは呼び出しログにあり、自分で計算できます：キャッシュ読み取り ÷（入力 + キャッシュ書き込み + キャッシュ読み取り）。