API взаимодействия

API Interactions — это наш самый простой и лучший способ работы с моделями и агентами Gemini. По состоянию на июнь 2026 года он стал общедоступным и рекомендуется для всех новых проектов. Хотя сейчас он считается устаревшим, оригинальный API generateContent по-прежнему полностью поддерживается.

Зачем использовать API для взаимодействия?

• Универсальный интерфейс для всех приложений : разработан как стандартный интерфейс для любого сценария использования, включая генерацию текста за один проход, многомодальное понимание, структурированные выходные данные, оркестровку инструментов и агентные рабочие процессы.
• Единый API для моделей и агентов : Единая конечная точка и шаблон для прямого вызова стандартных моделей Gemini, а также специализированных агентов (таких как Deep Research и пользовательские управляемые агенты).
• Новые возможности «из коробки» : такие функции, как опциональное отображение состояния диалога на стороне сервера с помощью previous_interaction_id , наблюдаемые шаги выполнения для отладки и отрисовки пользовательского интерфейса, а также фоновое выполнение длительных задач с помощью background=true .
• Снижение затрат при более высокой частоте попаданий в кэш : при использовании многоходовых диалогов опциональное управление состоянием на стороне сервера обеспечивает более эффективное кэширование контекста между ходами, снижая затраты на токены.
• Где будут запускаться новые функции : В дальнейшем все новые модели, многомодальные возможности, инструменты и функции для работы с агентами будут запускаться через API взаимодействий.

По умолчанию API взаимодействий сохраняет запросы, поэтому вы можете использовать возможности управления состоянием на стороне сервера, используя previous_interaction_id . Вы можете включить режим без сохранения состояния, установив store=false . Подробности см. в разделе « Сохранение данных» .

Начать

• Настройте своего помощника по программированию : подключитесь к Gemini Docs MCP и установите навык gemini-interactions-api , чтобы предоставить своему помощнику прямой доступ к последней документации для разработчиков и рекомендациям по лучшим практикам. Настройте своего помощника по программированию →
• Переход с generateContent : Если у вас уже есть интеграция, следуйте руководству по миграции , чтобы перейти на API взаимодействий.
• Начало работы : Руководство по началу работы с API взаимодействий .

Руководства по функциям

Изучите конкретные возможности API взаимодействий с помощью этих руководств. Вы можете использовать переключатель на этих страницах для переключения между generateContent и API взаимодействий:

• Генерация текста
• генерация изображений
• понимание изображений
• Понимание звука
• Понимание видео
• Обработка документов
• Вызов функции
• Структурированный вывод
• Агент глубоких исследований
• Гибкий вывод
• Приоритетный вывод

Как работает API взаимодействий

API взаимодействия основан на ключевом ресурсе: Interaction . Interaction представляет собой полный ход в разговоре или задаче. Оно действует как запись сессии, содержащая всю историю взаимодействия в виде хронологической последовательности шагов выполнения . Эти шаги включают в себя мысли модели, вызовы инструментов на стороне сервера или клиента и результаты (например, function_call и function_result ), а также итоговый model_output ). Сохраненный ресурс (получаемый через interactions.get ) также включает шаги ввода user_input для полного контекста, хотя ответ interactions.create возвращает только шаги, сгенерированные моделью.

При вызове метода interactions.create вы создаете новый ресурс Interaction .

Управление состоянием на стороне сервера

Вы можете использовать id завершенного взаимодействия в последующем вызове, используя параметр previous_interaction_id , чтобы продолжить разговор. Сервер использует этот идентификатор для получения истории разговора, что избавляет вас от необходимости повторно отправлять всю историю чата.

Параметр previous_interaction_id сохраняет только историю диалога (входные и выходные данные), используя previous_interaction_id . Остальные параметры относятся к конкретному взаимодействию и применяются только к тому конкретному взаимодействию, которое вы сейчас генерируете:

• tools
• system_instruction
• generation_config (включая thinking_level , temperature и т. д.)

Это означает, что вам необходимо повторно указывать эти параметры при каждом новом взаимодействии, если вы хотите, чтобы они применялись. Управление состоянием на стороне сервера является необязательным; вы также можете работать в режиме без сохранения состояния, отправляя полную историю разговора в каждом запросе.

Хранение и сохранение данных

По умолчанию API хранит все объекты Interaction ( store=true ), чтобы упростить использование функций управления состоянием на стороне сервера (с помощью previous_interaction_id ), фонового выполнения (с помощью background=true ) и целей мониторинга.

• Платный уровень : система сохраняет информацию о взаимодействиях в течение 55 дней .
• Бесплатный уровень : система сохраняет информацию о взаимодействиях в течение 1 дня .

Если вам это не нужно, вы можете установить store=false в своем запросе. Этот параметр управляется отдельно от управления состоянием; вы можете отказаться от хранения данных для любого взаимодействия. Однако обратите внимание, что store=false несовместим с фоновым выполнением и предотвращает использование previous_interaction_id для последующих ходов.

Для проектов платного уровня в AI Studio можно настроить период хранения, чтобы журналы автоматически помечались для удаления из хранилища проекта через 7, 14, 28 или 55 дней. Более короткий срок хранения может повлиять на возможность восстановления прошлых разговоров.

Вы можете удалить сохраненные взаимодействия в любое время, используя программный метод delete , для которого требуется идентификатор взаимодействия. Вы также можете просматривать и управлять журналами сохраненных взаимодействий, включая удаление из хранилища проекта, в AI Studio .

По истечении срока хранения ваши данные будут автоматически удалены.

Объекты взаимодействия обрабатываются в соответствии с условиями .

Просмотр взаимодействий в AI Studio

API хранит запросы к Interactions API, выполненные с store=true для проектов платного уровня. Вы можете просмотреть их непосредственно на странице «Журналы» в Google AI Studio . Подробнее см. в руководстве по журналам .

Передовые методы

• Частота попаданий в кэш : Неявное кэширование поддерживается как в режиме с сохранением состояния, так и в режиме без сохранения состояния (см. Быстрый старт ). Использование previous_interaction_id (режим с сохранением состояния) для продолжения диалогов позволяет системе проще использовать неявное кэширование истории диалогов, что повышает производительность и снижает затраты.
• Смешивание взаимодействий : У вас есть возможность комбинировать взаимодействия агентов и моделей в рамках диалога. Например, вы можете использовать специализированного агента, такого как агент Deep Research, для первоначального сбора данных, а затем использовать стандартную модель Gemini для последующих задач, таких как суммирование или переформатирование, связывая эти шаги с previous_interaction_id .

Поддерживаемые модели и агенты

SDK

Для доступа к API взаимодействий можно использовать последнюю версию SDK Google GenAI.

• В Python это пакет google-genai , начиная с версии 2.3.0 .
• В JavaScript это пакет @google/genai , начиная с версии 2.3.0 .

Более подробную информацию об установке SDK можно найти на странице «Библиотеки» .

Ограничения

• Удалённый MCP : Gemini 3 не поддерживает удалённый MCP, эта функция появится в ближайшее время.
• Совместимость моделей при многоходовом взаимодействии : при смешивании различных моделей в диалоге (как с сохранением состояния, так и без него) последующие модели должны поддерживать выходные модальности предыдущих моделей в качестве входных. Например, если вы генерируете изображение с помощью gemini-3.1-flash-image , вы не можете продолжить этот диалог с моделью, которая не принимает изображения в качестве входных данных (например, текстовой моделью или моделью генерации музыки, такой как Lyria).

Следующие функции поддерживаются API generateContent , но пока недоступны в API Interactions:

• Метаданные видео : Поле video_metadata используется для установки интервалов обрезки и пользовательской частоты кадров для лучшего понимания видео.
• Пакетный API
• Автоматический вызов функций (Python)
• Явное кэширование : Обратите внимание, что неявное кэширование на стороне сервера доступно в API взаимодействий через previous_interaction_id .
• Настройки безопасности : Пользовательские настройки безопасности не поддерживаются в API взаимодействий.

Обратная связь

Ваши отзывы крайне важны для разработки API взаимодействий. Делитесь своими мыслями, сообщайте об ошибках или предлагайте новые функции на нашем форуме сообщества разработчиков Google AI .

Что дальше?

• Попробуйте блокнот для быстрого запуска API взаимодействий .
• Узнайте больше об агенте Gemini Deep Research Agent .