Interactions API

Die Interactions API ist die beste Möglichkeit, mit Gemini-Modellen und -Agenten zu arbeiten. Seit Juni 2026 ist sie allgemein verfügbar und wird für alle neuen Projekte empfohlen. Obwohl sie jetzt als Legacy-API gilt, wird die ursprüngliche generateContent API weiterhin vollständig unterstützt.

Gründe für die Verwendung der Interactions API

• Universelle Schnittstelle für alle Anwendungen: Sie wurde als Standard schnittstelle für jeden Anwendungsfall entwickelt, einschließlich Textgenerierung in einer einzelnen Runde, multimodales Verständnis, strukturierte Ausgaben, Tool-Orchestrierung und Agent-Workflows.
• Eine einzige API für Modelle und Agenten: Ein einheitlicher Endpunkt und ein einheitliches Muster für den direkten Aufruf von Standard-Gemini-Modellen sowie spezialisierten Agenten (z. B. Deep Research und benutzerdefinierte verwaltete Agenten).
• Neue Funktionen sofort verfügbar: Funktionen wie optionaler serverseitiger Unterhaltungsstatus mit previous_interaction_id, beobachtbare Ausführungsschritte für das Debugging und die UI-Darstellung sowie die Hintergrund ausführung für zeitaufwendige Aufgaben mit background=true.
• Geringere Kosten durch höhere Cache-Trefferraten: Bei Unterhaltungen in mehreren Runden ermöglicht die optionale serverseitige Statusverwaltung ein effizienteres Kontext-Caching über mehrere Runden hinweg, wodurch die Tokenkosten gesenkt werden.
• Einführung neuer Funktionen: Zukünftig werden alle neuen Modelle, multimodalen Funktionen, Tools und Agent-Funktionen über die Interactions API eingeführt.

Standardmäßig speichert die Interactions API Anfragen, damit Sie die serverseitigen Statusverwaltungsfunktionen mit previous_interaction_id nutzen können. Sie können das zustandslose Verhalten aktivieren, indem Sie store=false festlegen. Weitere Informationen finden Sie im Abschnitt zur Datenaufbewahrung für Details.

Jetzt starten

• Programmieragent einrichten: Stellen Sie eine Verbindung zum Gemini Docs MCP her und installieren Sie die gemini-api-dev Funktion, um Ihrem Assistenten direkten Zugriff auf die neueste Entwicklerdokumentation und Best Practices zu ermöglichen. Eine detaillierte Anleitung finden Sie im Leitfaden Programmieragent einrichten.
• Von generateContent migrieren: Wenn Sie eine vorhandene Integration haben, folgen Sie der Migrationsanleitung, um zur Interactions API zu wechseln.
• Erste Schritte: Folgen Sie der Anleitung Erste Schritte mit der Interactions API guide.

Leitfäden für Funktionen

In diesen Leitfäden erfahren Sie mehr über die spezifischen Funktionen der Interactions API. Mit der Umschaltfläche auf diesen Seiten können Sie zwischen der generateContent API und der Interactions API wechseln:

• Textgenerierung
• Bildgenerierung
• Bildverständnis
• Verständnis von Audioinhalten
• Video-Understanding
• Dokumentverarbeitung
• Funktionsaufrufe
• Strukturierte Ausgabe
• Deep Research-Agent
• Flex-Inferenz
• Prioritätsinferenz

Funktionsweise der Interactions API

Die Interactions API dreht sich um eine Kernressource: die Interaction. Eine Interaction stellt eine vollständige Runde in einer Unterhaltung oder Aufgabe dar. Sie fungiert als Sitzungsaufzeichnung und enthält den gesamten Verlauf einer Interaktion als chronologische Abfolge von Ausführungsschritten. Zu diesen Schritten gehören die Gedanken des Modells, serverseitige oder clientseitige Tool-Aufrufe und -Ergebnisse (z. B. function_call und function_result) sowie die endgültige model_output. Die gespeicherte Ressource (über interactions.get abgerufen) enthält auch user_input-Schritte für den vollständigen Kontext. Die Antwort von interactions.create gibt jedoch nur vom Modell generierte Schritte zurück.

Wenn Sie interactions.create aufrufen, erstellen Sie eine neue Interaction Ressource:

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

Serverseitige Statusverwaltung

Sie können die id einer abgeschlossenen Interaktion in einem nachfolgenden Aufruf mit dem previous_interaction_id Parameter verwenden, um die Unterhaltung fortzusetzen. Der Server verwendet diese ID, um den Unterhaltungsverlauf abzurufen. So müssen Sie nicht den gesamten Chatverlauf noch einmal senden:

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

Mit dem Parameter previous_interaction_id wird nur der Unterhaltungsverlauf (Eingaben und Ausgaben) beibehaltenprevious_interaction_id. Die anderen Parameter sind interaktionsbezogen und gelten nur für die spezifische Interaktion, die Sie gerade generieren:

• tools
• system_instruction
• generation_config (einschließlich thinking_level, temperature usw.)

Das bedeutet, dass Sie diese Parameter in jeder neuen Interaktion noch einmal angeben müssen, wenn sie angewendet werden sollen. Diese serverseitige Statusverwaltung ist optional. Sie können auch im zustandslosen Modus arbeiten, indem Sie bei jeder Anfrage den vollständigen Unterhaltungsverlauf senden.

Datenspeicherung und -aufbewahrung

Standardmäßig speichert die API alle Interaction-Objekte (store=true), um die Verwendung der serverseitigen Statusverwaltungsfunktionen (mit previous_interaction_id), Hintergrundausführung (mit background=true) und die Beobachtbarkeit zu vereinfachen.

• Kostenpflichtiges Abo: Das System bewahrt Interaktionen 55 Tage lang auf.
• Kostenlose Stufe: Das System bewahrt Interaktionen einen Tag lang auf.

Wenn Sie das nicht möchten, können Sie in Ihrer Anfrage store=false festlegen. Diese Einstellung ist unabhängig von der Statusverwaltung. Sie können die Speicherung für jede Interaktion deaktivieren. Beachten Sie jedoch, dass store=false nicht mit Hintergrundausführung kompatibel ist und die Verwendung previous_interaction_id für nachfolgende Runden verhindert.

Bei Projekten mit kostenpflichtigem Abo können Sie das Aufbewahrungsfenster in AI Studio so konfigurieren, dass Protokolle nach 7, 14, 28 oder 55 Tagen automatisch zur Löschung aus dem Projektspeicher markiert werden. Eine kürzere Aufbewahrungsfrist kann sich auf den Abruf früherer Unterhaltungen auswirken.

Sie können gespeicherte Interaktionen jederzeit programmatisch mit der delete Methode löschen, dazu ist die Interaktions-ID erforderlich. In AI Studio können Sie auch Protokolle gespeicherter Interaktionen ansehen und verwalten, einschließlich des Löschens aus dem Projektspeicher, in AI Studio.

Nach Ablauf der Aufbewahrungsfrist werden Ihre Daten automatisch gelöscht.

Interaction-Objekte werden gemäß den Nutzungsbedingungen verarbeitet.

Interaktionen in AI Studio ansehen

Die API speichert Interactions API-Anfragen, die mit store=true für Projekte mit kostenpflichtigem Abo ausgeführt wurden. Sie können sie direkt auf der Seite „Protokolle“ in Google AI Studio ansehen. Weitere Informationen finden Sie im Leitfaden zu Protokollen.

Best Practices

• Cache-Trefferrate: Implizites Caching wird sowohl im zustandsorientierten als auch im zustandslosen Modus unterstützt (siehe Kurzanleitung). Wenn Sie previous_interaction_id (zustandsorientiert) verwenden, um Unterhaltungen fortzusetzen, kann das System implizites Caching für den Unterhaltungsverlauf einfacher nutzen. Das verbessert die Leistung und senkt die Kosten.
• Kombination von Interaktionen: Sie können Agent- und Modellinteraktionen innerhalb einer Unterhaltung kombinieren. Sie können beispielsweise einen spezialisierten Agenten wie den Deep Research-Agenten für die erste Datenerhebung verwenden und dann ein Standard-Gemini-Modell für Folgeaufgaben wie Zusammenfassen oder Neuformatieren nutzen. Diese Schritte lassen sich mit previous_interaction_id verknüpfen.

Unterstützte Modelle und Agenten

SDKs

Sie können die aktuelle Version der Google GenAI SDKs verwenden, um auf die Interactions API zuzugreifen.

• In Python ist das das Paket google-genai ab Version 2.3.0.
• In JavaScript ist das das Paket @google/genai ab Version 2.3.0.
• In Go ist das das Paket google.golang.org/genai.
• In Java ist das das Paket com.google.genai:google-genai.

Weitere Informationen zum Installieren der SDKs finden Sie auf der Seite „ Bibliotheken“.

Beschränkungen

• Remote-MCP: Gemini 3 unterstützt kein Remote-MCP. Diese Funktion ist demnächst verfügbar.
• Kompatibilität mit Modellen für mehrere Runden: Wenn Sie verschiedene Modelle in einer Unterhaltung kombinieren (entweder zustandsorientiert oder zustandslos), müssen die nachfolgenden Modelle die Ausgabemodalitäten der vorherigen Modelle als Eingabe unterstützen. Wenn Sie beispielsweise ein Bild mit gemini-3.1-flash-image generieren, können Sie die Unterhaltung nicht mit einem Modell fortsetzen, das keine Bildeingaben akzeptiert (z. B. ein reines Textmodell oder ein Musikgenerierungsmodell wie Lyria).

Die folgenden Funktionen werden von der generateContent API unterstützt, sind aber in der Interactions API noch nicht verfügbar:

• Batch API
• Automatische Funktionsaufrufe (Python)
• Explizites Caching: Serverseitiges implizites Caching ist in der Interactions API über previous_interaction_id verfügbar.
• Sicherheitseinstellungen: Benutzerdefinierte Sicherheitseinstellungen werden in der Interactions API nicht unterstützt.

Feedback

Ihr Feedback ist entscheidend für die Entwicklung der Interactions API. Teilen Sie uns Ihre Meinung mit, melden Sie Fehler oder fordern Sie Funktionen in unserem Google AI Developer Community-Forum an.

Nächste Schritte

• Probieren Sie das Kurzanleitungs-Notebook für die Interactions API aus.
• Weitere Informationen zum Deep Research-Agenten von Gemini.