Interactions API

Interactions API to najlepszy sposób na tworzenie aplikacji z wykorzystaniem modeli i agentów Gemini. Od czerwca 2026 r. jest ogólnie dostępna i zalecana we wszystkich nowych projektach. Chociaż jest on obecnie uważany za starszy, oryginalny interfejs generateContent API jest nadal w pełni obsługiwany.

Dlaczego warto korzystać z interfejsu Interactions API?

• Uniwersalny interfejs dla wszystkich aplikacji: zaprojektowany jako standardowy interfejs dla każdego przypadku użycia, w tym generowania tekstu w jednej turze, rozpoznawania multimodalnego, danych wyjściowych o strukturze, orkiestracji narzędzi i przepływów pracy agenta.
• Jeden interfejs API dla modeli i agentów: jeden ujednolicony punkt końcowy i wzorzec do bezpośredniego wywoływania standardowych modeli Gemini oraz wyspecjalizowanych agentów (takich jak Deep Research i niestandardowi agenci zarządzani).
• Nowe funkcje od razu po wyjęciu z pudełka: funkcje takie jak opcjonalny stan konwersacji po stronie serwera za pomocą previous_interaction_id, widoczne kroki wykonywania do debugowania i renderowania interfejsu oraz wykonywanie w tle długotrwałych zadań za pomocą background=true.
• Niższe koszty dzięki wyższym współczynnikom trafień w pamięci podręcznej: w przypadku rozmów wieloetapowych opcjonalne zarządzanie stanem po stronie serwera umożliwia wydajniejsze buforowanie kontekstu między etapami, co zmniejsza koszty tokenów.
• Miejsce wprowadzania nowych funkcji: wszystkie nowe modele, funkcje multimodalne, narzędzia i funkcje oparte na agentach będą od teraz wprowadzane w interfejsie Interactions API.

Domyślnie interfejs Interactions API przechowuje żądania, dzięki czemu możesz korzystać z funkcji zarządzania stanem po stronie serwera za pomocą previous_interaction_id. Możesz włączyć działanie bezstanowe, ustawiając store=false. Więcej informacji znajdziesz w sekcji Przechowywanie danych.

Rozpocznij

• Skonfiguruj agenta kodowania: połącz się z Gemini Docs MCP i zainstaluj gemini-api-dev umiejętność, aby zapewnić asystentowi bezpośredni dostęp do najnowszej dokumentacji dla deweloperów i sprawdzonych metod. Szczegółowe instrukcje znajdziesz w przewodniku konfigurowania agenta do kodowania.
• Migracja z generateContent: jeśli masz już integrację, postępuj zgodnie z przewodnikiem migracji, aby przejść na interfejs Interactions API.
• Rozpocznij: wykonaj czynności opisane w przewodniku dotyczącym interfejsu Interactions API.

Przewodniki po funkcjach

Z tych przewodników dowiesz się więcej o konkretnych możliwościach interfejsu Interactions API. Na tych stronach możesz przełączać się między interfejsami generateContent i Interactions API za pomocą przełącznika:

• Generowanie tekstu
• Generowanie obrazów
• Rozpoznawanie obrazów
• Rozumienie dźwięku
• Rozumienie filmów
• Przetwarzanie dokumentów
• Wywoływanie funkcji
• Uporządkowane dane wyjściowe
• Agent Deep Research
• Wnioskowanie Flex
• Wnioskowanie o priorytecie

Jak działa interfejs Interactions API

Interfejs API interakcji opiera się na podstawowym zasobie: Interaction. Symbol Interaction oznacza pełną turę w rozmowie lub zadaniu. Działa on jak zapis sesji, zawierający całą historię interakcji w postaci chronologicznej sekwencji kroków wykonania. Obejmują one przemyślenia modelu, wywołania narzędzi po stronie serwera lub klienta i wyniki (np. function_call i function_result) oraz ostateczną model_output. Zapisany zasób (pobrany za pomocą interactions.get) zawiera też user_input kroki, które zapewniają pełny kontekst, ale odpowiedź interactions.create zawiera tylko kroki wygenerowane przez model.

Gdy wykonujesz połączenie do interactions.create, tworzysz nowy zasób 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."
  }'

Zarządzanie stanem po stronie serwera

W kolejnym wywołaniu możesz użyć id zakończonej interakcji, korzystając z parametru previous_interaction_id, aby kontynuować rozmowę. Serwer używa tego identyfikatora do pobierania historii rozmowy, dzięki czemu nie musisz ponownie wysyłać całej historii czatu:

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"
  }'

Parametr previous_interaction_id zachowuje tylko historię rozmowy (dane wejściowe i wyjściowe) za pomocą previous_interaction_id. Pozostałe parametry mają zakres interakcji i mają zastosowanie tylko do konkretnej interakcji, którą obecnie generujesz:

• tools
• system_instruction
• generation_config (w tym thinking_level, temperature itp.)

Oznacza to, że jeśli chcesz, aby te parametry były stosowane, musisz ponownie określić je w każdej nowej interakcji. Zarządzanie stanem po stronie serwera jest opcjonalne. Możesz też działać w trybie bezstanowym, wysyłając pełną historię rozmowy w każdym żądaniu.

Przechowywanie danych

Domyślnie interfejs API przechowuje wszystkie obiekty Interaction (store=true), aby uprościć korzystanie z funkcji zarządzania stanem po stronie serwera (z previous_interaction_id), wykonania w tle (za pomocą background=true) i dostrzegalności.

• Wersja płatna: system przechowuje interakcje przez 55 dni.
• Bezpłatna wersja: system przechowuje interakcje przez 1 dzień.

Jeśli nie chcesz, aby tak się stało, możesz w swojej prośbie ustawić store=false. Ta kontrola jest niezależna od zarządzania stanem. Możesz zrezygnować z przechowywania danych w przypadku dowolnej interakcji. Pamiętaj jednak, że store=false jest niezgodny z wykonywaniem w tle i uniemożliwia używanie previous_interaction_id w kolejnych turach.

W przypadku projektów w wersji płatnej możesz skonfigurować okres przechowywania w AI Studio, aby automatycznie oznaczać logi do usunięcia z pamięci projektu po 7, 14, 28 lub 55 dniach. Krótszy okres przechowywania może wpłynąć na możliwość odzyskania wcześniejszych rozmów.

Zapisane interakcje możesz w każdej chwili usunąć programowo za pomocą metody delete, która wymaga identyfikatora interakcji. W AI Studio możesz też wyświetlać dzienniki zapisanych interakcji i nimi zarządzać, w tym usuwać je z pamięci projektu.

Po wygaśnięciu okresu przechowywania Twoje dane zostaną automatycznie usunięte.

Obiekty interakcji są przetwarzane zgodnie z warunkami.

Wyświetlanie interakcji w AI Studio

Interfejs API przechowuje żądania interfejsu Interactions API wykonane za pomocą store=true w przypadku projektów na poziomie płatnym. Możesz je wyświetlić bezpośrednio na stronie dzienników w Google AI Studio. Więcej informacji znajdziesz w przewodniku po logach.

Sprawdzone metody

• Współczynnik trafień w pamięci podręcznej: automatyczne buforowanie jest obsługiwane w trybie stanowym i bezstanowym (patrz Szybki start). Używanie previous_interaction_id (stanowego) do kontynuowania rozmów umożliwia systemowi łatwiejsze korzystanie z niejawnego buforowania historii rozmów, co zwiększa wydajność i obniża koszty.
• Mieszanie interakcji: możesz mieszać interakcje z agentem i modelem w ramach jednej rozmowy. Możesz na przykład użyć specjalistycznego agenta, takiego jak agent Deep Research, do wstępnego zbierania danych, a następnie użyć standardowego modelu Gemini do wykonywania kolejnych zadań, takich jak podsumowywanie lub formatowanie, łącząc te kroki za pomocą funkcji previous_interaction_id.

Obsługiwane modele i agenci

Pakiety SDK

Aby uzyskać dostęp do interfejsu API interakcji, możesz użyć najnowszej wersji pakietów SDK Google GenAI.

• W Pythonie jest to pakiet google-genai od wersji 2.3.0.
• W przypadku JavaScriptu jest to pakiet @google/genai od wersji 2.3.0.
• W przypadku Go jest to google.golang.org/genai package.
• W przypadku Javy jest to pakiet com.google.genai:google-genai.

Więcej informacji o instalowaniu pakietów SDK znajdziesz na stronie Biblioteki.

Ograniczenia

• Remote MCP: Gemini 3 nie obsługuje zdalnego MCP. Ta funkcja będzie dostępna wkrótce.
• Zgodność modelu wieloetapowego: w przypadku łączenia różnych modeli w rozmowie (stanowej lub bezstanowej) kolejne modele muszą obsługiwać tryby wyjściowe poprzednich modeli jako dane wejściowe. Jeśli na przykład wygenerujesz obraz za pomocą gemini-3.1-flash-image, nie możesz kontynuować tej rozmowy z modelem, który nie akceptuje danych wejściowych w postaci obrazu (np. z modelem obsługującym tylko tekst lub z modelem do generowania muzyki, takim jak Lyria).

Te funkcje są obsługiwane przez interfejs API generateContent, ale nie są jeszcze dostępne w interfejsie API interakcji:

• Batch API
• Automatyczne wywoływanie funkcji (Python)
• Jawne buforowanie: pamiętaj, że niejawne buforowanie po stronie serwera jest dostępne w interfejsie Interactions API za pomocą parametru previous_interaction_id.
• Ustawienia bezpieczeństwa: niestandardowe ustawienia bezpieczeństwa nie są obsługiwane w interfejsie Interactions API.

Prześlij opinię

Twoja opinia jest kluczowa dla rozwoju interfejsu API do interakcji. Podziel się swoimi przemyśleniami, zgłoś błędy lub poproś o funkcje na naszym forum społeczności deweloperów Google AI.

Co dalej?

• Wypróbuj notatnik z szybkim wprowadzeniem do interfejsu Interactions API.
• Dowiedz się więcej o agencie Deep Research w Gemini.