Interactions API

Die Interactions API ist die beste Möglichkeit, mit Gemini-Modellen und ‑Agents zu entwickeln. Ab Juni 2026 ist es allgemein verfügbar und wird für alle neuen Projekte empfohlen. Die ursprüngliche generateContent API gilt zwar als Legacy-API, wird aber weiterhin vollständig unterstützt.

Vorteile der Interactions API

• Universelle Schnittstelle für alle Anwendungen: Sie ist als Standardschnittstelle für alle Anwendungsfälle konzipiert, einschließlich der einmaligen Textgenerierung, des multimodalen Verständnisses, strukturierter Ausgaben, der Tool-Orchestrierung und von Agent-Workflows.
• Eine API für Modelle und Agents: Ein einheitlicher Endpunkt und ein einheitliches Muster zum direkten Aufrufen von Standard-Gemini-Modellen sowie von spezialisierten Agents wie Deep Research und benutzerdefinierten verwalteten Agents.
• Neue sofort einsatzbereite Funktionen: Funktionen wie der optionale serverseitige Konversationsstatus mit previous_interaction_id, beobachtbare Ausführungsschritte für das Debugging und das Rendern der Benutzeroberfläche sowie die Hintergrundausführung für zeitaufwendige Aufgaben mit background=true.
• Geringere Kosten durch höhere Cache-Trefferraten: Bei Verwendung von Mehrfachdialogen ermöglicht die optionale serverseitige Statusverwaltung ein effizienteres Kontext-Caching über mehrere Durchgänge hinweg, wodurch die Tokenkosten gesenkt werden.
• Einführung neuer Funktionen: Alle neuen Modelle, multimodalen Funktionen, Tools und Agent-Funktionen werden künftig über die Interactions API eingeführt.

Standardmäßig werden Anfragen in der Interactions API gespeichert, damit Sie die serverseitigen Funktionen zur Statusverwaltung 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 Datenaufbewahrung.

Jetzt starten

• KI-Programmieragenten einrichten: Verbinden Sie sich mit dem Gemini Docs MCP und installieren Sie den gemini-api-dev-Skill, um Ihrem Assistenten direkten Zugriff auf die neuesten Entwicklerdokumente und Best Practices zu ermöglichen. Eine ausführliche Anleitung finden Sie im Leitfaden zum Einrichten Ihres Coding-Agents.
• 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 im Leitfaden „Erste Schritte mit der Interactions API“.

Leitfäden für Funktionen

In diesen Anleitungen erfahren Sie mehr über die spezifischen Funktionen der Interactions API. Mit dem Ein/Aus-Schalter auf diesen Seiten können Sie zwischen der generateContent API und der Interactions API wechseln:

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

Funktionsweise der Interactions API

Die Interactions API dreht sich um eine zentrale Ressource: die Interaction. Ein Interaction stellt eine vollständige Runde in einer Unterhaltung oder Aufgabe dar. Es dient als Sitzungsaufzeichnung und enthält den gesamten Verlauf einer Interaktion als chronologische Abfolge von Ausführungsschritten. Diese Schritte umfassen die Überlegungen 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 (abgerufen über interactions.get) enthält auch user_input-Schritte für den vollständigen Kontext. Die interactions.create-Antwort 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 Parameter previous_interaction_id 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 (Ein- und Ausgaben) mit previous_interaction_id beibehalten. Die anderen Parameter sind interaktionsbezogen und gelten nur für die jeweilige Interaktion, die Sie gerade generieren:

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

Das bedeutet, dass Sie diese Parameter bei 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 den vollständigen Unterhaltungsverlauf in jeder Anfrage senden.

Datenspeicherung und ‑aufbewahrung

Standardmäßig werden alle Interaction-Objekte (store=true) von der API gespeichert, um die Verwendung von serverseitigen Funktionen zur Statusverwaltung (mit previous_interaction_id), Hintergrundausführung (mit background=true) und Observability zu vereinfachen.

• Kostenpflichtiges Abo: Interaktionen werden 55 Tage lang gespeichert.
• Kostenlose Stufe: Das System behält Interaktionen einen Tag lang bei.

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

Bei Projekten im kostenpflichtigen Tarif können Sie das Aufbewahrungszeitfenster in AI Studio konfigurieren, um Protokolle nach 7, 14, 28 oder 55 Tagen automatisch zum Löschen aus dem Projektspeicher zu markieren. Eine kürzere Aufbewahrungsdauer kann sich auf das Abrufen früherer Unterhaltungen auswirken.

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

Nach Ablauf des Aufbewahrungszeitraums werden Ihre Daten automatisch gelöscht.

Interaktionsobjekte werden gemäß den Nutzungsbedingungen verarbeitet.

Interaktionen in AI Studio ansehen

Die API speichert Interactions API-Anfragen, die mit store=true für Projekte in der kostenpflichtigen Stufe ausgeführt werden. Sie können sie direkt auf der Seite „Logs“ in Google AI Studio aufrufen. Weitere Informationen finden Sie im Leitfaden für Protokolle.

Best Practices

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

Unterstützte Modelle und KI-Agenten

SDKs

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

• In Python ist dies 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 com.google.genai:google-genai-Paket.

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 wird bald eingeführt.
• Kompatibilität von Mehrfachdialog-Modellen: Wenn Sie verschiedene Modelle in einer Unterhaltung (zustandsorientiert oder zustandslos) kombinieren, müssen nachfolgende 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 noch nicht in der Interactions API verfügbar:

• Batch API
• Automatisches Aufrufen von Funktionen (Python)
• Explizites Caching: Das serverseitige implizite 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. Im Google AI Developer Community-Forum können Sie Ihre Meinung äußern, Fehler melden oder Funktionen anfragen.

Nächste Schritte

• Kurzanleitung für die Interactions API
• Weitere Informationen zum Gemini Deep Research-Agent