Prompt Cachingコストガイド：キャッシュヒット、プレフィックス、および実際のAPI利用料金

プロンプトキャッシングのコストは、見出しの割引率ではなく、2回目のリクエストが1回目と完全に一致するかどうかによって決まります。claude-sonnet-5における20,000トークンのシステムプロンプトの試算では、1,000回のリクエストで、キャッシュなしの場合は約18.18ドル、2回目以降すべてがキャッシュヒットする場合は約2.00ドルとなります。もしリクエストごとにプレフィックスが変更される場合、同じプロンプトでもキャッシュなしのベースラインよりコストが高くなります。本ガイドでは、2026年10月3日に観測されたTokenLabの価格を使用して、その損益分岐点がどこにあるかを示し、ドキュメントで確認できなかった点についても明記します。

重要なポイント

• 調査した5つのモデルにおいて、キャッシュ読み取りコストは通常の入力価格の2%〜10%です。5つのうち2つは、キャッシュ書き込み価格が記載されていません。
• 書き込み価格が存在する場合、それは入力価格と同等（deepseek-v4.1-flash）か、入力価格の1.25倍（claude-sonnet-5、claude-sonnet-5-5）のいずれかです。
• 計算上、書き込み1回につき1回のキャッシュヒットがあれば、1.25倍の書き込みプレミアムを回収できます。ただし、これはキャッシュエントリが有効であることが前提であり、キャッシュの有効期間については、今回確認した資料には記載がありませんでした。
• キャッシングは請求の入力側のみを削減します。出力トークンの価格はこれまで通りです。
• 今回確認したTokenLabのAPIドキュメントには、usage内にキャッシュトークンを示すフィールドの記載がありません。自身のテストで生のオブジェクトをログに記録し、Usageと照合してください。

モデル別のプロンプトキャッシングコスト：読み取り、書き込み、および入力価格

以下は、2026年10月3日に各モデルのライブモデルAPIから読み取ったデータです。5つすべてが機能としてprompt-cacheをリストしており、価格は2026年10月2日 16:53:30.068Zに最終更新されたものです。価格は100万トークンあたりの米ドルです。

モデル	入力	キャッシュ読み取り	キャッシュ書き込み	入力に対する読み取りの割合	書き込み vs 入力
claude-sonnet-5	0.90	0.09	1.125	10%	1.25x
claude-sonnet-5-5	0.60	0.06	0.75	10%	1.25x
gpt-5.5	1.50	0.15	記載なし	10%	記載なし
deepseek-v4.1-flash (オフピーク)	0.15	0.003	0.15	2%	1.0x
deepseek-v4.1-flash (ピーク)	0.30	0.006	0.30	2%	1.0x
gemini-3.8-flash	0.375	0.0375	記載なし	10%	記載なし

パーセンテージの2列は、リストされた価格を独自に計算したものです。

ソース（すべて2026年10月3日観測）:

• claude-sonnet-5 (モデルページ: /models/claude-5/claude-sonnet-5)
• claude-sonnet-5-5 (モデルページ: /models/claude-5/claude-sonnet-5-5)
• gpt-5.5 (モデルページ: /models/gpt-5-5/gpt-5.5)
• deepseek-v4.1-flash (モデルページ: /models/deepseek-v4/deepseek-v4.1-flash)
• gemini-3.8-flash (モデルページ: /models/gemini-3/gemini-3.8-flash)

この表を読む際には、3つの詳細が重要です。

第一に、gpt-5.5とgemini-3.8-flashはキャッシュ読み取り価格をリストしていますが、キャッシュ書き込み価格は記載されていません。このデータから、初回プレフィックスがどのように請求されるかを断定することはできません。無料であるとも、入力レートで請求されるとも記載されていません。いずれかの前提で予測を立てる前に、最初のリクエスト後のUsageを確認してください。

第二に、deepseek-v4.1-flashを読み取った際、2つの価格エントリが見つかりました。off-peakエントリ（セレクタoffPeak: true）とpeakエントリ（offPeak: false）は、すべての行で2倍の差があります。トークンあたりのキャッシュ節約率は同じ割合ですが、ピーク時には絶対的なドル額が2倍になります。

第三に、これらはTokenLabの公開価格です。請求ガイド（2026年10月3日観測）によると、完了したリクエストは、それを生成した配信オプションに対して1回課金されます。Officialはモデル作成者の公開価格に従うため、作成者の価格表と比較する前に、どのオプションがリクエストを処理したかを確認してください。

「Get a Model」リファレンスには、機能の中にprompt-cacheを持つgpt-5.6-terraが示されています。そのサンプルレスポンスには価格が含まれていないため、このモデルは表から除外しました。カタログ内の他のモデルは確認していません。

プロンプトキャッシングコストの具体例：1つの長いシステムプロンプト

以下は、独自の数値を当てはめられるようにすべての入力を明示したシナリオです。これらは測定値ではなく、私たちの仮定です。

• 20,000トークンのシステムプロンプトとツールブロック（すべてのリクエストで同一）。
• リクエストごとに変更される200トークンのユーザーメッセージ。
• 1,000回のリクエスト。キャッシュは実行全体を通じて有効であるため、書き込み1回と読み取り999回が発生。
• 出力トークンは、キャッシングの有無にかかわらずコストが同じであるため無視。

claude-sonnet-5（入力0.90、読み取り0.09、書き込み1.125 / 100万トークン）の場合：

• キャッシュなし：1,000 × 20,200 = 20,200,000トークン × $0.90/1M = $18.18
• キャッシュ書き込み：20,000 × $1.125/1M = $0.0225
• キャッシュ読み取り：999 × 20,000 = 19,980,000 × $0.09/1M = $1.7982
• キャッシュなしのサフィックス：1,000 × 200 = 200,000 × $0.90/1M = $0.18
• キャッシュあり：0.0225 + 1.7982 + 0.18 = 約$2.00（キャッシュなしの数値より約89%削減）

次に失敗ケースです。プレフィックスがリクエストごとにわずかに変更されるため、毎回書き込みが発生し、読み取りが一度も行われない場合です。その場合、プレフィックスに対して1,000 × 20,000 × $1.125/1M = $22.50がかかり、さらにサフィックスに対して同じ$0.18がかかります。合計は約$22.68となり、キャッシュなしの$18.18を$4.50（25%）上回ります。

損益分岐点も同じ価格から導かれます。プレフィックス100万トークンあたり、書き込みは通常の入力より$0.225高く、読み取り1回につき$0.81節約できます。1回のヒットで書き込みコストを十分に回収できます（0.225 ÷ 0.81 ≈ 書き込み1回あたり0.28回の読み取り）。

他のモデルでの同シナリオ：

モデル	キャッシュなし	キャッシュあり（推定）	初回リクエストの前提
claude-sonnet-5	$18.18	$2.00	リストされた書き込み価格
claude-sonnet-5-5	$12.12	$1.33	リストされた書き込み価格
deepseek-v4.1-flash オフピーク	$3.03	$0.09	リストされた書き込み価格
deepseek-v4.1-flash ピーク	$6.06	$0.19	リストされた書き込み価格
gpt-5.5	$30.30	$3.33	書き込み価格なし；20,000トークンを入力レートで計算
gemini-3.8-flash	$7.58	$0.83	書き込み価格なし；20,000トークンを入力レートで計算

gpt-5.5の場合、計算は20,000 × $1.50/1M = $0.03、プラス19,980,000 × $0.15/1M = $2.997、プラス200,000 × $1.50/1M = $0.30となります。フラグを立てた2行は証拠に裏付けられていない仮定に基づいているため、概算として扱ってください。

プロンプトをキャッシュ可能にする：ドキュメントで確認されていること

証拠は以下の短い要件リストを裏付けています。

1. prompt-cacheをリストしているモデルを選ぶ。 Get a Model（2026年10月3日観測）からのcapabilities配列がチェック対象です。それがないモデルでは、割引を期待する根拠はありません。
2. 共有コンテンツを安定した位置に保つ。 Messagesエンドポイントでは、systemはトップレベルのフィールドであり、文字列またはコンテンツブロックの配列を受け取ります。Chat Completionsでは、システム命令はmessagesに入ります。いずれにせよ、繰り返される素材は最初に来るべきです。
3. 境界まで同一のバイトを送信する。 これは本記事の初版からの「正確なプレフィックス」ルールであり、表の価格設定が機能する方法と一致します。読み取り価格は、一致したプロンプトの部分にのみ適用されます。

Request A: [ System Prompt + Tool Definitions ] [ User Query A ]
           ▲───────────── CACHED PREFIX ────────▲ ▲── SUFFIX ──▲

Request B: [ System Prompt + Tool Definitions ] [ User Query B ]
           ▲─────────── CACHE HIT (READ) ───────▲ ▲── SUFFIX ──▲

再利用を最も頻繁に妨げる3つの習慣：

• システムプロンプトの先頭にあるタイムスタンプ、ユーザーID、またはセッションID。
• リクエスト間で順序が入れ替わったツール定義またはJSONキー。
• 共有テキスト内のインデントや改行の変更。

Create Messageリファレンスに記載されているリクエストの形式：

{
  "model": "claude-sonnet-5",
  "max_tokens": 512,
  "system": [
    {
      "type": "text",
      "text": "You are a support assistant. The following policy governs all responses: [Full Policy Text]"
    }
  ],
  "messages": [
    { "role": "user", "content": "What is the return period for damaged items?" }
  ]
}

本記事の以前のドラフトでは、そのシステムブロックにtypeがephemeralのcache_controlマーカーを置いていました。2026年10月3日に確認したCreate Messageリファレンスにはそのフィールドがリストされていないため、サンプルから削除しました。最小プレフィックス長やキャッシュの有効期間についても同様です。TokenLabのドキュメントにはいずれの数値も見当たりませんでした。明示的なマーカーやTTLに依存する前に、選択したモデルをテストし、2つの同一呼び出し間でキャッシュされたトークン数を比較してください。

キャッシュ価格の読み取りとキャッシュトークンの確認

上記の表をコードにコピーしないでください。請求ガイドには、アプリケーションが必要とする時に現在の価格を読み取るよう記載されています。文書化されている2つのルート：

curl "https://api.tokenlab.sh/v1/models/claude-sonnet-5"
curl "https://api.tokenlab.sh/v1/pricing?provider=openai&tag=chat"

前者は1つのモデルの機能、制限、および価格を返します。不明なモデルIDは404 model_not_foundを返します。後者はAPIキーを必要としないパブリックエンドポイントです。その文書化されたサンプルレスポンスにはgpt-4oのinput_per_1m_tokensとoutput_per_1m_tokensが表示されていますが、キャッシュフィールドはありません。そのサンプルのupdated_atは2026年4月20日であり、これはサンプルデータであり現在の価格ではありません。キャッシュ価格については、モデルごとのエンドポイントを使用しました。

キャッシングが機能したことを確認するために、文書化されたusageオブジェクトは期待よりも薄い内容です。Chat Completionsはprompt_tokens、completion_tokens、およびtotal_tokensをリストします。Messagesはinput_tokensとoutput_tokensをリストします。どちらのリファレンスもキャッシュトークンフィールドを名指ししていません。コーディングエージェントのコストガイド（2026年10月3日観測）では、レスポンスまたはUsageでキャッシュトークンの使用量を確認し、タスクごとの入力、出力、およびキャッシュトークンを記録するよう述べています。

私たちが実行するテスト：

1. 最後のユーザーメッセージのみを変更して、同じ長いプレフィックスのリクエストを数秒間隔で2回送信する。
2. 両方のレスポンスから完全な生のusageオブジェクトと、存在する場合はbilling_transaction_idをログに記録する。
3. 2回目のリクエストの料金をUsageで上記の計算と比較する。キャッシュヒットは、キャッシュなしの数値ではなく、「キャッシュあり」の数値に近くなるはずです。
4. 最初の行を意図的に変更して、ミスによるコストを確認する。

ストリーミングChat Completionsの場合は、stream_options.include_usage: trueを設定してストリームチャンク内で使用量を受け取ります。ストリームでは請求ヘッダーが欠落している可能性があるため、最終的な料金にはUsageを使用してください。トラブルシューティングガイドでは、model、startDate、およびendDateでフィルタリングしてサーバー側で照合を行うGET /v1/management/api-keys/{keyId}/usageについても説明しています。

プロンプトキャッシングのコストが割に合わない場合

キャッシングはリピートトラフィックへの賭けです。以下のような状況では損失となります：

• プレフィックスが繰り返されない。 一回限りの20,000トークンのドキュメントは、書き込みプレミアムを支払うだけで、何も還元されません。
• リクエストの到着が遅すぎる。 一致するリクエスト間のギャップがキャッシュの有効期間を超えると、すべての呼び出しが新規書き込みとなります。その有効期間は証拠の中に見当たらなかったため、モデルのページに記載されている内容に対して自身のギャップを測定してください。
• 境界の前にプレフィックスが変更される。 上記の失敗ケースにおける25%の超過支出は、まさにこのパターンによるものです。
• プレフィックスが小さい。 節約額はプレフィックスのトークン数に比例します。数百トークンでは呼び出しごとにわずかなセントしか節約できず、キャッシュ可能な最小サイズは証拠に含まれていません。
• 出力が請求の大半を占める。 キャッシングは入力のみを削減します。回答が長い場合、キャッシュによる削減分は合計のわずかな割合に過ぎません。
• モデルがキャッシュ価格をリストしていない。 請求ガイドによると、TokenLabの価格列のダッシュはVerifiedオファーがないことを意味し、無料であることを意味しません。割引を期待する前に、モデルの価格詳細を確認してください。

ワークロードパターン	キャッシングの有効性	理由
マルチターンのツールループ	高	命令とツール定義がステップ間で固定されているため。
多くのユーザーが1つの大きなドキュメントをクエリする	高	トラフィックのバーストが書き込みコストを迅速に償却するため。
頻度の低いバックグラウンドジョブ	低	キャッシュの有効期間を超えるギャップが繰り返しの書き込みを強制するため。
システムプロンプトが変動する	低	境界より前の変更が一致を破壊するため。

プロンプトキャッシングは、請求ガイドにある「キャッシングの実装（Implement caching）」のヒントとは異なります。これは、繰り返される同一リクエストに対するレスポンスを自身のアプリに保存することを意味します。それはモデル呼び出しを完全に回避しますが、リクエスト全体が繰り返される場合にのみ役立ちます。長いエージェントセッションについては、コーディングエージェントのコストガイドが、キャッシングと並んでコンテキストサイズ、出力制限、モデル選択をカバーしています。

FAQ

キャッシュヒットは常にリクエストを安くしますか？

一致したプレフィックスに対してのみであり、モデルがキャッシュ読み取り価格をリストしている場合に限ります。調査したモデルでは、読み取りコストは入力の2%〜10%です。サフィックスとすべての出力トークンは通常のレートで請求されます。書き込みプレミアムがあるモデルでのミスは、キャッシュなしの呼び出しよりもコストがかかる可能性があります。

キャッシュ書き込み価格が記載されていないのは無料と同じですか？

いいえ。gpt-5.5とgemini-3.8-flashについては、2026年10月3日時点でライブAPIはキャッシュ読み取り価格をリストしていましたが、書き込み価格はありませんでした。ゼロや入力レートを想定するのではなく、最初のリクエストを1回実行し、Usageで料金を確認してください。

キャッシュ可能なプロンプトのユーザーごとの値はどこに置くべきですか？

共有コンテンツの後、ユーザーメッセージまたは後半のmessagesエントリに配置してください。共有ブロックの前に変動するものがあるとプレフィックスが変更され、新しい書き込みが強制されます。これにはタイムスタンプ、セッションID、順序が入れ替わったツールリストが含まれます。

繰り返されたリクエストでキャッシュトークンが表示されないのはなぜですか？

私たちは以下の4点を順番に確認します。モデルはprompt-cacheをリストしていますか？プレフィックスは呼び出し間でバイト単位で同一ですか？2回目の呼び出しはキャッシュの有効期間内に到着しましたか？キャッシュされたカウントは、ログから除外されるフィールドにありますか？私たちが読んだドキュメントにはそのフィールド名がないため、usageオブジェクト全体をログに記録してください。

TokenLabモデルページでモデルを決定する前に、ライブキャッシュ価格を比較してください。