> ## 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.

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

> Кэширование Grok выполняется автоматически без платы за запись: кэшированный input тарифицируется по 0.25x. Блочная гранулярность в 128 token, как писать запросы для попадания в кэш, как читать cached_tokens и почему длинным диалогам место в цепочке responses.

Когда вы запускаете agents, длинные system prompts или многоходовые conversations в Grok, prompt caching тарифицирует **кэшированную часть** вашего input по ставке **0.25×** (экономия 75%) — и **никаких изменений в коде не требуется**, потому что кэширование полностью автоматическое.

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

Эта страница следует официальной документации xAI (`docs.x.ai/developers/advanced-api-usage/prompt-caching`) и основана на **практическом тестировании `grok-4.6` на шлюзе APIYI 2026-08-19** (124 вызова, сверено построчно с внутренними записями тарификации backend).

## В одном предложении

Если **начальная часть (префикс) вашего запроса совпадает с недавним запросом байт в байт**, вышестоящая система пропускает лишнюю работу: совпавшая часть тарифицируется по **0.25×**. Без параметров, без маркеров.

Чем это отличается от двух других:

* **vs Claude**: никаких маркеров `cache_control` — это просто происходит, когда условия выполнены
* **vs OpenAI**: столь же автоматически и столь же свободно в использовании, но Grok не дает вам управления маршрутизацией в стиле `prompt_cache_key`

## Зачем это нужно — посмотрите на коэффициенты

Если принять базовую цену input token модели за **1×**:

| Тип                 | Цена               | Примечания                                |
| ------------------- | ------------------ | ----------------------------------------- |
| Обычный ввод        | **1×**             | Любое попадание мимо, по полной цене      |
| Запись в кэш        | **0× (бесплатно)** | Происходит автоматически, ничего не стоит |
| **Попадание в кэш** | **0.25×**          | Кэшированная часть на 75% дешевле         |

**Точка безубыточности: второй запрос.** Платы за запись, которую нужно амортизировать, нет, поэтому в первый раз, когда префикс используется повторно, вся ваша экономия — это чистая выгода.

В долларах для `grok-4.6` (за 1 млн tokens, для обоих уровней контекстного окна):

| Уровень     | Обычный ввод | Попадание в кэш |
| ----------- | ------------ | --------------- |
| 0 – 200K    | \$2.00       | **\$0.50**      |
| 200K – 512K | \$4.00       | **\$1.00**      |

Пороговые значения уровней и ставки чтения из кэша для других моделей Grok приведены в [таблице ступенчатого ценообразования в обзоре Grok](/ru/api-capabilities/grok/overview).

### Хорошо подходит

* Один длинный system prompt плюс определения tools, вызываемые снова и снова (agents, support bots)
* Пакетная обработка одного документа (50 вопросов к одному контракту)
* RAG, где стабильные фрагменты документа находятся в начале prompt
* Многоходовые диалоги — но учтите, что в Grok два способа сделать это ведут себя очень по-разному (см. ниже)

### Плохо подходит

* Запросы, которые каждый раз отличаются уже с самого первого символа
* prompts ниже диапазона в тысячу tokens — в тестировании многократный вызов такого запроса так и не сформировал повторно используемый кэш

## Оба эндпоинта, с потоковой передачей и без неё, всё сверено

`/v1/chat/completions` и `/v1/responses`, как с потоковой передачей, так и без неё: **мы сверили все четыре комбинации с записями тарификации backend на 2026-08-19**, и закэшированная часть в каждом случае была тарифицирована по ставке кэша:

|                        | Без потоковой передачи | Потоковая передача |
| ---------------------- | ---------------------- | ------------------ |
| `/v1/chat/completions` | Сверено                | Сверено            |
| `/v1/responses`        | Сверено                | Сверено            |

<Info>
  **Для шлюза не требуется адаптация на стороне клиента.** Поведение кэша передаётся в upstream, `cached_tokens` возвращается дословно, а счёт backend указывает закэшированную часть отдельной позицией «чтение кэша».
</Info>

## Условия для попадания

| Условие                      | Требование                                                                                                                                |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Как активируется             | **Полностью автоматически** — без параметров, без маркеров                                                                                |
| Где начинается сопоставление | С начала массива `messages`, байт за байтом                                                                                               |
| Только добавление            | Редактирование, удаление или изменение порядка более ранних сообщений делает кэш недействительным; **добавление в конце не делает этого** |
| Размер блока                 | **128 tokens** (см. ниже)                                                                                                                 |
| Длина                        | Официальный минимум не публикуется; в тестах prompts ниже диапазона в тысячу tokens никогда не формировали повторно используемый кэш      |
| Временное окно               | Может быть официально вытеснено в любой момент — **чем короче интервал, тем надежнее**                                                    |

### Попадания округляются вниз до 128 tokens

```text theme={null}
cached_tokens = floor(matched prefix length / 128) * 128
```

Два раунда тестирования сходятся: префикс длиной 8802-token дал попадание 8704 (= 68 × 128), а в более раннем раунде префикс длиной 2735-token дал попадание 2688 (= 21 × 128). **Таким образом, `cached_tokens` обычно немного меньше вашего стабильного префикса — это ожидаемо.**

### Только добавление: изменение истории ломает это

Тот же префикс, отправленный подряд, с одним измененным вызовом:

| Действие                                   | `cached_tokens`         |
| ------------------------------------------ | ----------------------- |
| Без изменений                              | 8704                    |
| **Первый символ префикса изменен**         | 128 (фактически промах) |
| **Одна строка добавлена в конец префикса** | 8704 (не затронуто)     |
| Исходный префикс отправлен снова           | 8704                    |

**Что это означает на практике: сначала стабильное содержимое, затем изменчивое.**

```python theme={null}
# WRONG: dynamic content at the start of system, so the prefix changes every time and never hits
messages = [
    {"role": "system", "content": f"Current time {datetime.now()}. You are an assistant." + LONG_INSTRUCTIONS},
    {"role": "user", "content": question},
]

# RIGHT: long instructions and tool definitions stay stable up front, dynamic content goes in the user message
messages = [
    {"role": "system", "content": LONG_INSTRUCTIONS},          # stable, will hit
    {"role": "user", "content": f"Current time {datetime.now()}. {question}"},  # volatile, goes last
]
```

## Минимальный запускаемый пример

Отправьте один и тот же длинный префикс дважды с разными вопросами: первый записывает кэш, второй попадает в него.

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1"
)

# The prefix has to be long enough: below the thousand-token range you get essentially nothing
LONG_SYSTEM = open("long_instructions.txt").read()


def ask(question: str, label: str):
    r = client.chat.completions.create(
        model="grok-4.6",
        messages=[
            {"role": "system", "content": LONG_SYSTEM},
            {"role": "user", "content": question},
        ],
    )
    cached = r.usage.prompt_tokens_details.cached_tokens
    print(f"[{label}] input={r.usage.prompt_tokens} cached={cached}")


ask("Summarize the key points", "call 1")   # cold start: cached is 0 or a tiny value
ask("Give me 3 keywords", "call 2")         # expect cached close to the prefix length
```

Ожидаемый вывод:

```text theme={null}
[call 1] input=8804 cached=128
[call 2] input=8804 cached=8704
```

На втором вызове `cached` близко к длине system prompt (округлено вниз до 128), и эта часть тарифицируется по 0.25×.

<Info>
  Эндпоинт `/v1/responses` автоматически работает так же; поле — `usage.input_tokens_details.cached_tokens`. **Длинные разговоры получают дополнительное преимущество на этом эндпоинте** — см. ниже "Длинные разговоры относятся к цепочке responses".
</Info>

## Как отличить попадание от промаха — смотрите поле usage

| Эндпоинт               | Поле попадания                              |
| ---------------------- | ------------------------------------------- |
| `/v1/chat/completions` | `usage.prompt_tokens_details.cached_tokens` |
| `/v1/responses`        | `usage.input_tokens_details.cached_tokens`  |

### Как это читать: малые значения — это не попадания

Не просто проверяйте «больше нуля». **Сравнивайте `cached_tokens` со стабильной длиной префикса:**

| `cached_tokens`                                             | Интерпретация                  |
| ----------------------------------------------------------- | ------------------------------ |
| `0`                                                         | Промах                         |
| Крошечная доля префикса (десятки или один-два сотни)        | **Тоже считайте это промахом** |
| В тысячах, близко к длине префикса, округленной вниз до 128 | Настоящее попадание            |

При тестировании даже холодный первый вызов иногда возвращает значение в сто или двести. Не обманывайтесь — это не значит, что ваш префикс был закэширован.

### Сверка: подробность тарификации кэша в консоли

Внутренний лог для одного вызова перечисляет **количество token для cached-read и его множитель скидки отдельной строкой**, которую вы можете сопоставить с `cached_tokens` в ответе. Когда вам нужно точно знать, как был тарифицирован один вызов, это и есть авторитетный источник.

Трехшаговая самопроверка:

1. Создайте стабильный префикс длиной более тысячи token и отправьте два запроса подряд
2. Во втором ответе `cached_tokens` должно быть явно в тысячах
3. В бэкенд [журналах вызовов](/ru/faq/call-logs) этот запрос показывает строку «чтение из кэша» и заметно более низкую стоимость входных данных, чем у первого

## Улучшение процента попаданий

### Сформируйте стабильный префикс

* Длинные инструкции, few-shot-примеры и определения tools идут первыми; ввод пользователя и метки времени — последними
* Сохраняйте порядок определений tools и сериализацию JSON неизменными (не позволяйте сериализатору перемешивать ключи)
* Входные изображения тоже участвуют в сопоставлении префикса — при повторном использовании сохраняйте base64 / URL и параметры идентичными
* **Используйте один и тот же префикс в короткой серии запросов**, а не растягивайте обращения во времени

Методология совпадает с OpenAI; полную версию см. в [руководстве OpenAI по кэшированию промптов](/ru/api-capabilities/openai/prompt-caching).

### Длинные диалоги лучше вести в цепочке Responses

Это легко упустить как различие в Grok:

| Подход                                       | Что показали тесты                                                                                                                                                                                   |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/v1/chat/completions`, при добавлении ходов | За 5 ходов, при росте prompt с 8,8K до 10K, `cached_tokens` **оставался на уровне размера исходного статического префикса** — новые Q\&A из каждого хода так и не становились повторно используемыми |
| `/v1/responses` с `previous_response_id`     | Попадания растут с каждым ходом (измерено: 8704 на 2-м ходе → 9344 на 3-м ходе)                                                                                                                      |

Поэтому для длинных диалогов и многошаговых агентов предпочитайте цепочку Responses API:

```python theme={null}
r1 = client.responses.create(
    model="grok-4.6",
    input=[{"role": "system", "content": LONG_SYSTEM},
           {"role": "user", "content": "First question"}],
    store=True,
)

r2 = client.responses.create(
    model="grok-4.6",
    previous_response_id=r1.id,          # send only the new turn; the upstream carries the history
    input=[{"role": "user", "content": "Follow-up"}],
    store=True,
)
print(r2.usage.input_tokens_details.cached_tokens)
```

Различия между endpoint описаны в [обзоре endpoint на странице обзора Grok](/ru/api-capabilities/grok/overview).

### О `x-grok-conv-id`

Лучшие практики xAI рекомендуют отправлять заголовок `x-grok-conv-id` (UUID или ID сеанса) в каждом запросе, чтобы повысить процент попаданий. Мы провели симметричный A/B на APIYI — несколько независимых префиксов с заголовком и без него, по несколько повторных использований каждого — и **не увидели заметной разницы между двумя группами**. Отправлять его не вредно, но не рассчитывайте на него для повышения процента попаданий.

## Процент попаданий и чего ожидать

<Warning>
  **Попадания в кэш не гарантированы.** В документации xAI указано, что записи могут быть потеряны из-за давления на память, перезапуска сервиса или маршрутизации запроса на другой сервер.

  В тестах большинство запросов попадали в кэш, когда **стабильный префикс повторно использовался в плотной серии**, но наблюдается реальный джиттер, и он возникает выше по цепочке — со стороны вызывающего его ничто не контролирует. **Планируйте бюджет по цене без кэша и считайте попадания бонусом.**
</Warning>

И ещё один момент, который стоит сказать прямо: **ценность кэширования — в стоимости, а не в скорости.** Измеренное время до первого token отличалось всего на несколько сотен миллисекунд между попаданиями и промахами — не ожидайте, что кэширование сделает запросы с большим context window быстрыми.

## Частые подводные камни

| Симптом                                                     | Причина                                                                                                                                   |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `cached_tokens` всегда равен 0 или всегда очень мал         | Слишком короткий prompt (ниже диапазона в тысячу tokens) / в начале префикса стоит метка времени, UUID или случайный ID                   |
| Попадания то появляются, то исчезают                        | Вытеснение на стороне upstream — это ожидаемо; сократите интервал между повторными использованием и отправляйте пакетную работу всплеском |
| Попадания не дотягивают до префикса                         | Округление вниз до 128 tokens; это нормально                                                                                              |
| `cached_tokens` перестает расти в многоходовых чатах        | chat/completions повторно использует только исходный статический префикс — перенесите длинные разговоры в цепочку responses               |
| Редактирование более раннего сообщения уничтожило попадания | cache работает только на добавление: редактирование, удаление или перестановка истории делает его недействительным                        |
| Нет попаданий после переключения моделей                    | Кэши **изолированы для каждой модели** — `grok-4.6` и `grok-4.5` не используют общий кэш                                                  |

## Краткое сравнение с другими каналами

|                      | Grok                                                                      | OpenAI            | Gemini                               | Claude                    |
| -------------------- | ------------------------------------------------------------------------- | ----------------- | ------------------------------------ | ------------------------- |
| Как срабатывает      | **Автоматически**                                                         | **Автоматически** | Неявно, автоматически                | Вручную `cache_control`   |
| Плата за запись      | **Бесплатно**                                                             | **Бесплатно**     | Бесплатно                            | 1.25× / 2×                |
| Цена попадания       | 0.25×                                                                     | 0.1×              | Скидка до 90%, по данным Google      | 0.1×                      |
| Минимальный размер   | Не опубликовано; ниже \~1K tokens в тестах ничего не кэшируется           | 1024 tokens       | 4096 (серия 3) / 2048 (серия 2.5)    | 1024–4096                 |
| Дискретность блоков  | 128 tokens                                                                | 128 tokens        | —                                    | —                         |
| Надежность попадания | Попадания детерминированы, но вышестоящий сервис не дает никаких гарантий | Стабильно         | Не гарантируется; на практике средне | Стабильно                 |
| Поле попадания       | `cached_tokens`                                                           | `cached_tokens`   | `cachedContentTokenCount`            | `cache_read_input_tokens` |

Чтобы узнать о поддержке кэширования на всей платформе, см. [FAQ по тарификации кэша](/ru/faq/cache-billing).

<Info>
  **Все на этой странице было измерено на `grok-4.6` (2026-08-19).** xAI утверждает, что все языковые модели Grok поддерживают кэширование префикса; мы не проводили бенчмарки остальных по отдельности, поэтому воспринимайте такие детали, как дискретность блоков и поведение при коротких prompt, как то, что нужно подтверждать на вашей собственной нагрузке.

  Если тарификация, которую вы видите для данного префикса, явно расходится с тем, что описано здесь, обратитесь в поддержку, указав request-id из заголовков ответа.
</Info>

## Краткое резюме

<CardGroup cols={2}>
  <Card title="1. Полностью автоматически" icon="wand-sparkles">
    Никаких маркеров, никакой платы за запись. Выполните условия, и это будет кэшироваться; повторное использование во второй раз — это чистая экономия.
  </Card>

  <Card title="2. Только добавление" icon="layers">
    Сопоставление выполняется побайтно с начала сообщений; изменение истории делает его недействительным, а попадания округляются вниз до 128 tokens.
  </Card>

  <Card title="3. Связывайте длинные разговоры" icon="link">
    Многоходовой чат повторно использует только исходный статический префикс; responses + previous\_response\_id увеличивает попадания с каждым ходом.
  </Card>

  <Card title="4. Не рассчитывайте на попадания" icon="scale">
    Попадания не гарантированы. Планируйте бюджет по цене без кэша и воспринимайте скидку как бонус.
  </Card>
</CardGroup>

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

* Та же группа: [Обзор Grok](/ru/api-capabilities/grok/overview) · [Чат и рассуждение](/ru/api-capabilities/grok/chat) · [Веб-поиск и поиск в X](/ru/api-capabilities/grok/web-search) · [Выполнение кода и MCP](/ru/api-capabilities/grok/code-execution-mcp)
* Кэширование на других каналах: [Тарификация кэша OpenAI](/ru/api-capabilities/openai/prompt-caching) · [Тарификация кэша Gemini](/ru/api-capabilities/gemini/prompt-caching) · [Тарификация кэша Claude](/ru/api-capabilities/claude-prompt-caching)
* Обзор для всей платформы: [FAQ по тарификации кэша](/ru/faq/cache-billing)
* Получить или управлять token: `https://api.apiyi.com/token`
* Официальная документация xAI: `docs.x.ai/developers/advanced-api-usage/prompt-caching`