Модели OpenAI (GPT-4o и новее) поддерживают кэширование промптов. В базовом режиме никаких изменений в коде не нужно — кэширование работает прозрачно для всех запросов.
API запоминает начало (префикс) запроса. При следующем запросе с таким же началом уже обработанная часть переиспользуется со скидкой, что снижает задержку и стоимость.
Общие правила для обоих режимов:
- Кэшируются запросы длиной от 1 024 токенов
- Совпадение префикса должно быть точным — любое отличие сбрасывает кэш
- Кэшируется всё содержимое запроса: сообщения, изображения, описание инструментов, схемы structured output
Есть два режима кэширования — автоматический и ручной.
Доступен для всех моделей от GPT-4o и новее. Настраивать ничего не нужно: OpenAI сам ставит точку кэширования на конец запроса и кэширует подходящий префикс. Работает прозрачно для любых запросов.
Начиная с GPT-5.6 запись префикса в кэш стала платной (1.25× от входных токенов), поэтому появилась возможность управлять кэшированием вручную и не платить за лишние записи.
Режим задаётся параметром prompt_cache_options.mode:
implicit— автоматический режим (по умолчанию). OpenAI сам ставит точку кэширования на последнее сообщение и дополнительно учитывает ваши ручные точкиexplicit— ручной режим. Автоматическая точка отключается, кэшируются только явно отмеченные вами префиксы. Если ни одной точки не задано, запрос не кэшируется и записи в кэш не тарифицируются
Конец кэшируемого префикса отмечается полем prompt_cache_breakpoint: {"mode": "explicit"} внутри блока контента. Всё, что идёт до этой точки включительно, образует кэшируемый префикс; содержимое после неё можно менять, не сбрасывая кэш. За один запрос можно создать до 4 новых записей в кэш.
Для надёжного совпадения кэша на GPT-5.6 и новее обязательно передавайте prompt_cache_key.
{ "model": "gpt-5.6", "prompt_cache_key": "support-assistant-v1", "prompt_cache_options": { "mode": "explicit" }, "messages": [ { "role": "system", "content": [ { "type": "text", "text": "Длинный системный промпт (более 1024 токенов)...", "prompt_cache_breakpoint": { "mode": "explicit" } } ] }, { "role": "user", "content": "Вопрос пользователя" } ] }{ "model": "gpt-5.6", "prompt_cache_key": "support-assistant-v1", "prompt_cache_options": { "mode": "explicit" }, "input": [ { "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "Длинный контекст (более 1024 токенов)...", "prompt_cache_breakpoint": { "mode": "explicit" } }, { "type": "input_text", "text": "Вопрос пользователя" } ] } ] }
- Запись в кэш: бесплатно для моделей вплоть до GPT-5.5. Начиная с GPT-5.6 запись префикса тарифицируется как 1.25× от цены обычных входных токенов и отражается в поле
cache_write_tokensответа - Чтение из кэша: от 50% до 90% дешевле обычных входных токенов (зависит от модели: GPT-5 — 90%, GPT-4.1 — 75%, GPT-4o — 50%)
Кэш по умолчанию хранится в памяти 5–10 минут с момента последнего использования (до часа в периоды низкой нагрузки).
Для моделей от GPT-5 до GPT-5.5 доступен расширенный режим хранения — до 24 часов — через параметр prompt_cache_retention:
{ "model": "gpt-5.1", "input": "...", "prompt_cache_retention": "24h" }
Начиная с GPT-5.6 параметр prompt_cache_retention больше не используется. Вместо него минимальное время жизни задаётся через prompt_cache_options.ttl. Сейчас поддерживается единственное значение — 30m (оно же по умолчанию): кэшированный префикс остаётся доступным не менее 30 минут, но может храниться дольше.
- Располагайте статичное содержимое (системный промпт, инструкции, tools) в начале запроса
- Динамическую часть (вопрос пользователя) — в конце
- Порядок инструментов и изображений должен быть одинаковым между запросами
- Для запросов с общим длинным префиксом используйте параметр
prompt_cache_key— он улучшает маршрутизацию и повышает вероятность попадания в кэш (на GPT-5.6 и новее он обязателен для надёжного совпадения кэша)
Информация о кэшировании возвращается в поле usage ответа:
{ "usage": { "prompt_tokens": 2006, "completion_tokens": 300, "prompt_tokens_details": { "cached_tokens": 1920, "cache_write_tokens": 414 } } }
Значение cached_tokens показывает, сколько токенов было прочитано из кэша (тарифицируются со скидкой). Поле cache_write_tokens (только для GPT-5.6 и новее) показывает, сколько токенов было записано в кэш — они тарифицируются по ставке 1.25× от обычных входных токенов. Если cached_tokens равно 0 — запрос был обработан полностью с нуля.
Кэширование доступно для GPT-4o и всех более новых моделей, включая серии o1, o3, o4, GPT-5.
curl "https://api.proxyapi.ru/openai/v1/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <КЛЮЧ>" \ -d '{ "model": "gpt-4o", "messages": [ { "role": "system", "content": "Длинный системный промпт (более 1024 токенов)..." }, { "role": "user", "content": "Вопрос пользователя" } ] }'
curl "https://api.proxyapi.ru/openai/v1/responses" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <КЛЮЧ>" \ -d '{ "model": "gpt-4o", "input": [ { "role": "system", "content": "Длинный системный промпт (более 1024 токенов)..." }, { "role": "user", "content": "Вопрос пользователя" } ] }'
Отправьте два одинаковых запроса с интервалом в несколько секунд. Во втором ответе cached_tokens будет больше нуля — это означает, что кэш сработал и вы платите за эти токены дешевле.
