Claude Prompt Caching 快取計費指南

如果你用 Claude Code、Cline、Cursor，或者自己寫程式碼調 Claude API，Prompt Cache 是把賬單打下來最直接的一件事——命中快取的部分只按 0.1× 計費，相當於打 1 折。本頁基於 Anthropic 官方文件整理（docs.claude.com/en/docs/build-with-claude/prompt-caching），並按 API易的接入方式給出可直接複製的示例。

一句話理解

把一段反覆使用的長 prompt（系統說明 / 長文件 / few-shot 示例）打上 cache_control 標記，伺服器會把它存起來。下次相同字首的請求來，伺服器跳過重複處理，便宜約 10 倍、也更快。一段時間內沒人再用就會過期。

為什麼要用 —— 看賬單倍率

以模型原始輸入 token 價為 1× 計：

型別	價格	說明
普通輸入	1×	沒快取的部分，原價
快取寫入（5 分鐘 TTL）	1.25×	第一次寫入貴 25%
快取寫入（1 小時 TTL）	2×	想存更久要付更多
快取讀取（命中）	0.1×	後續每次便宜 90%

回本點：

5 分鐘 TTL：只需 2 次複用同一字首即可回本（1.25 + 0.1 = 1.35，比兩次不快取的 2.0 便宜）。
1 小時 TTL：需要 3 次才回本（2 + 0.2 = 2.2，比 3.0 便宜）。

TTL 是滑動視窗：每次命中都會把過期時間重置，因此活躍的會話不會平白過期。只有真正閒置超過 TTL 才會失效。

適合場景

同一份長系統提示詞被多次呼叫（Agent、客服機器人）
多輪對話（每加一輪，前面的歷史都能複用）
批次處理同一份文件（一份合同問 50 個問題）
RAG 把檢索到的穩定文件塊作為字首

不適合場景

每次 prompt 從第一個字開始都不一樣
整體很短，根本到不了最小 token 閾值（見下）

觸發快取的三個硬條件

缺一不可。

1. 必須顯式打標記 `cache_control`

content 不能是純字串，必須是 content block 陣列，在要快取的那一塊上加 cache_control：

# ❌ 錯：純字串永不快取
"content": "一大段長文..."

# ✅ 對：content block + cache_control
"content": [
    {
        "type": "text",
        "text": "一大段長文...",
        "cache_control": {"type": "ephemeral"},
    },
    {"type": "text", "text": "問題"},
]

2. 長度必須達到最小閾值

短於閾值的內容，就算打了標記也不會快取（不報錯，靜默忽略）。按模型不同：

模型	最小 tokens
Sonnet 4.5 / 4 / 3.7	1024
Sonnet 4.6 / 早期 Haiku	2048
Opus 4.5 / 4.6 / 4.7、Haiku 4.5	4096

中文 1 個字大約 0.5–1 token，所以 Sonnet 4.6 至少要 2000 字以上的穩定內容才有意義。閾值數字可能隨官方版本變化，以 Anthropic 官方文件為準。

3. 字首必須逐位元組相同

快取按字首匹配：從請求開頭一直到 cache_control 標記位置，這段位元組流必須和上一次完全一樣。改任何一個字元——哪怕是空格、JSON 欄位順序、時間戳——都算”新字首”，會重新寫入而不是命中。 實踐含義：穩定的東西放前面，易變的東西放後面。

# ❌ 錯：每換一個問題字首就變了，永遠命中不了
content = [
    {"type": "text", "text": "請回答下面問題: " + 問題},  # 這塊在變
    {"type": "text", "text": 長文, "cache_control": {"type": "ephemeral"}},
]

# ✅ 對：長文在前打標記，問題在後不打標記
content = [
    {"type": "text", "text": 長文, "cache_control": {"type": "ephemeral"}},  # 穩定
    {"type": "text", "text": 問題},                                            # 隨便變
]

最小可執行示例

跑兩次同一段長文 + 不同問題，第一次寫入快取，第二次命中：

import json, os, requests

URL = "https://api.apiyi.com/v1/messages"
KEY = os.environ["APIYI_API_KEY"]
HEADERS = {
    "content-type": "application/json",
    "x-api-key": KEY,
    "anthropic-version": "2023-06-01",
}

# 必須足夠長。Sonnet 4.6 至少 2048 tokens，大約 2000+ 中文字。
LONG_TEXT = open("long_document_zh.txt").read()


def ask(question: str, label: str):
    payload = {
        "model": "claude-sonnet-4-6",
        "max_tokens": 256,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": LONG_TEXT, "cache_control": {"type": "ephemeral"}},
                {"type": "text", "text": question},
            ],
        }],
    }
    r = requests.post(URL, headers=HEADERS, data=json.dumps(payload), timeout=120)
    u = r.json().get("usage", {})
    print(f"[{label}] input={u.get('input_tokens')} "
          f"write={u.get('cache_creation_input_tokens')} "
          f"read={u.get('cache_read_input_tokens')}")


ask("請概括主旨", "第1次")    # 期望 write>0, read=0
ask("請給3個關鍵詞", "第2次")  # 期望 write=0, read>0

期望看到的輸出：

[第1次] input=35 write=6512 read=0
[第2次] input=22 write=0    read=6512

第 2 次的 read ≈ 第 1 次的 write，說明同一段字首被命中複用了。

怎麼判斷命中沒命中 —— 看三個欄位

每次響應的 usage 裡：

欄位	含義	計費倍率
`input_tokens`	沒被快取的剩餘輸入 token	1×
`cache_creation_input_tokens`	這次寫入快取的 token 數	1.25× 或 2×
`cache_read_input_tokens`	這次從快取讀取的 token 數	0.1×

輸入總量 = 三者之和。 只要 cache_read_input_tokens > 0，你就在省錢。

最常見的踩坑

現象	原因
`write` 永遠是 `0` 或欄位不存在	沒打 `cache_control` 標記 / 長度沒到閾值 / 用了 OpenAI 相容格式
第 2 次 `write` 又 > 0，`read` 還是 0	字首變了。常見：prompt 裡有 `datetime.now()`、UUID、變化的使用者 ID；JSON 序列化順序不穩定；帶時間戳的 system 提示
隔了一會兒再調又變成寫入	閒置超過 TTL 過期。要常駐可加 `{"type": "ephemeral", "ttl": "1h"}`
同一份 prompt 切換模型後沒命中	快取按模型隔離，換模型相當於換 key
長對話最近幾輪不命中	單次請求最多 4 個 `cache_control` 斷點；且每個斷點的字首查詢視窗為 20 個 block，更久遠的內容不會被納入命中檢查

Prompt Cache 只在 Anthropic 原生格式（/v1/messages）下生效。 用 OpenAI 相容格式（/v1/chat/completions）調 Claude 時，無論你怎麼傳，都拿不到快取計費。Claude Code、Cline、Cursor 等深度場景請務必走原生格式。

進階：多輪對話怎麼打

把 cache_control 打在最近一條 user 訊息的最後一個 content block 上。每加一輪，快取讀取範圍會自動延伸到上一輪結束的位置：

# 每一輪請求構造時
messages[-1]["content"][-1]["cache_control"] = {"type": "ephemeral"}

兩個硬限制要注意：

單次請求最多 4 個 cache_control 斷點。
每個斷點的字首查詢只回溯最近 20 個 content block——超出 20 個 block 的更久遠內容不會再被檢索去拼命中。換言之：很長的多輪對話靠”最末一次打標記”是兜不住前面所有歷史的。

實踐建議：在工具定義/系統提示/長文件/最近一輪對話各打一個斷點，正好用滿 4 個槽位，讓不同變化頻率的內容互不影響彼此的命中。

API易關於快取的說明

API易完整透傳快取欄位。 你在請求裡寫的 cache_control 會原樣轉發給上游 Claude（AWS Claude 或 Claude Official），響應裡的 cache_creation_input_tokens / cache_read_input_tokens 也會原樣回吐給你——所以你的程式碼無需為中轉層做任何額外適配。

如何自檢：

第一次傳送時觀察響應 usage.cache_creation_input_tokens > 0（寫入成功）。
幾秒後用相同字首再發一次，應看到 usage.cache_read_input_tokens > 0（命中）。
後臺賬單裡會單獨顯示快取寫入 / 快取讀取兩類計費項，倍率與官方一致（1.25× / 2× / 0.1×）。

要點回顧

1. 打標記

cache_control: {"type": "ephemeral"} 加在 content block 上，純字串 content 永不快取。

2. 夠長度

Sonnet 4.6 ≥ 2048 tokens，Opus 4.7 / Haiku 4.5 ≥ 4096 tokens，否則靜默忽略。

3. 穩字首

穩定內容在前、易變內容在後；任何一個字元變化都會讓快取失效。

4. 看 usage

cache_read_input_tokens > 0 才說明真的省錢了。

產品基礎

基礎 API

圖片 API（官轉）

影片 API（官轉）

多模態理解 API

文本 API

Claude Prompt Caching 快取計費指南

一句話理解

為什麼要用 —— 看賬單倍率

適合場景

不適合場景

觸發快取的三個硬條件

1. 必須顯式打標記 `cache_control`

2. 長度必須達到最小閾值

3. 字首必須逐位元組相同

最小可執行示例

怎麼判斷命中沒命中 —— 看三個欄位

最常見的踩坑

進階：多輪對話怎麼打

API易關於快取的說明

要點回顧

1. 打標記

2. 夠長度

3. 穩字首

4. 看 usage

相關連結

​一句話理解

​為什麼要用 —— 看賬單倍率

​適合場景

​不適合場景

​觸發快取的三個硬條件

​1. 必須顯式打標記 cache_control

​2. 長度必須達到最小閾值

​3. 字首必須逐位元組相同

​最小可執行示例

​怎麼判斷命中沒命中 —— 看三個欄位

​最常見的踩坑

​進階：多輪對話怎麼打

​API易 關於快取的說明

​要點回顧

1. 打標記

2. 夠長度

3. 穩字首

4. 看 usage

​相關連結

一句話理解

為什麼要用 —— 看賬單倍率

適合場景

不適合場景

觸發快取的三個硬條件

1. 必須顯式打標記 `cache_control`

2. 長度必須達到最小閾值

3. 字首必須逐位元組相同

最小可執行示例

怎麼判斷命中沒命中 —— 看三個欄位

最常見的踩坑

進階：多輪對話怎麼打

API易關於快取的說明

要點回顧

相關連結