3 ключевых момента тарификации кэширования Claude: почему необходимо использовать нативный формат Anthropic для вызова

{Кэширование промптов Claude}
{Тарификация кэширования поддерживает только вызовы в нативном формате Anthropic.}
{Нативный формат Anthropic}
{/v1/messages}
{✓}
{Кэширование промптов}
{✓}
{Расширенное мышление}
{✓}
{PDF / Цитаты}
{✓}
{Структурированные выходные данные}
{Попадание в кэш — всего 10% стоимости}
{Экономьте до 90%}
{Режим совместимости OpenAI}
{/v1/chat/completions}
{✗}
{Prompt Caching не поддерживается}
{!}
{Расширенное мышление (часть)}
{✗}
{PDF / Цитаты не поддерживаются}
{✗}
{Режим strict игнорируется}
{Скидка без кэширования}
{Ввод по полной цене}
{Источник данных: официальная документация Anthropic | Подготовлено технической командой APIYI apiyi.com}

Многие разработчики при использовании Claude API сталкиваются с одной и той же проблемой: вроде бы включили prompt caching, а скидки в счетах не видно.

Ответ обычно прост — вы используете режим совместимости с OpenAI, в то время как тарификация кэширования в Claude поддерживается только в нативном формате Anthropic Messages API.

Это не баг, а четко прописанное в официальной документации Anthropic ограничение. В этой статье мы разберем технические принципы, способы вызова и сравним цены, чтобы вы поняли, как правильно использовать Claude prompt caching и перестали переплачивать на ровном месте.

1. В чем корень проблемы?

Большинство сервисов-прокси API (включая APIYI) предоставляют два типа эндпоинтов для Claude:

1. Нативный формат Anthropic: /v1/messages
2. Режим совместимости с OpenAI: /v1/chat/completions

Режим совместимости очень удобен: вы просто меняете base_url и api_key в коде для ChatGPT, и всё работает. Однако за это удобство приходится платить функциональностью. Prompt caching требует передачи специальных заголовков и структуры метаданных, которые протокол OpenAI просто не поддерживает.

2. Как работает правильный вызов с кэшированием

Чтобы кэширование заработало и вы получили скидку, нужно использовать нативный SDK Anthropic или отправлять запросы в формате Messages API.

Главное условие — добавить маркер cache_control в ту часть промпта, которую вы хотите сохранить.

Пример на Python (нативный формат):

import anthropic

client = anthropic.Anthropic(
    api_key="ваш_ключ",
    base_url="https://api.apiyi.com/v1" # Используем прокси APIYI
)

response = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "Ты — эксперт-аналитик. Вот огромный документ для контекста...",
            "cache_control": {"type": "ephemeral"} # Вот здесь магия кэширования!
        }
    ],
    messages=[
        {"role": "user", "content": "Проанализируй этот документ."}
    ]
)

В режиме совместимости с OpenAI (/v1/chat/completions) вы просто не сможете передать параметр "cache_control": {"type": "ephemeral"} — API его проигнорирует, и вызов модели пройдет по полной стоимости.

3. Сравнение затрат: почему это важно

Давайте посчитаем на примере модели Claude 3.5 Sonnet:

• Без кэширования (или в режиме OpenAI): Каждый запрос с контекстом в 100 000 токенов будет стоить вам около $0.30 (при цене $3.00 за 1M токенов).
• С кэшированием (нативный формат):
  • Первый запрос (запись в кэш): ~$0.375 (на 25% дороже стандартного ввода).
  • Все последующие запросы (попадание в кэш): $0.03 (скидка 90%!).

Если вы делаете 100 запросов к одному и тому же длинному документу, разница в цене составит $30 против ~$3.5. Использование «неправильного» формата API в данном случае — это буквально сжигание денег.

4. Как проверить, работает ли кэш?

При использовании нативного формата в ответе API (usage) появятся дополнительные поля:

• cache_creation_input_tokens: сколько токенов было записано в кэш.
• cache_read_input_tokens: сколько токенов было считано из кэша (за них вы платите копейки).

Если в вашем ответе только input_tokens и output_tokens — кэширование не работает.

Итог

Если ваша задача — экономия и высокая производительность на длинных контекстах:

1. Забудьте про режим совместимости с OpenAI для Claude.
2. Переходите на нативный формат Anthropic Messages API.
3. Используйте надежный сервис-прокси, такой как APIYI, который полностью поддерживает все нативные функции Claude, включая prompt caching.

Начните оптимизировать свои расходы на ИИ уже сегодня вместе с APIYI.

Основные принципы механизма кэширования промптов Claude (Prompt Caching)

Прежде чем углубляться в различия форматов вызова, давайте разберемся, как именно работает кэширование промптов (prompt caching) в Claude.

Как работает кэширование в Claude

Когда вы отправляете запрос с включенным кэшированием промптов, система выполняет следующие действия:

1. Проверка кэша: Система проверяет, был ли префикс промпта из вашего запроса уже закэширован в недавних операциях.
2. Попадание в кэш (Cache Hit): Если совпадение найдено, используется закэшированная версия, что значительно сокращает время обработки и стоимость.
3. Запись в кэш (Cache Miss): Если совпадения нет, система обрабатывает промпт целиком и после начала генерации ответа кэширует указанный префикс.

Что можно кэшировать в Claude

Механизм prompt caching позволяет кэшировать большинство блоков контента в запросе:

• Tools: Определения инструментов в массиве tools.
• System messages: Блоки контента в массиве system.
• Text messages: Текстовые блоки в массиве messages.content.
• Images & Documents: Изображения и документы в сообщениях пользователя.
• Tool use & tool results: Блоки с вызовами инструментов и их результатами.

🎯 Технический совет: Для сценариев, требующих частого вызова одних и тех же системных промптов, prompt caching является самым эффективным способом оптимизации затрат. Мы рекомендуем использовать API Claude в нативном формате Anthropic через платформу APIYI (apiyi.com), чтобы в полной мере воспользоваться скидками на кэширование.

Нативный формат Anthropic vs Режим совместимости с OpenAI: различия в поддержке кэша

Это самая важная часть статьи — фундаментальная разница между двумя форматами вызова в контексте функции кэширования Claude.

Официальное заявление Anthropic

Согласно официальной документации Anthropic по совместимости с OpenAI SDK:

"Prompt caching is not supported, but it is supported in the Anthropic SDK"
(Кэширование промптов не поддерживается [в режиме совместимости], но поддерживается в Anthropic SDK)

Это означает, что если вы вызываете Claude через режим совместимости с OpenAI (эндпоинт /v1/chat/completions), вы вообще не сможете использовать функцию prompt caching.

Сравнение функциональности двух форматов вызова Claude API

Почему режим совместимости с OpenAI не поддерживает кэширование Claude

Режим совместимости с OpenAI предназначен скорее для тестирования и сравнения возможностей моделей, а не для использования в высоконагруженной рабочей среде:

1. Различия в протоколах: Параметр cache_control является нативным полем Anthropic Messages API, и в формате OpenAI Chat Completions для него просто нет соответствующего поля.
2. Архитектурные ограничения: Слой совместимости должен преобразовывать формат OpenAI в формат Anthropic, и в процессе этого преобразования информация об управлении кэшем теряется.
3. Приоритеты разработки: Anthropic заявляет, что приоритетом для них является надежность и полнота функций нативного API Claude, а не расширение возможностей слоя совместимости.

💡 Важное примечание: Если ваш бизнес полагается на prompt caching для контроля затрат, вы обязаны использовать нативный формат Anthropic Messages API, а не режим совместимости с OpenAI.

Подробный разбор цен на Claude Prompt Caching: экономия до 90% затрат

Структура ценообразования Claude Prompt Caching — это, пожалуй, его главная фишка. Стоимость чтения при попадании в кэш составляет всего 10% от базовой цены за входные токены.

Сравнение цен на кэширование для всех моделей Claude

MTok = миллион токенов. Источник данных: официальная страница цен Anthropic (февраль 2026 г.)

Правила расчета стоимости кэширования Claude

Ценообразование кэша строится на трех простых множителях:

• Запись в кэш на 5 минут: Базовая цена входа × 1.25
• Запись в кэш на 1 час: Базовая цена входа × 2.0
• Чтение из кэша (попадание): Базовая цена входа × 0.1

Возьмем для примера Claude Sonnet 4.6 и представим, что у вас есть системный промпт на 100 000 токенов:

💰 Оптимизация затрат: В сценариях с повторным использованием одного и того же системного промпта (system prompt), вызов модели Claude через платформу APIYI (apiyi.com) в нативном формате Anthropic позволяет в полной мере использовать prompt caching и экономить до 90% бюджета.

Практический код Claude Prompt Caching: вызов в нативном формате Anthropic

Ниже приведены примеры кода, показывающие, как правильно включить Claude prompt caching.

Пример базового вызова: нативный формат Anthropic + Extended Thinking

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 16000,
    "stream": false,
    "thinking": {
      "type": "enabled",
      "budget_tokens": 10000
    },
    "messages": [
      {
        "role": "user",
        "content": "Сколько будет 27 * 453?"
      }
    ]
  }'

Это обычный вызов в нативном формате Anthropic с использованием функции Extended Thinking. Теперь посмотрим, как на этой основе включить prompt caching.

Автоматический режим: самый простой способ включить кэш Claude

Автоматическое кэширование — это простейший путь. Нужно всего лишь добавить поле cache_control на верхнем уровне тела запроса:

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "Вы — профессиональный помощник по технической документации. Вы помогаете пользователям понять, как использовать ИИ-модели и лучшие практики. Ваши ответы должны быть точными, краткими и практичными.",
    "messages": [
      {"role": "user", "content": "Какие основные особенности у Claude Sonnet 4.6?"},
      {"role": "assistant", "content": "Claude Sonnet 4.6 — это высокопроизводительная модель от Anthropic..."},
      {"role": "user", "content": "Каков размер её контекстного окна?"}
    ]
  }'

В автоматическом режиме система сама установит точку кэширования на последнем блоке контента, который можно закэшировать. В многоэтапных диалогах точка кэша будет автоматически смещаться вперед по мере роста переписки.

Режим явного кэширования: точный контроль контента

Для сценариев, где требуется тонкая настройка кэша, можно разместить cache_control на конкретных блоках контента:

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Вы — помощник по анализу юридических документов, эксперт в разборе условий контрактов и правовых рисков."
      },
      {
        "type": "text",
        "text": "[Здесь размещается полный текст юридического контракта на 50 страниц... контент примерно на 100 000 токенов]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Пожалуйста, проанализируй ключевые условия и потенциальные риски в этом контракте."
      }
    ]
  }'

В этом примере огромный юридический документ помечен для кэширования. При первом запросе он запишется в кэш, а при последующих вопросах по этому же документу в течение 5 минут будет происходить попадание в кэш, и вы заплатите лишь 10% от стоимости чтения.

Долгосрочный кэш на 1 час: продление времени хранения Claude

Если стандартных 5 минут недостаточно, можно выбрать кэширование на 1 час:

"cache_control": {"type": "ephemeral", "ttl": "1h"}

Кэш на 1 час полезен для:

• Длительных задач в воркфлоу агентов (дольше 5 минут);
• Сценариев, где паузы в диалоге с пользователем могут превышать 5 минут;
• Случаев, когда нужно эффективнее использовать лимиты (попадания в кэш не расходуют rate limits).

🚀 Быстрый старт: Рекомендуем использовать платформу APIYI (apiyi.com) для быстрого тестирования функции Claude prompt caching. Платформа полностью поддерживает нативный формат Anthropic Messages API, включая параметр cache_control, что позволяет настроить и проверить интеграцию всего за 5 минут.

Мониторинг и отладка производительности кэширования промптов Claude

После включения кэширования необходимо отслеживать его эффективность с помощью поля usage в ответе API.

Ключевые поля в ответе Claude с использованием кэша

{
  "usage": {
    "input_tokens": 50,
    "cache_creation_input_tokens": 100000,
    "cache_read_input_tokens": 0,
    "output_tokens": 500
  }
}

Формула расчета общего количества входных токенов:

total_input = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Почему кэш не срабатывает: основные причины

Если вы заметили, что кэш постоянно промахивается (miss), проверьте следующие моменты:

1. Неверный формат вызова: используется режим совместимости с OpenAI вместо нативного формата Anthropic.
2. Несоответствие контента: для попадания в кэш префикс промпта должен совпадать на все 100%.
3. Недостаточно токенов: объем текста не достиг минимального порога модели для кэширования.
4. Истечение времени: кэш удаляется, если он не использовался более 5 минут.
5. Изменение параметров: поменялись tool_choice, изображения или параметры thinking.

Минимальные требования к количеству токенов для моделей Claude

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

🎯 Совет по отладке: при вызове Claude API через платформу APIYI (apiyi.com) можно быстро проверить работу кэша по полю usage в ответе. Если и cache_read_input_tokens, и cache_creation_input_tokens равны 0, значит, функция кэширования не была активирована должным образом.

Claude Prompt Caching: Часто задаваемые вопросы (FAQ)

Q1: Можно ли использовать кэширование при вызове Claude в режиме совместимости с OpenAI?

Нет. Это официальное ограничение Anthropic. Режим совместимости с OpenAI (эндпоинт /v1/chat/completions) не поддерживает prompt caching. Чтобы использовать функцию кэширования, вы должны использовать нативный формат Anthropic Messages API (эндпоинт /v1/messages).

Через платформу APIYI (apiyi.com) вы можете использовать оба формата для вызова Claude API — если вам нужно кэширование, просто выберите эндпоинт /v1/messages.

Q2: Запись в кэш Claude стоит дороже обычного ввода. Стоит ли оно того?

Определенно стоит. Запись в кэш всего на 25% дороже базового ввода (при TTL 5 минут), но каждое попадание в кэш (cache hit) стоит всего 10% от стандартной цены. Если один и тот же контент используется более 2 раз, вы уже начинаете экономить. Рассмотрим на примере системного промпта объемом 100 000 токенов:

• Без кэша: $0.30 за каждый вызов (Sonnet 3.5/4.6)
• Запись в кэш: $0.375 (только первый раз)
• Чтение из кэша: $0.03 (каждый последующий раз)
• Экономия начинается уже со второго вызова!

Q3: Как в коде перейти с формата OpenAI на нативный формат Anthropic?

Основные моменты при миграции:

• Эндпоинт: /v1/chat/completions → /v1/messages
• Заголовки: добавьте anthropic-version: 2023-06-01
• Формат сообщений: структура массива messages практически идентична
• Системный промпт: вынесите его из messages в отдельное поле system
• Параметры: добавьте объект cache_control

Платформа APIYI (apiyi.com) поддерживает оба эндпоинта, поэтому при переходе вам нужно лишь изменить путь запроса и формат данных, менять API-ключ не требуется.

Q4: Можно ли использовать один и тот же кэш в разных запросах?

Кэш разделяется внутри одного Workspace (с 5 февраля 2026 года уровень изоляции изменен с организации на Workspace). Между разными организациями кэш никогда не передается.

Q5: Можно ли использовать кэширование вместе с Batch API?

Да. Batch API предоставляет скидку 50%, и множители стоимости кэширования

Справочные материалы

1. Официальная документация Anthropic по Prompt Caching: Подробное описание функции кэширования в Claude API

   • Ссылка: platform.claude.com/docs/en/build-with-claude/prompt-caching

2. Официальная страница с ценами Anthropic: Стоимость моделей Claude и кэширования

   • Ссылка: platform.claude.com/docs/en/about-claude/pricing

3. Документация по совместимости с OpenAI SDK: Описание ограничений функционала в режиме совместимости

   • Ссылка: platform.claude.com/docs/en/api/openai-sdk

📝 Автор: APIYI Team | Техническая команда APIYI, специализирующаяся на интеграции API больших языковых моделей и обмене техническим опытом. Посетите apiyi.com, чтобы найти больше технических руководств.