提示快取

「Prompt caching」（提示快取）透過允許從提示中的特定前綴恢復來最佳化您的 API 使用。這顯著減少了重複性任務或具有一致元素的提示的處理時間和成本。

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

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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 分鐘。每次使用快取內容時，快取都會免費重新整理。

定價

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

支援的模型

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

自動快取

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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-4-8",
  "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 個位置，將斷點本身計為第一個。如果系統在該視窗中找不到相符的項目，檢查就會停止（或從下一個明確斷點恢復，如果有的話）。

範例：不斷增長的對話中的回溯

您每輪附加新區塊，並在每個請求的最後一個區塊上設定 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%）
• 一般輸入 token：任何未快取的內容

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

快取策略與考量事項

快取限制

在 Claude API、Claude Platform on AWS、Vertex AI 和 Microsoft Foundry（測試版）上，最小可快取提示長度為：

• 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 4.6、Claude Sonnet 4.5、Claude Opus 4.1（已棄用）、Claude Opus 4（已棄用）和 Claude Sonnet 4（已棄用）為 1,024 個 token
• Claude Haiku 4.5 為 4,096 個 token
• Claude Haiku 3.5（已停用，Vertex AI 除外）為 2,048 個 token

模型可用性因平台而異，新發布模型的最小值也可能不同：在 Amazon Bedrock 上，Claude Fable 5 和 Claude Mythos 5 的最小可快取提示長度為 1,024 個 token。

較短的提示無法快取，即使標記了 cache_control 也是如此。任何快取少於此 token 數量的請求都會在不快取的情況下處理，且不會回傳錯誤。若要驗證提示是否已快取，請檢查回應使用量欄位：如果 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）。

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

使用思考區塊進行快取

當將擴展思考與提示快取一起使用時，思考區塊具有特殊行為：

與其他內容一起自動快取：雖然思考區塊無法明確標記 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+ 上，先前的思考區塊預設會保留，並仍然是快取前綴的一部分。

如需更詳細的資訊，請參閱擴展思考文件。

快取儲存與共用

• 組織和工作區隔離： 快取在組織之間是隔離的。不同的組織永遠不會共用快取，即使它們使用相同的提示。自 2026 年 2 月 5 日起，在 Claude API、Claude Platform on AWS 和 Microsoft Foundry（測試版）上，快取也在組織內按工作區隔離；Bedrock 和 Vertex AI 繼續僅使用組織層級隔離。

• 精確比對： 快取命中需要 100% 相同的提示區段，包括直到並包含標記為快取控制的區塊的所有文字和圖片。

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

有效快取的最佳實務

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

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

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

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

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

疑難排解常見問題

如果遇到非預期的行為：

• 確保快取區段在各次呼叫之間完全相同。對於明確斷點，驗證 cache_control 標記位於相同位置
• 檢查呼叫是否在快取生命週期內進行（預設為 5 分鐘）
• 驗證 tool_choice 和圖片使用在各次呼叫之間保持一致
• 驗證您快取的 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 物件中值的總和。

何時使用 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 個範例。這描繪了 3 個請求的輸入 token，每個請求都有不同的快取命中和快取未命中。因此，每個請求都有不同的計算定價，顯示在彩色方框中。

預熱快取

快取預熱讓您在使用者觸發真實請求之前，將系統提示或工具定義載入提示快取中。這消除了第一次使用者互動時的快取未命中延遲懲罰，降低對延遲敏感的應用程式的首個 token 時間（TTFT）。

運作方式

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

將 cache_control 斷點放在與後續請求共用的最後一個區塊上（通常是您的系統提示或工具定義），而不是佔位符使用者訊息上。否則快取項目會以佔位符為鍵，後續請求將無法命中它。這意味著使用明確快取斷點而不是自動快取，因為自動快取會將斷點放在最後一個區塊上，而在此情況下該區塊是佔位符。佔位符使用者訊息可以是任何具有非空白內容的字串（此處的範例使用 "warmup"）；其內容會被讀入模型但永遠不會被回答。

client = anthropic.Anthropic()

# 在使用者到達前觸發此操作，以預熱共用的系統提示快取。
prewarm = client.messages.create(
    model="claude-opus-4-8",
    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-4-8",
  "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-4-8",
        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-4-8",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


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

# 之後，當使用者提交訊息時，系統提示前綴已被快取。
response = respond("How do I implement a binary search tree?")
print(response.content[0].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"}

在 Message Batches 請求中，max_tokens: 0 也會被拒絕。預熱（pre-warming）的目標是縮短首個 token 的回應時間，這不適用於批次處理，而且在批次處理期間寫入的快取項目很可能在後續請求執行之前就已過期。

取代 max_tokens=1 的變通方法

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

提示快取範例

為了協助您開始使用「prompt caching」（提示快取），提示快取 cookbook 提供了詳細的範例和最佳實務。

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

資料保留

提示快取（包括自動和明確快取）符合 ZDR 資格。Anthropic 不會儲存您的提示或 Claude 回應的原始文字。

KV（鍵值）快取表示和已快取內容的加密雜湊僅保存在記憶體中，不會儲存於靜態儲存裝置。快取項目的最短生命週期為 5 分鐘（標準）或 1 小時（延長），之後會被迅速（但非立即）刪除。快取項目在組織之間是隔離的，而在 Claude API、Claude Platform on AWS 和 Microsoft Foundry（測試版）上，組織內的工作區之間也是隔離的。

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

常見問題