Gemini-Bildgenerierung über einen API-Proxy

Ein Proxy für die Gemini-Bild-API vermittelt zwischen deiner Anwendung und einem Gemini-Bildmodell. Dafür brauchst du eine Modell-ID mit Bildausgabe, das Anfrageformat des Dienstes und einen Weg zum fertigen Bild. Eine neue Basis-URL im Textclient allein weist keine Unterstützung für Bildgenerierung nach.

Bei OmniaKey lautet der dokumentierte Ablauf: Aufgabe erstellen → Status abfragen → Bild herunterladen. Er beginnt mit POST /v1/media/tasks. Hier findest du den vollständigen Ablauf und die Unterschiede zu Googles nativer API und zu OpenAI-kompatiblen Schnittstellen.

Welche Art von Proxy brauchst du?

Gemeint ist hier ein API-Dienst, der Modellanfragen, Authentifizierung und Antworten verarbeitet. Ein Netzwerkproxy leitet Datenverkehr weiter, übersetzt aber nicht automatisch zwischen Bild-APIs. Entscheidend ist die veröffentlichte Schnittstellenspezifikation.

Googles aktueller Leitfaden zur Bildgenerierung nutzt Beispiele der Interactions API. Die GenerateContent-Referenz beschreibt eine eigene Schnittstelle. Vermische weder Eingabefelder noch Antwortparser und setze nicht voraus, dass ein Proxy beide anbietet.

Auch Bildverständnis und Bildgenerierung unterscheiden sich. Ein Modell kann ein Foto beschreiben, ohne selbst Bilder auszugeben. Ein erfolgreicher Textaufruf bestätigt daher weder Bildgenerierung noch Bildbearbeitung. „OpenAI-kompatibel“ bedeutet außerdem nicht automatisch, dass jeder SDK-Aufruf für die gewählte Bildroute funktioniert.

Eine konkrete Bildmodell-ID wählen

Google unterscheidet unter anderem diese IDs:

• Nano Banana 2.1: gemini-nano-banana-2.1, Googles empfohlener Ausgangspunkt für neue Workflows zur Bildgenerierung.
• Nano Banana Pro: gemini-3-pro-image, ein eigenständiges Modell für anspruchsvollere visuelle Aufgaben.
• Nano Banana 2: gemini-3.1-flash-image, die vorherige Generation und kein Alias für 2.1.

Kopiere die ID aus dem Dienst, den du aufrufen möchtest. Prüfe Berechtigungen, Generierung und Bearbeitung, Größen sowie Abrechnungseinheit. Für 2.1 dokumentiert OmniaKey parameters.aspect_ratio und parameters.image_size mit 1K, 2K und 4K. Diese Felder sind nicht mit Googles imageConfig oder den GPT-Image-Feldern size und quality austauschbar.

Den aktuellen Eintrag findest du auf der Modellseite von Nano Banana 2.1. Bei der Auswahl hilft der Vergleich von 2.1 und Pro.

Ein Bild mit OmniaKey generieren

Du brauchst Bash, cURL, jq und einen OmniaKey-Schlüssel in der lokalen Umgebungsvariable OMNIAKEY_API_KEY. Führe die Befehle im Backend oder auf deinem Entwicklungsrechner aus; der Schlüssel gehört nicht in Browsercode. Der einfache englische Beispielprompt dient dazu, zuerst den API-Ablauf zu prüfen.

1. Aufgabe erstellen und speichern

Lege für diesen logischen Bildauftrag einen eindeutigen Idempotency-Key fest. Der Wert im Beispiel ist ein Demowert: Ersetze ihn einmal für eine neue Aufgabe und behalte Schlüssel und Anfragekörper bei Wiederholungen dieser Aufgabe unverändert bei. Speichere beides vor dem Senden.

curl --fail-with-body --silent --show-error \
  https://api.omniakey.com/v1/media/tasks \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gemini-image-demo-20261014-001" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "type": "image",
    "operation": "generate",
    "input": {"prompt": "A blue ceramic cup on a white studio table, no text"},
    "parameters": {"aspect_ratio": "1:1", "image_size": "1K"}
  }' -o task.json

Fahre nur fort, wenn cURL erfolgreich war und task.json eine id enthält. Neue Aufgaben liefern 202 Accepted; derselbe Schlüssel mit demselben Körper liefert die ursprüngliche Aufgabe mit 200. Angenommen heißt noch nicht fertig. Details erklärt der Aufgabenlebenszyklus auf Englisch.

2. Gespeicherte ID abfragen

Dieses Bash-Beispiel begrenzt die Zahl der Abfragen. Nach Erreichen der Grenze kannst du mit der gespeicherten ID später fortfahren. Es wird weder abgebrochen noch eine zweite Aufgabe erstellt.

TASK_ID="$(jq -er '.id' task.json)" || exit 1
for attempt in {1..60}; do
  curl --fail-with-body --silent --show-error \
    "https://api.omniakey.com/v1/media/tasks/$TASK_ID" \
    -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
    -o result.json || exit 1
  STATUS="$(jq -er '.status' result.json)" || exit 1
  case "$STATUS" in
    succeeded) break ;;
    failed|canceled) jq '.error' result.json; exit 1 ;;
    queued|processing) sleep 3 ;;
    *) exit 1 ;;
  esac
done

Bricht die Erstellung vor dem Empfang der ID wegen einer Zeitüberschreitung ab, wiederhole denselben Anfragekörper mit demselben Idempotenzschlüssel. Liegt eine ID vor, frage diese Aufgabe ab. Ein neuer Schlüssel kann einen weiteren kostenpflichtigen Auftrag erzeugen. Die Wiederherstellung ist zeitlich begrenzt: Aufgaben werden laut Dokumentation 24 Stunden nach Erstellung aufbewahrt.

3. Nur erfolgreiche Ergebnisse herunterladen

jq -e '.status == "succeeded"' result.json >/dev/null || exit 1
ASSET_URL="$(jq -er '.assets[0].url' result.json)" || exit 1
curl --fail --location --silent --show-error \
  "$ASSET_URL" -o generated-image

Bestimme die Dateiendung anhand von mime_type. Prüfe dann, ob sich das Bild öffnen lässt und die erwarteten Maße hat. Signierte URLs laufen ab. Solange Aufgabe und Bild verfügbar sind, kann eine erneute Abfrage eine frische URL liefern. Lade dauerhaft benötigte Ergebnisse herunter; ein signierter Link ist kein dauerhafter Speicher.

Mit einem Referenzbild bearbeiten

Verwende operation: "edit" und übergib eingebettete Base64-Daten in input.image. Für mehrere Referenzen gibt es, soweit unterstützt, input.images. Die Bearbeitungsanweisung steht weiterhin in input.prompt. Das vollständige Format zeigt die Bild-API-Dokumentation auf Englisch.

Die Aufgaben-API begrenzt den gesamten Anfragekörper einschließlich Base64 auf 1 MiB. Komprimiere oder verkleinere die Referenz bei Bedarf. Googles direkte Uploadgrenzen ersetzen nicht die Grenzen des Proxys. Beginne mit einer kleinen Referenz und einer klaren Änderung; kontrolliere auch, was unverändert bleiben sollte.

Ein anderer Prompt, ein anderes Bild, Modell oder ein geänderter Parameter ist eine neue Anfrage. Nutze dafür einen neuen Idempotenzschlüssel. Derselbe Schlüssel mit geändertem Körper ergibt 409 idempotency_key_reused.

Fehler an der richtigen Stelle suchen

Googles Fehlerleitfaden beschreibt Googles eigenes Verhalten. Ein Proxy fügt eine weitere Schicht hinzu. Protokolliere HTTP-Status, Fehlercode, Aufgaben-ID und Dauer ohne sensible Inhalte. Schlüssel und private Referenzbilder gehören nicht ins Protokoll. Ein JSON mit 200 allein belegt kein brauchbares Bild.

Kosten vergleichen und Integration prüfen

Googles direkte Abrechnung und ein Proxyangebot sind getrennte Leistungen. Prüfe vor größeren Mengen die aktuellen OmniaKey-Preise und die Einheit des Modells. Übertrage Texttokenpreise nicht auf Bildausgaben und rechne nicht damit, dass ein Gemini-Abo für Privatnutzer Proxyaufrufe bezahlt.

Ein sinnvoller Vergleich ist gesamter berechneter Betrag ÷ Zahl akzeptierter Bilder. Beziehe kostenpflichtige Wiederholungen und verworfene Bilder ein. Das ist eine Planungsformel, kein gemessener Benchmark und kein Preisversprechen.

Prüfe vor höherem Volumen fünf kleine Fälle:

1. Ein Textprompt liefert ein Bild, das sich im erwarteten Format und mit den richtigen Maßen öffnen lässt.
2. Eine Referenzbearbeitung setzt die Änderung um und erhält wichtige Details.
3. Derselbe Schlüssel mit demselben Körper liefert dieselbe Aufgaben-ID.
4. Nach lokaler Zeitüberschreitung lässt sich die Abfrage per ID fortsetzen.
5. Ein ungültiger Parameter oder nicht verfügbares Modell erzeugt einen verständlichen Fehler statt eines scheinbaren Erfolgs.

Halte Modell-ID, Parameter, Dauer, Endstatus, Kosten und Prüfergebnis fest. Kläre vor dem Versand produktiver Inhalte, wie der Dienst Prompts und Referenzbilder verarbeitet.

Häufige Fragen

Reicht eine neue Basis-URL im vorhandenen SDK?

Nur wenn der Proxy genau den Endpunkt, die Felder und die Bildantwort dokumentiert, die das SDK erwartet. Prüfe die Bildoperation selbst; ein funktionierender Chat reicht nicht.

Hebt ein Proxy die Gemini-Limits auf?

Nein. Grenzen des Anbieters, Modells, Proxys und Kontos können gleichzeitig gelten. Ein Gateway garantiert weder unbegrenzte Bildausgaben noch regionale Verfügbarkeit.

Mit welchem Modell sollte ich beginnen?

Prüfe den aktuellen Katalog und teste ein unterstütztes Bildmodell mit einer kleinen Aufgabe. Der Leitfaden zu Nano Banana 2.1 erläutert Modelländerungen; hier geht es um die API-Anbindung.

Quellen und nächster Schritt

Grundlagen sind Googles Bildleitfaden, GenerateContent-Referenz, Fehlerdokumentation und die verlinkten OmniaKey-Dokumente. Diese Referenzen sind auf Englisch. Die Spezifikationen wurden am 14. Oktober 2026 geprüft; bestätige deinen Modellzugriff vor dem Ausführen.