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.

Warum die Interactions API verwenden?

  • 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 ohne zusätzliche Konfiguration: 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 Aufgaben mit langer Ausführungszeit mit background=true.
  • Niedrigere Kosten durch höhere Cache-Trefferraten: Bei Mehrfachdialogen ermöglicht die optionale serverseitige Statusverwaltung ein effizienteres Kontext-Caching über mehrere Runden hinweg, wodurch die Tokenkosten gesenkt werden.
  • Hier werden neue Funktionen eingeführt: 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 Datenaufbewahrung für Details.

Jetzt starten

  • KI-Programmieragenten 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 KI-Programmieragenten 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 Sitzungsdatensatz 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 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 (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 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.
  • Kostenloses Abo: 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 Aufbewahrungsdauer 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 protokolle ansehen und verwalten, einschließlich der Löschung aus dem Projektspeicher, in AI Studio.

Nach Ablauf der Aufbewahrungsdauer 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 „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.
  • 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.8 Flash Modell gemini-3.8-flash
Gemini 3.7 Flash Modell gemini-3.7-flash
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.5 Modell lyria-3.5
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 Max (Vorabversion) Agent deep-research-max-preview-04-2026
Antigravity (Vorabversion) Agent antigravity-preview-05-2026

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.

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 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