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

API для взаимодействия — это наш новый интерфейс и самый простой способ работы с моделями и агентами Gemini. С июня 2026 года он доступен для общего использования и является рекомендуемым интерфейсом для всех новых проектов.

Хотя сейчас он считается устаревшим, оригинальный API generateContent по-прежнему полностью поддерживается.

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

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

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

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

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

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

• Показатель попадания в кэш : Использование 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, эта функция появится в ближайшее время.

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

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

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

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

Что дальше?

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