Interactions API – Übersicht

Die Interactions API bietet eine einheitliche, zustandsorientierte Oberfläche zum Erstellen von generativen KI-Anwendungen und agentischen Workflows mit Gemini-Modellen und -Agenten, die auf der Gemini Enterprise Agent Platform gehostet werden. Die generateContent API wird neben der Interactions API weiterhin vollständig unterstützt.

Vorteile der Interactions API

Die Interactions API bietet mehrere wichtige Vorteile für die Entwicklung von generativen KI-Anwendungen und agentischen Workflows:

  • Einzelne API für Modelle und Agenten: Ein einheitlicher Endpunkt und ein einheitliches Muster für den direkten Aufruf von Gemini-Standardmodellen sowie spezialisierten Agenten (z. B. Gemini Deep Research Agent und benutzerdefinierte verwaltete Agenten).
  • Neue Funktionen direkt einsatzbereit: Funktionen wie optionaler serverseitiger Unterhaltungsstatus mit previous_interaction_id, beobachtbare Ausführungsschritte für Debugging und UI-Rendering sowie Hintergrundausführung für langwierige Aufgaben mit background=true.

Funktionsweise der Interactions API

Die Interactions API basiert auf der Ressource Interaction. Ein Interaction stellt einen vollständigen Turn in einer Unterhaltung oder Aufgabe dar und dient als Sitzungsaufzeichnung, die eine chronologische Abfolge von Ausführungs-steps enthält:

  • user_input: Die Eingabenachrichten, multimodalen Dateien oder Toolergebnisse, die für die Runde bereitgestellt wurden. Gespeicherte Interaktionen, die mit interactions.get abgerufen werden, enthalten user_input Schritte für den vollständigen Kontext, während interactions.create-Antworten nur die Schritte zurückgeben, die während dieser Runde generiert wurden.
  • thought: Zwischenergebnisse der Argumentation, die vom Modell oder Agenten generiert werden, während die Antwort geplant wird.
  • Toolaufruf- und Ergebnisschritte: Clientseitige oder serverseitige Toolaufrufe und ‑ausgaben (z. B. function_call und function_result).
  • model_output: Der endgültige Text, das strukturierte JSON oder der multimodale Inhalt, der vom Modell oder Agenten erstellt wurde.

Wenn Sie interactions.create aufrufen, verarbeitet die Agent Platform Ihre Eingabe, führt alle konfigurierten serverseitigen Tools oder Agentenschleifen aus und gibt die resultierende Interaction-Ressource zurück. Codebeispiele für Python, TypeScript/JavaScript und REST finden Sie im Entwicklerhandbuch für die Interactions API.

Unterstützte Modelle

Die folgenden Gemini-Modelle unterstützen die Interactions API:

Klicken, um unterstützte Modelle einzublenden

Zusätzlich zu den Gemini-Modellen in der vorherigen Liste unterstützt die Interactions API die folgenden generativen Musikmodelle: * lyria-3-clip-preview und lyria-3-pro-preview: Generative Musikmodelle für High-Fidelity-Audioclips und vollständige Songkompositionen (nur in zustandslosen Interaktionen mit store=false unterstützt).

Unterstützte KI-Agenten

Sie können die folgenden Agenten über die Interactions API aufrufen, indem Sie den Parameter agent anstelle von model angeben:

  • antigravity-preview-05-2026: Autonomer Agent für allgemeine Zwecke, der für mehrstufige Problemlösung, Programmierung, Dateioperationen und die Verwendung von Tools entwickelt wurde.
  • deep-research-preview-04-2026: Gemini Deep Research-Agent, der für die autonome, mehrstufige Webrecherche und -synthese entwickelt wurde.
  • Benutzerdefinierte verwaltete KI-Agenten, die auf der Agent Platform bereitgestellt werden.

Funktionen und technische Daten

In den folgenden Abschnitten werden die wichtigsten Funktionen, technischen Spezifikationen und betrieblichen Überlegungen für die Interactions API beschrieben.

Zustandsverwaltung

Standardmäßig speichert die Interactions API Interaktionen auf dem Server (store=true) 7 Tage lang, damit Sie mehrstufige Unterhaltungen mit previous_interaction_id verketten und asynchrone Hintergrundaufgaben (background=true) ausführen können. Wenn Sie die zustandslose Ausführung aktivieren und Workflows mit Zero Data Retention (ZDR) unterstützen möchten, legen Sie store=false fest. Weitere Informationen finden Sie unter Sitzungsspeicher und Unterhaltungsstatus verwalten.

Anfrage- und multimodale Limits

Die Interactions API erzwingt die folgenden Limits für die Nutzlast von Anfragen und multimodale Eingaben:

  • Limits für die Anfragenutzlast: Die komprimierte HTTP-Anfragenutzlast darf bei synchronen und Streaming-interactions.create-Anfragen 256 MiB nicht überschreiten. Wenn service_tier auf deferred festgelegt ist (was erfordert, dass sowohl background als auch store true sind), darf die unkomprimierte Anfrage 9,75 MiB nicht überschreiten.
  • URI-Limit für Cloud Storage-Dateien: Standard-Gemini-Modellinteraktionsanfragen unterstützen bis zu 100 verschiedene Cloud Storage-URIs (gs://) pro Anfrage, einschließlich URIs, die aus früheren Gesprächsrunden über previous_interaction_id übernommen wurden. Interaktionen mit verwalteten KI-Agenten, Gemini Omni-Modelle und Lyria 3-Modelle sind von diesem Limit von 100 URIs ausgenommen. Informationen zu Berechtigungen und zur Verarbeitung von Multi-Turn-URIs finden Sie unter Auf hochgeladene Cloud Storage-Dateien zugreifen.
  • Multimodale Element- und Tokenlimits: Standard-Gemini-Modelle akzeptieren dieselbe Anzahl von Elementen pro Modalität wie generateContent (bis zu 3.000 Bilder und PDFs kombiniert, 1.000 Audiodateien, 10 Videos und bis zu 6.500 kombinierte multimodale Dateien, wenn Nur-Text-Dateien enthalten sind), begrenzt durch das Kontextfenster des Modells mit 1.048.576 Tokens. Einzelne Cloud Storage-Dateien dürfen nicht größer als 2 GiB minus 500 KiB sein und öffentliche HTTP- oder HTTPS-URLs dürfen nicht größer als 15 MiB sein. Wenn Sie mehr als 100 Dateien in einer einzelnen Anfrage senden möchten, übergeben Sie zusätzliche Anhänge inline innerhalb des Limits für die Anfragenutzlast oder rufen Sie generateContent auf.

Unterstützte Tools und Fundierung

Die folgenden integrierten Tools, Fundierungsanbieter und Suchfunktionen werden für Gemini 3-Modelle in der Interactions API unterstützt:

  • Fundierung mit der Google Suche und Webfundierung für Unternehmen: Fundiert Modellantworten mit Echtzeit-Webinformationen aus der Google Suche oder der Webfundierung für Unternehmen.
  • Agent Search und RAG Engine auf der Gemini Enterprise Agent Platform: Fundiert Modellantworten mit privaten Unternehmensdatenspeichern und Dokument-Repositories mithilfe von Agent Search und der RAG Engine.
  • Exa Web Search: Fundiert Modellantworten mit Websuchergebnissen aus der Such-API von Exa.
  • Parallel Web Search: Fundiert Modellantworten mit öffentlichen Webdaten in Echtzeit, die von der Such-API von Parallel Web Systems bereitgestellt werden.
  • URL-Kontext: Ruft Inhalte von öffentlichen Web-URLs ab, die in Ihrem Prompt enthalten sind, und analysiert sie.
  • Code-Ausführung: Ermöglicht dem Modell, Python-Code in einer sicheren Sandbox-Umgebung zu generieren und auszuführen.
  • Computernutzung: Ermöglicht Automatisierungsworkflows für Browser und Benutzeroberflächen.
  • Funktionsaufrufe: Ermöglicht es Modellen, sich mit externen Tools, APIs und Datenbanken zu verbinden, indem strukturierte Funktionsargumente zurückgegeben werden.

Die Interactions API unterstützt Web-Fundierung für Unternehmen und Fundierung mit der Google Suche. Ihre Nutzung dieser Funktionen unterliegt zusätzlich den dienstspezifischen Nutzungsbedingungen.

Abrechnung

Die Nutzung der Interactions API wird basierend auf dem Tokenverbrauch abgerechnet.

Die Abrechnung für unterbrochene oder nicht erfüllte Anfragen erfolgt so:

  • Manuelle Abbrüche: Wenn eine Interaktion vor dem Abschluss abgebrochen wird (z. B. durch Senden einer Abbruchanfrage), werden Ihnen die bis zum Abbruch verbrauchten Tokens in Rechnung gestellt.
  • Fehlgeschlagene Anfragen: Wenn eine Interaktionsanfrage aufgrund eines internen Systemfehlers oder eines Back-End-Fehlers fehlschlägt, werden Ihnen die Kosten für die fehlgeschlagene Anfrage nicht in Rechnung gestellt.

Sicherheit und Compliance

Die Interactions API unterstützt die folgenden Sicherheitskontrollen, Compliance-Zertifizierungen und Endpunktkonfigurationen:

  • Endpunkte: Die Interactions API unterstützt den globalen Endpunkt (locations/global auf aiplatform.googleapis.com) und die multiregionalen Endpunkte us und eu (locations/us auf aiplatform.us.rep.googleapis.com und locations/eu auf aiplatform.eu.rep.googleapis.com). Endpunkte für einzelne Regionen (z. B. us-central1 oder europe-west1) werden nicht unterstützt.
  • Datenstandort: Die Interactions API unterstützt den Datenstandort sowohl für die ML-Verarbeitung (in Verwendung) als auch für gespeicherte Interaktionsdaten im Ruhezustand (store=true), wenn Sie die multiregionalen Endpunkte us und eu (locations/us und locations/eu) verwenden. Anfragen, die an den Endpunkt global gesendet werden, bieten keine Garantien für den Datenstandort.
  • Kundenverwaltete Verschlüsselungsschlüssel (CMEK): Die Interactions API unterstützt CMEK für gespeicherte Interaktionsdaten über Bereitstellungsprofile (mit scope auf INTERACTIONS_API gesetzt) in den multiregionalen Standorten us und eu. Der Endpunkt global wird für CMEK nicht unterstützt.
  • VPC Service Controls (VPC-SC): Die Interactions API unterstützt VPC-SC, um Ihren API-Perimeter zu sichern und das Risiko einer Daten-Exfiltration zu minimieren.
  • Access Transparency (AXT): Die Interactions API unterstützt AXT-Logs, um nahezu in Echtzeit Einblick zu erhalten, wenn Google-Mitarbeiter auf gespeicherte Interaktionsinhalte zugreifen.
  • Sicherheits- und Compliance-Zertifizierungen: Die Interactions API erfüllt die FedRAMP High-Anforderungen innerhalb der Google Cloud FedRAMP High-Autorisierungsgrenze. Die Interactions API ist nicht mit den Anforderungen des Department of Defense (DoD) Impact Level 5 (IL5) oder den International Traffic in Arms Regulations (ITAR) konform.

Unterstützte SDKs

Sie können über das einheitliche Google Gen AI SDK oder direkte REST-Aufrufe auf die Interactions API zugreifen:

  • Python: google-genai-Version 2.3.0 oder höher
  • TypeScript/JavaScript: @google/genai-Version 2.3.0 oder höher
  • Go: google.golang.org/genai
  • Java: com.google.genai:google-genai

Ältere SDKs (google-cloud-aiplatform, @google-cloud/vertexai und google-generativeai) unterstützen die Interactions API nicht.

Nächste Schritte