Interactions API

Die Interactions API ist unsere neue Schnittstelle und die einfachste Möglichkeit, mit Gemini-Modellen und ‑Agenten zu arbeiten. Seit Juni 2026 ist sie allgemein verfügbar und die empfohlene Schnittstelle für alle neuen Projekte.

Die ursprüngliche generateContent API gilt zwar als Legacy-Version, wird aber weiterhin vollständig unterstützt.

Warum die Interactions API verwenden?

  • Neue Funktionen ohne zusätzliche Konfiguration: Optionaler serverseitiger Unterhaltungs status mit previous_interaction_id, beobachtbare Ausführungsschritte für das Debugging und das UI-Rendering sowie die Hintergrundausführung für Aufgaben mit langer Ausführungs zeit mit background=true.
  • Geringere Kosten durch höhere Cache-Trefferraten: Die serverseitige Statusverwaltung ermöglicht ein effizienteres Kontext-Caching über mehrere Unterhaltungsrunden hinweg, wodurch die Tokenkosten für Unterhaltungen mit mehreren Unterhaltungsrunden gesenkt werden.
  • Entwickelt für Frontier-Modelle und ‑Agenten: Speziell für Denkmodelle, die Verwendung von Tools in mehreren Schritten und komplexe Schlussfolgerungsabläufe entwickelt. So wird die Entwicklung, das Debugging und die Orchestrierung von agentischen Anwendungen vereinfacht.
  • Eine einzige API für Modelle und Agenten: Eine einheitliche Schnittstelle zum Aufrufen von Gemini-Modellen und ‑Agenten wie Deep Research und benutzerdefinierten verwalteten Agenten. Es sind keine separaten Endpunkte oder Muster erforderlich.
  • Hier werden neue Funktionen eingeführt: Künftig werden neue Modelle und Funktionen die über die Hauptfamilie hinausgehen, sowie neue agentische Funktionen und Tools ü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 zur Datenaufbewahrung für Details.

Jetzt starten

  • Coding-Agent 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. Coding-Agent einrichten →
  • Von generateContent migrieren: Wenn Sie eine vorhandene Integration haben, folgen Sie der Migrationsanleitung um zur Interactions API zu wechseln.
  • Erste Schritte: Erste Schritte mit dem Interactions API Erste Schritte Leitfaden.

Leitfäden für Funktionen

In diesen Leitfäden erfahren Sie mehr über die spezifischen Funktionen der Interactions API. Mit der Schaltflä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 Unterhaltungsrunde 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 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 Interaktionsobjekte (store=true), um die Verwendung der serverseitigen Statusverwaltungsfunktionen (mit previous_interaction_id), die Hintergrundausführung (mit background=true) und die Beobachtbarkeit zu vereinfachen.

  • Kostenpflichtiges Abo: 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. Beachten Sie jedoch, dass store=false nicht mit background=true kompatibel ist und die Verwendung von previous_interaction_id für nachfolgende Unterhaltungsrunden verhindert.

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

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

Das System verarbeitet Interaktionsobjekte gemäß den Nutzungsbedingungen.

Best Practices

  • Cache-Trefferrate: Wenn Sie previous_interaction_id verwenden, um Unterhaltungen fortzusetzen, kann das System das implizite Caching für den Unterhaltungsverlauf einfacher nutzen. Das verbessert die Leistung und senkt die Kosten.
  • Interaktionen kombinieren: Sie können Agenten- und Modellinteraktionen innerhalb 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 das Zusammenfassen oder Umformatieren nutzen. Verknüpfen Sie diese Schritte mit previous_interaction_id.

Unterstützte Modelle und 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 (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 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.

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