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.

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

Изучите возможности 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…