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

> Используйте кэш на 30 минут или 12 часов через Responses API для повторного использования промптов, документов и префиксов диалога.

Для моделей GPT-5.6 и новее, поддерживающих эту функцию, задайте `prompt_cache_options.ttl` в запросе к [Responses API](https://docs.apimart.ai/ru/api-reference/texts/openai/responses.md), чтобы выбрать минимальное время хранения кэша: 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 токенов; короткий заполнитель сам по себе не вызовет запись в кэш.

## Кэш на 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"` и добавьте `prompt_cache_breakpoint` в блок `input_text` в конце постоянного содержимого. В примере используются 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`: Токены, прочитанные из кэша в этом запросе. Значение больше 0 означает, что кэш был прочитан.
* `cache_write_tokens`: Общее число токенов, записанных в кэш в этом запросе.
* `cache_write_tokens_details.ttl_30m_tokens`: Токены, записанные с TTL 30 минут в этом запросе.
* `cache_write_tokens_details.ttl_12h_tokens`: Токены, записанные с TTL 12 часов в этом запросе.

После первой записи отправьте ещё один запрос с тем же постоянным префиксом и проверьте `cached_tokens`. Значение может быть 0, если префикс слишком короткий, содержимое изменилось или попадания в кэш не произошло.

### Пример cache usage и подсчёт токенов

Этот фрагмент ответа показывает только `usage` для модели OpenAI с поддержкой кэша и записями для обоих TTL. Фактические значения зависят от ответа.

```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`. Два счётчика TTL — составные части `cache_write_tokens`. Не складывайте общий счётчик с его частями повторно и не добавляйте чтение и запись в кэш к общему входу.

Здесь обычный ввод равен `12000 - 4000 - 7000 = 1000`, запись — `5000 + 2000 = 7000`, а общее число токенов — `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.