Prompt Caching 成本指南：缓存命中、前缀与实际 API 开销

Prompt Caching（提示词缓存）的成本取决于你的第二次请求是否与第一次完全一致，而不是取决于标题中提到的折扣力度。以 claude-sonnet-5 上的 20,000 token 系统提示词为例，1,000 次请求在不使用缓存时成本约为 18.18 美元，而如果第一次请求之后的所有请求都能命中缓存，成本则约为 2.00 美元。如果每次调用的前缀都在变化，那么同一提示词的成本反而会高于不使用缓存的基准线。本指南使用了 TokenLab 在 2026 年 10 月 3 日观察到的价格来展示这一界限，并标注了我们在文档中无法确认的内容。

核心要点

• 在我们检查的五款模型中，缓存读取成本为正常输入价格的 2% 到 10%。其中两款模型未列出缓存写入价格。
• 在有写入价格的情况下，其价格要么等于输入价格（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 月 3 日读取了下表中每个模型的实时模型 API。所有五款模型都在其能力中列出了 prompt-cache，且定价信息最后更新于 2026-10-02T16:53:30.068Z。价格单位为每 100 万 token 的美元金额。

模型	输入	缓存读取	缓存写入	读取占输入比例	写入与输入比
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 月 3 日观察：

• 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 月 3 日观察）称，已完成的请求将根据产生该请求的交付选项收费一次。Official 遵循模型制造商的公开价格，因此在与制造商的价格表进行比较之前，请确认是哪个选项服务了你的请求。

Get a Model 参考文档显示 gpt-5.6-terra 的能力中包含 prompt-cache。但其示例响应中不包含价格，因此我们未将该模型列入表中。我们没有检查目录中的其他模型。

Prompt Caching 成本计算示例：一个长系统提示词

以下是场景设定，所有输入均已列出，以便你代入自己的数字。这些是我们的假设，而非测量值。

• 一个 20,000 token 的系统提示词和工具块，在每次请求中均相同。
• 一个 200 token 的用户消息，每次请求都会改变。
• 1,000 次请求，缓存在整个运行期间保持有效，因此有 1 次写入和 999 次读取。
• 忽略输出 token，因为无论是否使用缓存，它们的成本都相同。

claude-sonnet-5，输入 0.90，读取 0.09，写入 1.125（每 100 万 token）：

• 不使用缓存：1,000 × 20,200 = 20,200,000 token × $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 返回的 capabilities 数组（2026 年 10 月 3 日观察）。没有该能力的模型无法提供折扣预期。
2. 保持共享内容在稳定位置。 在 Messages 端点上，system 是一个顶层字段，接受字符串或内容块数组。在 Chat Completions 上，系统指令位于 messages 中。无论哪种方式，重复的内容都应放在最前面。
3. 在边界之前发送完全相同的字节。 这是本文原始版本中的精确前缀规则，它与表格价格的运作方式相匹配。读取价格仅适用于提示词中匹配的部分。

Request A: [ System Prompt + Tool Definitions ] [ User Query A ]
           ▲───────────── CACHED PREFIX ────────▲ ▲── SUFFIX ──▲

Request B: [ System Prompt + Tool Definitions ] [ User Query B ]
           ▲─────────── CACHE HIT (READ) ───────▲ ▲── SUFFIX ──▲

三种习惯最容易破坏重用：

• 系统提示词顶部的日期戳、用户 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?" }
  ]
}

本文的早期草稿在该系统块上放置了一个 cache_control 标记，类型为 ephemeral。我们在 2026 年 10 月 3 日阅读的 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。两个参考文档都没有命名 cached-token 字段。编码代理成本指南（2026 年 10 月 3 日观察）建议在响应或 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 价格列中的短横线表示没有经过验证的报价，而不是免费。在指望任何折扣之前，请检查模型的定价详情。

工作负载模式	缓存可行性	原因
多轮工具循环	高	指令和工具定义在步骤间保持固定。
许多用户查询同一个大型文档	高	流量爆发能迅速摊销写入成本。
不频繁的后台作业	低	间隔超过缓存生命周期会强制重复写入。
变化的系统提示词	低	边界之前的更改会破坏匹配。

Prompt Caching 也不同于计费指南中的“实现缓存”提示，后者是指在你的应用程序中存储重复相同请求的响应。这完全避免了模型调用，但仅在整个请求重复时才有用。对于长代理会话，编码代理成本指南涵盖了上下文大小、输出限制和模型选择，以及缓存相关内容。

常见问题解答

缓存命中是否总是使请求更便宜？

仅针对匹配的前缀，且仅当模型列出了缓存读取价格时。在我们检查的模型中，读取成本为输入的 2% 到 10%。后缀和所有输出 token 按正常费率计费。在有写入溢价的模型上，未命中缓存的成本可能高于不使用缓存的调用。

缺失的缓存写入价格是否等同于免费？

不是。对于 gpt-5.5 和 gemini-3.8-flash，实时 API 在 2026 年 10 月 3 日列出了缓存读取价格，但没有列出写入价格。请运行一次首次请求并在 Usage 中读取费用，而不是假设为零或按输入费率计费。

每用户的值应该放在可缓存提示词的什么位置？

将它们放在共享内容之后，放在用户消息或较后的 messages 条目中。在共享块之前变化的任何内容都会改变前缀并强制进行新的写入。这包括时间戳、会话 ID 和重新排序的工具列表。

为什么重复请求显示没有缓存 token？

我们会按顺序检查四件事。模型是否列出了 prompt-cache？前缀在调用之间是否字节一致？第二次调用是否在缓存生命周期内到达？缓存计数是否在你的日志记录丢弃的字段中？我们阅读的文档没有命名该字段，因此请记录整个 usage 对象。

在你在 TokenLab 模型页面上确定模型之前，请先比较实时缓存价格。