OpenAI 10 月 20 日给 Responses API 加上 12 小时提示缓存之后,这笔账该看 usage 里的哪几个数字?

截至 2026 年 10 月 21 日:12 小时是 Responses API 上的最短缓存时间。30 分钟写入按 1.25 倍计,12 小时按 2.5 倍计。账单看 cached_tokens 和两个 ttl 字段。cache_write_tokens 不能再加一次。

先给结论: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 倍对话和隔得很近的智能体步骤
12h12 小时普通输入价的 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 处 30m03,0002,000
没有2,000 处 30m,再到 5,000 处 12h005,000
前 2,000 仍在 30 分钟覆盖内5,000 处 12h005,000
前 2,000 仍在 12 小时覆盖内5,000 处 30m2,0003,0000

把仍有效的 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 又加了一次。

  • JSON 校验 — 先确认这些字段都在,再核对两个 ttl 之和。
  • JSON Diff — 对比两次 usage,看多出来的是 12 小时写入还是普通输入。
  • JSONPath — 从一组响应里取出 ttl_12h_tokens 大于 0 的那些。

常见问题 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,以及四个用量数字是否对得上减法。