Кэширование и тарификация Claude

В отличие от автоматического кэширования у GPT/Gemini, кэширование подсказок в нативном интерфейсе Claude является явно объявляемым:
помечайте блоки контента, которые нужно кэшировать, с помощью cache_control. После попадания в кэш эта часть тарифицируется по коэффициенту кэша.

Использование

Добавьте cache_control к system или к блоку содержимого сообщения:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<несколько тысяч символов правил или базы знаний>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "Ответь согласно правилам:……" }]
}

Проверка попадания

В usage ответа:

{
  "usage": {
    "input_tokens": 42,
    "cache_creation_input_tokens": 4810,
    "cache_read_input_tokens": 0,
    "output_tokens": 213
  }
}

При первом вызове: cache_creation_input_tokens учитывается при создании кэша (чуть дороже стандартной цены);
При последующих попаданиях: cache_read_input_tokens тарифицируется по коэффициенту кэша (значительно дешевле стандартной цены);
Срок жизни кэша — в пределах нескольких минут, при продолжении вызовов он автоматически продлевается.

Практические рекомендации

Размещайте точку кэша после длинного и стабильного содержимого: системных подсказок, определений инструментов, справочной документации;
Кэшируемое содержимое должно быть идентичным побайтно; не включайте в шаблон изменяющиеся поля, такие как временные метки;
Низкочастотные вызовы (с интервалом больше срока жизни кэша) не будут попадать в кэш, а повторное создание кэша будет только дороже —
в сценариях с низкой частотой просто не добавляйте cache_control;
При вызове Claude через OpenAI-совместимый интерфейс кэширование обрабатывается автоматически на стороне вышестоящего уровня, и этот параметр не нужен,
см. Кэширование и тарификация。