Кэширование промптов 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 /. Они могут совпадать, но это свойство текущих цен, а не правило: сверяйте оба поля.
Протокол OpenAI
В ответе / поле usage.prompt_tokens включает кэшированные токены. Прочитанные из кэша лежат в prompt_tokens_details.cached_tokens, записанные в prompt_tokens_details.cache_write_tokens. Шлюз вычитает их из prompt_tokens, остаток оплачивается по ставке входа. Так же устроен /: токены из input_tokens_details вычитаются из input_tokens.
{
"usage": {
"prompt_tokens": 2300,
"completion_tokens": 120,
"prompt_tokens_details": {
"cached_tokens": 2000,
"cache_write_tokens": 200
}
}
}Кэшируется ли промпт в этом протоколе, решает модель. Держите неизменную часть в начале сообщений.
Протокол Anthropic
В методе / отметьте неизменный блок полем cache_control со значением {"type": "ephemeral"}. Шлюз оплачивает поля usage так, как они пришли: input_tokens по ставке входа, cache_read_input_tokens по ставке чтения, cache_creation_input_tokens по ставке записи. Из input_tokens ничего не вычитается.
cURL
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
{
"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 поля оплачиваются как пришли, без вычитания.