Interactions API

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

Warum die Interactions API verwenden?

  • Universelle Schnittstelle für alle Anwendungen: Sie wurde als Standard schnittstelle für alle Anwendungsfälle 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 ohne zusätzliche Konfiguration: Funktionen wie optionaler serverseitiger Unterhaltungsstatus mit previous_interaction_id, beobachtbare Ausführungsschritte für das Debugging und das UI-Rendering sowie die Hintergrund ausführung für zeitaufwendige Aufgaben mit background=true.
  • Geringere Kosten durch höhere Cache-Trefferraten: Bei Mehrfachdialogen ermöglicht die optionale serverseitige Statusverwaltung ein effizienteres Kontext-Caching über mehrere Runden hinweg, wodurch die Token-Kosten gesenkt werden.
  • Hier werden neue Funktionen eingeführt: Zukünftig werden alle neuen Modelle, multimodalen Funktionen, Tools und Agent-Funktionen in der 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-interactions-api 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:

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.

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 ruft mit dieser ID den Unterhaltungsverlauf ab, sodass Sie den gesamten Chatverlauf nicht noch einmal senden müssen.

Mit dem Parameter previous_interaction_id wird nur der Unterhaltungsverlauf (Eingaben und Ausgaben) beibehalten previous_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 den vollständigen Unterhaltungsverlauf in jeder Anfrage 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 behält Interaktionen 55 Tage lang bei.
  • Kostenloses Abo: 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. 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 den Aufbewahrungszeitraum in AI Studio so konfigurieren, dass Logs nach 7, 14, 28 oder 55 Tagen automatisch zur Löschung aus dem Projektspeicher markiert werden. Ein kürzerer Aufbewahrungszeitraum kann sich auf den Abruf früherer Unterhaltungen auswirken.

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

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

Interactions-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 „Logs“ in Google AI Studio ansehen. Weitere Informationen finden Sie im Leitfaden zu Logs.

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, was die Leistung verbessert und die Kosten senkt.
  • Interaktionen kombinieren: Sie können Agent- und Modellinteraktionen in 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 können Sie mit previous_interaction_id verknüpfen.

Unterstützte Modelle und Agenten

Modellname Typ Modell-ID
Gemini 3.6 Flash Modell gemini-3.6-flash
Gemini 3.5 Flash Modell gemini-3.5-flash
Gemini 3.1 Pro (Vorabversion) Modell gemini-3.1-pro-preview
Gemini 3.5 Flash-Lite Modell gemini-3.5-flash-lite
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 (Vorabversion) 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 (Vorabversion) 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 das 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 mit Mehrfachdialog-Modellen: Wenn Sie in einer Unterhaltung verschiedene Modelle 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:

Feedback

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

Nächste Schritte