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,以及四個用量數字是否對得上減法。