Gemini API reference

In dieser API-Referenz werden die Standard-, Streaming- und Echtzeit-APIs beschrieben, die Sie für die Interaktion mit den Gemini-Modellen verwenden 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 nach den 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 in die folgenden wichtigen Endpunkte unterteilt:

  • 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. Das ist am besten für nicht interaktive Aufgaben geeignet, bei denen Sie auf das gesamte Ergebnis warten können.
  • Streaming-Inhaltsgenerierung (streamGenerateContent): Hier werden Server-Sent Events (SSE) verwendet, um Teile der Antwort an Sie zu senden, sobald sie generiert werden. Das sorgt für eine schnellere und interaktivere Nutzung von Anwendungen wie Chatbots.
  • Live API (BidiGenerateContent): Eine zustandsorientierte WebSocket-basierte API für bidirektionales Streaming, die für Echtzeit-Konversationsanwendungsfälle entwickelt wurde.
  • Batchmodus (batchGenerateContent): Ein Standard-REST-Endpunkt zum Senden von Batches mit generateContent-Anfragen.
  • Einbettungen (embedContent): Ein Standard-REST-Endpunkt, der einen Texteinbettungsvektor aus der 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 diese Funktionen ebenfalls. Sie können über die generateContent API darauf zugreifen.
  • Plattform-APIs:Utility-Endpunkte, 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 ihn 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 dazu, wie Sie Ihren Schlüssel mit den Gemini SDKs an die API übergeben, finden Sie im Leitfaden Gemini API-Schlüssel 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. Das sorgt für eine bessere Nutzererfahrung bei interaktiven 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 Kernobjekten besteht:

  • Content-Objekt: Stellt einen einzelnen Zug in einer Unterhaltung dar.
  • Part-Objekt: Ein Datenelement in einem Content-Turn, z. B. Text oder ein Bild.
  • inline_data (Blob): Ein Container für rohe 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 für eine Äußerung in der Unterhaltung stehen. In den meisten Fällen haben Sie für die einfache Texterstellung ein einzelnes Content-Objekt. Wenn Sie jedoch den Unterhaltungsverlauf beibehalten möchten, können Sie mehrere Content-Objekte verwenden.

Das Folgende zeigt einen typischen generateContent-Anfragetext:

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 Streaming- und Standardmodus ähnlich, mit Ausnahme der folgenden Punkte:

Auf übergeordneter 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.

Beispiele anfordern

Die folgenden Beispiele zeigen, wie diese Komponenten bei verschiedenen Arten von Anfragen zusammenwirken.

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 sowohl Text als auch ein Bild in einem Prompt angeben möchten, sollte das parts-Array zwei Part-Objekte enthalten: eines für den Text und eines für das Bild inline_data.

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 Zügen erstellen möchten, definieren Sie das contents-Array mit mehreren Content-Objekten. Die API verwendet den gesamten Verlauf als Kontext für die nächste Antwort. Der 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." }
        ]
      }
    ]
  }'

Zusammenfassung

  • Content ist der Umschlag: Er ist der Container der obersten Ebene für einen Nachrichtenabschnitt, unabhängig davon, ob er vom Nutzer oder vom Modell stammt.
  • Part ermöglicht Multimodalität: Verwenden Sie mehrere Part-Objekte in einem einzelnen Content-Objekt, um verschiedene Datentypen (Text, Bild, Video-URI usw.) zu kombinieren.
  • Wählen Sie eine Datenmethode aus:
    • Verwenden Sie für kleine, direkt eingebettete Medien (wie die meisten Bilder) ein Part mit inline_data.
    • Für größere Dateien oder Dateien, die Sie in mehreren Anfragen verwenden möchten, können Sie die File API verwenden, um die Datei hochzuladen und mit einem file_data-Teil darauf zu verweisen.
  • Verlauf von Unterhaltungen verwalten: Erstellen Sie für Chatanwendungen, die die REST API verwenden, das contents-Array, indem Sie für jede Runde Content-Objekte anhängen und dabei zwischen den Rollen "user" und "model" wechseln. Wenn Sie ein SDK verwenden, finden Sie in der SDK-Dokumentation Informationen dazu, wie Sie den Unterhaltungsverlauf am besten verwalten.

Beispielantworten

Die folgenden Beispiele zeigen, wie diese Komponenten bei verschiedenen Arten von Anfragen zusammenwirken.

Reine Textantwort

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

Hier ist 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
    }
  ],
}

Im Folgenden finden Sie eine Reihe von Streaming-Antworten. Jede Antwort enthält ein responseId, das 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-Streaming-Anwendungsfälle zu ermöglichen. Weitere Informationen finden Sie im Live API-Leitfaden und in der Live API-Referenz.

Spezialisierte Modelle

Zusätzlich zu den Modellen der Gemini-Familie bietet die Gemini API Endpunkte für spezialisierte Modelle wie Imagen, Lyria und Embedding-Modelle. Sie finden diese Anleitungen im Bereich „Modelle“.

Plattform-APIs

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

Nächste Schritte

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

Möglicherweise sind auch die Leitfäden zu den Funktionen interessant, in denen verschiedene Gemini API-Funktionen vorgestellt und Codebeispiele bereitgestellt werden: