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

# OpenAI 上下文缓存使用指南

> 通过 Responses API 使用 30 分钟或 12 小时缓存，复用固定提示词、文档和对话前缀。

对于支持此功能的 GPT-5.6 及以后模型，在 [Responses API](https://docs.apimart.ai/cn/api-reference/texts/openai/responses.md) 请求中设置 `prompt_cache_options.ttl`，即可选择 30 分钟或 12 小时的最短缓存保留时间。本文使用 `gpt-6.1-terra` 演示。

> [!NOTE]
>
> 12 小时缓存仅支持 `/v1/responses`，不支持 `/v1/chat/completions`。TTL 表示最短缓存保留时间，不表示到期立即删除，也不保证每次请求都命中缓存。

## 准备 API 密钥

```bash theme={null}
export API_KEY="YOUR_API_KEY"
```

> [!NOTE]
>
> 示例中的长文本是占位内容。请替换为实际需要复用的内容，待缓存前缀至少需要 1,024 token。直接使用这段短占位文本不会触发缓存写入。

## 使用 30 分钟缓存

将 `prompt_cache_options.ttl` 设置为 `"30m"`。省略 `ttl` 时也使用 30 分钟；省略 `mode` 时默认使用隐式缓存，由上游自动选择缓存断点。

```bash theme={null}
curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "30m"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'
```

## 使用 12 小时缓存

将同一字段改为 `"12h"`，其余请求结构保持一致：

```bash theme={null}
curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'
```

## 固定前缀、不同问题：使用显式断点

如果每次请求都复用同一份长文档，只改变最后的问题，将 `mode` 设置为 `"explicit"`，并在固定内容末尾的 `input_text` 块上添加 `prompt_cache_breakpoint`。下面使用 12 小时缓存；改用 30 分钟时，将请求中的 `ttl` 改为 `"30m"`。

> [!NOTE]
>
> 只设置 `mode: "explicit"` 而不添加断点，不会读取或写入缓存。下面的断点未单独设置 TTL，因此继承请求级 `prompt_cache_options.ttl`。

```bash theme={null}
curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h",
    "mode": "explicit"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)...",
          "prompt_cache_breakpoint": {
            "mode": "explicit"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Summarize the three main points in the reference material."
        }
      ]
    }
  ]
}'
```

后续请求继续发送相同的模型、固定前缀和断点，只修改最后一条用户消息。保持前缀内容、顺序及影响上下文的设置一致；无需另行创建或传入缓存 ID。

## 查看缓存是否生效

检查响应中的 `usage.input_tokens_details`：

* `cached_tokens`: 本次从缓存读取的 token 数，大于 0 表示发生了缓存读取。
* `cache_write_tokens`: 本次写入缓存的 token 总数。
* `cache_write_tokens_details.ttl_30m_tokens`: 本次按 30 分钟 TTL 写入的 token 数。
* `cache_write_tokens_details.ttl_12h_tokens`: 本次按 12 小时 TTL 写入的 token 数。

首次写入后，再次请求时保持同一稳定前缀，并检查 `cached_tokens`。前缀过短、内容变化或缓存未命中时，读取量可能为 0。

### 缓存 usage 示例与统计口径

下面是支持 OpenAI 缓存的模型同时包含两档写入时的响应片段，仅展示 `usage`；具体数值以实际返回为准。

```json theme={null}
{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 5000,
        "ttl_12h_tokens": 2000
      }
    },
    "output_tokens": 1000,
    "total_tokens": 13000
  }
}
```

普通输入量:

```text theme={null}
input_tokens - input_tokens_details.cached_tokens - input_tokens_details.cache_write_tokens
```

```text theme={null}
cache_write_tokens = ttl_30m_tokens + ttl_12h_tokens
total_tokens = input_tokens + output_tokens
```

读写缓存已包含在 `input_tokens` 中。两档写入量是 `cache_write_tokens` 的拆分，不要把总量与明细再次相加，也不要把读写缓存加到总输入量上。

本例普通输入为 `12000 - 4000 - 7000 = 1000`；写入量为 `5000 + 2000 = 7000`；总 token 数为 `12000 + 1000 = 13000`。

缓存行为参考 [OpenAI 官方缓存指南](https://developers.openai.com/api/docs/guides/prompt-caching)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.