> ## 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 Context Caching Guide

> Use 30-minute or 12-hour caching through the Responses API to reuse stable prompts, documents, and conversation prefixes.

For GPT-5.6 and later models that support this feature, set `prompt_cache_options.ttl` in a [Responses API](https://docs.apimart.ai/en/api-reference/texts/openai/responses.md) request to select a minimum cache lifetime of 30 minutes or 12 hours. These examples use `gpt-6.1-terra`.

> [!NOTE]
>
> 12-hour caching is supported only by `/v1/responses`, not `/v1/chat/completions`. TTL specifies a minimum cache lifetime, not a deletion deadline or a guarantee that every request hits the cache.

## Set your API key

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

> [!NOTE]
>
> The long text in these examples is a placeholder. Replace it with the content you want to reuse. The cacheable prefix must contain at least 1,024 tokens; the short placeholder alone will not trigger a cache write.

## Use 30-minute caching

Set `prompt_cache_options.ttl` to `"30m"`. Omitting `ttl` also selects 30 minutes. Omitting `mode` uses implicit caching, where the upstream service selects the cache breakpoint automatically.

```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."
        }
      ]
    }
  ]
}'
```

## Use 12-hour caching

Change the same field to `"12h"` and keep the rest of the request structure unchanged:

```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."
        }
      ]
    }
  ]
}'
```

## Reuse a fixed prefix with different questions

To reuse a long document while changing only the final question, set `mode` to `"explicit"` and add `prompt_cache_breakpoint` to the `input_text` block at the end of the fixed content. This example uses 12 hours; change the request TTL to `"30m"` for 30 minutes.

> [!NOTE]
>
> Setting `mode: "explicit"` without adding a breakpoint disables cache reads and writes. The breakpoint below has no separate TTL, so it inherits the request-level `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."
        }
      ]
    }
  ]
}'
```

Send the same model, fixed prefix, and breakpoint on subsequent requests, changing only the final user message. Keep the prefix content, ordering, and context-affecting settings consistent. You do not need to create or pass a cache ID.

## Check cache usage

Inspect `usage.input_tokens_details` in the response:

* `cached_tokens`: Tokens read from the cache for this request. A value above 0 indicates a cache read.
* `cache_write_tokens`: Total tokens written to the cache for this request.
* `cache_write_tokens_details.ttl_30m_tokens`: Tokens written with a 30-minute TTL for this request.
* `cache_write_tokens_details.ttl_12h_tokens`: Tokens written with a 12-hour TTL for this request.

After the initial write, send another request with the same stable prefix and check `cached_tokens`. Reads can be 0 if the prefix is too short, the content changes, or the request misses the cache.

### Cache usage example and token counting

This response excerpt shows only `usage` for an OpenAI model that supports caching, with writes at both TTLs. Actual counts depend on the response.

```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
  }
}
```

Ordinary input tokens:

```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
```

Cache reads and writes are already included in `input_tokens`. The two TTL counts are components of `cache_write_tokens`: do not add the total and its components again, or add cache reads and writes to total input.

Here, ordinary input is `12000 - 4000 - 7000 = 1000`, writes are `5000 + 2000 = 7000`, and total tokens are `12000 + 1000 = 13000`.

See the [official OpenAI prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) for cache behavior.


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