Руководство по кэшированию контекста OpenAI

Для моделей GPT-5.6 и новее, поддерживающих эту функцию, задайте prompt_cache_options.ttl в запросе к Responses API, чтобы выбрать минимальное время хранения кэша: 30 минут или 12 часов. В примерах используется gpt-6.1-terra.

Кэш на 12 часов доступен только через /v1/responses, но не через /v1/chat/completions. TTL задаёт минимальное время хранения, а не срок удаления и не гарантию попадания в кэш при каждом запросе.

Задайте ключ API

export API_KEY="YOUR_API_KEY"

Длинный текст в примерах — заполнитель. Замените его реальным содержимым для повторного использования. Кэшируемый префикс должен содержать не менее 1 024 токенов; короткий заполнитель сам по себе не вызовет запись в кэш.

Кэш на 30 минут

Установите prompt_cache_options.ttl в "30m". Если ttl не указан, также используются 30 минут. Без mode применяется неявное кэширование: вышестоящий сервис автоматически выбирает точку кэширования.

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", сохранив остальную структуру запроса:

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".

Если задать mode: "explicit" без точки кэширования, чтения и записи в кэш не будет. У точки ниже нет собственного TTL, поэтому она наследует prompt_cache_options.ttl из запроса.

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. Фактические значения зависят от ответа.

{
  "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
  }
}

Обычные входные токены:

input_tokens - input_tokens_details.cached_tokens - input_tokens_details.cache_write_tokens

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.

Обзор

Модели

Текстовая серия

Серия изображений

Видеосерия

Аудиосерия

Серия модерации

Управление загрузками

Управление задачами

Управление аккаунтом

Руководство по кэшированию контекста OpenAI

Задайте ключ API

Кэш на 30 минут

Кэш на 12 часов

Один префикс для разных вопросов

Проверка использования кэша

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

​Задайте ключ API

​Кэш на 30 минут

​Кэш на 12 часов

​Один префикс для разных вопросов

​Проверка использования кэша

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

Задайте ключ API

Кэш на 30 минут

Кэш на 12 часов

Один префикс для разных вопросов

Проверка использования кэша

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