Interactions API

Die Interactions API ist die einfachste und beste Möglichkeit, Anwendungen mit Gemini-Modellen und ‑Agents zu entwickeln. Seit Juni 2026 ist sie 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 Textgenerierung in einem Durchgang, des multimodalen Verständnisses, strukturierter Ausgaben, der Tool-Orchestrierung und agentischer Workflows.
  • Eine API für Modelle und Agents: Ein einheitlicher Endpunkt und ein einheitliches Muster zum direkten Aufrufen von Standard-Gemini-Modellen sowie spezialisierten Agents (z. B. Deep Research und benutzerdefinierte verwaltete Agents).
  • Neue Funktionen sofort verfügbar: Funktionen wie der optionale serverseitige Unterhaltungsstatus 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.
  • Niedrigere Kosten durch höhere Cache-Trefferraten: Bei Verwendung von Unterhaltungen mit mehreren Durchgängen 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 in der 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 statuslose Verhalten aktivieren, indem Sie store=false festlegen. Weitere Informationen finden Sie im Abschnitt Datenaufbewahrung.

Jetzt starten

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:

Funktionsweise der Interactions API

Die Interactions API dreht sich um eine zentrale Ressource: die Interaction. Ein Interaction stellt einen vollständigen Zug 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 Modellüberlegungen, 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 einen Aufruf an interactions.create senden, erstellen Sie eine neue Interaction-Ressource.

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.

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 neu 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 speichert die API alle Interaktionsobjekte (store=true), um die Verwendung von serverseitigen Funktionen zur Statusverwaltung (mit previous_interaction_id), Hintergrundausführung (mit background=true) und Observability zu vereinfachen.

  • Aboversion: Das System behält Interaktionen 55 Tage lang bei.
  • Kostenlose Stufe: Das System behält Interaktionen einen Tag lang bei.

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. store=false ist jedoch nicht mit der Hintergrundausführung 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 vergangener 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 der Aufbewahrungsdauer 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 zu Logs.

Best Practices

  • Cache-Trefferrate: 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 mischen: Sie können Agent- und Modellinteraktionen in einem Gespräch mischen. 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

Modellname Typ Modell-ID
Gemini 3.5 Flash Modell gemini-3.5-flash
Gemini 3.1 Pro (Vorabversion) Modell gemini-3.1-pro-preview
Gemini 3.1 Flash Lite Modell gemini-3.1-flash-lite
Gemini 3 Flash (Vorabversion) Modell gemini-3-flash-preview
Gemini 2.5 Pro Modell gemini-2.5-pro
Gemini 2.5 Flash Modell gemini-2.5-flash
Gemini 2.5 Flash-Lite Modell gemini-2.5-flash-lite
Gemini 3 Pro Image Modell gemini-3-pro-image
Gemini 3.1 Flash Image Modell gemini-3.1-flash-image
Gemini 3.1 Flash TTS (Vorabversion) Modell gemini-3.1-flash-tts-preview
Gemma 4 31B IT Modell gemma-4-31b-it
Gemma 4 26B MoE IT Modell gemma-4-26b-a4b-it
Lyria 3-Clip-Vorschau Modell lyria-3-clip-preview
Lyria 3 Pro (Vorabversion) Modell lyria-3-pro-preview
Deep Research-Vorabversion Agent deep-research-preview-04-2026
Deep Research-Vorabversion Agent deep-research-max-preview-04-2026
Antigravity-Vorschau Agent antigravity-preview-05-2026

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.

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 Modellen mit mehreren Durchgängen: Wenn Sie verschiedene Modelle in einer Unterhaltung (mit oder ohne Status) 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:

Feedback

Ihr Feedback ist für die Entwicklung der Interactions API von entscheidender Bedeutung. Im Google AI Developer Community-Forum können Sie Ihre Meinung äußern, Fehler melden oder Funktionen anfragen.

Nächste Schritte