Prompt Caching 成本指南：Cache Hits、Prefixes 與實際 API 支出

Prompt Caching（提示詞快取）的成本取決於您的第二次請求是否與第一次完全相同，而非取決於標題上的折扣。根據我們對 claude-sonnet-5 上 20,000 個 token 的系統提示詞進行的估算，1,000 次請求在未快取的情況下成本約為 $18.18，而如果第一次之後的每次請求都能命中快取，成本則約為 $2.00。如果每次呼叫的前綴都發生變化，則該提示詞的成本會高於未快取的基準。本指南使用 2026-10-03 觀察到的 TokenLab 價格來標示該界線，並標註了我們在文件中無法確認的資訊。

重點摘要

• 在我們檢查的五款模型中，快取讀取（Cache read）的成本為正常輸入價格的 2% 到 10%。其中兩款模型未列出快取寫入（Cache write）價格。
• 在有寫入價格的情況下，其價格要麼等於輸入價格（deepseek-v4.1-flash），要麼是輸入價格的 1.25 倍（claude-sonnet-5、claude-sonnet-5-5）。
• 根據我們的計算，每次寫入後只要有一次快取命中，即可抵銷 1.25 倍的寫入溢價。這假設快取項目仍然有效，且我們閱讀的證據中並未記載快取的存活時間。
• 快取僅能降低帳單中的輸入部分。輸出 token 的定價則與以往相同。
• 我們閱讀的 TokenLab API 文件中並未在 usage 欄位中列出 cached-token 欄位。請記錄您自己測試中的原始物件，並將其與 Usage 進行核對。

各模型的 Prompt Caching 成本：讀取、寫入與輸入價格

我們於 2026-10-03 讀取了下方每個模型的即時模型 API。所有五款模型都在其功能中列出了 prompt-cache，且定價最後更新於 2026-10-02T16:53:30.068Z。價格為每 100 萬個 token 的美元金額。

模型	輸入	快取讀取	快取寫入	讀取佔輸入比例	寫入 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%	未列出

兩個百分比欄位是我們對所列價格進行的除法計算。

資料來源，均於 2026-10-03 觀察：

• 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)

閱讀此表格時有三個細節很重要。

首先，gpt-5.5 和 gemini-3.8-flash 列出了快取讀取價格，但沒有列出快取寫入價格。我們無法從這些數據中得知這兩款模型在首次前綴請求時是如何計費的。證據並未說明它是免費的，也沒有說明它是按輸入費率計費的。在基於任何假設進行預測之前，請先在第一次請求後檢查 Usage。

其次，當我們讀取 deepseek-v4.1-flash 時，我們發現了兩個價格條目。off-peak 條目（選擇器 offPeak: true）和 peak 條目（offPeak: false）在每一行上都有兩倍的差異。您每個 token 的快取節省百分比相同，但尖峰時段的絕對金額會翻倍。

第三，這些是 TokenLab 的公開價格。計費指南（2026-10-03 觀察）指出，已完成的請求會針對產生該請求的交付選項收費一次。Official 遵循模型製造商的公開價格，因此在與製造商的價格表進行比較之前，請確認是哪個選項服務了您的請求。

Get a Model 參考資料顯示 gpt-5.6-terra 的功能中包含 prompt-cache。其範例回應中沒有價格，因此我們將該模型排除在表格之外。我們沒有檢查目錄中的其他模型。

Prompt Caching 成本範例：一個長系統提示詞

以下是場景設定，列出了所有輸入數據，以便您可以代入自己的數字。這些是我們的假設，而非測量結果。

• 一個 20,000 個 token 的系統提示詞和工具區塊，每次請求都相同。
• 一個 200 個 token 的使用者訊息，每次請求都會變更。
• 1,000 次請求，快取在整個執行期間保持有效，因此有一次寫入和 999 次讀取。
• 忽略輸出 token，因為無論是否使用快取，它們的成本都相同。

claude-sonnet-5，每 100 萬個 token 輸入 0.90、讀取 0.09、寫入 1.125：

• 不使用快取：1,000 × 20,200 = 20,200,000 tokens × $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 萬個前綴 token，寫入成本比普通輸入高出 $0.225，而每次讀取可節省 $0.81。一次命中即可抵銷寫入成本並有餘裕（0.225 ÷ 0.81 ≈ 每次寫入需 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 個 token
gemini-3.8-flash	$7.58	$0.83	未列出寫入價格；我們按輸入費率計算 20,000 個 token

對於 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。這兩行標記的數據基於證據不支持的假設，因此請將其視為粗略估計。

使提示詞可快取：文件確認的內容

證據支持一份簡短的需求清單。

1. 選擇一個列出 prompt-cache 的模型。 來自 Get a Model（2026-10-03 觀察）的 capabilities 陣列是檢查標準。沒有此功能的模型無法讓您預期獲得折扣。
2. 將共享內容保持在穩定位置。 在 Messages 端點上，system 是一個頂層欄位，接受字串或內容區塊陣列。在 Chat Completions 上，系統指令位於 messages 中。無論哪種方式，重複的材料都應該放在最前面。
3. 在邊界之前發送相同的位元組。 這是本文原始版本中的精確前綴規則，它與表格價格的運作方式相符。讀取價格僅適用於提示詞中匹配的部分。

請求 A: [ 系統提示詞 + 工具定義 ] [ 使用者查詢 A ]
           ▲───────────── 快取前綴 ────────▲ ▲── 後綴 ──▲

請求 B: [ 系統提示詞 + 工具定義 ] [ 使用者查詢 B ]
           ▲─────────── 快取命中 (讀取) ───────▲ ▲── 後綴 ──▲

三種習慣最常破壞重複使用：

• 系統提示詞頂部的時間戳記、使用者 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?" }
  ]
}

本文的早期草稿在該系統區塊上放置了一個類型為 ephemeral 的 cache_control 標記。我們在 2026-10-03 閱讀的 Create Message 參考資料中並未列出該欄位，因此我們將其從範例中刪除。最小前綴長度和快取存活時間也是如此。我們在閱讀的 TokenLab 文件中沒有找到任何相關數據。在依賴明確標記或 TTL 之前，請測試您選擇的模型並比較兩次相同呼叫中的快取 token 數量。

讀取快取價格與確認快取 token

不要將上述表格複製到程式碼中。 計費指南建議在您的應用程式需要時讀取當前價格。兩種已記錄的路徑：

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

第一個路徑返回單個模型的功能、限制和定價。未知的模型 ID 會返回 404 model_not_found。第二個是一個不需要 API 金鑰的公開端點。其記錄的範例回應顯示了 gpt-4o 的 input_per_1m_tokens 和 output_per_1m_tokens，但沒有快取欄位。該範例中的 updated_at 是 2026-04-20，這是範例數據，而非當前定價。對於快取價格，我們使用了按模型劃分的端點。

為了確認快取是否有效，記錄的 usage 物件比您希望的還要精簡。Chat Completions 列出了 prompt_tokens、completion_tokens 和 total_tokens。Messages 列出了 input_tokens 和 output_tokens。兩個參考資料都沒有命名快取 token 欄位。程式設計代理成本指南（2026-10-03 觀察）建議在回應或 Usage 中確認快取 token 的使用量，並記錄每個任務的輸入、輸出和快取 token。

我們建議執行的測試：

1. 發送兩次相同的長前綴請求，間隔幾秒，僅更改最後的使用者訊息。
2. 記錄兩次回應中的完整原始 usage 物件，以及 billing_transaction_id（如果存在）。
3. 將第二次請求在 Usage 中的費用與上述計算進行比較。快取命中應落在「使用快取」的數字附近，而不是未快取的數字。
4. 刻意更改第一行以查看未命中的成本，重複上述步驟。

對於串流 Chat Completions，請設定 stream_options.include_usage: true 以在串流區塊中接收使用量。串流上可能沒有計費標頭，因此請使用 Usage 來獲取最終費用。疑難排解指南也描述了 GET /v1/management/api-keys/{keyId}/usage，它按 model、startDate 和 endDate 進行篩選，以便進行伺服器端核對。

何時 Prompt Caching 不划算

快取是對重複流量的賭注。在以下情況下它會失敗：

• 前綴從不重複。 一次性的 20,000 個 token 文件會支付任何寫入溢價，且無法獲得任何回報。
• 請求到達速度太慢。 如果匹配請求之間的間隔超過了快取存活時間，每次呼叫都是一次新的寫入。我們在證據中沒有找到該存活時間，因此請根據模型頁面所述來測量您自己的間隔。
• 前綴在邊界之前發生變化。 上述失敗案例中 25% 的超支正是來自這種模式。
• 前綴很小。 節省量與前綴 token 成正比。幾百個 token 每次呼叫僅能節省幾分錢，且證據中沒有提到最小可快取大小。
• 輸出主導了帳單。 快取僅能修剪輸入。如果答案很長，快取線在總成本中所佔的比例很小。
• 模型未列出快取價格。 計費指南指出 TokenLab 價格欄中的破折號表示沒有 Verified 優惠，而非免費。在指望任何折扣之前，請檢查模型的定價細節。

工作負載模式	快取可行性	原因
多輪工具迴圈	高	指令和工具定義在步驟之間保持固定。
許多使用者查詢同一個大型文件	高	流量爆發能迅速攤銷寫入成本。
不頻繁的背景作業	低	間隔大於快取存活時間會強制重複寫入。
變化的系統提示詞	低	邊界之前的變更會破壞匹配。

Prompt Caching 也與計費指南中的「實作快取」提示不同，後者是指在您自己的應用程式中儲存重複相同請求的回應。這完全避免了模型呼叫，但只有在整個請求重複時才有用。對於長代理工作階段，程式設計代理成本指南涵蓋了上下文大小、輸出限制和模型選擇以及快取。

常見問題解答

快取命中是否總是能讓請求更便宜？

僅針對匹配的前綴，且僅在模型列出快取讀取價格時。在我們檢查的模型中，讀取成本為輸入的 2% 到 10%。後綴和所有輸出 token 均按正常費率計費。在有寫入溢價的模型上，未命中可能比未快取的呼叫成本更高。

缺失的快取寫入價格是否等同於免費？

不。對於 gpt-5.5 和 gemini-3.8-flash，即時 API 在 2026-10-03 列出了快取讀取價格，但沒有寫入價格。請執行一次首次請求並在 Usage 中讀取費用，而不是假設為零或輸入費率。

使用者特定值應該放在可快取提示詞的哪裡？

將它們放在共享內容之後，放在使用者訊息或後期的 messages 條目中。在共享區塊之前變更的任何內容都會改變前綴並強制進行新的寫入。這包括時間戳記、工作階段 ID 和重新排序的工具清單。

為什麼重複的請求顯示沒有快取 token？

我們會按順序檢查四件事。模型是否列出了 prompt-cache？前綴在呼叫之間是否位元組完全相同？第二次呼叫是否在快取存活時間內到達？快取計數是否在您的日誌記錄會丟棄的欄位中？我們閱讀的文件中沒有命名該欄位，因此請記錄整個 usage 物件。

在您於 TokenLab 模型頁面上決定使用某個模型之前，請先比較即時快取價格。