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. Подробнее о хранении данных…

Начать

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

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

Ознакомьтесь с руководствами по возможностям Interactions 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).

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

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

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

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

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

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