> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GPT 提示詞快取

> GPT 提示快取（Prompt Caching）用法與計費：GPT-5.6 系列 gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna 快取寫入按 1.25 倍輸入價、讀取按 0.1 倍計費，支援 prompt_cache_key 與顯式快取斷點，含介面範例與命中排查。

GPT 系列模型（gpt-4o 及之後）的提示快取（Prompt Caching）自動生效：請求前綴達到 1,024 Token、且與近期請求逐字一致時，命中部分按快取讀取價計費，同時降低首 Token 延遲。GPT-5.6 系列（`gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna`）對快取機制做了升級：快取寫入開始獨立計費（1.25 倍輸入價）、快取讀取為 0.1 倍輸入價、快取至少保留 30 分鐘，並新增 `prompt_cache_key` 可靠匹配與顯式快取斷點參數。

兩代模型的快取行為速覽：

|                    | GPT-5.6 之前                       | GPT-5.6 及之後                                   |
| :----------------- | :------------------------------- | :-------------------------------------------- |
| 快取方式               | 自動                               | 自動 + 顯式斷點                                     |
| 最小快取長度             | 1,024 Token                      | 1,024 Token                                   |
| 快取寫入計費             | 不另計費                             | 1.25x 基礎輸入價                                   |
| 快取讀取計費             | 按對應模型的快取讀取價                      | 0.1x 基礎輸入價                                    |
| 快取保留時間             | 不活躍 5–10 分鐘後清除，最長 1 小時           | 至少保留 30 分鐘                                    |
| `prompt_cache_key` | 可選，用於提高命中率                       | 官方要求設定，以啟用更可靠的快取匹配                            |
| 24 小時擴展保留          | 部分模型支援（`prompt_cache_retention`） | 由 `prompt_cache_options.ttl` 取代，當前僅支援 `"30m"` |

## 快速開始

提示快取無需額外設定：用相同的長前綴連續請求兩次，第二次回應的 `usage.prompt_tokens_details.cached_tokens` 大於 0 即為命中。GPT-5.6 系列建議同時設定 `prompt_cache_key`：

<CodeGroup>
  ```shell Curl theme={null}
  curl https://aihubmix.com/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -d '{
      "model": "gpt-5.6-sol",
      "prompt_cache_key": "my-app-report-assistant-v1",
      "messages": [
        {
          "role": "system",
          "content": "You are a meticulous assistant for analyzing quarterly financial reports... [此處放置固定不變的長指令或參考資料，≥1024 Token]"
        },
        {
          "role": "user",
          "content": "Summarize the key figures in one sentence."
        }
      ]
    }'
  ```

  ```py Python (OpenAI SDK) theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AIHUBMIX_API_KEY"],  # 金鑰從環境變數讀取
      base_url="https://aihubmix.com/v1",
  )

  long_context = "You are a meticulous assistant for analyzing quarterly financial reports... [固定不變的長指令或參考資料，≥1024 Token]"

  # 相同前綴連續請求兩次，第二次命中快取
  for i in range(2):
      completion = client.chat.completions.create(
          model="gpt-5.6-sol",
          prompt_cache_key="my-app-report-assistant-v1",
          messages=[
              {"role": "system", "content": long_context},
              {"role": "user", "content": "Summarize the key figures in one sentence."},
          ],
      )
      print(completion.usage.prompt_tokens_details)
  ```
</CodeGroup>

兩次呼叫的實測 usage（2026-07-10，`gpt-5.6-sol`）：

```json theme={null}
// 第 1 次呼叫：無命中
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 0}

// 第 2 次呼叫：前綴命中快取
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 2816}
```

## 快取計費

GPT-5.6 系列的快取計費規則：

| 計費項        | 費率          |
| :--------- | :---------- |
| 常規輸入 Token | 按平台定價       |
| 快取寫入 Token | 1.25x 基礎輸入價 |
| 快取讀取 Token | 0.1x 基礎輸入價  |
| 輸出 Token   | 按平台定價       |

OpenAI 官方對該規則的表述（出自 [GPT-5.6 發布公告](https://openai.com/index/gpt-5-6/)）："For GPT‑5.6 and later models, cache writes are billed at 1.25x the model's uncached input rate, while cache reads continue to receive the 90% cached-input discount."。[官方提示快取指南](https://developers.openai.com/api/docs/guides/prompt-caching)中該倍率的適用範圍表述為 "GPT-5.6 models and later model families"（GPT-5.6 及之後的模型家族）。各模型的官方標價見 [OpenAI Pricing](https://developers.openai.com/api/docs/pricing)，AIHubMix 實際價格以[模型廣場](https://aihubmix.com/models)為準。

由官方倍率可以直接算出損益：寫入一段前綴比不快取多付 0.25 倍輸入價，此後每命中一次省 0.9 倍輸入價。前綴只要被重複使用 1 次即淨節省；重複使用次數越多節省越多。前綴完全不會重複使用的一次性請求會多付寫入費，可以用 explicit 模式關閉快取（見下文「GPT-5.6 快取參數」）。

GPT-5.6 之前的模型快取寫入不另計費，快取讀取按對應模型的快取讀取價計費，各模型價格以[模型廣場](https://aihubmix.com/models)為準。

<Note>
  GPT-5.6 系列區分長短上下文檔位：單次請求輸入超過 272K Token 時，整個請求按長上下文檔位計費（輸入 2 倍、輸出 1.5 倍）。快取寫入 1.25x、讀取 0.1x 的倍率在長上下文檔位下同樣成立，基數為長上下文檔位的輸入價。
</Note>

## 快取如何自動生效

發送請求時，系統會檢查請求前綴（按 messages、tools 等序列化後的順序）是否與近期請求的前綴逐字一致：

1. 前綴達到 1,024 Token 且找到一致的快取前綴時，命中部分按快取讀取價計費，並降低首 Token 延遲；
2. 未找到時按常規輸入處理，並把前綴寫入快取（GPT-5.6 及之後按 1.25x 計寫入費）；
3. 命中要求前綴逐位元組一致，前綴中任何一處變化都會使該位置之後的快取全部失效。

以下場景收益最明顯：

* 固定的長系統指令或大量 few-shot 範例
* RAG 場景中重複引用的長參考資料
* 攜帶大量工具定義（tools）的 Agent 工作流
* 只往後追加訊息的長多輪對話

快取保留時間：GPT-5.6 之前的模型在不活躍 5–10 分鐘後清除、最長 1 小時；GPT-5.6 及之後至少保留 30 分鐘，實際可能保留更久。快取不跨組織共享，且快取對輸出內容沒有影響。

## GPT-5.6 快取參數

GPT-5.6 系列新增了三個快取相關參數（Chat Completions 與 Responses API 通用）：

| 參數                        | 類型 / 位置      | 取值                                                     | 預設                              |
| :------------------------ | :----------- | :----------------------------------------------------- | :------------------------------ |
| `prompt_cache_key`        | string，請求頂層  | 自訂穩定識別碼，建議按業務或租戶劃分；單個 key 的總流量建議控制在約 15 次/分鐘內          | 無                               |
| `prompt_cache_options`    | object，請求頂層  | `mode`: `"implicit"` / `"explicit"`；`ttl`: 僅支援 `"30m"` | `mode: "implicit"`、`ttl: "30m"` |
| `prompt_cache_breakpoint` | object，內容區塊內 | `{"mode": "explicit"}`，標記快取前綴的結束位置                     | 不設定斷點                           |

GPT-5.6 之前的模型不支援這三個參數中的 `prompt_cache_options` 與 `prompt_cache_breakpoint`，請求會被拒絕；舊模型的 24 小時擴展保留參數 `prompt_cache_retention`（`"24h"` / `"in_memory"`）在 GPT-5.6 及之後由 `prompt_cache_options.ttl` 取代。

三種快取控制方式的關係：

1. **預設（implicit 模式）**：不傳任何快取參數也會自動寫快取——系統在最新一條訊息的位置自動設定斷點。GPT-5.6 及之後，自動發生的快取寫入同樣按 1.25x 計費。
2. **implicit 模式 + 顯式斷點**：在自動斷點之外，可在內容區塊上設定 `prompt_cache_breakpoint`，把快取邊界固定在穩定內容的末尾；斷點之後的內容變化不會破壞斷點之前的前綴快取。
3. **explicit 模式**：`prompt_cache_options.mode` 設為 `"explicit"` 後只使用手動斷點；完全不設定斷點時該請求不使用快取、也不產生快取寫入費。[官方原文](https://developers.openai.com/api/docs/guides/prompt-caching)："If the conversation contains no explicit breakpoints, the request does not use prompt caching or incur cache-write charges."

用 explicit 模式關閉一次性長請求的快取寫入費：

```json theme={null}
{
  "model": "gpt-5.6-sol",
  "prompt_cache_options": {"mode": "explicit"},
  "messages": [
    {"role": "user", "content": "[不會重複使用的一次性長內容]"}
  ]
}
```

顯式斷點的官方規範用法（斷點設定在固定長內容區塊的末尾）：

```json theme={null}
{
  "model": "gpt-5.6-sol",
  "prompt_cache_key": "my-app-report-assistant-v1",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "[固定不變的長指令或參考資料，≥1024 Token]",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        }
      ]
    },
    {"role": "user", "content": "Summarize the key figures in one sentence."}
  ]
}
```

硬約束（官方口徑）：

* 每個請求最多建立 4 個新的快取寫入；implicit 模式下自動斷點佔用其中 1 個；
* 斷點之前的前綴仍需達到 1,024 Token 才會被快取；
* 讀取時在最近 50 個斷點中取最長匹配前綴；
* 斷點設定在不支援的內容區塊上會返回 `400 invalid_request_error`。Chat Completions 支援 `text` / `image_url` / `input_audio` / `file` / `refusal` 區塊，Responses API 支援 `input_text` / `input_image` / `input_file` 區塊。

<Note>
  AIHubMix 對 `prompt_cache_breakpoint` 內容區塊斷點及 Responses API 快取命中的支援正在完善中。現階段推薦透過 Chat Completions 使用自動快取並設定 `prompt_cache_key`（本頁快速開始範例，已驗證可命中）；`prompt_cache_options` 的 explicit 模式可正常用於關閉快取寫入。本頁將隨支援進度更新。
</Note>

## 為什麼快取沒有命中

命中要求斷點位置之前的所有內容逐位元組一致。第二次請求 `cached_tokens` 仍為 0 時，按以下清單排查：

* **前綴不足 1,024 Token**：低於最小快取長度的請求按常規輸入處理；
* **前綴中混入了變化內容**：時間戳、會話 ID、使用者變數等應放到固定內容之後，前綴中任何一處變化都會使之後的快取失效；
* **tools 定義或順序變化**：工具列表參與前綴計算，定義與排列順序都必須完全一致；
* **圖片 detail 參數不一致**：`detail` 影響圖片 Token 化結果，需保持相同；
* **結構化輸出 schema 變化**：`response_format` 的 JSON Schema 作為系統訊息前綴參與快取，schema 變化即前綴變化；
* **`reasoning_effort` 變化**：官方將其列為快取命中率降低的常見原因之一（"Changes to reasoning effort"）；
* **超過快取保留期**：GPT-5.6 之前不活躍 5–10 分鐘後清除，GPT-5.6 及之後至少保留 30 分鐘；
* **未設定 `prompt_cache_key`（GPT-5.6）**：不設定時仍可能自動命中，但不使用更可靠的匹配機制。

## 最佳實踐

* 固定內容（系統指令、範例、參考資料、工具定義）放在請求最前面，每輪變化的內容放在最後；
* 為共享同一前綴的流量設定同一個穩定的 `prompt_cache_key`，單個 key 的總流量控制在約 15 次/分鐘內，超出時按業務拆分更多 key；
* 多輪對話只向後追加訊息，避免修改歷史訊息；
* 保持相同前綴的請求有持續流量，減少快取被清除；
* 前綴不會重複使用的一次性長請求，用 explicit 模式避免快取寫入費（GPT-5.6 及之後）；
* 透過 `usage.prompt_tokens_details.cached_tokens` 持續監控命中情況。

## 常見問題

### GPT 的提示快取需要手動開啟嗎？

無需手動開啟：前綴達到 1,024 Token 即自動快取。GPT-5.6 及之後建議同時設定 `prompt_cache_key` 以獲得更可靠的快取匹配。

### GPT-5.6 的快取寫入費如何計算？如何避免不必要的寫入費？

快取寫入按基礎輸入價的 1.25 倍計費，讀取按 0.1 倍計費；前綴被重複使用 1 次即淨節省。前綴不會重複使用的一次性長請求，把 `prompt_cache_options.mode` 設為 `"explicit"` 且不設定斷點，該請求即不使用快取、不產生寫入費。

### 快取能保留多久？

GPT-5.6 及之後至少保留 30 分鐘（`ttl` 當前僅支援 `"30m"`，實際可能保留更久）；GPT-5.6 之前的模型在不活躍 5–10 分鐘後清除、最長 1 小時，部分舊模型支援 `prompt_cache_retention: "24h"` 擴展保留。

### GPT-5.6 的顯式斷點和 Claude 的 cache\_control 有什麼區別？

兩者都用於把快取邊界固定在穩定內容末尾。主要區別：GPT-5.6 無需任何參數即自動快取、斷點為可選精細控制，Claude 需在請求中啟用快取（頂層 `cache_control` 自動斷點或內容區塊級顯式斷點）；GPT-5.6 快取至少保留 30 分鐘，Claude 預設 5 分鐘、可選 1 小時；兩者的快取讀取都按 0.1 倍輸入價計費。Claude 的用法見 [Claude 提示詞快取](/zh-Hant/api/Claude-Cache)。

### 快取會影響輸出內容嗎？

沒有影響。官方口徑：提示快取只影響輸入側的處理與計費，模型生成輸出的方式與不使用快取時完全相同。

## 官方參考

本頁機制、倍率與參數口徑均來自以下 OpenAI 官方來源：

* [GPT-5.6 發布公告](https://openai.com/index/gpt-5-6/)：快取寫入 1.25x / 讀取 90% 折扣的計費規則
* [提示快取指南](https://developers.openai.com/api/docs/guides/prompt-caching)：機制、參數、usage 欄位與限制
* [OpenAI Pricing](https://developers.openai.com/api/docs/pricing)：各模型官方標價
* [GPT-5.6 模型文件](https://platform.openai.com/docs/models/gpt-5.6-sol)：上下文視窗、長上下文計費閾值

AIHubMix 各模型實際價格以[模型廣場](https://aihubmix.com/models)為準。

***

最後更新：2026-07-10