Кэширование промптов в Claude API: как оно работает и сколько экономит

Что кэширование промптов делает со счётом за Claude API

Кэширование промптов говорит Anthropic сохранить переиспользуемый префикс вашего запроса — всё до заданной вами точки cache_control, — чтобы следующий запрос с тем же префиксом прочитал его из кэша, а не обрабатывал заново. Чтение из кэша стоит долю от свежих входных токенов, а запись в кэш идёт с небольшой надбавкой к входной цене. Если приложение каждый раз отправляет один и тот же большой контекст (системный промпт, снимок кодовой базы, набор документов), кэширование превращает самую дорогую часть каждого вызова в самую дешёвую.

Запись в кэш и чтение из него тарифицируются отдельными корзинами токенов в ответе API и в вашем счёте, так что всегда видно, сколько именно сэкономил кэш. Сам ответ при этом не меняется — та же модель, то же качество, тот же стриминг.

Читайте также: Как экономить токены в Claude API

Где ставить брейкпоинты cache_control в запросе

Если cache_control отсутствует или везде равен null, запрос Claude автоматически получает prompt cache на пять минут. Добавьте маркер cache_control, когда нужен точный брейкпоинт нативного Messages. Всё до маркера — системный промпт, определения инструментов, предыдущие сообщения — становится кэшируемым префиксом. Вот реальный запрос к apiToken.sale с закэшированным системным промптом:

curl https://router.apitoken.sale/v1/messages \
  -H "x-api-key: sk-pool-•••" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are a senior reviewer... (long stable instructions)",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [{"role": "user", "content": "Review this diff: ..."}]
  }'

• На запрос можно поставить до четырёх брейкпоинтов cache_control — типичная раскладка: один после инструментов, один после системного промпта и один после большого справочного документа.
• Кэш сопоставляет префиксы точно, начиная с первого токена. Измените один символ в системном промпте — и всё после него промахнётся мимо кэша.
• Сохраняются только блоки больше минимального кэшируемого размера — около 1 024 токенов на моделях Sonnet и Opus и больше на Haiku. Короткие промпты молча пропускают кэширование.
• Изменчивый контент (метки времени, данные конкретного пользователя) размещайте после последнего брейкпоинта, никогда — внутри префикса.

Кеширование Claude из OpenAI-совместимого клиента

Модели Claude используют один путь prompt cache через нативный Messages, Chat Completions и Responses. На OpenAI-совместимых путях передавайте cache_control как верхнеуровневое пользовательское расширение запроса. Не помещайте брейкпоинт Anthropic внутрь OpenAI message или input part: эти части переводятся. Если расширение отсутствует, apiToken.sale добавляет автоматический cache на пять минут после перевода.

• Для TTL 1 час передайте cache_control: {type: "ephemeral", ttl: "1h"} и заголовок anthropic-beta: extended-cache-ttl-2025-04-11.
• В OpenAI SDK передайте расширение через extra_body, а beta-заголовок — через extra_headers.
• Chat Completions показывает попадания в usage.prompt_tokens_details.cached_tokens.
• Responses показывает попадания в usage.input_tokens_details.cached_tokens.
• Расширение действует только для модели из catalog plane anthropic/*. Модели OpenAI и Gemini сохраняют собственное поведение prompt cache.

Цены на запись и чтение кэша

Anthropic оценивает операции с кэшем как множители к входной ставке модели. Запись — разовая надбавка за кэшируемый блок; чтение — то место, где деньги возвращаются. На apiToken.sale единая скидка 50% для B2C применяется к каждой строке использования, включая кэш-строки, уже после расчёта официальных затрат.

По умолчанию запись в кэше живёт пять минут, и таймер сбрасывается при каждом попадании, поэтому активная сессия держит кэш тёплым сколь угодно долго. Часовой TTL доступен за более высокую цену записи — для нагрузок со всплесками. Чтение из кэша стоит одну десятую свежего ввода — и одну двадцатую после применения скидки, — так что префикс, прочитанный трижды за время жизни TTL, уже дешевле, чем отправить его свежим дважды.

Записи кэша не разделяются между аккаунтами и никогда не протекают между клиентами apiToken.sale. Ваш закэшированный префикс переиспользуется только запросами, аутентифицированными в контексте того же апстрим-аккаунта.

Какие нагрузки попадают в кэш — а какие никогда

• Кодинг-агенты и ассистенты в IDE, которые с каждым ходом пересылают тот же контекст репозитория, CLAUDE.md и схемы инструментов.
• RAG-пайплайны по фиксированному набору документов — кэшируйте корпус, меняйте только вопрос.
• Чат-боты с длинными стабильными системными промптами и библиотеками few-shot примеров.
• Пакетные задачи, классифицирующие или извлекающие данные из множества коротких элементов по одному большому блоку инструкций.

Кэширование ничего не даёт разовым вопросам, промптам, которые меняются на каждом вызове, и префиксам ниже минимального размера. Если каждый запрос действительно уникален, вы платите надбавку за запись и никогда не получаете чтения — измерьте, прежде чем включать кэш вслепую.

Как подтвердить попадания в кэш в объекте usage

Каждый ответ Messages API отчитывается о кэш-строках прямо в блоке usage. Тёплый кэш выглядит так:

"usage": {
  "input_tokens": 38,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 14802,
  "output_tokens": 412
}

Следите за cache_read_input_tokens между запросами: в здоровой интеграции после первого вызова бо́льшая часть контекста приземляется именно туда, а cache_creation_input_tokens остаётся около нуля, пока не истечёт TTL. На apiToken.sale те же строки видны в панели: каждый запрос указан с моделью, провайдером и разбивкой до уровня токенов, и каждая кэш-строка отражена в детализации использования — экономия проверяема, а не подразумевается.

Кэш плюс предоплаченная скидка

Кэширование снижает количество токенов, за которые вы платите полную цену; скидка apiToken.sale снижает цену за токен. Они перемножаются. Конкретная математика на Claude Sonnet 5 (официально $2 за 1M входных токенов): пересылка контекста в 100 000 токенов свежим стоит $0.20 за вызов. Из кэша — $0.02, а после единой скидки 50% для B2C контекстная часть вызова опускается до $0.01 — снижение в 20 раз на той части счёта, которая раньше его доминировала.

Биллинг остаётся предоплаченным и простым: один баланс покрывает поддерживаемые модели Claude, GPT, Gemini и Kimi, каждая тарифицируется по своей официальной карте ставок до применения скидки. Пополните один раз — и хорошо закэшированная нагрузка растянет тот же баланс гораздо дальше некэшированного трафика.

Ставки на вход, выход и кэш по каждой модели →

Смоделируйте закэшированную нагрузку в калькуляторе стоимости Claude API →

Частые вопросы

Похожие гайды