Документация Кэширование ответов

Кэширование ответов

Кэширование ответов позволяет сохранять результаты идентичных API-запросов и возвращать их из кэша при повторных обращениях. При попадании в кэш (cache HIT) ответ возвращается мгновенно, а все счётчики billable usage обнуляются — запрос не тарифицируется.

Кэширование работает на уровне API (перед отправкой запроса провайдеру) и не зависит от конкретной модели или провайдера. Поддерживаются как streaming, так и non-streaming запросы.

Кэшируются только успешные ответы (200 OK). Ответы с ошибками, rate limit и частичные результаты не кэшируются. Ответы, содержащие tool calls, кэшируются как часть успешной генерации.

Для streaming-запросов при попадании в кэш ответ воспроизводится через тот же streaming-канал — клиент получает те же чанки контента. Поля id, created и заголовок X-Generation-Id в каждом чанке соответствуют новому cache-hit поколению, а не оригинальному.

Включение кэширования

1. Через заголовки запроса (per-request)

Добавьте заголовок X-OpenRouter-Cache: true для включения кэширования для конкретного запроса:

curl https://api.ru-openrouter.ru/v1/chat/completions \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -H "Content-Type: application/json" \
  -H "X-OpenRouter-Cache: true" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "What is the meaning of life?"}
    ]
  }'

import requests

response = requests.post(
    "https://api.ru-openrouter.ru/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk_ваш_api_ключ",
        "Content-Type": "application/json",
        "X-OpenRouter-Cache": "true",
    },
    json={
        "model": "google/gemini-2.5-flash",
        "messages": [
            {"role": "user", "content": "What is the meaning of life?"}
        ],
    },
)

Первый запрос — cache MISS. Ответ сохраняется в кэш и тарифицируется:

HTTP/2 200
X-OpenRouter-Cache-Status: MISS
X-OpenRouter-Cache-TTL: 3600

{
  "id": "gen-abc123",
  "model": "google/gemini-2.5-flash",
  "choices": ["..."],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 120,
    "total_tokens": 135
  }
}

Повторный идентичный запрос — cache HIT. Usage обнулён, запрос не тарифицируется. Каждый cache hit получает свой уникальный generation ID:

HTTP/2 200
X-OpenRouter-Cache-Status: HIT
X-OpenRouter-Cache-Age: 42
X-OpenRouter-Cache-TTL: 3558
X-Generation-Id: gen-def456

{
  "id": "gen-def456",
  "created": 1746000012,
  "model": "google/gemini-2.5-flash",
  "choices": ["..."],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

2. Через личный кабинет (настройка пользователя)

В личном кабинете (Dashboard) доступен переключатель «Кэширование». При включении:

Кэширование автоматически применяется ко всем API-запросам данного пользователя
TTL по умолчанию: 3600 секунд (1 час)
Не требуется указывать заголовок X-OpenRouter-Cache в каждом запросе

Приоритет: заголовки запроса имеют приоритет над настройкой в личном кабинете. Если в запросе передан X-OpenRouter-Cache: false, кэширование будет отключено, даже если в личном кабинете оно включено.

Как это работает

Два запроса считаются идентичными, если у них совпадают:

API ключ
Модель (model)
Тип эндпоинта (chat/completions, responses, embeddings)
Режим streaming (stream: true / false)
Тело запроса (включая все параметры)

При включённом кэшировании API формирует ключ кэша из этих параметров. Если идентичный запрос уже выполнялся и кэш не истёк, возвращается сохранённый ответ.

Недетерминированность: Кэшированные ответы возвращаются как есть, независимо от стохастических параметров вроде temperature. Если нужны свежие ответы, отключите кэширование или используйте короткий TTL.

Детали ключа кэша

Ключ кэша формируется из:

API ключа
Модели (model)
Типа эндпоинта (chat/completions, responses, embeddings и т.д.)
Режима streaming (stream: true/false)
SHA-256 хеша тела запроса

Streaming и non-streaming запросы кэшируются отдельно — запрос с stream: true не вернёт кэш non-streaming ответа и наоборот.

Тело запроса нормализуется перед хешированием, поэтому лишние пробелы не влияют на ключ. Однако порядок свойств JSON значим:

Разный порядок свойств в логически идентичном JSON (например, {"model":"x","messages":[]} vs {"messages":[],"model":"x"}) даёт разные ключи
Пропуск опциональных полей vs явная отправка значений по умолчанию (например, temperature: 1.0) — разные ключи
Заголовки атрибуции (HTTP-Referer, X-Title) и заголовки выбора провайдера не входят в ключ кэша
Мультимодальные запросы (изображения, аудио, видео, файлы) кэшируются — полное тело запроса, включая base64-контент, участвует в хешировании

Конкурентные запросы

Если два идентичных запроса поступают одновременно до того, как первый ответ записан в кэш, оба получат cache MISS и будут тарифицированы независимо. Объединения запросов (request coalescing) не происходит.

Заголовки запроса

Заголовок	Значение	Описание
`X-OpenRouter-Cache`	`true` / `false`	Включить/отключить кэширование для этого запроса
`X-OpenRouter-Cache-TTL`	`<секунды>`	Свой TTL (1–86400 секунд, по умолчанию 3600)
`X-OpenRouter-Cache-Clear`	`true`	Принудительно сбросить кэш для этого запроса

Сброс кэша (Cache Clearing)

Чтобы принудительно получить свежий ответ для конкретного запроса, отправьте заголовок X-OpenRouter-Cache-Clear: true вместе с X-OpenRouter-Cache: true (или с включённым кэшированием в личном кабинете). Это удаляет существующую запись в кэше для данного ключа, выполняет новый запрос к провайдеру и сохраняет новый ответ.

X-OpenRouter-Cache-Clear не имеет эффекта, если кэширование не включено для запроса. Сброс затрагивает только одну запись в кэше, соответствующую текущему запросу — другие кэшированные ответы не затрагиваются.

Новая запись в кэше использует TTL из заголовка X-OpenRouter-Cache-TTL, настройки личного кабинета или значение по умолчанию (3600 секунд), следуя стандартным правилам приоритета.

Приоритет заголовков

Заголовки запроса и настройки личного кабинета взаимодействуют следующим образом:

X-OpenRouter-Cache: false отключает кэширование, даже если в личном кабинете оно включено
X-OpenRouter-Cache: true включает кэширование, если в личном кабинете оно не настроено
X-OpenRouter-Cache-TTL переопределяет TTL из настроек личного кабинета (по умолчанию: 3600 секунд)
X-OpenRouter-Cache-Clear сбрасывает кэш только для текущего запроса, если кэширование включено
Если ни заголовок, ни настройка личного кабинета не заданы — кэширование выключено

Заголовки ответа

Заголовок	Значение	Описание
`X-OpenRouter-Cache-Status`	`HIT` / `MISS`	Попадание в кэш или промах
`X-OpenRouter-Cache-Age`	`<секунды>`	Сколько времени ответ находится в кэше (только при `HIT`)
`X-OpenRouter-Cache-TTL`	`<секунды>`	Оставшийся TTL при `HIT`; полный TTL при `MISS`
`X-Generation-Id`		Уникальный ID генерации (присутствует на каждом ответе, кэшированном или нет)

TTL (Time-to-Live)

TTL определяет, как долго кэшированный ответ остаётся валидным.

По умолчанию: 3600 секунд (1 час)
Диапазон: от 1 секунды до 86400 секунд (24 часа)
Настройка: через заголовок X-OpenRouter-Cache-TTL или в личном кабинете

Поддерживаемые эндпоинты

Эндпоинт	Формат API
`/v1/chat/completions`	OpenAI Chat Completions
`/v1/responses`	OpenAI Responses
`/v1/embeddings`	OpenAI Embeddings

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

Кэширование провайдера: Некоторые провайдеры предлагают собственное кэширование промптов (например, Anthropic prompt caching, OpenAI cached context). Это отдельный механизм, не связанный с Response Caching API. Response Caching работает на уровне API до отправки запроса провайдеру, а кэширование провайдера — внутри инфраструктуры провайдера. Они могут использоваться одновременно.

Тарификация

Cache hits — бесплатны. Все счётчики billable usage обнуляются:

Для chat/completions и responses: usage.prompt_tokens, usage.completion_tokens, usage.total_tokens = 0
Для embeddings: usage.prompt_tokens, usage.total_tokens = 0

Вы тарифицируетесь только за оригинальный запрос, который заполнил кэш (cache MISS).

Cache hits не учитываются в rate limits провайдеров, так как запрос не достигает провайдера.

Ограничения

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

Хранение данных

Кэшированные ответы хранятся в edge-инфраструктуре в течение TTL и автоматически удаляются по истечении. Данные из кэша не используются для обучения и не передаются третьим лицам.

Примеры использования

Agent Workflows

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

Модульное тестирование

Получайте повторяемые ответы для тестов. После первого запуска, заполнившего кэш, последующие идентичные запросы возвращают тот же ответ при нулевой стоимости. Для детерминированных первых запусков используйте temperature: 0 или фиксированный seed.

Повторяющиеся запросы

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

Мониторинг эффективности кэша

Статус cache hit/miss отображается в заголовках ответа (X-OpenRouter-Cache-Status). Каждый cache hit получает уникальный X-Generation-Id, что позволяет отслеживать отдельные кэшированные ответы.