提示快取

「Prompt caching」（提示快取）透過允許從提示中的特定前綴繼續處理，來最佳化您的 API 使用。這能大幅減少重複性任務或具有一致元素之提示的處理時間與成本。

啟用提示快取有兩種方式：

• 自動快取：在請求的頂層新增單一 cache_control 欄位。系統會自動將快取斷點套用至最後一個可快取的區塊，並隨著對話增長將其向前移動。最適合多輪對話，讓不斷增長的訊息歷史自動被快取。
• 明確快取斷點：將 cache_control 直接放在個別內容區塊上，以精細控制確切要快取的內容。

最簡單的入門方式是使用自動快取：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    messages=[
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'.",
        }
    ],
)
print(response.usage.model_dump_json())

使用自動快取時，系統會快取直到最後一個可快取區塊（含）為止的所有內容。在後續具有相同前綴的請求中，快取的內容會自動被重複使用。

提示快取的運作方式

當您傳送啟用提示快取的請求時：

1. 系統會檢查直到指定快取斷點為止的提示前綴，是否已在最近的查詢中被快取。
2. 若找到，則使用快取版本，減少處理時間與成本。
3. 否則，系統會處理完整提示，並在回應開始後快取該前綴。

這對以下情況特別有用：

• 包含許多範例的提示
• 大量的上下文或背景資訊
• 具有一致指令的重複性任務
• 冗長的多輪對話

預設情況下，快取的存留時間為 5 分鐘。每次使用快取內容時，快取都會免費重新整理。

存留時間是從寫入或讀取快取項目的請求開始時計算，而非從其回應結束時計算。產生回應所花費的時間會計入存留時間：如果回應需要 4 分鐘串流完成，則重複使用相同快取前綴的後續請求必須在該回應完成後約 1 分鐘內開始。

定價

提示快取引入了新的定價結構。下表顯示每個支援模型每百萬 token 的價格：

^{1 Claude Fable 5.1 與 Claude Mythos 5.1 的快取命中與刷新定價為基本輸入價格的 0.025 倍。所有其他模型則使用標準的 0.1 倍乘數。}

支援的模型

所有現行 Claude 模型皆支援提示快取（自動與明確兩種方式）。

自動快取

自動快取是啟用提示快取最簡單的方式。您無需在個別內容區塊上放置 cache_control，只需在請求主體的頂層新增單一 cache_control 欄位。系統會自動將快取斷點套用至最後一個可快取的區塊。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a helpful assistant that remembers our conversation.",
    messages=[
        {"role": "user", "content": "My name is Alex. I work on machine learning."},
        {
            "role": "assistant",
            "content": "Nice to meet you, Alex! How can I help with your ML work today?",
        },
        {"role": "user", "content": "What did I say I work on?"},
    ],
)
print(response.usage.model_dump_json())

自動快取在多輪對話中的運作方式

使用自動快取時，快取點會隨著對話增長自動向前移動。每個新請求都會快取直到最後一個可快取區塊為止的所有內容，而先前的內容則從快取中讀取。

快取斷點會自動移至每個請求中的最後一個可快取區塊，因此隨著對話增長，您無需更新任何 cache_control 標記。

TTL 支援

預設情況下，自動快取使用 5 分鐘 TTL。您可以指定 1 小時 TTL，價格為基本輸入 token 價格的 2 倍：

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

與區塊層級快取結合使用

自動快取與明確快取斷點相容。兩者一起使用時，自動快取斷點會佔用 4 個可用斷點位置中的一個。

這讓您可以結合兩種方法。例如，使用明確斷點快取您的系統提示，同時由自動快取處理對話：

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}

維持不變的部分

自動快取使用相同的底層快取基礎架構。定價、最低 token 門檻、上下文排序要求以及 20 個區塊的回溯視窗，皆與明確斷點相同。

邊界情況

• 如果最後一個區塊已有具相同 TTL 的明確 cache_control，則自動快取不會執行任何操作。
• 如果最後一個區塊具有不同 TTL 的明確 cache_control，API 會傳回 400 錯誤。
• 如果已存在 4 個明確的區塊層級斷點，API 會傳回 400 錯誤（沒有剩餘位置可供自動快取使用）。
• 如果最後一個區塊不符合作為自動快取斷點目標的資格，系統會靜默地向後尋找最近的合格區塊。若找不到，則略過快取。

明確快取斷點

若要對快取進行更多控制，您可以將 cache_control 直接放在個別內容區塊上。當您需要快取以不同頻率變更的不同區段，或需要精細控制確切要快取的內容時，這會很有用。

建構您的提示

將靜態內容（工具定義、系統指令、上下文、範例）放在提示的開頭。使用 cache_control 參數標記可重複使用內容的結尾以進行快取。

快取前綴依以下順序建立：tools、system，然後是 messages。此順序形成一個階層，每個層級都建立在前一個層級之上。

自動前綴檢查的運作方式

您可以只在靜態內容的結尾使用一個快取斷點，系統會自動找出先前請求已寫入快取的最長前綴。了解其運作方式有助於您最佳化快取策略。

三個核心原則：

1. 快取寫入只發生在您的斷點處。 以 cache_control 標記區塊會寫入恰好一個快取項目：以該區塊結尾之前綴的雜湊值。系統不會為任何更早的位置寫入項目。由於雜湊是累積的，涵蓋直到並包含斷點的所有內容，因此變更斷點處或斷點之前的任何區塊，都會在下一個請求中產生不同的雜湊值。

2. 快取讀取會向後尋找先前請求所寫入的項目。 在每個請求中，系統會計算您斷點處的前綴雜湊值，並檢查是否有相符的快取項目。若不存在，它會一次向後移動一個區塊，檢查每個較早位置的前綴雜湊值是否與快取中已有的內容相符。它尋找的是先前的寫入，而非穩定的內容。

3. 回溯視窗為 20 個區塊。 系統每個斷點最多檢查 20 個位置，斷點本身計為第一個。如果系統在該視窗中找不到相符的項目，檢查便會停止（或從下一個明確斷點繼續，若有的話）。在 Claude API 上，一連串連續的 tool_use 區塊計為一個位置，一連串連續的 tool_result 區塊也是如此，因此具有許多平行工具呼叫的輪次本身不會將前一個請求的項目推出視窗之外。

範例：在增長的對話中回溯

您每輪附加新區塊，並在每個請求的最後一個區塊上設定 cache_control：

• 第 1 輪： 10 個區塊，斷點在區塊 10。不存在先前的快取項目。系統在區塊 10 寫入一個項目。
• 第 2 輪： 15 個區塊，斷點在區塊 15。區塊 15 沒有項目，因此系統向後移至區塊 10 並找到第 1 輪的項目。在區塊 10 快取命中；系統只重新處理區塊 11 至 15，並在區塊 15 寫入新項目。
• 第 3 輪： 35 個區塊，斷點在區塊 35。系統檢查 20 個位置（區塊 35 至 16）但一無所獲。第 2 輪在區塊 15 的項目位於視窗外一個位置，因此沒有快取命中。在區塊 15 新增第二個斷點會在該處啟動第二個回溯視窗，從而找到第 2 輪的項目。

常見錯誤：將斷點放在每次請求都會變更的內容上

您的提示有一個大型靜態系統上下文（區塊 1 至 5），後面接著一個包含時間戳記與使用者訊息的每次請求區塊（區塊 6）。您在區塊 6 上設定 cache_control：

• 請求 1： 在區塊 6 快取寫入。雜湊值包含時間戳記。
• 請求 2： 時間戳記不同，因此區塊 6 處的前綴雜湊值不同。回溯會經過區塊 5、4、3、2 和 1，但系統從未在這些位置寫入項目。沒有快取命中。您每次請求都要支付新的快取寫入費用，卻從未獲得讀取。

回溯不會找出斷點後方的穩定內容並加以快取。它找的是先前請求已寫入的項目，而寫入只發生在斷點處。將 cache_control 移至區塊 5（跨請求保持不變的最後一個區塊），之後每個請求都會讀取快取的前綴。自動快取也會落入同樣的陷阱：它將斷點放在最後一個可快取區塊上，而在此結構中，該區塊正是每次請求都會變更的區塊，因此請改在區塊 5 上使用明確斷點。

重點摘要： 將 cache_control 放在其前綴在您希望共用快取的各請求之間完全相同的最後一個區塊上。在增長的對話中，只要每輪新增的區塊少於 20 個，最後一個區塊即可運作：較早的內容永遠不會變更，因此下一個請求的回溯會找到先前的寫入。對於具有可變後綴（時間戳記、每次請求的上下文、傳入的訊息）的提示，請將斷點放在靜態前綴的結尾，而非可變區塊上。

何時使用多個斷點

如果您想要達成以下目的，最多可以定義 4 個快取斷點：

• 快取以不同頻率變更的不同區段（例如，工具很少變更，但上下文每天更新）
• 對確切要快取的內容有更多控制
• 當增長的對話將您的斷點推至距離上次快取寫入 20 個或更多區塊時，確保快取命中

了解快取斷點成本

快取斷點本身不會增加任何成本。 您只需支付以下費用：

• 快取寫入： 當新內容寫入快取時（5 分鐘 TTL 比基本輸入 token 多 25%）
• 快取讀取： 當使用快取內容時（基本輸入 token 價格的 10%，在 Claude Fable 5.1 和 Claude Mythos 5.1 上為 2.5%）
• 一般輸入 token： 任何未快取的內容

新增更多 cache_control 斷點不會增加您的成本——您仍然根據實際快取與讀取的內容支付相同金額。斷點讓您能控制哪些區段可以獨立快取。

快取策略與考量

快取限制

在 Claude API、Claude Platform on AWS、Google Cloud 和 Microsoft Foundry 上，最低可快取提示長度為：

• Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5、Claude Fable 5 和 Claude Mythos 5 為 512 個 token
• Claude Mythos Preview 和 Claude Opus 4.7 為 2,048 個 token
• Claude Opus 4.6 和 Claude Opus 4.5 為 4,096 個 token
• Claude Opus 4.8、Claude Sonnet 5、Claude Sonnet 4.6、Claude Sonnet 4.5、Claude Opus 4.1（已退役，Bedrock 和 Google Cloud 除外）、Claude Opus 4（已退役，Google Cloud 除外）和 Claude Sonnet 4（已退役，Bedrock 和 Google Cloud 除外）為 1,024 個 token
• Claude Haiku 4.5 為 4,096 個 token
• Claude Haiku 3.5（已退役，Bedrock 和 Google Cloud 除外）為 2,048 個 token

這些最低值適用於每個模型可用的所有平台。

較短的提示無法被快取，即使以 cache_control 標記也是如此。任何快取少於此 token 數量的請求都會在不快取的情況下處理，且不會傳回錯誤。若要驗證提示是否已被快取，請檢查回應的 usage 欄位：如果 cache_creation_input_tokens 和 cache_read_input_tokens 皆為 0，則該提示未被快取（很可能是因為未達到最低長度要求）。

如果您的提示僅略低於您的模型與平台的最低值，擴充快取內容以達到門檻通常是值得的。快取讀取的成本遠低於未快取的輸入 token，因此達到最低值可以降低經常重複使用之提示的成本。

對於並行請求，請注意快取項目只有在第一個回應開始後才可用。如果您需要平行請求的快取命中，請等待第一個回應後再傳送後續請求。

目前，「ephemeral」是唯一支援的快取類型，預設存留時間為 5 分鐘。

可以快取的內容

請求中的大多數區塊都可以被快取。這包括：

• 工具：tools 陣列中的工具定義
• 系統訊息：system 陣列中的內容區塊
• 文字訊息：messages.content 陣列中的內容區塊，適用於使用者與助理輪次
• 圖片與文件：messages.content 陣列中的內容區塊，位於使用者輪次中
• 工具使用與工具結果：messages.content 陣列中的內容區塊，位於使用者與助理輪次中

這些元素皆可被快取，無論是自動快取或以 cache_control 標記。

無法快取的內容

雖然大多數請求區塊都可以被快取，但有一些例外：

• 思考區塊無法直接以 cache_control 快取。然而，當思考區塊出現在先前的助理輪次中時，它們可以與其他內容一起被快取。以這種方式快取時，從快取讀取時它們確實會計為輸入 token。

• 子內容區塊（如引用）本身無法直接快取。請改為快取頂層區塊。

  就引用而言，作為引用來源資料的頂層文件內容區塊可以被快取。這讓您能透過快取引用將參照的文件，有效地將提示快取與引用搭配使用。

• 空白文字區塊無法被快取。

什麼會使快取失效

對快取內容的修改可能會使部分或全部快取失效。

如建構您的提示中所述，快取遵循以下階層：tools → system → messages。每個層級的變更都會使該層級及所有後續層級失效。

下表顯示不同類型的變更會使快取的哪些部分失效。✘ 表示快取失效，✓ 表示快取仍然有效。

追蹤快取效能

使用回應中 usage 內的這些 API 回應欄位（若為串流則為 message_start 事件）來監控快取效能：

• cache_creation_input_tokens：建立新項目時寫入快取的 token 數量。
• cache_read_input_tokens：此請求從快取擷取的 token 數量。
• input_tokens：未從快取讀取或未用於建立快取的輸入 token 數量（亦即最後一個快取斷點之後的 token）。

搭配思考區塊進行快取

將思考與提示快取搭配使用時，思考區塊具有特殊行為：

與其他內容一起自動快取： 雖然思考區塊無法明確以 cache_control 標記，但當您使用工具結果進行後續 API 呼叫時，它們會作為請求內容的一部分被快取。這通常發生在工具使用期間，當您將思考區塊傳回以繼續對話時。

輸入 token 計算： 當思考區塊從快取讀取時，它們會在您的使用量指標中計為輸入 token。這對成本計算與 token 預算很重要。

快取失效模式：

• 當僅提供工具結果作為使用者訊息時，快取仍然有效
• 在 Opus 4.5+ 和 Sonnet 4.6+ 上，即使新增非工具結果的使用者內容，思考區塊預設也會被保留，因此快取仍然有效
• 在較早的 Opus/Sonnet 模型和所有 Haiku 模型上，新增非工具結果的使用者內容時快取會失效，導致所有先前的思考區塊從上下文中移除
• 即使沒有明確的 cache_control 標記，此快取行為也會發生

如需快取失效的更多詳情，請參閱什麼會使快取失效。

工具使用範例：

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# On earlier Opus/Sonnet and all Haiku models, non-tool-result user block causes prior thinking blocks to be stripped; on Opus 4.5+/Sonnet 4.6+ they are kept

在較早的 Opus/Sonnet 模型和所有 Haiku 模型上，此時所有先前的思考區塊都會從上下文中移除。在 Opus 4.5+ 和 Sonnet 4.6+ 上，先前的思考區塊預設會被保留，並仍是快取前綴的一部分。

如需更詳細的資訊，請參閱思考與提示快取。

快取儲存與共用

• 組織與工作區隔離： 快取在組織之間是隔離的。不同組織永遠不會共用快取，即使它們使用相同的提示。在 Claude API、Claude Platform on AWS 和 Microsoft Foundry 上，快取也會在組織內依工作區隔離；Bedrock 和 Google Cloud 僅使用組織層級的隔離。

• 完全相符： 快取命中需要 100% 相同的提示區段，包括直到並包含以 cache control 標記之區塊的所有文字與圖片。

• 輸出 token 產生： 提示快取對輸出 token 的產生沒有影響。您收到的回應與未使用提示快取時所得到的完全相同。

有效快取的最佳實務

若要最佳化提示快取效能：

• 對於多輪對話，從自動快取開始。它會自動處理斷點管理。
• 當您需要快取具有不同變更頻率的不同區段時，使用明確的區塊層級斷點。
• 快取穩定、可重複使用的內容，例如系統指令、背景資訊、大型上下文或常用的工具定義。
• 將快取內容放在提示的開頭以獲得最佳效能。
• 策略性地使用快取斷點來分隔不同的可快取前綴區段。
• 將斷點放在跨請求保持相同的最後一個區塊上。對於具有靜態前綴與可變後綴（時間戳記、每次請求的上下文、傳入的訊息）的提示，那就是前綴的結尾，而非可變區塊。
• 定期分析快取命中率，並視需要調整您的策略。

針對不同使用案例進行最佳化

根據您的情境調整提示快取策略：

• 對話式代理：降低長時間對話的成本與延遲，尤其是具有冗長指令或上傳文件的對話。
• 程式碼助理：透過在提示中保留程式碼庫的相關區段或摘要版本，改善自動完成與程式碼庫問答。
• 大型文件處理：在提示中納入完整的長篇資料（包括圖片），而不增加回應延遲。
• 詳細指令集：分享大量的指令、程序與範例清單，以微調 Claude 的回應。開發人員通常會在提示中包含一兩個範例，但透過提示快取，您可以納入 20 個以上多樣化的高品質答案範例，獲得更好的效能。
• 代理式工具使用：提升涉及多次工具呼叫與反覆程式碼變更之情境的效能，其中每個步驟通常需要新的 API 呼叫。
• 與書籍、論文、文件、Podcast 逐字稿及其他長篇內容對話：將整份文件嵌入提示中，讓使用者向其提問，使任何知識庫活起來。

常見問題疑難排解

如果遇到非預期的行為：

• 確保快取區段在各次呼叫之間完全相同。對於明確斷點，請驗證 cache_control 標記位於相同位置
• 檢查呼叫是否在快取存留時間內進行（預設為 5 分鐘）
• 驗證 tool_choice、圖片使用、思考設定與 output_config.effort 在各次呼叫之間保持一致
• 確認您快取的 token 數量至少達到您的模型與平台的最低值（請參閱快取限制）
• 確認您的斷點位於跨請求保持相同的區塊上。快取寫入只發生在斷點處，如果該區塊發生變更（時間戳記、每次請求的上下文、傳入的訊息），前綴雜湊值便永遠不會相符。回溯不會找出斷點後方的穩定內容；它只會找到較早請求在其自身斷點處寫入的項目
• 驗證您 tool_use 內容區塊中的鍵具有穩定的順序，因為某些語言（例如 Swift、Go）在 JSON 轉換期間會隨機排列鍵的順序，從而破壞快取
• 使用快取診斷讓 API 比較連續的請求，並回報提示的哪個部分出現分歧

1 小時快取期限

如果您覺得 5 分鐘太短，Anthropic 也提供 1 小時的快取期限，需額外付費。

若要使用延長的快取，請在 cache_control 定義中包含 ttl，如下所示：

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

回應包含如下的詳細快取資訊：

{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

請注意，目前的 cache_creation_input_tokens 欄位等於 cache_creation 物件中各值的總和。

如果您在使用網頁搜尋等伺服器工具時看到您未請求的 ephemeral_5m_input_tokens 寫入，請參閱搭配提示快取的工具使用。

何時使用 1 小時快取

如果您有以固定頻率使用的提示（亦即使用頻率高於每 5 分鐘一次的系統提示），請繼續使用 5 分鐘快取，因為它會持續免費重新整理。

1 小時快取最適合用於以下情境：

• 當您的提示使用頻率可能低於每 5 分鐘一次，但高於每小時一次時。例如，當代理式的附屬代理需要超過 5 分鐘，或當儲存與使用者的長篇聊天對話，且您通常預期該使用者可能不會在接下來 5 分鐘內回應時。
• 當延遲很重要，且您的後續提示可能在 5 分鐘之後才傳送時。
• 當您想要改善速率限制的利用率時，因為快取命中不會從您的速率限制中扣除。

混合不同的 TTL

您可以在同一請求中同時使用 1 小時與 5 分鐘的快取控制，但有一個重要限制：具有較長 TTL 的快取項目必須出現在較短 TTL 之前（亦即 1 小時快取項目必須出現在任何 5 分鐘快取項目之前）。

混合 TTL 時，API 會在您的提示中決定三個計費位置：

1. 位置 A：最高快取命中處的 token 數（若無命中則為 0）。
2. 位置 B：A 之後最高的 1 小時 cache_control 區塊處的 token 數（若不存在則等於 A）。
3. 位置 C：最後一個 cache_control 區塊處的 token 數。

您將被收取以下費用：

1. A 的快取讀取 token。
2. (B - A) 的 1 小時快取寫入 token。
3. (C - B) 的 5 分鐘快取寫入 token。

以下是三個範例。這描繪了 3 個請求的輸入 token，每個請求都有不同的快取命中與快取未命中。因此，每個請求都有不同的計算定價，顯示在彩色方框中。

預熱快取

「Cache pre-warming」（快取預熱）讓您可以在使用者觸發實際請求之前，先將系統提示或工具定義載入提示快取中。這消除了首次使用者互動時快取未命中所造成的延遲損失，為對延遲敏感的應用程式降低「time-to-first-token」（首個 token 時間），即 TTFT。

運作方式

在您的請求中設定 max_tokens: 0。API 會將您的提示讀入模型，並在任何 cache_control 斷點處寫入快取，然後立即返回而不產生任何輸出。回應會包含一個空的 content 陣列、stop_reason: "max_tokens"，以及一個完整填入的 usage 區塊。

請將 cache_control 斷點放在與後續請求共用的最後一個區塊上（通常是您的系統提示或工具定義），而不是放在佔位用的使用者訊息上。否則快取項目會以該佔位訊息作為鍵值，後續請求將無法命中。同時也請使用與後續請求相同的思考設定與 output_config.effort：這些值會被渲染進提示中（請參閱什麼會使快取失效），因此使用不同設定進行預熱可能會寫入一個您的實際流量永遠不會命中的項目。這表示您應使用明確快取斷點而非自動快取，因為自動快取會將斷點放在最後一個區塊上，而在此情境中最後一個區塊就是佔位訊息。佔位用的使用者訊息可以是任何包含非空白內容的字串（此處範例使用 "warmup"）；其內容會被讀入模型，但永遠不會被回答。

client = anthropic.Anthropic()

# 在使用者到來之前先執行此操作，以預熱共用的系統提示快取。
prewarm = client.messages.create(
    model="claude-opus-5",
    max_tokens=0,
    system=[
        {
            "type": "text",
            "text": "You are an expert software engineer with deep knowledge of distributed systems...",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason)  # "max_tokens"
print(prewarm.content)  # []
print(prewarm.usage)

API 會回傳一個空的 content 陣列：

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 5120,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 5120,
      "ephemeral_1h_input_tokens": 0
    },
    "iterations": [
      {
        "input_tokens": 8,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 5120,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 5120,
          "ephemeral_1h_input_tokens": 0
        },
        "type": "message"
      }
    ],
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}

典型使用模式

在您的應用程式啟動時（或依排程間隔）發送預熱請求，然後在預熱完成後發送實際的使用者請求：

client = anthropic.Anthropic()

SYSTEM_PROMPT = [
    {
        "type": "text",
        "text": "You are an expert software engineer with deep knowledge of distributed systems...",
        "cache_control": {"type": "ephemeral"},
    }
]


def prewarm_cache() -> None:
    """Call this at application startup or on a scheduled interval."""
    client.messages.create(
        model="claude-opus-5",
        max_tokens=0,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": "warmup"}],
    )


def respond(user_message: str) -> anthropic.types.Message:
    """The real user request; benefits from a warm cache."""
    return client.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# 在任何使用者流量到達之前先預熱快取。
prewarm_cache()

# 之後當使用者送出訊息時，系統提示前綴已在快取中。
response = respond("How do I implement a binary search tree?")
for block in response.content:
    if block.type == "text":
        print(block.text)

請記住，快取 TTL 仍然適用。對於預設的 5 分鐘快取，請至少每 5 分鐘發送一次新的預熱請求以保持快取處於預熱狀態。若使用者請求之間的間隔較長，請改用 1 小時快取時長。

限制

如果設定了以下任何一項，max_tokens: 0 請求會以 invalid_request_error 被拒絕，因為每一項都意味著需要產生零 token 預算無法產生的輸出：

• stream: true
• 擴展思考（thinking.type: "enabled"）
• 結構化輸出（output_config.format）
• tool_choice 為 {"type": "tool", ...} 或 {"type": "any"}

max_tokens: 0 在 Message Batches 請求中也會被拒絕。預熱針對的是首個 token 時間，這並不適用於批次處理，而且在批次處理期間寫入的快取項目很可能會在後續請求執行之前就過期。

取代 max_tokens=1 的變通做法

在 max_tokens: 0 可用之前，有些應用程式使用 max_tokens: 1 的預熱呼叫來達到相同效果。建議優先採用 max_tokens: 0 的方式：不會產生任何輸出，因此沒有需要丟棄的單一 token 回覆，不會計費任何輸出 token，而且請求的意圖明確無歧義。

提示快取範例

為了協助您開始使用提示快取，提示快取 cookbook 提供了詳細的範例與最佳實務。

以下程式碼片段展示了各種提示快取模式。這些範例示範了如何在不同情境中實作快取，協助您了解此功能的實際應用：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents.",
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?",
        }
    ],
)
print(response.usage.model_dump_json())

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": { "location": { "type": "string" } },
        "required": ["location"]
      }
    },
    {
      "name": "get_time",
      "description": "Get the current time in a given time zone",
      "input_schema": {
        "type": "object",
        "properties": { "timezone": { "type": "string" } },
        "required": ["timezone"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        # ……目前為止的長對話
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ],
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Good to know."},
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"},
                },
            ],
        },
    ],
)
print(response.usage.model_dump_json())

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[
        {
            "name": "search_documents",
            "description": "Search through the knowledge base",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Search query"}
                },
                "required": ["query"],
            },
        },
        {
            "name": "get_document",
            "description": "Retrieve a specific document by ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {"type": "string", "description": "Document ID"}
                },
                "required": ["doc_id"],
            },
            "cache_control": {"type": "ephemeral"},
        },
    ],
    system=[
        {
            "type": "text",
            "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
            "cache_control": {"type": "ephemeral"},
        },
        {
            "type": "text",
            "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "Can you search for information about Mars rovers?",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars rovers"},
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
                }
            ],
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Yes, please tell me about the Perseverance rover specifically.",
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
    ],
)
print(response.usage.model_dump_json())

資料保留

提示快取（自動與明確兩者皆是）符合 ZDR 資格。Anthropic 不會儲存您的提示或 Claude 回應的原始文字。

KV（key-value，鍵值）快取表示以及已快取內容的加密雜湊僅保存在記憶體中，不會以靜態方式儲存。已快取項目的最短存續期為 5 分鐘（標準）或 1 小時（延長），之後會被及時（但非立即）刪除。快取項目在組織之間是隔離的，並且在 Claude API、Claude Platform on AWS 以及 Microsoft Foundry 上，組織內的工作區之間也是隔離的。

關於所有功能的 ZDR 資格，請參閱 API 與資料保留。

常見問題

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

client.beta.prompt_caching.messages.create(**params)

client.messages.create(**params)

client.beta.promptCaching.messages.create(/* ... */);

client.messages.create(/* ... */);