> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Руководство по тарификации неявного кэширования Gemini

> Неявное кэширование Gemini включено автоматически, и попадания тарифицируются по официальной скидке — но частота попаданий ниже, чем у Claude/OpenAI, так что планируйте бюджет исходя из цен без кэширования.

Канал Gemini в APIYI автоматически включает **неявное кэширование контекста**: при совпадении префикса запроса совпавшая часть тарифицируется по официальной скидке, а поле `cached_content_token_count` возвращается без изменений — без каких-либо изменений кода.

Сразу главное: **кэширование Gemini существует, но на него не стоит рассчитывать.** Поведение неявного кэша определяется на стороне upstream, и реальные показатели попаданий заметно уступают [OpenAI](/ru/api-capabilities/openai/prompt-caching) и [Claude](/ru/api-capabilities/claude-prompt-caching). Рассматривайте это как приятный бонус и **всегда оценивайте стоимость по цене без кэширования**.

Эта страница основана на официальной документации Google (`ai.google.dev/gemini-api/docs/caching`, по состоянию на июнь 2026 года).

## Механизм в одном предложении

Когда открывающий сегмент (префикс) запроса совпадает с недавним запросом и достигает минимальной длины, upstream автоматически повторно использует свой кэш: совпавшая часть тарифицируется по официальной скидке (официально **до 90%**), без каких-либо маркеров.

## Условия срабатывания

| Условие                    | Требование                                                                                                      |
| -------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Минимальная длина префикса | **Серия Gemini 3 / 3.1 / 3.5: 4096 tokens**; серия 2.5: 2048 tokens                                             |
| Стабильный префикс         | Побайтово идентичен с первого символа; динамический контент (временные метки, случайные ID) нарушает совпадение |
| Временное окно             | Кэши истекают после периода бездействия; запросы подряд срабатывают надежнее                                    |

Обратите внимание: порог кэширования у Gemini (4096) значительно выше, чем у OpenAI (1024) — **короткие system prompts на Gemini практически никогда не дают попадание в кэш**, и именно поэтому кэширование Gemini кажется неубедительным.

## Как подтвердить попадание

Проверьте `usage_metadata.cached_content_token_count`:

```python theme={null}
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[LONG_STABLE_PREFIX, question]
)

usage = response.usage_metadata
print(f"Input: {usage.prompt_token_count}")
print(f"Cache hits: {usage.cached_content_token_count}")  # > 0 means a hit
```

Попадания отображаются как строки со скидкой в панели тарификации; в ответах REST поле — `usageMetadata.cachedContentTokenCount`.

## Повышение ваших шансов

Тот же подход, что и у OpenAI (подробное объяснение в [Руководстве по тарификации кэша OpenAI](/ru/api-capabilities/openai/prompt-caching)):

* **Сначала стабильный контент**: длинные системные инструкции, документы, few-shot-примеры в начале; ввод пользователя и временные метки — в конце
* **Сделайте префикс длинным**: все, что короче 4096 token (серия Gemini 3), никогда не попадает в кэш
* **Сгруппируйте повторное использование по времени**: отправляйте batch-задачи одну за другой, не растягивайте их во времени
* Многотуровые чаты по своей природе образуют префиксы только с добавлением и легче попадают в кэш

Даже если вы все сделаете правильно, **попадание в кэш не гарантировано** — неявное кэширование работает по возможности, в отличие от детерминированного поведения OpenAI/Claude.

## Явное кэширование (cachedContents)

Google также предлагает API явного кэширования (`cachedContents` — создайте объект кэша с TTL и укажите на него ссылку). Это **ресурс на стороне сервера с состоянием, который в настоящее время не поддерживается** в канале APIYI; используйте неявное кэширование.

## Сравнение с другими каналами

|                      | Gemini                                  | OpenAI                   | Claude                    |
| -------------------- | --------------------------------------- | ------------------------ | ------------------------- |
| Триггер              | Неявный, автоматический                 | Полностью автоматический | Ручные маркеры            |
| Минимальный порог    | **4096** (3 series) / 2048 (2.5 series) | 1024                     | 1024–4096                 |
| Скидка за попадание  | Официально до 90%                       | 0.1×                     | 0.1×                      |
| Надежность попадания | ⚠️ Best-effort, посредственно           | ✅ Стабильно              | ✅ Стабильно               |
| Поле попадания       | `cached_content_token_count`            | `cached_tokens`          | `cache_read_input_tokens` |

**Для нагрузок, чувствительных к кэшированию, с длинными и часто повторяющимися префиксами (агенты, RAG, пакетные документы), предпочитайте каналы OpenAI или Claude.** Обзор поддержки кэша по всей платформе: [FAQ по тарификации кэша](/ru/faq/cache-billing).

## Связанные ссылки

* Эта группа: [Native Calls](/ru/api-capabilities/gemini/native) · [Multimodal & Code Execution](/ru/api-capabilities/gemini/multimodal) · [Function Calling](/ru/api-capabilities/gemini/function-calling)
* Другие каналы: [OpenAI Cache Billing](/ru/api-capabilities/openai/prompt-caching) · [Claude Cache Billing](/ru/api-capabilities/claude-prompt-caching)
* Официальная документация Google: `ai.google.dev/gemini-api/docs/caching`