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

Если вы запускаете агентов, многоходовые чаты или пакетные задания на документах в серии 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 — делает все, что идет после него, тарифицируемым по полной стоимости. Практическое правило: сначала стабильное содержимое, в конце изменчивое.

# ❌ 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, без дополнительной оплаты — повторное использование в тот же день практически всегда дает попадание в кэш

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

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

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

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

[1st] input=2330 cached=0
[2nd] input=2335 cached=2304

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

Эндпоинт /v1/responses тоже автоматически кэшируется; поле — usage.input_tokens_details.cached_tokens. Внутреннее тестирование OpenAI показывает, что использование кэша в Responses на 40%–80% выше, чем в Chat Completions — для многоходовых агентов используйте Native Calls.

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

Эндпоинт	Поле попадания
`/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 заметно повышает коэффициент попаданий:

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

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

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

Сохраняйте порядок определения 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

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.

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

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

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

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

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

1. Полностью автоматически

Без маркеров, без платы за запись — кэширование применяется автоматически, а 2-е использование дает чистую экономию.

2. Достаточно длинный

Для начала кэширования требуется минимум 1024 tokens префикса; попадания учитываются шагами по 128 tokens.

3. Стабильный префикс

Сначала стабильное содержимое, затем изменчивое; не включайте временные метки и случайные ID в начало.

4. Следите за использованием

Только cached_tokens > 0 подтверждает попадание в кэш — за эту часть тарификация составляет 10%.

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

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

Основы

Базовый API

Image API (официальный)

Video API (официальный)

API мультимодального понимания

Текстовый API

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

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

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

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

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

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

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

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

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

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

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

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

маршрутизация prompt_cache_key

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

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

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

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

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

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

1. Полностью автоматически

2. Достаточно длинный

3. Стабильный префикс

4. Следите за использованием

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

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

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

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

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

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

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

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

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

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

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

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

​маршрутизация prompt_cache_key

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

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

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

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

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

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

1. Полностью автоматически

2. Достаточно длинный

3. Стабильный префикс

4. Следите за использованием

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

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

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

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

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

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

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

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

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

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

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

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

маршрутизация prompt_cache_key

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

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

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

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

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

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

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