Claude API のプロンプトキャッシュで API 料金が月3万円浮いた実装記録

業務システムに Claude API を組み込んでから、月の API 料金が10万円を超えるようになっていました。プロンプトキャッシュを実装したら、これが月7万円台に。約3万円、率にして30%の削減です。実装手順と効果検証を公開します。

当社のClaude API 利用状況

SaaS のメインAI機能として Claude Sonnet を呼び出しています。代表的なユースケース：

• 顧客の業務知識を含む長めの system prompt（約8,000トークン）
• 1日あたり 約3,000リクエスト
• 毎リクエストの user プロンプトは数百トークン

つまり「同じ system prompt を何千回も投げ続けている」状態でした。

プロンプトキャッシュとは

Claude API の機能で、長い system prompt や reference 文書を「キャッシュ」しておくことで、2回目以降の呼び出し料金が大幅に下がる仕組み。

料金体系：

• 通常の input：$3 / 1M tokens
• キャッシュ書込（初回）：$3.75 / 1M tokens（25%増し）
• キャッシュ読出（2回目以降）：$0.30 / 1M tokens（90%引き）

つまり初回だけ少し高く、2回目以降が10分の1になります。

導入の判断基準

プロンプトキャッシュが効くのは以下の条件：

1. 同じ system prompt や添付資料を繰り返し使う
2. 1024 トークン以上のキャッシュ可能内容（最低単位）
3. キャッシュ TTL（5分）内に再呼び出しがある

当社の場合は1日3,000リクエスト ≒ 1秒1リクエスト弱なので、TTL 内に余裕で再ヒットする条件でした。

実装：たった1行の変更

Python SDK の場合、キャッシュ対象に cache_control パラメータを追加するだけ：

response = client.messages.create(
    model="claude-sonnet-4-7",
    system=[
        {
            "type": "text",
            "text": LONG_SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"}  # ←これを追加
        }
    ],
    messages=[...]
)

これだけです。TypeScript SDK でも同様の形式。

導入1週間後の効果検証

1週間で14,000円の削減。月換算で6万円相当。当初試算の3万円を超える効果になりました。

注意点1：キャッシュTTL（5分）

キャッシュは5分間有効。5分以上アクセスが空くとキャッシュ消失、次回は再びキャッシュ書込料金（25%増し）が発生。

当社のように高頻度アクセスがある場合は問題ないが、ピーク時以外はキャッシュ削れて再書込になる傾向。それでも全体ではコスト削減になっていました。

注意点2：キャッシュは部分一致しない

system prompt 全体が完全一致している必要があります。動的に変える部分（ユーザー名等）が含まれていると、毎回キャッシュ無効。

対策：動的部分を user message 側に分離し、system prompt は固定化する設計に変更。

注意点3：キャッシュサイズの最低単位

1024 トークン以上ないとキャッシュ対象になりません。短い system prompt では効果なし。

当社では8,000トークンあったので問題なし。短い指示しか出していないなら、参考資料等を system prompt に追加して長くするのも一手。

応用：複数プロンプトのキャッシュ

system prompt 内で複数の cache_control ブロックを使うことで、文脈の異なるキャッシュを管理可能。

system=[
    {"type": "text", "text": COMPANY_KNOWLEDGE, "cache_control": {"type": "ephemeral"}},
    {"type": "text", "text": USER_PROFILE, "cache_control": {"type": "ephemeral"}},
]

これで「会社知識ブロック」「ユーザー個別ブロック」を別々にキャッシュ管理できます。

使うべきケース・使わないべきケース

使うべき

• 長い system prompt（1024トークン以上）
• 同じプロンプトを高頻度（5分以内）で呼び出し
• RAG で大量の参考文書を付与
• 少ない種類の system prompt × 大量リクエスト

使わないべき

• 毎回完全に違う system prompt
• 呼び出し頻度が低い（1時間に1回以下）
• system prompt が短い（<1024 tokens）

まとめ：実装コスト1分・月3万円削減

プロンプトキャッシュは「設定するかしないか」だけで30〜70%の Claude API 料金削減につながります。コードの変更は1行、効果は即座、リスクほぼゼロ。

すでに月数万円以上の API 料金がかかっているプロダクトなら、今すぐ実装する価値があります。当社のように、想定以上の効果が出る可能性が高いです。