メインコンテンツへスキップ
見出し画像

プロンプトキャッシュとは?Claudeの料金が安くなる仕組みを、Claude Codeで効いているか実測【5分と1時間・効かなくなる条件・2026年10月】

    「キャッシュを使うと、Claude の料金が安くなる」。API の解説でも、Claude Code の使い方の記事でも、この言葉を見かけます。けれど、次の3つが分からないまま「安くなるらしい」で終わっていないでしょうか。

    • 何が同じだと、安くなるのか

    • 実際に、いくら違うのか

    • Claude Code を使っているとき、本当に効いているかをどう確かめるのか

    この記事は、この3つに答えます。仕組みと料金は、公式ドキュメントを要約し、公式の単価で計算しました。効いているかどうかは、私が実際に取った数字で確かめました。

    私は Claude Code と Codex を毎日使って、教材づくり、note・Gumroad への出品、画像づくりを自動化している個人です。API の専門家ではありません。計算や読み違いがあるかもしれません。全文無料です。

    情報の扱いを書いておきます。公式の情報は、2026年10月17日に読んだものです。公式の文は「要約すると」と断って、私の言葉で書きます。実測は、同じ日に次の条件で取りました。Windows 11、Claude Code 2.1.301、claude -p(画面なし)、モデルは Haiku 5.5(claude-haiku-5-5)と Sonnet 5.5 です。費用は JSON に出る total_cost_usd の値で、API の定価で計算されたものです。サブスクリプションの枠で、いくら減ったかを表すものではありません。

    この記事で分かること

    • プロンプトキャッシュの仕組みと、効く条件

    • Haiku 5.5 の料金(書き込みと読み取り)と、損をする使い方

    • usage に出る3つの数字の読み方

    • 実測:同じ指示を2回送ったとき、1文字変えたとき、モデルを変えたとき

    • Claude Code でも効いているかの確かめ方

    • 効かなくなる条件と、公式の文書の食い違い

    先に結論

    • プロンプトキャッシュは、毎回同じ「前置き」を覚えておき、次に送るときに読み直して安くする仕組みです。Haiku 5.5 では、読み取りの単価は通常の入力の10分の1です

    • 覚えるときの書き込みは、通常より高くなります。5分の書き込みは1.25倍、1時間の書き込みは2倍です。そのため、1回しか使わない前置きは損になります

    • 1文字でも変わると、変わった区切りの中身は全部書き直しになります。私の実測では、指示の最初の1文字を変えても、最後の1文字を変えても、その指示の全体が書き込みに戻りました

    • Claude Code でも効いています。CLAUDE.md が0文字のとき、同じ条件で2回目に送った費用は、初回の $0.0019 から $0.0003 に下がりました

    • 効いたかは、usage の cache_read_input_tokens で確かめます。同じ前置きを2回送って読み取りが0のままなら、どこかが毎回変わっている可能性があります。ただし、同じ指示なのに読み取りが0になった回もありました。原因は分かりません

    画像

    仕組み:同じ前置きを、読み直す

    ここからは、公式ドキュメントの要約です。

    プロンプトキャッシュは、リクエストの先頭側にある「前置き(プレフィックス)」を覚えておき、同じ前置きで次のリクエストが来たら、覚えた分を読み直す仕組みです。覚える対象は、順番に tools(道具の定義)、system(システムプロンプト)、messages(会話)です。cache_control を付けたブロックまでが対象になります。

    押さえる点は、次の4つです。

    • 読み直せるのは、前置きが完全に一致するときだけです。画像とテキストを含めて、cache_control を付けたブロックまで1文字も違わないことが条件です

    • 既定の期間は5分です。覚えた部分が使われるたびに、追加の料金なしで期間が延びます。期間は、書き込みや読み取りのリクエストが始まった時点から数えます

    • 1時間の期間も選べます。その分の追加料金がかかります。指定は cache_control に ttl: "1h" を付けます。5分と1時間を混ぜるときは、1時間のものを前に置きます

    • Haiku 5.5 では、512トークン未満の前置きは覚えられません。cache_control を付けても、キャッシュされずに処理され、エラーも出ません。気づきにくいので、注意が要ります

    料金:書き込みは高く、読み取りは10分の1

    Haiku 5.5 の料金です。100万トークンあたり、プロンプトが10万トークン以下のときの単価を書きます。

    • 通常の入力:$0.10

    • 5分の書き込み:$0.125(通常の1.25倍)

    • 1時間の書き込み:$0.20(通常の2倍)

    • 読み取り:$0.01(通常の0.1倍)

    • 出力:$0.50

    プロンプトが10万トークンを超えると、単価は上がります。通常の入力は $0.50、5分の書き込みは $0.625、1時間の書き込みは $1、読み取りは $0.05 です。この10万トークンの数え方には、キャッシュの読み取りと書き込みの分も含まれます。前置きが大きいと、読み取りで安くなるつもりが、高い区分に入ることがあります。ちょうど10万トークンの扱いは、公式の表記が「以下」と「超」だけで、はっきり確かめられませんでした。

    Batch API(まとめて後で処理する方式)との併用は、公式に「できる」と書かれています。併用したときの単価は、この記事では確かめていません。

    ここからは私の計算です。通常の入力で1回送る分を1とすると、5分の書き込みは1.25、読み取りは0.1です。書き込みを1回し、読み直しを1回すると、1.25+0.1=1.35で、通常の2回分(2)より安くなります。1時間の書き込みは2なので、2回送っただけでは2.1となり、通常の2回分より高くなります。3回目まで送ると2.2で、通常の3回分(3)より安くなります。つまり、単価の上では、5分なら2回、1時間なら3回使うと元が取れます。ただし、読み直しが期限の中で起きることが前提です。

    usage の読み方:3つの数字を足すと入力の全部になる

    レスポンスの usage には、次の3つが出ます。

    • cache_creation_input_tokens:今回、キャッシュに書き込んだトークン数(書き込み)

    • cache_read_input_tokens:今回、キャッシュから読み取ったトークン数(読み取り)

    • input_tokens:キャッシュに読み書きされなかった分。最後のキャッシュの区切りより後ろの部分

    公式の要約では、この3つを足したものが、入力の全トークン数です。

    claude -p の JSON 出力にも、同じ項目が出ます。私はこの記事のために、CLAUDE.md の無い空のフォルダで、Haiku 5.5 に「OK と答えて」と頼み、usage を1回取りました。抜粋は次のとおりです。

    "usage": {
      "input_tokens": 2,
      "cache_creation_input_tokens": 8440,
      "cache_read_input_tokens": 16536,
      "output_tokens": 37,
      "cache_creation": {
        "ephemeral_1h_input_tokens": 8440,
        "ephemeral_5m_input_tokens": 0
      }
    }

    書き込みの内訳に、1時間(ephemeral_1h)と5分(ephemeral_5m)が分かれて出ます。この例では、書き込みは全部1時間の分でした。この1回は、後の実測とは別に取ったものです。

    実測:同じ指示は読み直され、1文字で書き直しになった

    実測の条件を、もう一度書きます。約5,000字の日本語の指示を --system-prompt に入れて、--tools "" で実行しました。依頼は「OK と答えて」だけです。毎回、前の実行の約4秒後に送りました。

    同じ指示をもう一度送る

    • 1回目:書き込み 6,240、読み取り 2,643、費用 $0.00129

    • 2回目(同じ指示):書き込み 0、読み取り 8,883、費用 $0.00014

    • 3回目(同じ指示):書き込み 0、読み取り 8,883、費用 $0.00013

    1回目の読み取りの 2,643 は、どの回でも同じ数でした。指示より前にある固定の部分だと読めます(指示の最初の1文字を変えても、この 2,643 は読み取りのままでした)。何の部分かは、確かめていません。2回目からは、6,240 と 2,643 を合わせた 8,883 が、すべて読み取りになりました。

    費用には、返事(出力)の分も入っています。入力の部分だけで計算すると、1回目はほぼ全部が書き込みの費用、2回目はほぼ全部が読み取りの費用です。同じ指示の2回目と3回目の費用は、$0.00009〜$0.00017 でした。1回目の約 $0.0013 に対して、おおむね8分の1から14分の1です。返事の長さで少し揺れます。

    1文字変えると、その指示は全部書き直し

    • 指示の最初の1文字を変えると:書き込み 6,240、読み取り 2,643。同じ変更の2回目は、読み取り 8,883 に戻りました

    • 指示の最後の1文字を変えると:書き込み 6,241、読み取り 2,643。2回目は、読み取り 8,884 に戻りました

    • 別の指示文でも、同じ傾向でした(書き込みは 6,266 または 6,267)

    最後の1文字を変えただけなのに、書き込みが指示の全部(約6,240)に戻ったことが、ポイントです。読み直しは、cache_control の区切りの単位で効くと読めます。区切りより前のどこかが変われば、その区切りまでの全体が書き直しになります。これは私の読み方です。公式の要約にある「区切りより前の内容が変わると、別のハッシュになる」という記述とも合います。

    モデルを変えると、キャッシュは別になる

    • Sonnet 5.5 で初めて送った:書き込み 6,243、費用 $0.02528

    • 同じ指示を Sonnet 5.5 でもう一度送った:読み取り 8,886、費用 $0.00093

    • 同じ文章を Haiku 5.5 で初めて送った:書き込み 6,241。読み取りは 2,643 だけ

    Haiku 5.5 は、Sonnet 5.5 が覚えた前置きを読み直しませんでした。モデルを変えると、キャッシュは別扱いになると読めます。

    途中で見た、読み取りが0の回

    ここは、うまくいかなかった例です。

    • Sonnet 5.5 の3回目(同じ指示):書き込み 5,246、読み取り 0、費用 $0.02103。直前の2回目では、読み取り 8,886 が効いていました

    • 本編の表とは別に、最初に取った試し(表には入れていません)でも、2回目が書き込み 5,212、読み取り 0 になった回がありました

    どちらも、原因は分かりません。キャッシュは、いつも効くとは限りません。だから、数字を毎回見ることが大切です。

    Claude Code でも効いている

    Claude Code を使うと、毎回、Claude Code 自身の指示や道具の定義が送られます。そこにもキャッシュが効いているかを確かめました。CLAUDE.md の長さを 0、3,000、12,000、48,000 字に変えて、それぞれ初回と2回目を取りました。依頼は「OK と答えて」です。

    • 0字:初回は書き込み 8,436、読み取り 16,536、費用 $0.0019。2回目は書き込み 0、読み取り 24,972、費用 $0.0003

    • 3,000字:初回は書き込み 11,372、費用 $0.0024。2回目は読み取り 27,908、費用 $0.0003

    • 12,000字:初回は書き込み 19,788、費用 $0.0041。2回目は読み取り 36,324、費用 $0.0004

    • 48,000字:初回は書き込み 53,311、費用 $0.0109。2回目は読み取り 69,847、費用 $0.0008

    CLAUDE.md が長いほど、初回の書き込みは増えます。ただし、2回目からは読み取りで済みます。

    初回の書き込みは、1時間の分として数えられていたと読めます。0字のときの初回の費用 $0.0019 は、書き込みを1時間の単価($0.20/100万トークン)で数えると合います。5分の単価($0.125)で数えると、約 $0.0012 にしかならず、合いません。前の節の1回目($0.00129)も、1時間の単価で合います。1時間の書き込みを指定して比べたわけではないので、これは費用の数字からの読みです。

    サブスクリプションの人にとって、キャッシュの読み取りが枠の中でどれだけ数えられるかは、この記事の材料では確かめられませんでした。ここに出した費用は API の定価による計算で、枠の減り方とは違います。

    効かなくなる条件

    公式の要約と、私の実測を分けて書きます。

    公式の要約では、次の変更でキャッシュが無効になります。

    • tools(道具の定義:名前・説明・引数)を変えると、キャッシュ全体が無効になります

    • thinking の設定(モードや budget_tokens)を変えると、messages の部分が無効になります

    • 会話の途中で、トップレベルの effort(推論の深さ)の値を変えると、会話の messages の部分が無効になります。公式の prompting のページにある記述です

    • 画像を足したり消したりすると、messages の部分が無効になります

    • cache_control より前の内容が1つでも変わると、次のリクエストは別のハッシュになり、キャッシュは使われません

    ここに、食い違いがあります。tool_choice(道具の選び方)の変更について、公式の文書のトラブルシューティングの節では「キャッシュを無効にする」と書かれ、無効化の表では「messages の部分だけに影響する」と書かれていました。どちらが正しいかは、確かめられませんでした。

    私の実測で、読み直しが止まったものは次のとおりです。

    • 指示の1文字の変更(最初でも最後でも):その指示の全体が書き直しになりました

    • モデルの変更:別のキャッシュ扱いになりました

    512トークン未満の前置きについては、公式の要約に書かれているだけです。短い前置きで試してはいません。

    実践:変わらない部分を先頭に、確かめる

    順番のルール(tools → system → messages)は、公式の要約です。そこから、次のように並べると読めます。以下は私の読み方と整理で、公式の助言の文ではありません。

    1. 変わらない部分を先頭に置く。道具の定義、長いシステムの指示、CLAUDE.md など、毎回同じものです

    2. 変わる部分は後ろに置く。今日の依頼、読ませるファイルの中身、データです

    3. 時刻・日付・ID・乱数を、前置きの先頭に入れない。先頭が毎回違うと、前置きは毎回書き直しになります。1文字の実測と同じ理由です

    4. usage で確かめる。同じ前置きを2回続けて送り、2回目の cache_read_input_tokens が、1回目に書き込まれた分くらいになっているかを見ます。0のままなら、どこかが毎回変わっているか、512トークン未満の可能性があります。ただし、効いていた指示が0になった例もあったので、1回の0で決めつけず、何回か見てください

    5. 料金は3つの数字を別々に計算する。書き込みは単価が高く、読み取りは安く、キャッシュされなかった分は通常の入力の単価です

    使うときの注意点

    • 効いていても、毎回効くとは限りません。実測では、効いていた指示の読み取りが0になった回がありました

    • 費用の数字は、API の定価による計算です。サブスクリプションの枠の減り方は、確かめられませんでした

    • 1回しか使わない前置きは、書き込みの分だけ割高になります。読み直せる見込みがあるものだけを、キャッシュの対象にしてください

    • 確かめていないこと:5分の期限が切れた後の動き、1時間の期間を指定して比べたこと、Batch API と併用したときの単価、日本語のトークン数(公式に記述がありません)、ちょうど10万トークンの扱い、512トークン未満の動き、tool_choice の食い違い

    まとめ

    • プロンプトキャッシュは、同じ前置きを覚えておき、読み直す仕組みです。読み取りは通常の入力の10分の1です

    • 書き込みは割高です。単価の上では、5分なら2回、1時間なら3回使うと元が取れます(私の計算)

    • 1文字でも変わると、変わった区切りの中身は全部書き直しになります

    • Claude Code でも効いています。CLAUDE.md が0文字のとき、2回目の費用は初回の6分の1ほどでした

    • 効いたかは usage で確かめます。読み取りが0のままなら、毎回何かが変わっている可能性があります

    次の一歩は、いま使っている長い前置き(CLAUDE.md や、システムの指示)を1つ選んで、同じ依頼を2回続けて送り、usage の cache_read_input_tokens を見ることです。2回目に読み取りが増えていれば、効いています。10分で、できます。


    次に読む

    このアカウントをフォローすると、Claude Code や Codex の新しい記事が届きます。ぜひフォローしてください。

    この先で分かること(今後の有料記事)

    • 長い前置きを、キャッシュが効く順に並べ替える実物の例(CLAUDE.md・スキル・システムの指示)

    • 1回の作業で使ったトークンと費用を、毎回記録する仕組み

    • 効かなかった回の記録と、取り直しの手順

    まさのAI実務ラボ|Codex・Claude Code では、有料記事が読み放題になります。テンプレートや指示文をまとめて使いたい方はご覧ください。

    あなたへのおすすめ