Interactions API

Interfejs Interactions API to najlepszy sposób na tworzenie aplikacji z wykorzystaniem modeli i agentów Gemini. Od czerwca 2026 r. jest on ogólnie dostępny i zalecany w przypadku wszystkich nowych projektów. Pierwotny interfejs generateContent API jest nadal w pełni obsługiwany, choć jest już uważany za starszy.

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, uporządkowanych danych wyjściowych, koordynacji narzędzi i Agentic Workflows.
• 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 rozmowy po stronie serwera za pomocą parametru previous_interaction_id, widoczne kroki wykonania do debugowania i renderowania interfejsu oraz wykonywanie w tle długotrwałych zadań za pomocą parametru 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 turami, co zmniejsza koszty tokenów.
• Miejsce, w którym pojawiają się nowe funkcje: w przyszłości wszystkie nowe modele, funkcje multimodalne , narzędzia i funkcje agenta będą dostępne 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ą parametru previous_interaction_id. Możesz włączyć działanie bezstanowe, ustawiając parametr store=false. Szczegółowe informacje znajdziesz w sekcji Przechowywanie danych.

Rozpocznij

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

Przewodniki po funkcjach

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

• Generowanie tekstu
• Generowanie obrazów
• Rozumienie 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 priorytetowe

Jak działa interfejs Interactions API

Interfejs Interactions API opiera się na podstawowym zasobie: Interaction. Interaction reprezentuje pełną turę w rozmowie lub zadaniu. Działa jako rekord sesji, który zawiera całą historię interakcji jako chronologiczną sekwencję kroków wykonania. Te kroki obejmują myśli modelu, wywołania narzędzi po stronie serwera lub klienta oraz wyniki (np. function_call i function_result) oraz końcowe model_output. Przechowywany zasób (pobierany za pomocą interactions.get) zawiera też kroki user_input dla pełnego kontekstu, chociaż odpowiedź interactions.create zwraca tylko kroki wygenerowane przez model.

Gdy wywołujesz interactions.create, tworzysz nowy Interaction zasób:

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

Aby kontynuować rozmowę, możesz użyć parametru previous_interaction_id w kolejnym wywołaniu, podając id zakończonej interakcji. 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ą parametru previous_interaction_id. Pozostałe parametry są zakresowe i dotyczą tylko 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 je ponownie określić 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 (za pomocą previous_interaction_id), wykonywania w tle (za pomocą background=true) i obserwacji.

• Płatny poziom: system przechowuje interakcje przez 55 dni.
• Poziom bezpłatny: system przechowuje interakcje przez 1 dzień.

Jeśli nie chcesz tego robić, możesz ustawić parametr store=false w żądaniu. To ustawienie jest niezależne od zarządzania stanem. Możesz zrezygnować z przechowywania 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 na płatnym poziomie 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 pobieranie wcześniejszych rozmów.

Przechowywane interakcje możesz usunąć w dowolnym momencie za pomocą metody delete w sposób programowy, co wymaga podania identyfikatora interakcji. W AI Studio możesz też wyświetlać logi przechowywanych interakcji i nimi zarządzać, w tym usuwać je z pamięci projektu, w AI Studio.

Po upływie okresu przechowywania Twoje dane zostaną automatycznie usunięte.

Obiekty Interactions są przetwarzane zgodnie z warunkami.

Wyświetlanie interakcji w AI Studio

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

Sprawdzone metody

• Współczynnik trafień w pamięci podręcznej: buforowanie niejawne jest obsługiwane w trybie stanowym i bezstanowym (patrz Szybki start). Używanie parametru previous_interaction_id (stanowego) do kontynuowania rozmów umożliwia systemowi łatwiejsze wykorzystanie buforowania niejawnego w przypadku historii rozmowy, co zwiększa wydajność i obniża koszty.
• Łączenie interli: możesz dowolnie łączyć interakcje agenta i modelu w ramach rozmowy. Na przykład do wstępnego zbierania danych możesz użyć wyspecjalizowanego agenta, takiego jak agent Deep Research, a następnie użyć standardowego modelu Gemini do wykonywania kolejnych zadań, takich jak podsumowywanie lub formatowanie, łącząc te kroki za pomocą parametru previous_interaction_id.

Obsługiwane modele i agenci

Pakiety SDK

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

• W Pythonie jest to pakiet google-genai w wersji 2.3.0 lub nowszej.
• W JavaScript jest to pakiet @google/genai w wersji 2.3.0 lub nowszej.
• W Go jest to pakiet google.golang.org/genai.
• W Javie jest to pakiet com.google.genai:google-genai.

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

Ograniczenia

• Zdalny MCP: Gemini 3 nie obsługuje zdalnego MCP. Ta funkcja będzie dostępna już wkrótce.
• Zgodność modelu wieloetapowego: w przypadku łączenia różnych modeli w rozmowie (stanowej lub bezstanowej) kolejne modele muszą obsługiwać dane wyjściowe poprzednich modeli jako dane wejściowe. Jeśli np. wygenerujesz obraz za pomocą modelu 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 modelem generującym muzykę, takim jak Lyria).

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

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

Prześlij opinię

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

Co dalej?

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