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 взаимодействий:

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

Как работает 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 несовместим с