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

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

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

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

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

Начните

• Настройте своего помощника по программированию : подключитесь к 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 несовместим с background=true и предотвращает использование previous_interaction_id для последующих ходов.

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

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

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

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

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

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

SDK

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

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

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

Ограничения

• Статус бета-версии : API взаимодействий находится в стадии бета-тестирования/предварительного просмотра. Функции и схемы могут изменяться.
• Удалённый MCP : Gemini 3 не поддерживает удалённый MCP, эта функция появится в ближайшее время.

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

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

Изменения, нарушающие покой

API для взаимодействия в настоящее время находится на ранней стадии бета-тестирования. Мы активно разрабатываем и совершенствуем возможности API, схемы ресурсов и интерфейсы SDK на основе реального использования и отзывов разработчиков.

В результате могут произойти существенные изменения, нарушающие обратную совместимость . Обновления могут включать изменения в:

• Схемы ввода и вывода.
• Сигнатуры методов SDK и структуры объектов.
• Поведение отдельных функций.

Для рабочих нагрузок в производственной среде следует продолжать использовать стандартный API generateContent . Он остается рекомендуемым вариантом для стабильных развертываний, и мы будем продолжать активно его разрабатывать и поддерживать.

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

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

Что дальше?

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