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

# Руководство по тарификации Prompt Caching OpenAI

> Кэширование OpenAI полностью автоматическое, без наценки и бесплатно для записи: тарификация кэшированного входа составляет 10% от цены входа. Как писать запросы, которые дают попадание в кэш, и как читать `cached_tokens`.

Если вы запускаете агентов, многоходовые чаты или пакетные задания на документах в серии gpt-5, кэширование промптов снижает тарификацию за кэшированную часть ваших входных данных до **10% от обычной цены** — и для этого **не требуется никаких изменений кода**; кэширование полностью автоматическое.

Эта страница основана на официальной документации OpenAI (`developers.openai.com/api/docs/guides/prompt-caching`, по состоянию на июнь 2026 года), с примерами, адаптированными для APIYI.

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

Если **начальный сегмент (префикс)** запроса точно совпадает с недавним запросом и его длина составляет не менее 1024 token, сервер не выполняет его повторную обработку: совпавшая часть тарифицируется по **0.1×**, а задержка снижается до 80%.

Два главных отличия от кэширования Claude:

* **Нет маркеров**: нет `cache_control` — кэширование включается автоматически, когда условия выполнены
* **Нет платы за запись**: Claude взимает 1.25× / 2× за запись; OpenAI записывает бесплатно

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

Если базовая цена входного token модели равна **1×**:

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

**Точка безубыточности: 2-й запрос.** Поскольку нет стоимости записи, которую нужно амортизировать, каждое повторное использование префикса — это чистая экономия; проще, чем у Claude, где вы заранее платите 1.25× и для выхода в ноль нужны два повторных использования.

По текущим ценам APIYI (за 1M tokens):

| Модель              | Обычный ввод | Попадание в кэш |
| ------------------- | ------------ | --------------- |
| `gpt-5.4`           | \$2.50       | **\$0.25**      |
| `gpt-5.4-mini`      | \$0.75       | **\$0.075**     |
| `gpt-5.5`           | \$5.00       | **\$0.50**      |
| `gpt-5.1` / `gpt-5` | \$1.25       | **\$0.125**     |

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

* Длинный system prompt + определения tools, используемые повторно между вызовами (агенты, боты поддержки)
* Многоходовые диалоги (каждый новый ход автоматически дает попадание в кэш по всей предыдущей истории)
* Пакетная обработка одного документа (например, 50 вопросов об одном контракте)
* RAG со стабильными фрагментами документа, размещенными в начале prompt

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

* Запросы, которые отличаются уже с первого символа
* Prompts меньше 1024 tokens всего (ниже порога кэширования)

## Три жестких условия для попадания в кэш

Все три обязательны.

### 1. Префикс длиной не менее 1024 tokens

Запросы короче 1024 tokens никогда не кэшируются (ошибки нет — просто это незаметно не применяется). После 1024 попадания в кэш расширяются с шагом в 128-token: совпавшая длина попадает на такие ступени, как 1024, 1152, 1280 …, поэтому `cached_tokens` обычно отображается немного ниже вашего полного стабильного префикса. Это нормально.

### 2. Идентичный префикс побайтно

Кэширование — это сопоставление префикса: сравнение начинается с первого символа и останавливается на первом различии. Любое изменение — метка времени, имя пользователя, порядок ключей JSON — делает все, что идет после него, тарифицируемым по полной стоимости.

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

```python theme={null}
# ❌ Wrong: dynamic content at the start of system — prefix changes every time, 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 bits go last
messages = [
    {"role": "system", "content": long_instructions},          # stable — will hit
    {"role": "user", "content": f"Current time {datetime.now()}. {question}"},  # volatile — last
]
```

### 3. Повторное использование в течение окна хранения

* Базовый срок хранения: удаляется после **5–10 минут** простоя, максимум через 1 hour
* **С 29 мая 2026 года (UTC)**, gpt-5.1 и более поздние модели (включая варианты Pro) по умолчанию используют **24-часовое расширенное хранение** (`prompt_cache_retention: "24h"`) для организаций без ZDR, без дополнительной оплаты — повторное использование в тот же день практически всегда дает попадание в кэш

## Минимальный рабочий пример

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

```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"
)

# Must be long enough: at least 1024 tokens (~750+ English words)
LONG_SYSTEM = open("long_instructions.txt").read()


def ask(question: str, label: str):
    r = client.chat.completions.create(
        model="gpt-5.4",
        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", "1st")   # expect cached=0
ask("Give 3 keywords", "2nd")            # expect cached ≈ prefix length
```

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

```text theme={null}
[1st] input=2330 cached=0
[2nd] input=2335 cached=2304
```

У 2-го вызова `cached` длина близка к длине системного prompt (округлено до 128) — эта часть тарифицируется по 10%.

<Info>
  Эндпоинт `/v1/responses` тоже автоматически кэшируется; поле — `usage.input_tokens_details.cached_tokens`. Внутреннее тестирование OpenAI показывает, что использование кэша в Responses на 40%–80% выше, чем в Chat Completions — для многоходовых агентов используйте [Native Calls](/ru/api-capabilities/openai/native).
</Info>

## Попало? Смотрите поля использования

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

**`cached_tokens > 0` означает, что вы экономите**: эта часть тарифицируется по 0.1×, а оставшиеся `prompt_tokens - cached_tokens` тарифицируются по полной цене.

## Продвинутый уровень: повышение коэффициента попаданий

### маршрутизация prompt\_cache\_key

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

```python theme={null}
r = client.chat.completions.create(
    model="gpt-5.4",
    messages=messages,
    prompt_cache_key="user-12345"  # pin routing per user/session
)
```

<Warning>
  Как только одна комбинация «prefix + prompt\_cache\_key» превышает примерно **15 запросов/минуту**, трафик начинает распределяться на другие машины, и коэффициент попаданий снижается. При высокой параллельности **разделяйте ключи по пользователям или сессиям** — не используйте один глобальный ключ.
</Warning>

### Формирование стабильного префикса

* Сохраняйте порядок определения tools и сериализацию JSON неизменными (не позволяйте сериализатору случайно менять порядок ключей)
* Входные изображения тоже участвуют в сопоставлении префикса — при повторном использовании сохраняйте одинаковыми URL / base64 и `detail` parameter
* Чтобы варьировать доступные tools для разных сценариев, используйте `allowed_tools`, чтобы ограничить подмножество, вместо редактирования списка `tools` — первый вариант не ломает префикс кэша

### Многоходовые чаты попадают в кэш автоматически

Массив messages с добавлением только в конец естественным образом обеспечивает стабильность префикса: история каждого хода является полным префиксом предыдущего хода. Попадания происходят автоматически, без дополнительных действий.

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

| Симптом                                      | Причина                                                                                                                                                    |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cached_tokens` всегда 0                     | В сумме менее 1024 tokens / динамический контент в начале префикса (метки времени, UUID, случайные ID)                                                     |
| Непостоянные попадания                       | Высокая параллельность без разделения `prompt_cache_key` / простой после истечения срока хранения                                                          |
| Число попаданий ниже ожидаемого              | Обрезка по шагу 128 tokens (нормально) / динамический контент попал в середину префикса                                                                    |
| После переключения моделей попаданий нет     | Кэши изолированы для каждой модели — `gpt-5.4` и `gpt-5.4-mini` не разделяют                                                                               |
| При вызове Claude отсутствуют cached\_tokens | Вызовы, совместимые с OpenAI, к Claude не могут использовать кэш Claude — используйте [Нативные вызовы Claude](/ru/api-capabilities/claude-prompt-caching) |

## OpenAI и Claude: кэширование в кратком обзоре

|                       | OpenAI (серия gpt-5)                  | Claude                                   |
| --------------------- | ------------------------------------- | ---------------------------------------- |
| Триггер               | **Полностью автоматически**, без кода | Ручные маркеры `cache_control`           |
| Плата за запись       | **Бесплатно**                         | 1.25× (5 min) / 2× (1 hour)              |
| Цена попадания        | 0.1×                                  | 0.1×                                     |
| Минимальный порог     | 1024 tokens                           | 1024–4096 tokens в зависимости от модели |
| Срок хранения         | От 5 min; по умолчанию 24h в gpt-5.1+ | 5 min / 1 hour (скользящее продление)    |
| Поле для отслеживания | `cached_tokens`                       | `cache_read_input_tokens`                |

Для полного руководства по стороне Claude см. [Руководство по тарификации кэша Claude](/ru/api-capabilities/claude-prompt-caching).

## APIYI и кэширование

<Info>
  **Канал APIYI OpenAI поддерживает попадания в кэш.** Запросы пересылаются наверх без изменений, поле `cached_tokens` возвращается вам без изменений, а панель тарификации показывает совпавшую часть отдельной строкой «cache read» по официальной ставке 0.1× — в вашем коде не требуется никакой адаптации под middleware.
</Info>

Самопроверка:

1. Сформируйте стабильный префикс длиной не менее 1024 tokens и отправьте 2 запроса подряд
2. Во 2-м ответе должно отображаться `cached_tokens > 0`
3. В журналах вызовов входная стоимость 2-го запроса должна быть заметно ниже, чем у 1-го

## Ключевые выводы

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

  <Card title="2. Достаточно длинный" icon="ruler">
    Для начала кэширования требуется минимум 1024 tokens префикса; попадания учитываются шагами по 128 tokens.
  </Card>

  <Card title="3. Стабильный префикс" icon="lock">
    Сначала стабильное содержимое, затем изменчивое; не включайте временные метки и случайные ID в начало.
  </Card>

  <Card title="4. Следите за использованием" icon="search">
    Только `cached_tokens > 0` подтверждает попадание в кэш — за эту часть тарификация составляет 10%.
  </Card>
</CardGroup>

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

* Эта группа: [Нативные вызовы](/ru/api-capabilities/openai/native) · [Совместимый режим](/ru/api-capabilities/openai/compatible) · [Вызов функций](/ru/api-capabilities/openai/function-calling)
* Кэширование на стороне Claude: [Руководство по тарификации Claude Cache](/ru/api-capabilities/claude-prompt-caching)
* Получить / управлять token: `https://api.apiyi.com/token`
* Официальная документация OpenAI: `developers.openai.com/api/docs/guides/prompt-caching`