使用 Kimi API 的上下文缓存功能

上下文缓存让服务端复用你的相同请求前缀。前缀指请求 messages 中从开头连续的 token 序列；缓存按最长匹配前缀计算，匹配成功即为命中。命中部分按缓存命中价格计费，命中越多，越节省成本。以 kimi-k3 为例，缓存命中价格仅为未命中价格的 1/10。本页介绍如何提高缓存命中率、选择和设置 TTL（Time To Live，缓存时长），并通过 usage 字段验证缓存效果。

哪些内容适合缓存

上下文缓存适合在多次请求中重复发送固定内容的场景，例如：

场景	反复发送的固定内容
文档问答	产品文档、知识库或公司制度
编程 Agent	代码库、开发规范和工具定义
长会话 Agent	system prompt、工具定义和会话规则
定时巡检与报告	报告模板、指标定义和参考资料

命中缓存后，重复部分按缓存命中价格计费。如果相同前缀很少复用，或复用间隔超过 TTL，使用上下文缓存的收益有限，不必专门配置。

上下文缓存能省多少钱

Cache Write（缓存写入）现在单独列为计费项。以 kimi-k3 为例，缓存相关价格如下：

计费项	价格（每 1M tokens）	说明
Input（缓存未命中）	¥20	请求中未命中缓存的部分（每次请求单独计费）
Cache Write（`5m`）	¥20	前缀首次写入缓存时一次性收取；写入后 5 分钟内有效，每次命中后有效期重新计算为 5 分钟
Cache Write（`1h`）	¥40	前缀首次写入缓存时一次性收取；写入后 1 小时内有效，每次命中后有效期重新计算为 1 小时
Cached Input（缓存命中）	¥2	请求中命中缓存的部分（每次请求单独计费）

其他模型与计费项的完整价格，见模型推理价格说明。费用可以总结为两点：

总价不变：缓存写入的拆分是计费透明化，不是涨价。写入成本原先就包含在输入价格中，拆分后现有请求的整体费用不变。
命中就省钱：缓存命中价格是缓存未命中价格的 1/10。以 kimi-k3 为例，命中部分按缓存命中价格计费（¥2 / 1M tokens），每次命中比缓存未命中少 ¥18 / 1M tokens。

以 1h 为例算一笔账（假设前缀 1M tokens），只要在 1 小时内再命中 2 次，就比选 5m 划算；命中越多省得越多。

选 1h 而不是 5m，唯一多付的成本是写入费贵 ¥20（¥40 vs ¥20）。
之后每命中一次缓存，这部分输入的成本从 ¥20 降到 ¥2，省 ¥18。
所以：命中 1 次，省 ¥18；命中 2 次，共省 ¥36，扣掉多付的 ¥20，选择 1h 比选择 5m 净省 ¥16。

提高缓存命中率

缓存按请求前缀匹配。前缀中任何一处发生变化，该位置之后的内容都无法复用，因此建议：

把稳定的 system prompt、工具定义、参考资料和代码库放在请求前部。
把用户问题、工具结果和任务状态等每轮变化的内容放在后部。
保持同一会话中固定内容的顺序和文本完全一致，不要在前缀中插入时间戳、随机 ID 或其他动态字段。
将定时任务的执行间隔控制在 TTL 内，利用命中续期保持缓存有效。
缓存按组织（org）隔离：同一组织内共享，组织之间不共享。

缓存不支持手动清除；缓存前缀无活动超过所选 TTL 后自动过期。

选择合适的 TTL

缓存写入支持 5m 和 1h 两档 TTL。不传 prompt_cache_options 时，系统默认使用 5m TTL：满足命中条件的前缀会自动写入并尝试复用，账单上会产生相应的缓存写入费用。

连续追问间隔通常不超过 5 分钟时，选择 5m。
请求间隔会超过 5 分钟、但能在 1 小时内复用时，选择 1h；命中 2 次即可覆盖多付的写入费用（算账见「上下文缓存能省多少钱」一节）。
相同前缀通常要间隔超过 1 小时才会复用时，不建议专门配置缓存。

缓存条目的 TTL 在首次写入时锁定，不能改写：相同前缀命中后按原 TTL 免费续期，新增部分也按锁定的 TTL 继续写入。已有条目完全过期后，才能用新的 TTL 重新写入。

如何设置缓存 TTL

Chat Completions API 和 Responses API 在省略 prompt_cache_options 时默认按 5m TTL 写入缓存。需要指定 TTL 时，传入 prompt_cache_options：

# 将 prompt_cache_options.ttl 设置为 "5m" 或 "1h"。
curl https://api.moonshot.cn/v1/chat/completions \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --data '{
    "model": "kimi-k3",
    "messages": [
      {"role": "system", "content": "你是一个产品文档问答助手。\n\n产品文档：……"},
      {"role": "user", "content": "这个产品支持哪些认证方式？"}
    ],
    "prompt_cache_options": {"mode": "implicit", "ttl": "1h"}
  }'

prompt_cache_options.mode 当前仅支持 implicit，ttl 支持 5m 和 1h。Responses API 使用相同的参数，详见 Responses API。 Anthropic Messages API 使用顶层 cache_control 控制缓存写入。传入该字段时，请求前缀会按指定 TTL 写入缓存；省略该字段时，本次请求只读取 5m 缓存，不写入缓存：

# 将 cache_control.ttl 设置为 "5m" 或 "1h"。
curl https://api.moonshot.cn/anthropic/v1/messages \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --data '{
    "model": "kimi-k3",
    "cache_control": {"type": "ephemeral", "ttl": "1h"},
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "你好"}]
  }'

cache_control 只在请求顶层生效，消息体内的同名标记会被忽略。完整参数说明见 Messages API。现有请求无需改造。缓存写入拆分后，账单会新增缓存写入明细。

查看缓存读写用量

不同 API 使用不同的 usage 字段记录缓存读写情况。依赖 usage 字段统计成本的应用，请按下表迁移字段：

API	总输入	缓存读取	缓存写入
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	`usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens`	`usage.cache_read_input_tokens`	`usage.cache_creation_input_tokens`

对于 Chat Completions API 和 Responses API，缓存读取、缓存写入和未缓存部分互斥，三者之和等于总输入 Token 数。Messages 的 usage.input_tokens 不包含缓存读取和写入部分；其中 usage.cache_creation.ephemeral_5m_input_tokens 和 usage.cache_creation.ephemeral_1h_input_tokens 分别记录两个 TTL 下的写入 Token 数。使用 Chat Completions API 的流式请求时，需要设置 stream_options.include_usage=true，完整的缓存读写明细才会出现在最后一个 chunk 的 usage 字段中。

常见问题

哪些模型支持缓存写入？

kimi-k3 支持 Cache Write；kimi-k2.7、kimi-k2.7-highspeed、kimi-k2.6 不支持。

缓存命中后怎么计费？续期收费吗？

相同 TTL 的相同前缀命中缓存后：

命中部分不再收取 Cache Write 费用，仅按 Cached Input（缓存命中）价格计费，以 kimi-k3 为例约为缓存未命中价格的 1/10；
缓存在有效期内被命中会自动按原 TTL 免费续期，续期不单独收费。

例如：首次请求写入 1h 缓存并支付一次写入费用；30 分钟后再请求且命中，缓存从该时间点自动续期 1 小时，后续请求只按缓存命中价格计费。

5m 和 1h 两个档位怎么选？

关键看请求间隔：

请求间隔稳定小于 5 分钟（如连续调用的 Agent 任务）：默认 5m 档即可，命中会免费续期，无需选择 1h；
请求间隔可能超过 5 分钟（长会话、有人工介入的任务）：选择 1h 档可以避免缓存过期后重复写入，显著降低成本，同时缩短首 token 延迟（TTFT）。

按定价，1h 写入命中 2 次即可覆盖多付的写入费用，命中越多省得越多（算账见上文「上下文缓存能省多少钱」）；详细选型建议见「选择合适的 TTL」。

两个档位的缓存互通吗？可以手动删除缓存吗？

5m 与 1h 是两个缓存不互通；缓存按组织（org）隔离，同一组织内共享，组织之间不共享。缓存不支持手动清除，无活动超过所选 TTL 后自动过期，例如 5m 档缓存至少 5 分钟无活动后过期。

创建缓存后可以切换 TTL 吗？

不可以。缓存条目的 TTL 在首次写入时锁定，有效期内反复命中也只按原 TTL 免费续期。如需切换 TTL，等该条目完全过期后，再按新 TTL 重新写入。

什么时候会产生缓存未命中费用？

缓存按块存储，不足一整块的部分无法写入缓存，会计为缓存未命中，按缓存未命中（Input）价格计费。

账单和对账有什么变化？

控制台「财务管理 → 账户总览」页面底部的「月账单概览」支持导出每月账单 Excel，导出的表格新增「账单明细-缓存写入」sheet，按天展示 5m / 1h 各自的写入费用，以及项目、组织、API Key 等维度：
控制台「计费明细 → 请求明细」新增「写缓存 Tokens(5min)」和「写缓存 Tokens(1h)」两列，方便对账；输入 tokens = 缓存未命中 tokens + 缓存命中 tokens + 缓存写入 tokens：

以 Chat Completions API 为例，如需在代码中区分本次写入的 TTL 档位，可读取响应 Header：

Msh-Usage-Cache-Write-Tokens-5m：本次按 5m 档写入的 token 数；
Msh-Usage-Cache-Write-Tokens-1h：本次按 1h 档写入的 token 数。

本次请求全部命中、没有新增写入时，对应值为 0。

有地方能看缓存命中效果吗？

有。控制台新增 Caching 概览页，可以查看各模型在时间范围内的缓存命中 / 未命中 / 缓存写入 tokens 构成、缓存命中率，以及缓存写入摊销倍数（缓存命中 tokens ÷ 缓存写入 tokens，数值越大代表缓存越划算）。

开始使用

模型能力

工具调用

核心工作流

生态集成

调试与运维

使用 Kimi API 的上下文缓存功能

哪些内容适合缓存

上下文缓存能省多少钱

提高缓存命中率

选择合适的 TTL

如何设置缓存 TTL

查看缓存读写用量

常见问题

相关文档

Chat Completions API

Responses API

Messages API

模型推理价格说明

​哪些内容适合缓存

​上下文缓存能省多少钱

​提高缓存命中率

​选择合适的 TTL

​如何设置缓存 TTL

​查看缓存读写用量

​常见问题

​相关文档

Chat Completions API

Responses API

Messages API

模型推理价格说明

哪些内容适合缓存

上下文缓存能省多少钱

提高缓存命中率

选择合适的 TTL

如何设置缓存 TTL

查看缓存读写用量

常见问题

相关文档