Gemini Pro API Guide: Schlüssel, Endpunkt, Modell-IDs und OpenAI-Kompatibilität

Die Gemini Pro API wird über die Gemini API mit einem in Google AI Studio erstellten Schlüssel genutzt. Für eine direkte REST-Anfrage rufen Sie den generateContent-Endpunkt des Modells auf; für eine bestehende OpenAI-SDK-Integration konfigurieren Sie den Client mit der OpenAI-kompatiblen Basis-URL von Google und verwenden eine aktuelle Gemini-Modell-ID wie gemini-3.1-pro-preview. Der wichtige Punkt ist, dass „Gemini Pro“ ein Suchbegriff für eine Produktfamilie ist, keine dauerhafte API-Kennung. Produktionsanwendungen sollten daher die aktuelle Modellliste von Google lesen, bevor sie eine ID festlegen.

Gemini Pro API Einrichtung auf einen Blick

Sie benötigen vier Werte, um eine Anfrage zu stellen:

Einstellung	Wert
API-Schlüssel	Erstellen Sie einen in Google AI Studio
Nativer Basis-Host	https://generativelanguage.googleapis.com
Nativer API-Pfad	/v1beta/models/{model}:generateContent
OpenAI-kompatible Basis-URL	https://generativelanguage.googleapis.com/v1beta/openai/
Beispiel-Modell-ID	gemini-3.1-pro-preview

Die Gemini API Schnellstartanleitung von Google dokumentiert die Erstellung von API-Schlüsseln und das native Anfragemuster. Der OpenAI-Kompatibilitätsleitfaden dokumentiert die Kompatibilitäts-Basis-URL für Anwendungen, die bereits das OpenAI Python- oder JavaScript-SDK verwenden.

Verwenden Sie das native Gemini SDK oder die REST API, wenn Sie Gemini-spezifische Funktionen nutzen möchten, sobald Google sie bereitstellt. Verwenden Sie die Kompatibilitätsschicht, wenn Sie bereits einen OpenAI-konformen Client haben und den Migrationsaufwand reduzieren möchten. Kompatibilität ist nützlich, garantiert aber nicht, dass jede anbieterspezifische Option perfekt zwischen den APIs abgebildet wird.

Wie man einen Google API-Schlüssel für Gemini erhält

Erstellen Sie den Schlüssel in Google AI Studio und speichern Sie ihn dann in einer Umgebungsvariable, anstatt ihn im Quellcode zu platzieren:

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

Behandeln Sie dies als eine serverseitige Anmeldeinformation. Committen Sie ihn nicht in Git, geben Sie ihn nicht in Logs aus und betten Sie ihn nicht in Browser-JavaScript oder ein mobiles App-Bundle ein. Wenn ein Frontend Gemini-Ausgaben benötigt, senden Sie die Benutzeranfrage an Ihr eigenes Backend und lassen Sie das Backend die Google API aufrufen.

Für einen Produktionsdienst sollten Sie auch entscheiden, wem das Google Cloud-Projekt gehört, wie Schlüssel rotiert werden, welche Umgebungen separate Anmeldeinformationen erhalten und wo Kontingente überwacht werden. Die API-Schlüssel-Anleitung von Google erklärt, wie Gemini API-Schlüssel mit Google Cloud-Projekten verknüpft sind.

Wie man den nativen Gemini API-Endpunkt aufruft

Die native REST-Route setzt die Modell-ID in die URL. Dieses Beispiel fordert das aktuelle Pro-Vorschaumodell auf, eine prägnante Migrationscheckliste zurückzugeben:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Erstelle eine Sieben-Schritte-Checkliste für die Migration einer Python-API von einer Region in zwei Regionen. Füge Rollback-Prüfungen hinzu."
          }
        ]
      }
    ]
  }'

Die Antwort enthält Kandidaten mit generiertem Inhalt. Echte Anwendungen sollten eine leere Kandidatenliste, blockierte Inhalte, Zeitüberschreitungen und Nicht-2xx-Antworten behandeln, anstatt direkt in das erste Antwortobjekt zu indizieren.

Die URL verwendet v1beta, da dies die Route ist, die in den aktuellen Gemini API-Beispielen von Google gezeigt wird. Halten Sie die API-Version in der Konfiguration, damit Sie eine neue Version testen können, ohne Endpunkt-Strings im gesamten Codebase zu verstreuen.

Anatomie des nativen Endpunkts

Der Pfad hat drei Teile:

/v1beta/models/{model}:generateContent

• v1beta ist die API-Version.
• {model} ist die genaue Modell-ID von Googles Gemini-Modellseite.
• generateContent ist die Generierungsmethode.

Eine 404-Antwort bedeutet oft, dass die Modell-ID, API-Version oder Methode nicht übereinstimmt. Bevor Sie den Authentifizierungscode ändern, vergleichen Sie den vollständigen Pfad mit der aktuellen Modelldokumentation.

Wie man Gemini mit einem OpenAI-kompatiblen Client verwendet

Wenn Ihre Anwendung bereits das OpenAI Python-Paket verwendet, installieren Sie es und ändern Sie den API-Schlüssel, die Basis-URL und die Modell-ID:

pip install openai

import os

from openai import OpenAI


client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

response = client.chat.completions.create(
    model="gemini-3.1-pro-preview",
    messages=[
        {
            "role": "system",
            "content": "Sie sind ein präziser Bewerter von Softwarearchitektur.",
        },
        {
            "role": "user",
            "content": "Bewerten Sie ein Queue-Worker-Design und listen Sie die fünf häufigsten Fehlermodi auf.",
        },
    ],
)

print(response.choices[0].message.content)

Dies ist der kürzeste Weg für Teams mit einer bestehenden Chat-Completions-Abstraktion. Es macht auch ein Evaluierungs-Framework leichter wiederverwendbar: Halten Sie Prompt und Antwortprüfungen konstant, tauschen Sie dann die Anbieterkonfiguration aus.

Gehen Sie nicht von identischem Verhalten aus, nur weil zwei Anbieter denselben SDK-Aufruf akzeptieren. Systemanweisungen, Tool-Schemas, multimodale Eingaben, Sicherheitshandhabung, Streaming-Ereignisse, Token-Abrechnung und Fehler-Payloads können sich unterscheiden. Führen Sie anbieterspezifische Tests durch, bevor Sie den Produktionsverkehr umstellen.

Wie man Gemini-Modell-IDs auswählt und verwaltet

Vermeiden Sie es, einen Marketingnamen wie gemini-pro direkt in die Anwendungslogik zu setzen. Die verfügbaren Modell-IDs von Google ändern sich, wenn Vorschaumodelle eingeführt, hochgestuft und eingestellt werden. Zum Zeitpunkt der Überprüfung dieses Leitfadens listete die offizielle Modellseite von Google gemini-3.1-pro-preview als Pro-Klassen-Modellkennung.

Verwenden Sie stattdessen eine Konfigurationsebene:

import os


GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview")

Diese kleine Entscheidung macht Modell-Upgrades zu einer Bereitstellungsänderung statt einer Code-Neufassung. Für einen größeren Dienst speichern Sie diese Felder zusammen:

{
  "provider": "google",
  "base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
  "model": "gemini-3.1-pro-preview",
  "timeout_seconds": 60
}

Bevor Sie ein neues Modell in Produktion nehmen:

1. Bestätigen Sie, dass die ID in der aktuellen Modelldokumentation von Google oder der Modell-API erscheint.
2. Prüfen Sie, ob das Modell Preview, Stable oder zur Einstellung vorgesehen ist.
3. Führen Sie Ihren eigenen Evaluierungssatz für Antwortqualität und Tool-Call-Korrektheit durch.
4. Messen Sie Latenz, Token-Verbrauch und Fehlerraten mit repräsentativen Prompts.
5. Fügen Sie ein Fallback-Modell oder einen klaren Fehlerpfad hinzu, bevor Sie den gesamten Verkehr umleiten.

Ratenbegrenzungen sind keine einzelne universelle Zahl. Sie hängen vom Modell und der Nutzungsstufe ab. Lesen Sie daher die Ratenbegrenzungsdokumentation der Gemini API von Google und überwachen Sie die für Ihr Projekt geltenden Grenzen.

Wie man ein anbieterwechselbares Backend erstellt

Eine OpenAI-kompatible Schnittstelle kann Codeänderungen reduzieren, aber der Anbieterwechsel funktioniert am besten, wenn Ihre eigene Anwendung den Vertrag definiert. Halten Sie die Anbieterkonfiguration außerhalb der Geschäftslogik und normalisieren Sie die Ausgabe, die Sie tatsächlich benötigen.

import os

from openai import OpenAI


PROVIDERS = {
    "gemini": {
        "api_key": os.environ["GEMINI_API_KEY"],
        "base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
        "model": os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview"),
    },
    "novita": {
        "api_key": os.environ["NOVITA_API_KEY"],
        "base_url": "https://api.novita.ai/openai",
        "model": os.getenv("NOVITA_MODEL", "xiaomimimo/mimo-v2.5-pro"),
    },
}


def generate(provider_name: str, prompt: str) -> str:
    provider = PROVIDERS[provider_name]
    client = OpenAI(
        api_key=provider["api_key"],
        base_url=provider["base_url"],
    )
    response = client.chat.completions.create(
        model=provider["model"],
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content or ""

Dieses Beispiel legt die Unterschiede bewusst offen, anstatt sie zu verstecken. Jeder Anbieter behält seine eigenen Anmeldeinformationen, Basis-URL und Modell-ID. Die Anwendung erhält einen normalisierten String, während anbieterspezifische Tests umfangreichere Funktionen wie Tools oder multimodale Eingaben abdecken können.

Die LLM-API-Dokumentation von Novita AI verwendet eine OpenAI-kompatible API-Form für unterstützte Modelle. Dies kann nützlich sein, wenn ein Team Gemini mit Open-Source-Modellen vergleichen möchte, ohne die gesamte Client-Ebene neu aufbauen zu müssen.

Wie Gemini in ein Agenten-Backend passt

Ein Agenten-Backend hat mindestens zwei getrennte Verantwortlichkeiten:

1. Inferenz: Das Modell entscheidet, was es sagt oder welches Tool es aufruft.
2. Ausführung: Eine kontrollierte Laufzeitumgebung führt Datei-, Shell-, Browser- oder Anwendungsaktionen aus.

Die Gemini API kann die Inferenzseite übernehmen. Sie sollte nicht als Ausführungsgrenze behandelt werden. Wenn ein Modell einen Shell-Befehl vorschlägt, muss Ihre Anwendung den Tool-Aufruf dennoch validieren, autorisieren, in einer isolierten Umgebung ausführen, das Ergebnis erfassen und entscheiden, welcher Kontext an das Modell zurückgesendet wird.

Novita Agent Sandbox ist für isolierte Agentenausführungsworkflows konzipiert. Eine praktische Architektur kann Gemini für die Argumentation verwenden, während eine Sandbox Code- oder Browseraufgaben separat behandelt:

Benutzeranfrage
    -> Agent-Dienst
        -> Gemini API für Argumentation und Tool-Auswahl
        -> Richtlinienprüfungen für die vorgeschlagene Aktion
        -> Agent Sandbox für isolierte Ausführung
        -> Tool-Ergebnis zurück an den Agent-Dienst
        -> Gemini API für die endgültige Antwort

Diese Trennung macht das Modell austauschbar und hält die nicht vertrauenswürdige Ausführung vom Anwendungsserver fern. Sie gibt dem Backend auch einen Ort, um Zeitüberschreitungen, Netzwerkrichtlinien, Dateigrenzen, Audit-Logs und Benutzerautorisierung durchzusetzen.

Für eine erste Version legen Sie nur wenige enge Tools offen, definieren Sie JSON-Schemas für ihre Argumente, lehnen Sie unbekannte Felder ab und setzen Sie harte Grenzen für Ausführungszeit und Ausgabegröße. Fügen Sie umfassendere Computer- oder Browser-Funktionen erst hinzu, wenn das Berechtigungsmodell klar ist.

Wann ein Open-Source-Modell besser geeignet ist

Gemini Pro-Modelle sind eine gute Option, wenn Ihre Anwendung die Modellfähigkeiten von Google und die verwaltete API benötigt. Ein Open-Source-Modell kann besser geeignet sein, wenn Sie einen zweiten Anbieter benötigen, das Modellverhalten anhand einer sichtbaren Upstream-Version bewerten möchten oder ein Modell bevorzugen, das neben anderer Infrastruktur über einen OpenAI-kompatiblen Endpunkt verfügbar ist.

MiMo-V2.5-Pro ist eine aktuelle Option auf Novita AI. Die Upstream-Modellkarte von Xiaomi beschreibt es als Open-Source-Mixture-of-Experts-Modell, während Novita AI die gehostete Modell-ID xiaomimimo/mimo-v2.5-pro bereitstellt. Da sowohl der Google-Kompatibilitätsendpunkt als auch Novita AI mit einem OpenAI-konformen Client aufgerufen werden können, kann das im vorherigen Abschnitt beschriebene anbieterwechselbare Muster sie mit denselben Prompts und Akzeptanzprüfungen evaluieren.

Wählen Sie nicht allein aufgrund des Labels. Erstellen Sie einen kleinen Evaluierungssatz aus Ihrer tatsächlichen Arbeitslast: Code-Review-Kommentare, Support-Fragen, retrievalgestützte Antworten, Tool-Aufrufe oder lange Dokumente. Vergleichen Sie Ausgabequalität, Latenz, Fehlerverhalten und Kosten anhand aktueller Anbieter-Dashboards, bevor Sie eine Routing-Entscheidung treffen.

Häufige Gemini API-Fehler

400: Ungültige Anfrage

Überprüfen Sie die JSON-Struktur, Nachrichtenrollen, Tool-Definitionen und Parameternamen. Eine Option, die von einem anderen OpenAI-kompatiblen Anbieter akzeptiert wird, wird möglicherweise nicht von der Kompatibilitätsschicht von Google akzeptiert.

401 oder 403: Authentifizierungs- oder Berechtigungsfehler

Bestätigen Sie, dass GEMINI_API_KEY in der Prozessumgebung vorhanden ist und zum beabsichtigten Google Cloud-Projekt gehört. Überprüfen Sie auch, ob das Projekt und das ausgewählte Modell für das Konto und die Region verfügbar sind.

404: Modell oder Methode nicht gefunden

Vergleichen Sie die genaue Modell-ID mit der aktuellen Gemini-Modellliste. Überprüfen Sie bei nativen REST-Aufrufen die API-Version und das Suffix :generateContent. Überprüfen Sie bei OpenAI-kompatiblen Aufrufen, ob die Basis-URL mit /v1beta/openai/ endet.

429: Ratenbegrenzung überschritten

Wiederholen Sie den Vorgang mit exponentiellem Backoff und Jitter, betrachten Sie Wiederholungen jedoch nicht als Ersatz für Kapazitätsplanung. Stauen Sie burstartige Arbeit, begrenzen Sie gleichzeitige Anfragen und überprüfen Sie die aktuelle Nutzungsstufe des Projekts sowie die modellspezifischen Grenzen.

Das SDK funktioniert, aber die Ausgabe unterscheidet sich nach dem Anbieterwechsel

Kompatibilität bezieht sich auf die Anforderungsschnittstelle, nicht auf identisches Modellverhalten. Führen Sie Prompt-, Structured-Output- und Tool-Call-Tests für jeden Anbieter und jede Modellversion erneut durch.

Fazit

Beginnen Sie mit der nativen Gemini API, wenn Sie den klarsten Weg zu Gemini-spezifischen Funktionen wünschen. Beginnen Sie mit dem OpenAI-kompatiblen Endpunkt, wenn Sie bereits ein OpenAI-konformes Backend haben oder eine schnelle Anbieterevaluierung benötigen. Halten Sie in beiden Fällen den API-Schlüssel serverseitig, platzieren Sie die Modell-ID in der Konfiguration, testen Sie die genaue Modellversion und trennen Sie die Modellargumentation von der Agentenausführung.

Für ein widerstandsfähiges Produktionsdesign behalten Sie mindestens ein alternatives Modell hinter derselben anwendungseigenen Schnittstelle. Das gibt Ihrem Team eine praktische Möglichkeit, eine Open-Source-Option auf Novita AI zu testen, Modelllebenszyklusänderungen zu handhaben und die Agentenausführung in eine isolierte Sandbox zu leiten, anstatt jede Verantwortung an einen API-Aufruf zu koppeln.

FAQ

Gibt es noch eine Modell-ID namens gemini-pro?

Gehen Sie nicht davon aus, dass gemini-pro die aktuelle ID ist. „Gemini Pro API“ wird häufig als Suchbegriff für die leistungsfähigeren Gemini-Modelle von Google verwendet, aber Anwendungen müssen eine exakte ID von der aktuellen Gemini-Modellseite verwenden. Dieser Leitfaden verwendet gemini-3.1-pro-preview als geprüftes Beispiel.

Wo erhalte ich einen Google API-Schlüssel für Gemini?

Erstellen Sie einen Gemini API-Schlüssel in Google AI Studio. Speichern Sie ihn in einem serverseitigen Secret wie GEMINI_API_KEY, nicht im Quellcode oder Frontend-JavaScript.

Was ist der Gemini API-Endpunkt?

Der native Host ist https://generativelanguage.googleapis.com. Eine Generate-Content-Anfrage verwendet /v1beta/models/{model}:generateContent. Die OpenAI-kompatible Basis-URL von Google ist https://generativelanguage.googleapis.com/v1beta/openai/.

Ist die Gemini Studio API anders als die Gemini API?

Google AI Studio ist die Weboberfläche, die Entwickler zum Experimentieren und Erstellen eines Schlüssels verwenden. Anwendungsanfragen gehen an die Gemini API. Suchen nach „Gemini Studio API“ beziehen sich normalerweise auf diesen AI-Studio-zu-API-Workflow.

Ist die Google Bard API dieselbe wie die Gemini API?

Gemini ist die aktuelle API- und Modellmarke. Ältere Suchen nach einer Google Bard API sollten die aktuelle Gemini API-Dokumentation, Endpunkte und Modell-IDs verwenden, anstatt alte Bard-Beispiele.

Kann ich das OpenAI SDK mit Gemini verwenden?

Ja. Google dokumentiert einen OpenAI-Kompatibilitätsendpunkt. Setzen Sie die Client-Basis-URL auf die Kompatibilitäts-URL von Google, geben Sie Ihren Gemini API-Schlüssel an und wählen Sie eine unterstützte Gemini-Modell-ID. Testen Sie anbieterspezifische Funktionen, bevor Sie sich auf vollständige Verhaltensgleichheit verlassen.

Kann Gemini Code für einen KI-Agenten ausführen?

Gemini kann über Code nachdenken und Tool-Aufrufe vorschlagen, aber die Ausführung sollte in einer kontrollierten Laufzeitumgebung erfolgen. Halten Sie den Modellaufruf getrennt von einer isolierten Umgebung wie Agent Sandbox und validieren Sie jede angeforderte Aktion, bevor Sie sie ausführen.

Empfohlene Artikel

• Best LLM API Platform for Switching Providers
• What Are Coding Agents? Architecture, Tools, and Safety
• MiMo 2.5 API on Novita AI: OpenAI-Compatible Chat API