先给结论:10 月 20 日加上的是 Responses API 里的最短缓存时间,不是到点删除。prompt_cache_options.ttl 省略时是 30m,写入按普通输入价的 1.25 倍计;写成 12h,写入按 2.5 倍计。这两个倍数是写入的总价,不是在普通输入之上再加一笔。读取两种时长一样:GPT-5.6 及以后多数模型是 0.1 倍,GPT-6.1 Sol 是 0.05 倍。账单看 cached_tokens、ttl_30m_tokens、ttl_12h_tokens。cache_write_tokens 已经是后两个之和,不能再加一次。
这篇按 2026 年 10 月 21 日写,依据前一天的 API 更新日志,以及仍挂在开发者站上的提示缓存指南。更新日志把这项标在 v1/responses。昨天本站写过《M3.1 Flash 的答案在哪个字段》。这里同样按字段读,不按一句「缓存命中了」读。
10 月 20 日实际加上了什么
更新日志写的是:现在可以在 API 里选择 12 小时提示缓存,让隔了几小时的请求仍按缓存输入价计费。指南把选择放在 Responses API 的 prompt_cache_options.ttl 上,对象是 GPT-5.6 及以后的模型。
| ttl | 最短时间 | 写入倍率 | 指南给的用途 |
|---|---|---|---|
30m,省略时的默认 | 30 分钟 | 普通输入价的 1.25 倍 | 对话和隔得很近的智能体步骤 |
12h | 12 小时 | 普通输入价的 2.5 倍 | 整天复用的说明和参考材料 |
OpenAI 可以比你要的最短时间留得更久。12h 不设定删除时刻,也不改数据保留政策的上限。它也不保证下一次一定复用到那份 KV,更不保证延迟更低。不支持的取值返回 400 invalid_request_error。这项不改旧模型上的 prompt_cache_retention:那是另一套参数,指南的对照表里,GPT-5.5 只用 24h,而且没有额外的写入倍率。
12h 写在哪条接口上
对照表把 12 小时写成「在 Responses API 里」。请求级 ttl 作用在隐式断点上,也作用在自己没写 ttl 的显式断点上。单个显式断点用 prompt_cache_breakpoint.ttl 覆盖。两个都不写,就是 30m。
Chat Completions 的创建接口参考仍把 prompt_cache_options.ttl 写成目前只接受 30m。把 12h 塞进 chat/completions,缓存指南没有这条出口。智能体 API 的模型调用跟 Responses 的缓存行为走同一套,但 10 月 20 日的日志点名的是 v1/responses。
一次请求最多写 4 个断点。隐式模式会占掉其中一个名额,显式断点就剩 3 个。mode 设成 explicit 且一个显式断点都没有时,这次请求不做提示缓存。GPT-5.6 及以后,可缓存前缀至少 1,024 个可见输入 token,OpenAI 自带的隐藏内容不计入这个下限。更早的模型上报 cached_tokens 时会向下取整到 128 的倍数;GPT-5.6 及以后按合格边界原数上报,隐藏 token 除外。
同一次请求里两种时长怎么计
一个断点覆盖它前面的整段前缀。同一次请求里,每个 token 只按覆盖它的已选写入中最长的那档计一次。后面如果有一个 12 小时写入,它前面、落在这段前缀里的断点也跟着变成 12 小时覆盖。指南给的四行是:
| 请求前的缓存 | 这次选的断点 | 读取 | 30 分钟写入 | 12 小时写入 |
|---|---|---|---|---|
| 没有 | 2,000 处 12h,再到 5,000 处 30m | 0 | 3,000 | 2,000 |
| 没有 | 2,000 处 30m,再到 5,000 处 12h | 0 | 0 | 5,000 |
| 前 2,000 仍在 30 分钟覆盖内 | 5,000 处 12h | 0 | 0 | 5,000 |
| 前 2,000 仍在 12 小时覆盖内 | 5,000 处 30m | 2,000 | 3,000 | 0 |
把仍有效的 30 分钟覆盖升级成 12 小时,会按 12 小时再写一次这些 token,早先那笔写入不退。已经在有效 12 小时条目里的部分仍按读取计。一次 30 分钟读取会把覆盖刷新到这次读取之后至少 30 分钟;如果用的是仍有效的 12 小时条目,保留「原到期时间」和「读取后再过 30 分钟」里更晚的那个。它不重新开始 12 小时,也不再收一笔写入。
usage 里这几个数字怎么加
支持 prompt_cache_options 的 Responses 模型,把写入拆进 input_tokens_details.cache_write_tokens_details。ttl_30m_tokens 和 ttl_12h_tokens 互不重叠,加起来等于 cache_write_tokens。两个字段都会返回,其中一个可以是 0。cached_tokens 只计按读取计费的 token,不含按写入计费的,包括从 30 分钟升级到 12 小时的那部分。
{
"usage": {
"input_tokens": 12000,
"input_tokens_details": {
"cached_tokens": 4000,
"cache_write_tokens": 7000,
"cache_write_tokens_details": {
"ttl_30m_tokens": 3000,
"ttl_12h_tokens": 4000
}
}
}
}
普通输入是 12000 - 4000 - 7000 = 1000。输入费用是:普通输入乘输入价,cached_tokens 乘缓存读取价,ttl_30m_tokens 乘 1.25 倍输入价,ttl_12h_tokens 乘 2.5 倍输入价,再除以 1,000,000。指南用每百万 1 美元的输入价、0.10 美元的缓存读取价,算出这组数字的输入费用是 0.01515 美元。GPT-6.1 Sol 的读取是 0.05 倍,不是这组示例里的 0.1 倍。同一组 token 数换成 0.05 倍读取,不能仍写成 0.01515。
命中不了,常常是前缀变了
缓存存的是 KV,不是 token 原文。整段渲染后的前缀必须一致。指南点名会改前缀的设置包括 model、tools、parallel_tool_calls、text.format(结构化输出会带上输出格式说明和你给的 schema)、reasoning.effort、text.verbosity,以及会改写前文的 context_management。schema 一变,从改动处往后就对不上旧条目。
缓存落在单台机器上。流量超过每分钟 15 次,可能被分流到没有这份条目的机器。缓存不跨组织,也不跨区域处理边界。GPT-5.6 及以后由 OpenAI 自动路由,prompt_cache_key 不再用来优化命中;它仍可用来把不同客户的用量分开记账。迁移说明写的是:从更早模型换到 GPT-5.6 及以后时,用 prompt_cache_options.ttl 替换 prompt_cache_retention。
要留下的是这张用量单
一次调用至少留下这些,而不是只留「命中了」:
{
"api": "responses",
"model": "gpt-6.1-sol",
"request_ttl": "30m",
"input_tokens": 12000,
"cached_tokens": 4000,
"cache_write_tokens": 7000,
"ttl_30m_tokens": 3000,
"ttl_12h_tokens": 4000,
"ordinary_input_tokens": 1000
}
ordinary_input_tokens 必须等于输入减去读取再减去写入。两个 ttl 字段必须加回 cache_write_tokens。对不上,就是把升级写入算进了读取,或把 cache_write_tokens 又加了一次。
常见问题 FAQ
Chat Completions 也能把 ttl 写成 12h 吗?
缓存指南把 12h 写在 Responses API 上。Chat Completions 的创建接口参考仍写着 ttl 目前只接受 30m。10 月 20 日的更新日志点名的是 v1/responses。
12h 是不是 12 小时后一定删掉?
不是。它是最短保留时间。OpenAI 可以留得更久。它不设定删除时刻,也不改数据保留政策的上限,也不保证下一次命中或更低延迟。
2.5 倍是在普通输入之外再加的费用吗?
不是。指南写明这是写入的总价。一个 token 若按 12 小时写入计费,就不再按普通输入价计一次。普通输入是 input_tokens 减去 cached_tokens 再减去 cache_write_tokens。
已经付过 30 分钟写入,升级到 12 小时会退那一笔吗?
不退。仍有效的 30 分钟覆盖升到 12 小时时,这些 token 按 12 小时再写一次。已经在有效 12 小时条目里的部分仍按读取计。
算账单时 cache_write_tokens 还要再加一次吗?
不要。它等于 ttl_30m_tokens 加 ttl_12h_tokens。两个分量按 1.25 倍和 2.5 倍分别乘输入价。再把 cache_write_tokens 加进去,写入就被算了两遍。
cached_tokens 大于 0 就代表这次更快吗?
指南写的是:最短时间决定能不能按读取价计费,不保证每次都复用到机器上的 KV,也不保证延迟更低。超过每分钟 15 次的流量还可能被分流到没有这份缓存的机器。
总结
10 月 20 日这项是 Responses API 上的最短时间选择。30 分钟写入 1.25 倍,12 小时写入 2.5 倍,读取仍是 0.1 倍或 Sol 的 0.05 倍。用量单把写入拆成两个 ttl 字段。把 cache_write_tokens 和这两个字段加在一起,账就重了。
schema、工具定义和模型名都会改前缀。留单时记下接口是 responses、请求里的 ttl,以及四个用量数字是否对得上减法。