Kimi K3.1 Pro 上下文前缀缓存与 TTL 配置：自动写入、命中与用量核对

一句话结论

Kimi API 会按请求前缀自动复用固定内容；Kimi K3.1 Pro 支持 Cache Write，可用默认 5m 或显式 1h TTL，但必须保持稳定前缀的顺序与文本不变，并按 API 的 usage 字段核对命中和写入。

适用场景

• 适合的任务：重复发送产品文档、代码库、工具定义、system prompt 的文档问答、编码 Agent、长会话和定时报告。

• 不适合的任务：前缀很少复用、两次请求间隔超过 TTL，或需要手动清理缓存的流程。

• 适用的模型版本：kimi-k3.1-pro；官方 FAQ 明确列出其支持 Cache Write。

• 适用的客户端、Agent 或 API：Kimi API 的 Chat Completions、Responses；Anthropic Messages 使用对应的顶层 cache_control。

• 推荐的推理档位和参数：Chat Completions/Responses 省略 prompt_cache_options 时使用 5m；间隔可能超过 5 分钟但在 1 小时内复用时设置 ttl="1h"。

可直接使用的内容

下面保留官方最小 Chat Completions 配置。mode 当前只支持 implicit，ttl 只支持 5m 和 1h：

curl https://api.moonshot.ai/v1/chat/completions \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --data '{
    "model": "kimi-k3.1-pro",
    "messages": [
      {"role": "system", "content": "You are a product documentation assistant.\n\nProduct documentation: ..."},
      {"role": "user", "content": "Which authentication methods does this product support?"}
    ],
    "prompt_cache_options": {"mode": "implicit", "ttl": "1h"}
  }'

测试或工作流步骤

1. 把不会变化的 system prompt、工具定义、参考资料和代码库放在请求前部。

2. 把每轮变化的用户问题、工具结果和任务状态放在末尾。

3. 在同一会话中保持固定内容的顺序和精确文本不变；不要在前缀中放时间戳或随机 ID。

4. 省略 prompt_cache_options，让 Chat Completions/Responses 自动按 5m 写入并复用；需要更长间隔时显式使用 {"mode":"implicit","ttl":"1h"}。

5. 让定时请求间隔落在 TTL 内；一次命中会按原 TTL 免费续期。

6. 注意缓存按 organization 隔离，5m 与 1h 是两套不共享的缓存，不能手动删除。

7. 若请求间隔通常超过 1 小时，不要为该前缀专门配置缓存。

8. 对流式 Chat Completions 设置 stream_options.include_usage=true，在最后一个 chunk 获取完整读写拆分。

9. 用响应 usage 字段记录 total input、cache read 和 cache write，不要只看总输入 token。

原始证据与数据

• 缓存匹配请求前缀；前缀中任意位置变化后，该位置之后的内容不能复用。

• kimi-k3.1-pro 和 kimi-k3 支持 Cache Write；页面 FAQ 列出的 K2.7、K2.7 Highspeed 和 K2.6 不支持。

• Cache Write 单独计费；命中部分只按 Cached Input 计费，同一 TTL 内命中不会再次收取写入费。

• 缓存按 block 存储；小于一个完整 block 的部分不能写入缓存，会按 cache miss 的普通输入价格计费。

• TTL 在首次写入时锁定；命中只按原 TTL 续期，新内容也按锁定 TTL 写入，必须等条目完全过期后才能换 TTL。

• 官方以 kimi-k3 展示价格：Input（miss）$3.00/1M tokens、Cache Write 5m $3.00、Cache Write 1h $6.00、Cached Input $0.30。这些是页面对 kimi-k3 的价格示例，本文不外推为 K3.1 Pro 当前价格。

• 以 1M token 前缀计算，1h 相比 5m 只多 $3.00 写入费；官方说明两次额外命中即可覆盖该差额。本文未进行价格或命中测试。

• Chat Completions 的字段为 usage.prompt_tokens、usage.prompt_tokens_details.cached_tokens、usage.prompt_tokens_details.cache_write_tokens。

• Responses 的字段为 usage.input_tokens、usage.input_tokens_details.cached_tokens、usage.input_tokens_details.cache_write_tokens。

• Messages 的总输入需相加 input_tokens + cache_read_input_tokens + cache_creation_input_tokens；写入还可按 ephemeral_5m_input_tokens 和 ephemeral_1h_input_tokens 拆分。

• Chat Completions/Responses 中，cache read、cache write 和未缓存部分互斥，并合计为总输入；Messages 的 input_tokens 不含读写缓存。

• 控制台提供 Caching Overview，可查看 hit、miss、cache-write token、命中率和缓存写入摊销倍数；账单明细也提供 5min/1h 写入字段。

• Anthropic Messages 的 cache_control 只在顶层生效；放在 messages 内容内部会被忽略，省略时同样使用 5m。

• 账单拆分后，原有请求无需改动；月度账单可按项目、组织和 API key 查看 5m/1h 写入明细。

• Chat Completions 响应头 Msh-Usage-Cache-Write-Tokens-5m 和 Msh-Usage-Cache-Write-Tokens-1h 可标识本次按 TTL 写入的 token。

• 没有新写入时，对应写入响应头为 0；计费核对公式为：输入 token = 未缓存 token + 命中 token + 写入 token。

适用边界

• 页面把缓存机制和 kimi-k3.1-pro 示例放在同一 API 指南中，但价格表明确写的是 kimi-k3；不能用该表推断 K3.1 Pro 的价格。

• “自动写入”以满足命中条件为前提；前缀未达到完整 block、内容变化或条目已过期时，不能按命中处理。

• 缓存按组织隔离；同一 organization 内可共享，跨 organization 不共享。

• 5m 和 1h 不是可互换的标签；已写入条目的 TTL 不能在有效期内修改。

• 官方说明是配置和计费规则，不代表本文已发起真实 API 请求；没有伪造命中率、延迟或价格实测结果。

• 页面将命中率和 cache-write amortization multiple 定义为控制台观察指标；本文不把它们改写为 K3.1 Pro 的固定性能承诺。

复现说明

1. 打开官方 Context Caching 指南，确认标题、K3.1 Pro 示例及 FAQ。

2. 使用测试 API Key，分别省略 prompt_cache_options、设置 ttl="5m" 和设置 ttl="1h"，保持固定前缀完全一致。

3. 记录响应中的 cached tokens、cache-write tokens 和未缓存输入；流式请求先开启 include_usage。

4. 不要把一次 HTTP 成功、账单展示或代码中存在配置当作命中测试；应以真实 usage 字段和控制台缓存统计分别核对。

5. 复现不同 TTL 时，先让原条目完全过期，再用新 TTL 写入同一前缀。