Gemini API reference

In dieser API-Referenz werden die Standard-, Streaming- und Echtzeit-APIs beschrieben, mit denen Sie mit den Gemini-Modellen interagieren können. Sie können die REST APIs in jeder Umgebung verwenden, die HTTP-Anfragen unterstützt. In der Kurzanleitung erfahren Sie, wie Sie Ihren ersten API-Aufruf starten. Wenn Sie die Referenzen für unsere sprachspezifischen Bibliotheken und SDKs suchen, klicken Sie in der linken Navigationsleiste unter SDK-Referenzen auf den Link für die entsprechende Sprache.

Primäre Endpunkte

Die Gemini API ist um die folgenden Hauptendpunkte herum organisiert:

• Standardmäßige Inhaltserstellung (generateContent): Ein Standard-REST-Endpunkt, der Ihre Anfrage verarbeitet und die vollständige Antwort des Modells in einem einzigen Paket zurückgibt. Diese Option eignet sich am besten für nicht interaktive Aufgaben, bei denen Sie auf das gesamte Ergebnis warten können.
• Streaming-Inhaltserstellung (streamGenerateContent): Verwendet vom Server gesendete Ereignisse (Server-Sent Events, SSE), um Ihnen Teile der Antwort zu senden, sobald sie generiert werden. Dies bietet eine schnellere und interaktivere Nutzererfahrung für Anwendungen wie Chatbots.
• Live API (BidiGenerateContent): Eine zustandsbehaftete WebSocket-basierte API für bidirektionales Streaming, die für Echtzeit-Unterhaltungsanwendungsfälle entwickelt wurde.
• Batchmodus (batchGenerateContent): Ein Standard-REST Endpunkt zum Senden von Batches von generateContent Anfragen.
• Einbettungen (embedContent): Ein Standard-REST-Endpunkt, der einen Texteinbettungsvektor aus dem Eingabe-Content generiert.
• Gen Media APIs: Endpunkte zum Generieren von Medien mit unseren spezialisierten Modellen wie Imagen für die Bildgenerierung, und Veo für die Videogenerierung. Gemini bietet auch diese Funktionen, auf die Sie mit der generateContent API zugreifen können.
• Plattform-APIs: Hilfsendpunkte, die Kernfunktionen wie das Hochladen von Dateien und das Zählen von Tokens unterstützen.

Authentifizierung

Alle Anfragen an die Gemini API müssen einen x-goog-api-key-Header mit Ihrem API-Schlüssel enthalten. Sie können einen solchen Schlüssel mit wenigen Klicks in Google AI Studio erstellen.

Hier sehen Sie ein Beispiel für eine Anfrage mit dem API-Schlüssel im Header:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Eine Anleitung zum Übergeben Ihres Schlüssels an die API mit Gemini SDKs, siehe den Leitfaden API-Schlüssel für Gemini verwenden.

Inhaltserstellung

Dies ist der zentrale Endpunkt zum Senden von Prompts an das Modell. Es gibt zwei Endpunkte zum Generieren von Inhalten. Der Hauptunterschied besteht darin, wie Sie die Antwort erhalten:

• generateContent (REST) : Empfängt eine Anfrage und gibt eine einzelne Antwort zurück, nachdem das Modell die gesamte Generierung abgeschlossen hat.
• streamGenerateContent (SSE): Empfängt genau dieselbe Anfrage, aber das Modell streamt Teile der Antwort zurück, sobald sie generiert werden. Dies bietet eine bessere Nutzererfahrung für interaktive Anwendungen, da Sie Teilergebnisse sofort anzeigen können.

Struktur des Anfragetexts

Der Anfragetext ist ein JSON-Objekt, das für den Standard- und den Streamingmodus identisch ist und aus einigen Kern objekten besteht:

• Content -Objekt: Stellt eine einzelne Runde in einer Unterhaltung dar.
• Part -Objekt: Ein Datenelement in einer Content-Runde (z. B. Text oder ein Bild).
• inline_data (Blob): Ein Container für Roh-Media-Bytes und deren MIME-Typ.

Auf der obersten Ebene enthält der Anfragetext ein contents-Objekt, das eine Liste von Content-Objekten ist, die jeweils Runden in einer Unterhaltung darstellen. In den meisten Fällen haben Sie für die einfache Textgenerierung ein einzelnes Content-Objekt. Wenn Sie jedoch den Unterhaltungsverlauf beibehalten möchten, können Sie mehrere Content-Objekte verwenden.

Hier sehen Sie einen typischen Anfragetext für generateContent:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

Struktur des Antworttexts

Der Antworttext ist für den Streaming- und den Standardmodus ähnlich, mit Ausnahme der folgenden Punkte:

• Standardmodus: Der Antworttext enthält eine Instanz von GenerateContentResponse.
• Streamingmodus: Der Antworttext enthält einen Stream von GenerateContentResponse Instanzen.

Auf hoher Ebene enthält der Antworttext ein candidates-Objekt, das eine Liste von Candidate-Objekten ist. Das Candidate-Objekt enthält ein Content-Objekt mit der generierten Antwort des Modells.

Beispielanfragen

Die folgenden Beispiele zeigen, wie diese Komponenten für verschiedene Arten von Anfragen zusammenkommen.

Nur-Text-Prompt

Ein einfacher Text-Prompt besteht aus einem contents-Array mit einem einzelnen Content-Objekt. Das parts-Array dieses Objekts enthält wiederum ein einzelnes Part-Objekt mit einem text-Feld.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a single paragraph."
          }
        ]
      }
    ]
  }'

Multimodaler Prompt (Text und Bild)

Wenn Sie in einem Prompt sowohl Text als auch ein Bild angeben möchten, sollte das parts-Array zwei Part-Objekte enthalten: eines für den Text und eines für die inline_data des Bildes.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

Unterhaltungen über mehrere Themen (Chat)

Wenn Sie eine Unterhaltung mit mehreren Runden erstellen möchten, definieren Sie das contents-Array mit mehreren Content-Objekten. Die API verwendet diesen gesamten Verlauf als Kontext für die nächste Antwort. Die role für jedes Content-Objekt sollte zwischen user und model wechseln.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

Wichtigste Ergebnisse

• Content ist der Umschlag: Es ist der Container auf oberster Ebene für eine Nachrichtenrunde, unabhängig davon, ob sie vom Nutzer oder vom Modell stammt.
• Part ermöglicht Multimodalität: Verwenden Sie mehrere Part-Objekte in einem einzelnen Content-Objekt, um verschiedene Datentypen zu kombinieren (Text, Bild, Video-URI usw.).
• Wählen Sie Ihre Datenmethode aus:
  • Verwenden Sie für kleine, direkt eingebettete Medien (wie die meisten Bilder) ein Part mit inline_data.
  • Verwenden Sie für größere Dateien oder Dateien, die Sie in mehreren Anfragen verwenden möchten, die File API, um die Datei hochzuladen, und verweisen Sie mit einem file_data-Teil darauf.
• Unterhaltungsverlauf verwalten: Erstellen Sie für Chatanwendungen, die die REST API verwenden, das contents Array, indem Sie für jede Runde Content Objekte anhängen, abwechselnd zwischen den Rollen "user" und "model". Wenn Sie ein SDK verwenden, finden Sie in der SDK-Dokumentation die empfohlene Methode zum Verwalten des Unterhaltungsverlaufs.

Antwortbeispiele

Die folgenden Beispiele zeigen, wie diese Komponenten für verschiedene Arten von Anfragen zusammenkommen.

Nur-Text-Antwort

Eine Standardtextantwort besteht aus einem candidates-Array mit einem oder mehreren content-Objekten, die die Antwort des Modells enthalten.

Hier sehen Sie ein Beispiel für eine Standardantwort:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

Hier sehen Sie eine Reihe von Streamingantworten. Jede Antwort enthält eine responseId, die die vollständige Antwort zusammenfasst:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Live API (BidiGenerateContent) WebSockets API

Die Live API bietet eine zustandsbehaftete WebSocket-basierte API für bidirektionales Streaming, um Echtzeit-Streaminganwendungsfälle zu ermöglichen. Weitere Informationen finden Sie im Leitfaden zur Live API und in der Referenz zur Live API.

Spezialisierte Modelle

Neben der Gemini-Modellfamilie bietet die Gemini API Endpunkte für spezialisierte Modelle wie Imagen, Lyria und Einbettungsmodelle. Diese Leitfäden finden Sie im Abschnitt „Modelle“.

Plattform-APIs

Die übrigen Endpunkte ermöglichen zusätzliche Funktionen, die mit den bisher beschriebenen Hauptendpunkten verwendet werden können. Weitere Informationen finden Sie in den Themen Batchmodus und File API im Abschnitt „Leitfäden“.

Nächste Schritte

Wenn Sie gerade erst anfangen, sehen Sie sich die folgenden Leitfäden an, die Ihnen helfen, das Programmiermodell der Gemini API zu verstehen:

• Kurzanleitung: Gemini API
• Leitfaden zu Gemini-Modellen

Möglicherweise möchten Sie sich auch die Leitfäden zu den Funktionen ansehen, in denen verschiedene Funktionen der Gemini API vorgestellt werden und Codebeispiele enthalten sind:

• Textgenerierung
• Kontext-Caching
• Einbettungen