提示词缓存

187API 会在 Claude Messages 格式的请求里自动补 cache_control 断点。命中缓存的部分按输入价的 10% 计费，首次写入按 125% 计费。

计费口径

情形	计费
未命中（正常输入）	输入价 × 1
缓存命中（读取）	输入价 × 0.1
缓存写入（首次）	输入价 × 1.25
未达 1024 token 门槛	不产生缓存，按正常输入价

命中与否以上游返回的实际用量为准，可在控制台的用量明细里查看缓存 token 数。

:::info 门槛前缀长度需要达到 1024 token 才进入缓存。低于这个长度的请求不会产生缓存收益，也不会被多扣钱。 :::

断点是怎么注入的

只对 Claude Messages 格式（请求体带 messages 字段）生效，最多 4 个断点。按下面顺序补，补满 4 个即停：

tools 数组最后一个元素
system 最后一段（纯字符串时先转成数组形态）
最后一条消息里最后一个非 thinking 块
倒数第二个 user 消息（长工具循环的旧锚点，messages 少于 4 条时跳过）

移植原则与被缓存的上游行为保持一致：

只补不删：你自己已经写好的断点原样保留，包括 ttl
你已写满 4 个断点时不再注入，也不删除、不重排
新注入的断点固定为 5 分钟（{"type": "ephemeral"}，不带 ttl）
thinking / redacted_thinking 块不挂断点——上游不接受，且不是稳定前缀
content 是纯字符串（非数组）的消息块不挂断点，上游不接受这种形态

想自己控制断点

完全可以。你显式写 cache_control 的块优先级天然更高——我们只做"补齐"，不覆盖。想精确控制缓存边界时，自己把断点打在真正稳定的前缀末尾即可。

{
  "model": "MiniMax-M2.5",
  "system": [
    {
      "type": "text",
      "text": "很长且稳定的系统提示词……",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [
    {"role": "user", "content": "问题"}
  ]
}

让缓存真正命中的写法

缓存只认前缀完全一致。以下写法会破坏命中：

反模式	后果
系统提示词里塞当前时间戳 / 随机 ID	每轮前缀都不同，永远不命中
动态内容放在最前面	同上，且越靠前破坏越大
每一轮都改写 system 文案	断点位置整体失效
把追求变化的内容放在稳定内容之前	稳定部分再也命中不了

正确顺序：稳定内容在前（系统提示词、工具定义、长文档），变化内容在后（本轮提问）。

增量计费示例

假设系统提示词稳定 2000 token，输入价 P，同一会话连续问三次：

请求	输入 token 构成	计费
第 1 次	2000 写入	2000P × 1.25
第 2 次	2000 命中	2000P × 0.1
第 3 次	2000 命中	2000P × 0.1

第二、三次相对未命中节省 90% 的输入成本。这就是长系统提示词场景下账单明显低于预期总额的原因——不是漏计费。

已知限制

缓存的生命周期由上游决定，不保证在 5 分钟后仍然有效
换 key 不影响缓存（缓存挂在渠道侧，不挂在 key 上）
上游变更会导致缓存短暂失效，属于正常现象
多轮长对话超过上游回看窗口时，早期内容可能不再命中

计费口径​

断点是怎么注入的​

想自己控制断点​

让缓存真正命中的写法​

增量计费示例​

已知限制​