KodikRouter — прозрачный шлюз. Никаких специальных заголовков не требуется: кэширование управляется телом запроса, как в нативных SDK от OpenAI / Anthropic / Google. Мы пробрасываем поля cache_control и любые расширения на блоках контента без изменений, а в ответе считаем корректную стоимость с учётом скидки кэша.

Два режима

Implicit caching

Держите начало messages одинаковым между запросами. Попадание в кэш зависит от минимальной длины префикса, модели, TTL и попадания к тому же провайдеру. Для GPT-4o проверяйте префикс от 1024 токенов. Нулевой cached_tokens для короткого запроса ожидаем и не доказывает ошибку. Факт попадания подтверждается полем prompt_tokens_details.cached_tokens, а не повторением текста. Для сравнения фиксируйте модель, провайдера и точное тело запроса; служебные инструкции маскирования при наличии плейсхолдеров тоже входят во входные токены.

{
  "model": "openai/gpt-4.1",
  "messages": [
    { "role": "system",  "content": "<длинный стабильный system prompt>" },
    { "role": "user",    "content": "Что такое TypeScript?" }
  ]
}

Минимальный размер промпта

Запросы короче порога не кэшируются — это аппаратное ограничение провайдеров, не KodikRouter.

Explicit caching: cache_control

Для Anthropic, Gemini explicit и Qwen используйте структурированный формат сообщений (массив блоков типизированного контента вместо строки) и расставьте контрольные точки кэша.

Anthropic — auto-cache для чата (рекомендуется)

Верхнеуровневый cache_control в запросе говорит Anthropic автоматически продвигать точку кэширования по мере роста диалога — лучший вариант для чатов.

{
  "model": "anthropic/claude-sonnet-4.6",
  "cache_control": { "type": "ephemeral" },
  "messages": [
    {
      "role": "system",
      "content": [
        { "type": "text", "text": "<очень длинный стабильный system prompt>" }
      ]
    },
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Опиши изменения в проекте за неделю." }
      ]
    }
  ]
}

Anthropic — точечный breakpoint

Если нужен ручной контроль, ставьте cache_control на конкретный блок. Максимум 4 точки на запрос.

{
  "model": "anthropic/claude-sonnet-4.6",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "<длинная стабильная инструкция, ≥1024 токенов>",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Краткий вопрос к этому контексту." }
      ]
    }
  ]
}

1-часовой TTL

По умолчанию кэш живёт 5 минут. Для долгих сессий укажите ttl: "1h" — запись в кэш стоит 2x от входа, зато повторное чтение остаётся дешёвым весь час.

{
  "type": "text",
  "text": "<длинная инструкция>",
  "cache_control": { "type": "ephemeral", "ttl": "1h" }
}

Gemini и Qwen

Тот же синтаксис: cache_control: { "type": "ephemeral" } на блоке контента. Gemini уважает только последний breakpoint в запросе — ставьте его в конец префикса, который хотите закэшировать.

Что делает KodikRouter

Мы не валидируем и не переписываем cache_control — sticky-маршрутизация до того же узла с прогретым кэшем делается шлюзом автоматически по хэшу промпта. Мы только корректно тарифицируем ответ с учётом скидки.

Чтение информации из ответа

В каждом ответе (стриминг и не-стриминг) есть блок usage:

В стриминговых ответах блок usage приходит в последнем SSE-чанке (с finish_reason).

Стоимость

Цены в каталоге — ориентировочные. Провайдеры могут менять тарифы, включая кэш и длинный контекст. При наличии положительной стоимости от провайдера (usage.cost) для чата используется она; иначе стоимость рассчитывается по каталогу с раздельным учётом fresh / cached / cache-write. База в USD умножается на курс и наценку KodikRouter.

В журнале запросов cost_rub_exact — списание в рублях с шестью знаками после запятой, provider_cost_usd — база в долларах до конвертации и наценки. Поле cost_usd в API журнала — устаревший псевдоним суммы в рублях; он сохранён для совместимости и не означает доллары. Для сверки используйте явно обозначенные валютные поля.

GET /v1/fx/usd-rub возвращает курс effective_rate_rub без наценки и отдельное поле pricing_markup_pct. Рублёвые цены на сайте включают оба. Новые записи содержат billing_details с применёнными параметрами и идентификаторами из ответа провайдера. Версия модели доступна только если она явно передана; название модели или изменение курса сами по себе версию не подтверждают.

Полная выгрузка: GET /v1/usage/export.json?from=2026-10-19&to=2026-10-19. Даты — в UTC, обе границы включены. Для списка используйте limit=200&offset=0, затем увеличивайте offset на 200. Параметры page и days не поддерживаются. Выгрузка не ограничена размером страницы.