Zum Hauptinhalt springen
Diese Seite behandelt Gemini über API-Keys von Google AI Studio. Für Gemini auf Vertex AI von Google Cloud siehe den Leitfaden zu Google Vertex AI. Standardmäßig routet GoModel Gemini-Requests für Chat, Responses, Embeddings und Bilder über die nativen APIs von Gemini (generateContent, batchEmbedContents, Imagen predict). Wechseln Sie zum OpenAI-kompatiblen Endpunkt, wenn Sie Kompatibilitätsverhalten benötigen, das der native Adapter noch nicht implementiert (insbesondere entfernte image_url-Werte).

Konfigurieren

Oder in config.yaml:
USE_GOOGLE_GEMINI_NATIVE_API wird weiterhin als veralteter globaler Schalter berücksichtigt, wenn GEMINI_API_MODE pro Provider nicht gesetzt ist. Verwenden Sie bevorzugt GEMINI_API_MODE.
Der native AI-Studio-Modus kann außerdem GoModels Prompt-Cache-Pläne nach dem Routing als fünfminütige Cached-Content-Objekte von Gemini umsetzen. Die Wiederverwendung ist auf den für die Session gewählten API-Key beschränkt; Datenverkehr ohne Session mit rotierenden Keys überspringt das Anlegen der Objekte, damit eine Ressource nie unter falschen Zugangsdaten wiederverwendet wird. Gemini-4-Modelle haben kein explizites Caching (Google cacht gemeinsame Präfixe implizit), daher werden für sie keine Objekte angelegt. Vertex erhält derzeit den ursprünglichen Request ohne Cached-Content-Objekte. Google speichert Gemini-API-Requests bei neuen Projekten im kostenpflichtigen Tarif standardmäßig. Im nativen Modus wird ein store: false aus Chat Completions als Geminis Opt-out pro Request weitergeleitet; der OpenAI-kompatible Endpunkt hat kein solches Feld.

Base-URLs

GoModel verwendet intern getrennte Basis-URLs für natives Gemini und die OpenAI-kompatible API:
  • nativer Chat/Modelle: https://generativelanguage.googleapis.com/v1beta
  • OpenAI-kompatibel: https://generativelanguage.googleapis.com/v1beta/openai
GEMINI_BASE_URL überschreibt sie. Endet der Wert auf /openai, verwendet GoModel ihn für den OpenAI-kompatiblen Client und leitet die native Basis ab, indem /openai entfernt wird. Dateien und Batches verwenden immer die OpenAI-kompatible Schnittstelle; Chat, Embeddings und Bilder folgen dem API-Modus.

Embeddings

Im nativen Modus werden Embeddings über models/{model}:batchEmbedContents bedient. dimensions wird auf outputDimensionality abgebildet, und encoding_format: "base64" wird berücksichtigt. Der native Modus erfasst die Token-Nutzung, die Gemini für neuere Modelle wie gemini-embedding-2 meldet. Ältere Modelle wie gemini-embedding-001 und die OpenAI-kompatible Schnittstelle melden keine. Diese Responses enthalten daher Token-Zahlen von null. Wird das Modell pro Token abgerechnet, werden diese Nutzungszeilen ohne Token-Zahlen mit einem Vorbehalt zur Kostenberechnung markiert.

Bildgenerierung und -bearbeitung

Im nativen Modus funktionieren die OpenAI-kompatiblen Bild-Endpunkte mit Gemini-Bildmodellen (gemini-2.5-flash-image, gemini-3.1-flash-image, gemini-nano-banana-2.1, …, über generateContent). Liefert das Modell kein Bild, enthält der Fehler Geminis Finish-Reason und Meldung (zum Beispiel IMAGE_RECITATION). Google hat Imagen im August 2026 aus der AI-Studio-API entfernt; Imagen wird weiterhin auf Vertex AI bereitgestellt. Bildbearbeitungen erfordern den nativen Modus und ein Gemini-Bildmodell; Masken werden nicht unterstützt. Details zur Parameterabbildung und zu den Preisen finden Sie in den Provider-Hinweisen der Images API.

Bilder in Chat-Responses

Im nativen Modus können bildfähige Modelle (gemini-2.5-flash-image, gemini-3-pro-image-preview, …) Bilder aus Chat Completions und Responses zurückgeben. message.content bleibt der Text-String. Bei Chat Completions landen die Bilder in einem separaten Array images, demselben Feld, das auch OpenRouter verwendet. Clients, die das Feld nicht auslesen, ignorieren es einfach:
In der Responses API ist jedes Bild ein eigenes Output-Item image_generation_call. Das Base64-Bild steht in result und das Format in output_format, wie im Output von OpenAI. Um das Bild in einem späteren Turn zu bearbeiten, senden Sie die Assistant-Nachricht (mit images) oder das Item image_generation_call unverändert zurück, damit Gemini die Thought Signature jedes Bildes erhält. Clients von /v1/messages (Anthropic Messages API) erhalten nur den Text. Beim Streaming kommt jedes Bild vollständig an: in Chat Completions im delta.images eines Chunks, in der Responses API als fertiges Item image_generation_call. Ein Upstream-Stream-Event, das ein ganzes Bild als Base64 enthält, darf bis zu 32 MiB groß sein; Stream-Plugins halten standardmäßig höchstens 4 MiB, daher beendet ein größeres Bild einen Stream, der durch sie läuft. Fordern Sie 2K- und 4K-Bilder ohne Streaming an, wenn solche Plugins aktiv sind. Jedes Bild umfasst mehrere Megabyte Base64. Audit-Logs erfassen höchstens 1 MB eines Response-Bodys, sodass ein protokollierter Body gekürzt und entsprechend markiert wird. Der Response-Cache speichert die gesamte Response.

Reasoning Effort

Im nativen Modus wird reasoning_effort (oder reasoning.effort) in Geminis thinkingConfig übersetzt: Thinking lässt sich bei Gemini 3 und 4 nicht abschalten, und Pro-Modelle, 3.7 und 3.8 Flash sowie Gemini 4 (gemini-4-argon, …) lehnen minimal ab. GoModel sendet daher die niedrigste Stufe, die diese Modelle akzeptieren, statt Googles 400 weiterzugeben. Ein explizites extra_body.google.thinking_config wird unverändert weitergeleitet, wenn es thinking_budget oder thinking_level setzt; andernfalls ergänzt reasoning_effort darin seine Stufe oder sein Budget. Dieselbe Begrenzung gilt im Modus openai_compatible, in dem Googles Endpunkt reasoning_effort als Thinking-Stufe weiterleitet und dieselben Werte ablehnt. Bei Gemini 4 zählen Thinking-Tokens gegen max_tokens, und eine lange Antwort, die das Ausgabelimit pro Request erreicht, endet mit length (Geminis CONTINUATION); GoModel setzt sie nicht fort.

Sampling-Parameter bei Gemini 3 und 4

Googles Migrationsleitfäden für Gemini 3 und 4 empfehlen, temperature, top_p und top_k aus jedem Request zu entfernen, weil die Modelle auf ihre Standardwerte abgestimmt sind (Gemini 4 ignoriert sie), und führen candidate_count als nicht unterstützt. Im nativen Modus entfernt GoModel diese vier Felder daher für Gemini 3 und neuer (gemini-3-*, gemini-3.8-*, gemini-4-*, …) und leitet sie für Gemini 2.5, Gemma und andere Modelle weiterhin weiter. presence_penalty und frequency_penalty werden nie weitergeleitet: Jedes aktuelle Modell der Gemini API, 2.5 eingeschlossen, antwortet mit HTTP 400 „Penalty is not enabled for this model“. max_tokens, stop, response_format und Thinking-Einstellungen sind nicht betroffen. Im Modus openai_compatible entfernt GoModel außerdem die Felder, die Googles Endpunkt als unbekannt ablehnt (seed, logprobs, top_logprobs, store, metadata, logit_bias, top_k, prediction, prompt_cache_key, safety_identifier, verbosity, web_search_options), zusammen mit den Penalties, und repariert die gestreamten Tool-Aufrufe, die dieser Endpunkt ohne index ausgibt und mit stop statt tool_calls beendet.

Thought Signatures

Gemini 3 und 4 hängen den von ihnen ausgegebenen Funktionsaufrufen eine verschlüsselte thoughtSignature an und lehnen einen Folge-Request ab (HTTP 400, „Function call is missing a thought_signature“), wenn dieser Aufruf ohne Signatur im Verlauf zurückkommt. Im nativen Modus stellt GoModel die Signatur auf dieselbe Weise bereit wie Googles eigener OpenAI-kompatibler Endpunkt, sodass ein Client, der Assistant-Nachrichten unverändert zurücksendet, weiterhin funktioniert:
Dasselbe extra_content-Element erscheint bei gestreamten tool_calls-Deltas, bei function_call-Ausgabeelementen der Responses API, bei tool_use-Blöcken der Anthropic Messages API und (bei reinen Text-Turns) an der Assistant-Nachricht selbst. Senden Sie es unverändert zurück; nur der erste Aufruf eines parallelen Batches trägt eine Signatur. Andere Provider sehen es nie; die gemeinsame Konvention ist unter Extra Content, Thinking-Blöcke und Thought Signatures beschrieben. Eine flache thought_signature (oder thoughtSignature) am Tool-Aufruf oder an dessen function-Objekt wird ebenfalls akzeptiert, sodass Clients, die für andere Gateways gebaut wurden, weiterhin funktionieren. Enthält ein Gemini-3- oder Gemini-4-Verlauf einen Funktionsaufruf ohne jede Signatur (die Konversation begann mit einem anderen Modell, oder der Client hat das Feld verworfen), sendet GoModel Googles dokumentierten Platzhalter skip_thought_signature_validator, statt den 400 weiterzugeben – im nativen Modus wie im Modus openai_compatible. Die Reasoning-Kontinuität ist für diesen Turn eingeschränkt, senden Sie daher bevorzugt die echte Signatur zurück.

Bildeingabe

Für per URL gehostete Bilder im nativen Modus rufen Googles eigene Beispiele zuerst die URL ab und senden die Bytes an generateContent.

Videoeingabe

Im nativen Modus wird eine data:-URL zu einem eingebetteten Videoteil (standardmäßig video/mp4, wenn die Data-URL keinen Medientyp angibt), während URIs von YouTube, Files API und Cloud Storage als Dateireferenz gesendet werden, die Gemini selbst auflöst. Jede andere entfernte https://...-URL wird abgelehnt statt verworfen – laden Sie sie zuerst über die Gemini Files API hoch.

Nachrichten und Tools

Im nativen Modus werden OpenAI-Chat-Felder wie folgt auf generateContent abgebildet: Gemini akzeptiert allowedFunctionNames nur mit ANY oder VALIDATED. Deshalb wird aus einer auto-Teilmenge VALIDATED: Das Modell kann weiterhin mit Text antworten, aber jeder Aufruf, den es tätigt, ist auf die aufgelisteten Tools beschränkt. VALIDATED gilt für den gesamten Request, sodass ein einziges strict-Tool dazu führt, dass jedes deklarierte Tool schemavalidiert wird. Gemini bietet keine Möglichkeit, einen Turn auf einen einzigen Funktionsaufruf zu beschränken, und das Benennen eines einzelnen Tools hilft nicht: Gemini kann dieselbe Funktion in einem Turn mehrfach aufrufen. Wenn parallel_tool_calls: false (oder Anthropics disable_parallel_tool_use) wichtig ist, behandeln oder verwerfen Sie die zusätzlichen Aufrufe in Ihrem Client. Eine allowed_tools-Auswahl mit leerer tools-Liste wird mit 400 abgelehnt, wie bei OpenAI.

Noch nicht integriert

  • Automatisches Abrufen entfernter image_url-Werte im nativen Modus.
  • Hochladen entfernter Bilder oder Videos über die Gemini Files API vor einem Chat-Request.

Referenzen

Zuletzt geändert am 8. November 2026