Interactions API

Die Interactions API ist unsere neue Schnittstelle und die einfachste Möglichkeit, Gemini-Modelle und ‑Agents zu nutzen. Ab Juni 2026 ist sie allgemein verfügbar und die empfohlene Schnittstelle für alle neuen Projekte.

Die ursprüngliche generateContent API wird weiterhin vollständig unterstützt, obwohl sie jetzt als Legacy-API gilt.

Vorteile der Interactions API

  • Neue Funktionen sofort verfügbar: Optionaler serverseitiger Konversationsstatus mit previous_interaction_id, beobachtbare Ausführungsschritte für Debugging und UI-Rendering sowie Hintergrundausführung für lang andauernde Aufgaben mit background=true.
  • Geringere Kosten durch höhere Cache-Trefferraten: Durch die serverseitige Statusverwaltung kann der Kontext über mehrere Turns hinweg effizienter im Cache gespeichert werden. So lassen sich die Tokenkosten für Unterhaltungen mit mehreren Turns senken.
  • Für Grenzmodelle und ‑agenten entwickelt: Speziell für Denkmodelle, mehrstufige Tool-Nutzung und komplexe Schlussfolgerungsabläufe entwickelt. So wird das Erstellen, Debuggen und Orchestrieren von agentischen Anwendungen vereinfacht.
  • Eine API für Modelle und Agents: Eine einheitliche Schnittstelle zum direkten Aufrufen von Gemini-Modellen und ‑Agents wie Deep Research und benutzerdefinierten verwalteten Agents – es sind keine separaten Endpunkte oder Muster erforderlich.
  • Neue Funktionen: Künftig werden neue Modelle und Funktionen, die über die Kernfamilie hinausgehen, sowie neue agentische Funktionen und Tools ü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

Leitfäden für Funktionen

In diesen Leitfäden erfahren Sie mehr über die spezifischen Funktionen der Interactions API. Mit dem 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 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 Interaktionsobjekte (store=true) von der API gespeichert, um die Verwendung von serverseitigen Funktionen zur Statusverwaltung (mit previous_interaction_id), die Ausführung im Hintergrund (mit background=true) und die Beobachtbarkeit 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 background=true kompatibel und verhindert die Verwendung von previous_interaction_id für nachfolgende Turns.

Sie können gespeicherte Interaktionen jederzeit mit der Löschmethode in der API-Referenz löschen. Sie können Interaktionen nur löschen, wenn Sie die Interaktions-ID kennen.

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

Das System verarbeitet Interaktionsobjekte gemäß den Nutzungsbedingungen.

Best Practices

  • Cache-Trefferquote: Wenn Sie previous_interaction_id verwenden, um Unterhaltungen fortzusetzen, kann das System den impliziten Cache für den Unterhaltungsverlauf leichter nutzen. 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.1 Flash Lite Modell gemini-3.1-flash-lite
Gemini 3.1 Flash-Lite (Vorabversion) Modell gemini-3.1-flash-lite-preview
Gemini 3.1 Pro (Vorabversion) Modell gemini-3.1-pro-preview
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
Lyria 3-Clip-Vorschau Modell lyria-3-clip-preview
Lyria 3 Pro (Vorabversion) Modell lyria-3-pro-preview
Deep Research-Vorabversion Agent deep-research-pro-preview-12-2025
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 aktuelle Version der Google GenAI SDKs verwenden, um auf die Interactions API zuzugreifen.

  • In Python ist dies das Paket google-genai ab Version 1.55.0.
  • In JavaScript ist das das @google/genai-Paket ab Version 1.33.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.

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