К содержимому

Кэширование промптов API: ставки и поля usage

Модель может взять повторяющееся начало промпта из кэша. Чтение и запись кэша идут по отдельным ставкам.

Ставки кэша в каталоге

Колонка «Кэш» показывает ставку чтения за 1 млн токенов, а карточка модели ставку записи. Наличие ставки не подтверждает, что текущий маршрут использует кэш. В аудите 14 октября 2026 маршруты claude-opus-4.6, claude-opus-4.7 и claude-opus-4.8 возвращали ответы без расхода кэша; повторный промпт оплачивался как обычный вход.

Часть промптаСтавка
Некэшированный входставка входа
Прочитано из кэшаставка чтения кэша
Записано в кэшставка записи в кэш на 5 минут или на час

Запись оплачивается двумя ставками: cache_write_5m для кэша на 5 минут и cache_write_1h для кэша на час. Обе отдаёт GET /v1/models. Они могут совпадать, но это свойство текущих цен, а не правило: сверяйте оба поля.

Протокол OpenAI

В ответе /v1/chat/completions поле usage.prompt_tokens включает кэшированные токены. Прочитанные из кэша лежат в prompt_tokens_details.cached_tokens, записанные в prompt_tokens_details.cache_write_tokens. Шлюз вычитает их из prompt_tokens, остаток оплачивается по ставке входа. Так же устроен /v1/responses: токены из input_tokens_details вычитаются из input_tokens.

json
{
  "usage": {
    "prompt_tokens": 2300,
    "completion_tokens": 120,
    "prompt_tokens_details": {
      "cached_tokens": 2000,
      "cache_write_tokens": 200
    }
  }
}

Кэшируется ли промпт в этом протоколе, решает модель. Держите неизменную часть в начале сообщений.

Протокол Anthropic

В методе /v1/messages отметьте неизменный блок полем cache_control со значением {"type": "ephemeral"}. Шлюз оплачивает поля usage так, как они пришли: input_tokens по ставке входа, cache_read_input_tokens по ставке чтения, cache_creation_input_tokens по ставке записи. Из input_tokens ничего не вычитается.

cURL

bash
curl https://relay-llm.ru/v1/messages \
  -H "x-api-key: $RELAY_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 512,
    "system": [
      {
        "type": "text",
        "text": "STATIC_INSTRUCTIONS",
        "cache_control": {
          "type": "ephemeral"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "QUESTION"
      }
    ]
  }'

Ответ: usage

json
{
  "usage": {
    "input_tokens": 100,
    "cache_read_input_tokens": 2000,
    "cache_creation_input_tokens": 200,
    "output_tokens": 120
  }
}

Вместо MODEL_ID подставьте идентификатор модели из каталога. Примеры читают ключ из переменной окружения RELAY_API_KEY, адрес API уже подставлен.

Срок хранения задаётся полем ttl в cache_control. Если ответ раскладывает запись по срокам (поля cache_creation.ephemeral_5m_input_tokens и cache_creation.ephemeral_1h_input_tokens), шлюз берёт эту раскладку, а положительный остаток общей суммы сверх двух частей оплачивает по ставке часового кэша: при общей записи 1000 токенов, 100 на пять минут и 100 на час оплачиваются 100 токенов по ставке пяти минут и 900 по ставке часа. Если пришла одна общая сумма, она оплачивается по ставке часового кэша, когда хотя бы один блок запроса просит ttl: "1h", иначе по ставке пятиминутного.

Как читать расход

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

Если в ответе нет полей записи кэша, запись не оплачивается: итоговое списание не достраивает её по разметке cache_control. Оценка записи нужна только резерву, который откладывается с запасом и возвращается разницей после ответа.

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

Сверяйте расход по полям usage вашего ответа:

  • в протоколе OpenAI прочитанные и записанные токены вычитаются из входа;
  • в протоколе Anthropic поля оплачиваются как пришли, без вычитания.

Резерв и списание

Готовы? Три шага, чтобы начатьВойдите в консоль · пополните баланс · создайте API Key