Interactions API

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

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

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

По умолчанию Interactions API сохраняет запросы, чтобы вы могли использовать функции управления состоянием на стороне сервера с помощью previous_interaction_id. Чтобы включить режим без отслеживания состояния, задайте значение store=false. Подробную информацию вы найдете в разделе Хранение данных.

Начать

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

Обзор функций

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

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

Как работает Interactions API

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

Когда вы вызываете interactions.create, вы создаете новый ресурс Interaction:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a short story about a time-traveling lighthouse."
)

print(interaction.output_text)

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Tell me a short story about a time-traveling lighthouse.",
});

console.log(interaction.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me a short story about a time-traveling lighthouse."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Tell me a short story about a time-traveling lighthouse."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a short story about a time-traveling lighthouse."
  }'

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

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

from google import genai

client = genai.Client()

# 1. First turn
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi, my name is Phil."
)

# 2. Second turn (chained using previous_interaction_id)
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id
)

print(turn2.output_text)

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

// 1. First turn
const turn1 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Hi, my name is Phil.",
});

// 2. Second turn (chained using previous_interaction_id)
const turn2 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "What is my name?",
  previous_interaction_id: turn1.id,
});

console.log(turn2.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// 1. First turn
Interaction turn1 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("Hi, my name is Phil."))
                    .build()))
        .interaction()
        .get();

// 2. Second turn (chained using previousInteractionId)
Interaction turn2 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("What is my name?"))
                    .previousInteractionId(turn1.id().get())
                    .build()))
        .interaction()
        .get();

System.out.println(turn2.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. First turn
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hi, my name is Phil."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Second turn (chained using PreviousInteractionID)
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            Input:                 interactions.NewInteractionsInput("What is my name?"),
            PreviousInteractionID: turn1.Interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if turn2.Interaction.OutputText != nil {
        fmt.Println(*turn2.Interaction.OutputText)
    }
}

# Replace PREVIOUS_INTERACTION_ID with the id returned from the first turn
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is my name?",
    "previous_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

Чтобы получить доступ к Interactions API, используйте последнюю версию Google GenAI SDK.

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

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

Ограничения

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

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

• Batch API
• Автоматический вызов функций (Python)
• Явное кеширование. Обратите внимание, что в Interactions API доступно неявное кеширование на стороне сервера через previous_interaction_id.

Как оставить отзыв

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

Дальнейшие действия

• Попробуйте блокнот с кратким руководством по Interactions API.
• Подробнее об агенте Gemini Deep Research…