Gemini Interactions API и generateContent: как выбрать? 4 таблицы ясно показывают актуальное сравнение на 2026 год

打开 официальную документацию Gemini, особенно страницы вроде генерации изображений Nano Banana, можно заметить вверху переключатель: с одной стороны Interactions API, с другой — generateContent API. И это не просто обновление документации: Google в июне 2026 года официально вывел Interactions API в GA (статус общей доступности) и рекомендует всем новым проектам использовать именно его в приоритете. В этой статье я собрал официальную документацию и результаты практических тестов через шлюз APIYI, чтобы разом объяснить ключевые различия, пробелы в возможностях и что лучше выбирать на практике.

Ключевая ценность: после прочтения вам будет понятно, чем Interactions API и generateContent отличаются по идее, управлению состоянием и покрытию возможностей, а также какой подход выбрать при вызове Gemini через сервис-прокси APIYI.

Ключевые различия Interactions API и generateContent

Сразу к сути: это не просто отношения «новая версия старой». Это две разные концепции. generateContent — это безсостояний режим «один запрос — один ответ», где клиент сам хранит всю историю диалога. Interactions API, наоборот, переносит управление состоянием на сервер и перестраивает весь сценарий вокруг нового понятия — Interaction.

В официальной документации Interaction определяется как «один полный цикл диалога или задачи», внутри которого есть последовательность шагов, идущих по времени: ход рассуждений модели, вызовы инструментов и их результаты, а также финальный ответ модели. Это значит, что Interactions API изначально заточен под многошаговые диалоги и agent-задачи, а не только под разовый вопрос-ответ.

Так становится понятнее, почему Google использует формулировку «официально доступно», а не просто «добавлена новая функция». Interactions API был в публичной бете с декабря 2025 года, а в июне 2026 года его официально объявили GA. В официальном блоге прямо сказано: «Мы рекомендуем всем новым проектам и приложениям использовать Interactions API». Кроме того, вся официальная документация уже по умолчанию показывает именно эту новую парадигму, и Google продвигает её как стандарт не только внутри своих SDK, но и через партнёров экосистемы. Иными словами, это не опциональное улучшение, а переопределение того, как вообще надо вызывать Gemini. При этом есть и миграционный гайд, так что переход можно делать постепенно, без жёсткого принуждения.

Сравниваемый параметр	generateContent (legacy)	Interactions API
Текущий статус	Устаревший, но полностью поддерживается	С июня 2026 года — GA
Официальная рекомендация	Можно продолжать использовать в существующих проектах	Рекомендуется для всех новых проектов
Базовый метод	generateContent	interactions.create / get / delete
Идея дизайна	Безсостояний единичный запрос	Таск-цикл на основе Interaction со статусом
Будущие новые возможности	По-прежнему получит новые основные модели	Передовые agent-возможности будут появляться здесь первыми

🎯 Техническая рекомендация: если вы вызываете Gemini-модели через APIYI apiyi.com, сначала потратьте несколько минут на сверку с официальной документацией и проверьте, на какой парадигме сейчас построен ваш проект. Так вы поймёте, нужно ли уже мигрировать, и не попадёте в ловушку, когда из-за того, что в документации по умолчанию показывается Interactions API, кажется, будто ваш старый код уже устарел.

Ключевое различие между двумя подходами к запросам и управлению состоянием

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

Interactions API решает эту задачу иначе: вы передаёте в следующий запрос previous_interaction_id из предыдущего ответа, а сервер сам подхватывает всю историю диалога. Клиенту больше не нужно вручную склеивать и пересылать контекст. В официальной документации также есть параметр background=true для долгих задач и возможность наблюдать этапы выполнения, что удобно и для отладки, и для показа промежуточных шагов в UI. Для agent-подобных продуктов это особенно полезно.

Но у серверного управления состоянием есть и обратная сторона. По умолчанию store имеет значение true, то есть система сохраняет записи interaction: у платных аккаунтов — 55 дней, у бесплатных — 1 день. Если из-за приватности или требований комплаенса поставить store=false, хранение отключится, но вместе с этим пропадут и две возможности: продолжение диалога через previous_interaction_id и фоновое выполнение. Это компромисс, который нужно заранее учитывать.

С точки зрения стоимости у APIYI тоже есть чёткая позиция: когда состояние хранится на сервере, историю одного и того же диалога не нужно каждый раз заново включать в входные токены, поэтому заметно растёт и hit rate кэша. Если говорить словами самой документации — «ниже стоимость, выше частота попадания в кэш». Для сценариев вроде чат-ботов поддержки или вопросов по длинным документам, где контекста много, разница со временем становится очень заметной. А вот для одиночной генерации или пакетной обработки, где состояние по природе не нужно, это преимущество почти не играет роли.

Есть ещё одна мелочь, которую легко упустить: параметры tools, system_instruction, generation_config — включая thinking_level, temperature и другие поля — задаются на каждый запрос отдельно. Даже если вы продолжаете диалог через previous_interaction_id, эти настройки не наследуются автоматически и их всё равно нужно передавать явно каждый раз.

Возможность	generateContent	Interactions API
Поддержка истории диалога	Клиент вручную собирает всю историю	Сервер автоматически подхватывает через previous_interaction_id
Фоновое выполнение долгих задач	Не поддерживается	Поддерживается через background=true
Видимость промежуточных шагов	Нужно разбирать вручную	Есть observable execution steps
Политика хранения записей	Нет такой концепции	По умолчанию хранит: 55 дней для платных / 1 день для бесплатных
Наследование инструментов и параметров генерации	Каждый раз передавать явно	Каждый раз передавать явно, автоматического наследования нет

💡 Совет по выбору: если в проекте много многошаговых диалогов или вы строите workflow в стиле agent, механизм управления состоянием в Interactions API действительно экономит немало кода-обвязки. Но если у вас в основном одиночные запросы, это преимущество может почти не ощущаться. Мы бы советовали сначала прогнать небольшой A/B-тест на платформе APIYI apiyi.com, а уже потом решать, стоит ли мигрировать.

В чём разрыв по возможностям: что уже есть, а чего пока нет

Interactions API — это новый подход, но в документации честно перечислены и ограничения. При выборе это обязательно надо учитывать: нельзя смотреть только на слово «новее» и автоматически считать, что он универсальнее.

Официально сказано, что Interactions API пока не поддерживает поле video metadata для понимания видео, Batch API, автоматический вызов функций в Python (automatic function calling), а также явное кэширование (explicit caching). При этом неявное кэширование через previous_interaction_id поддерживается.
С другой стороны, generateContent полностью поддерживает потоковый вывод, вызов функций, Batch API, явное кэширование, а также полный набор мультимодальных входов: текст, изображения, аудио, видео и документы.

Возможность	generateContent	Interactions API
Batch API	✅ Поддерживается	❌ Пока не поддерживается
Явное кэширование (explicit caching)	✅ Поддерживается	⚠️ Только неявное кэширование
Поле video metadata	✅ Поддерживается	❌ Пока не поддерживается
Автоматический вызов функций в Python	✅ Поддерживается	❌ Пока не поддерживается
Потоковый вывод / вызов функций	✅ Поддерживается	✅ Поддерживается
Заявленная стоимость и hit rate кэша	Обычный биллинг	По заявлению APIYI — ниже стоимость и выше hit rate

На примере генерации изображений Nano Banana различие особенно хорошо видно в том, как получать результат.
Interactions API даёт удобные свойства вроде interaction.output_image и interaction.output_text, то есть финальное изображение или текст можно достать напрямую. А вот generateContent работает на более низком уровне: нужно итерироваться по массиву candidates[0].content.parts и самому проверять тип каждого part. Для проектов, где уже написан парсер под generateContent, такая разница обычно означает довольно заметную переработку кода — просто сменить endpoint здесь не получится.

Эти пробелы нельзя считать мелкими деталями. Batch API — это, по сути, базовый инструмент для дешёвой пакетной обработки офлайн-задач. Если после миграции выяснится, что новый подход его не поддерживает, придётся перестраивать всю цепочку обработки.
Явное кэширование, в свою очередь, напрямую влияет на стоимость в сценариях с длинным контекстом: если в бизнесе есть большие фиксированные system prompt или повторно используемые справочные материалы, без explicit caching уже нельзя точно управлять тем, что именно кэшируется и на какой срок. Именно поэтому в документации и сохраняются две технические линии одновременно, а generateContent не отправляют на пенсию. По крайней мере до тех пор, пока эти возможности не будут полностью закрыты, он остаётся незаменимым.

🔧 Практический совет: если ваш бизнес сильно завязан на Batch API для пакетной обработки или на explicit caching для снижения затрат, пока рано резко переключаться на Interactions API — можно потерять важные возможности. Лучше сначала следить за обновлениями официального гайда по миграции, а уже потом решать, стоит ли менять production-код.

Практический тест шлюза APIYI: какой парадигмой пользоваться сейчас

Вывод сразу в начале: по результатам практической проверки на 4 июля 2026 года при вызове Gemini через шлюз APIYI по-прежнему нужно использовать нативный формат generateContent.

Техническая команда APIYI напрямую протестировала ключевые пути Interactions API и проверила два основных способа авторизации. Результаты такие:

Тестовый endpoint	Способ авторизации	Результат
POST /v1beta2/interactions	Bearer token	❌ 404 (Invalid URL)
POST /v1beta/interactions	Bearer token	❌ 404 (Invalid URL)
POST /v1beta2/interactions	заголовок x-goog-api-key	❌ 404 (Invalid URL)
POST /v1beta/models/{model}:generateContent	Bearer token	✅ Ответ получен нормально

В официальной документации APIYI прямо сказано: «Шлюз APIYI пока не поддерживает проксирование Interactions API — пути /v1beta2/interactions и /v1beta/interactions оба возвращают 404», и там же дано однозначное рекомендация: «При вызове Gemini через APIYI продолжайте использовать нативный формат generateContent». Именно поэтому вся документация APIYI по Gemini сейчас унифицирована под формат generateContent: так читатель может просто скопировать код и сразу запустить его, не упираясь в 404 по пути.

Важно понимать, что это состояние динамическое, а не пожизненное ограничение. По мере того как Interactions API будет становиться официальным стандартом, шлюз, скорее всего, тоже подтянет поддержку; тогда APIYI обновит соответствующую документацию. Сейчас же можно следить за страницей docs.apiyi.com/api-capabilities/gemini/interactions-api, чтобы получать актуальный статус поддержки, и не тестировать endpoint вручную каждый раз.

Эти тесты ещё раз показывают довольно типичную, но часто игнорируемую вещь: «официально доступно» на уровне документации и «уже поддерживается конкретным шлюзом или сторонним SDK» — это совсем не одно и то же. Если разработчик просто посмотрит на дефолтный пример из официальной документации и без проверки вставит код Interactions API в текущую конфигурацию прокси, он с высокой вероятностью сначала упрётся в 404, а потом потратит время на поиск: это он сам ошибся в коде или шлюз ещё не обновился. В таких случаях лучше сначала проверить, поддерживает ли ваша цепочка вызова — прямой доступ к официальному API или сторонний прокси — новый формат, и уже потом копаться в бизнес-логике.

🚀 Быстрый старт: если вы хотите прямо сейчас проверить, нормально ли работает цепочка вызова Gemini, лучше всего подключаться через APIYI apiyi.com в формате generateContent. Платформа даёт единый base_url, поддерживает вызов текстовых, графических и других моделей Gemini и не требует отдельно разруливать детали авторизации.

Как выбрать: рекомендации по сценарию

С учётом сравнения возможностей выше и результатов практического теста даю простую таблицу с рекомендациями по сценариям.

Сценарий использования	Рекомендуемый вариант	Причина
Вызов Gemini через шлюз APIYI	generateContent	Сейчас шлюз поддерживает только этот формат, а пути Interactions API возвращают 404
Нужна пакетная обработка через Batch API	generateContent	Interactions API пока не поддерживает Batch API
Нужен явный кэш для снижения стоимости	generateContent	У Interactions API сейчас есть только неявный кэш
Строите многоходового agent для диалога и подключаетесь напрямую к официальному API	Можно оценить Interactions API	Серверное управление состоянием убирает необходимость вручную собирать историю
Нужно видеть промежуточные шаги выполнения модели для отладки	Interactions API	Есть нативная поддержка observable execution steps
В текущем проекте generateContent уже работает	Пока не мигрировать	legacy по-прежнему полностью поддерживается и в ближайшее время тоже будет получать новые модели

Если совсем коротко, мигрировать или нет — зависит не от того, «новый» это формат или нет, а от того, покрывает ли Interactions API все ваши зависимости и поддерживает ли ваша цепочка вызова Gemini — прямой официальный доступ или прокси через шлюз — эту новую парадигму. Для большинства разработчиков, которые вызывают APIYI через прокси, на текущем этапе безопаснее оставить generateContent.

Часто задаваемые вопросы

Q1: Может ли generateContent быть отключён? Стоит ли сейчас вообще делать на нём новый проект?

В ближайшее время — нет. Официально заявлено, что хотя generateContent и помечен как legacy, он «по-прежнему полностью поддерживается», и в обозримом будущем для него будут выходить новые основные модели Gemini. Если вы вызываете Gemini через APIYI apiyi.com, то сейчас спокойно можно строить новый проект на generateContent — не нужно переживать из-за того, что в документации по умолчанию показывается Interactions API.

Q2: Когда шлюз APIYI начнёт поддерживать Interactions API?

Точного срока пока нет. Это зависит и от того, насколько этот подход приживётся в официальной экосистеме, и от того, как быстро сам шлюз будет адаптирован. Совет простой: следите за обновлениями официальной документации на платформе APIYI apiyi.com — как только появится поддержка проксирования Interactions API, соответствующие материалы сразу обновят. Не нужно самостоятельно по кругу проверять состояние endpoint’ов.

Q3: Можно ли смешивать оба API в одном проекте?

С технической точки зрения — да, если цепочка вызовов это поддерживает, оба подхода могут сосуществовать. Например, generateContent можно использовать для пакетных задач Batch API, а в сценарии многоходового диалога при прямом подключении к официальному API попробовать Interactions API. Но при вызове через шлюз APIYI сейчас путь Interactions API возвращает 404, поэтому пока лучше придерживаться формата generateContent, чтобы не плодить в одном проекте две разные логики вызова и не усложнять поддержку.

Итог

После того как Interactions API в июне 2026 года был переведён в официальный статус, он действительно стал отражать долгосрочное направление Google для вызова Gemini. Серверное управление состоянием, наблюдаемость шагов выполнения и похожие возможности очень интересны для agent-приложений. Но при этом у него всё ещё есть заметные пробелы — в Batch API, явном кэшировании, metadata для видео и так далее. generateContent по-прежнему полностью поддерживается и в ближайшее время тоже продолжит обновляться. Что ещё важнее: по текущим практическим тестам через шлюз APIYI вызов Gemini по всем связанным с Interactions API путям возвращает 404, а доступным вариантом сейчас остаётся только generateContent. Если вам нужен стабильный и надёжный вызов моделей Gemini, рекомендуем подключаться через APIYI apiyi.com в нативном формате generateContent. Когда шлюз начнёт поддерживать новый подход, документацию сразу обновят.

Практические тестовые данные и проверка официальной информации были выполнены командой APIYI. Если хотите узнать больше о деталях вызова моделей серии Gemini, свяжитесь со службой поддержки APIYI apiyi.com.

Справочные материалы

1. Google AI for Developers — обзор Interactions API: понятие Interaction, основные методы и возможности

   • Ссылка: ai.google.dev/gemini-api/docs/interactions-overview

2. Google AI for Developers — generateContent (Legacy): статус поддержки и набор возможностей устаревшего API

   • Ссылка: ai.google.dev/gemini-api/docs/interactions

3. Официальная документация APIYI — статус поддержки Gemini Interactions API: результаты проверки эндпоинтов на шлюзе и рекомендации по вызовам

   • Ссылка: docs.apiyi.com/api-capabilities/gemini/interactions-api