提示快取

「Prompt caching」（提示快取）可讓系統從提示中的特定前綴接續處理，藉此最佳化您的 API 使用。對於重複性任務或包含固定元素的提示，這能大幅減少處理時間與成本。

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

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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 的價格：

Model	Base tokens		Prompt caching
Name	Input	Output	5m writes	1h writes	Hits and refreshes
Claude Fable 5.1For demanding reasoning and long-horizon agentic work	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Opus 5.5For long-running agentic coding and knowledge work	$4 / MTok	$20 / MTok	$5 / MTok	$8 / MTok	$0.20 / MTok2
Claude Sonnet 5The best combination of speed and intelligence	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.20 / MTok
Claude Haiku 4.5The fastest model with near-frontier intelligence	$1 / MTok	$5 / MTok	$1.25 / MTok	$2 / MTok	$0.10 / MTok
Additional models
Claude Mythos 5.1	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Fable 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Mythos 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Opus 5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.8	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.7	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.6	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.1	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Opus 4	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Sonnet 4.6	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4.5	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Haiku 3.5	$0.80 / MTok	$4 / MTok	$1 / MTok	$1.60 / MTok	$0.08 / MTok

^{1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.}

^{2 Cache hits and refreshes on Claude Opus 5.5 are priced at 0.05x the base input price.}

^{All other models use the standard 0.1x multiplier.}

支援的模型

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

自動快取

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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 分鐘的「time to live」（存活時間），即 TTL。您可以指定 1 小時的 TTL，價格為基本輸入 token 價格的 2 倍：

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

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

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

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

{
  "model": "claude-opus-5-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 個區塊的「lookback window」（回溯視窗），都與明確斷點的規則相同。

邊界情況

• 如果最後一個區塊已經有相同 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），但什麼都沒找到。位於區塊 15 的第 2 輪項目剛好在視窗外一個位置，因此沒有命中快取。在區塊 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%，在 Claude Opus 5.5 上為 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.5、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。每個層級的變更都會使該層級及所有後續層級失效。

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

在支援對話中途的工具變更的模型上，inline-tools-2026-09-15 beta 標頭讓您可以在對話進行到一半時新增工具或變更工具定義，而無需編輯 tools。請在對話中途系統訊息的 tool_addition 區塊中傳送定義，並讓 tools 保持與您最初傳送時完全相同。快取前綴仍然相符，因此只有附加的訊息會被當作新輸入處理。唯一的例外是沒有任何非延遲工具的 tools 陣列，在這種情況下，以此方式定義的第一個工具會在該請求中造成一次完整的快取未命中。請參閱在訊息中定義工具。

追蹤快取效能

使用以下 API 回應欄位監控快取效能，這些欄位位於回應中的 usage 內（如果使用串流，則位於 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 的生成沒有影響。您收到的回應與未使用提示快取時完全相同。

有效快取的最佳實務

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

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

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

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

• 對話式代理：降低長時間對話的成本與「latency」（延遲），特別是包含冗長指示或上傳文件的對話。
• 程式設計助理：透過在提示中保留相關區段或程式碼庫的摘要版本，改善自動完成和程式碼庫問答。
• 大型文件處理：在提示中納入完整的長篇資料（包括圖片），而不會增加回應延遲。
• 詳細的指示集：分享大量的指示、程序和範例清單，以微調 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」（快取預熱）可讓您在使用者觸發實際請求之前，先將系統提示或工具定義載入「prompt cache」（提示快取）。這能消除首次使用者互動時因快取未命中而產生的「latency」（延遲），為對延遲敏感的應用程式縮短「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-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-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-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-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"}

在 Message Batches 請求中，max_tokens: 0 同樣會被拒絕。預熱的目標是首個 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-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-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-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-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())

資料保留

提示快取（包括自動和明確快取）符合「Zero Data Retention」（零資料保留），即 ZDR 的資格。Anthropic 不會儲存您提示或 Claude 回應的原始文字。

已快取內容的「key-value」（鍵值），即 KV 快取表示和加密雜湊僅保存在記憶體中，不會以靜態方式儲存。快取項目的最短存續時間為 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(/* ... */);