Viele Entwickler, die zum ersten Mal die Nano Banana Pro API (entspricht dem Google-Modell gemini-3-pro-image-preview) aufrufen, tappen in dieselbe Falle: Sie verwenden den Parameter size: "1024x1024" aus der OpenAI / DALL-E-Ära wieder. Das Ergebnis: Entweder lässt sich die Auflösung des generierten Bildes nicht anpassen, es erscheint direkt ein 400-Fehler oder der Parameter wird vom Server einfach ignoriert.
Dies ist der häufigste „High-Frequency-Bug“ beim Aufruf der Nano Banana Pro API. Der richtige Weg ist: Die Auflösung wird durch die beiden Parameter imageConfig.imageSize (Schärfe 1K/2K/4K) und imageConfig.aspectRatio (Seitenverhältnis 1:1/16:9/…) bestimmt. Übergeben Sie keinesfalls ein size-Feld. Dieser Artikel erklärt das Thema auf 600 Zeilen und liefert direkt kopierbare curl-, Python- und Node.js-Codebeispiele.
Kernpunkte beim Aufruf der Nano Banana Pro API
Bevor Sie den Code kopieren, verinnerlichen Sie bitte diese drei goldenen Regeln – wenn Sie diese verstehen, ist der Rest des Artikels nur noch Detailarbeit:
- Modellbezeichnung: Nano Banana Pro =
gemini-3-pro-image-preview(auch Gemini 3 Pro Image genannt), gehört zur Google Gemini 3-Serie für Bilderzeugung und -bearbeitung. Manche nennen es auch Nano Banana 2, es ist im Grunde dasselbe. - Protokoll ist Gemini-nativ: Es ist kein OpenAI Chat Completions-kompatibles Protokoll. Der Pfad für die Anfrage lautet
:generateContent, die obersten Felder im Request-Body sindcontents+generationConfig. Es gibt wedermessagesnoch das OpenAI-typischesize-Feld. - Auflösung = imageSize × aspectRatio:
imageSizesteuert die Schärfestufe (512 / 1K / 2K / 4K),aspectRatiosteuert das Bildseitenverhältnis (1:1 / 16:9 / 9:16 / …). Beide zusammen bestimmen die endgültige Pixelanzahl.
📌 Zusammenfassung in einem Satz: Wenn Sie Nano Banana Pro über das Gemini-Protokoll aufrufen, vergessen Sie die OpenAI-Gewohnheit
size: "1024x1024"komplett. Der API-Proxy-Dienst von APIYI (apiyi.com) behält das native Gemini-Protokoll für den Nano Banana Pro-Endpunkt vollständig bei; jedeimageConfig-Schreibweise, die bei Google offiziell funktioniert, funktioniert auch bei APIYI.
Kurzübersicht der Nano Banana Pro Parameter
| Parameter | Position | Funktion | Beispielwerte |
|---|---|---|---|
imageSize |
generationConfig.imageConfig |
Schärfestufe | "512" / "1K" / "2K" / "4K" |
aspectRatio |
generationConfig.imageConfig |
Seitenverhältnis | "1:1" / "16:9" / "9:16" / "4:3" etc. |
responseModalities |
generationConfig |
Ausgabemodalität | ["IMAGE"] (erforderlich) |
contents[].parts[].text |
contents |
Text-Eingabeaufforderung | Freitext |
contents[].parts[].inline_data |
contents |
Referenzbild (base64) | Enthält mime_type und data |
⚠️ Das in der Tabelle fehlende
size-Feld: Da es kein gültiger Parameter für das Gemini-Protokoll ist, sollten Sie es nicht übergeben.
Warum Sie den size-Parameter nicht verwenden sollten: Gründe auf Protokollebene
Dies ist der wichtigste Abschnitt dieses Artikels. Wir beleuchten das Thema auf drei Ebenen, um es vollständig zu durchdringen.
Protokollebene: Gemini und OpenAI sind zwei unabhängige Spezifikationen
Die Bild-APIs von OpenAI (DALL-E 2/3, gpt-image-1) verwenden den String-Parameter size: "1024x1024" auf der obersten Ebene; die Bild-API von Google Gemini 3 hingegen ist als verschachteltes imageConfig-Objekt konzipiert. Beide Spezifikationen sind völlig unabhängig voneinander. Nano Banana Pro basiert auf dem nativen Gemini-Protokoll, daher gilt:
- ❌
size: "1024x1024"—— Das Gemini-Protokoll kennt dieses Feld nicht. - ❌
size: "1K"—— Dieses Feld existiert nicht. - ❌
n: 4—— Es gibt kein Feld für "generiere N Bilder auf einmal" wie bei OpenAI. - ✅
imageConfig.imageSize: "1K"—— Korrekt. - ✅
imageConfig.aspectRatio: "16:9"—— Korrekt.
Verhaltensebene: Was passiert, wenn man size trotzdem mitsendet?
Die serverseitige Verarbeitung führt meist zu einem von drei Szenarien, von denen keines Ihren Wünschen entspricht:
- Stummes Ignorieren: Das vorgelagerte Gateway verwirft unbekannte Felder als ungültig. Sie glauben, die Einstellung sei aktiv, aber das System gibt standardmäßig 1K im 1:1-Format aus.
- Direkter 400-Fehler: Gateways mit strenger Schema-Validierung lehnen die Anfrage aufgrund unbekannter Felder sofort ab.
- Beeinflussung von Abrechnung/Routing: Manche Proxy-Ebenen interpretieren
sizeals Routing-Signal und leiten die Anfrage an die falsche Endpunkt-Version weiter.
Engineering-Ebene: Technische Schulden durch unsauberen Code
Viele Teams kapseln die APIs verschiedener Anbieter wie OpenAI, Gemini oder Stability in einer gemeinsamen Aufrufschicht und verwenden gewohnheitsmäßig ein "universelles size-Feld". Das sieht zwar elegant aus, ist aber eine Fehlerquelle. Es wird empfohlen, beim Aufruf von nativen Gemini-Schnittstellen wie Nano Banana Pro eine separate Konvertierungskette zu nutzen. Mappen Sie den size-Parameter explizit auf imageConfig.imageSize + imageConfig.aspectRatio, anstatt den ursprünglichen size-Wert einfach durchzureichen.
💡 Empfehlung: Wenn Sie Nano Banana Pro über APIYI (apiyi.com) aufrufen, schreiben Sie eine kleine Konvertierungsfunktion. Diese sollte Strings wie
"1024x1024"inimageSize: "1K"undaspectRatio: "1:1"zerlegen, um Mischkonfigurationen von Grund auf zu vermeiden.
Vollständige Vergleichstabelle: imageSize × aspectRatio
imageSize-Stufen und Abrechnung
| imageSize | Ungefähre Auflösung | Output-Token | Preis (Referenz) | Empfohlene Anwendung |
|---|---|---|---|---|
"512" |
512×512 Ebene | Niedrig | Am günstigsten | Thumbnails / Entwürfe |
"1K" |
1024×1024 Ebene | ~1120 | ≈ $0,134 | Standardempfehlung |
"2K" |
2048×2048 Ebene | ~1120 | ≈ $0,134 | HD-Poster |
"4K" |
4096×4096 Ebene | ~2000 | ≈ $0,24 (ca. 80% teurer) | Druckqualität |
💰 Kostenhinweis: 4K ist etwa 80 % teurer als 1K/2K. Nutzen Sie 4K nicht unüberlegt. Für die meisten Web-/App-Szenarien reicht 1K völlig aus; 4K sollte nur bei Bedarf für ultrahohe Auflösungen verwendet werden. Die aktuellen Preise finden Sie auf der Website von APIYI (apiyi.com).
Vollständige Liste der unterstützten aspectRatio-Werte
| Verhältnis | Verwendung |
|---|---|
"1:1" |
Profilbilder / Quadratische Social-Media-Bilder |
"16:9" |
Querformat-Video-Thumbnails / Desktop-Hintergründe |
"9:16" |
Hochformat-Kurzvideos / Handy-Hintergründe |
"4:3" |
Klassisches Foto-Querformat |
"3:4" |
Klassisches Foto-Hochformat |
"3:2" / "2:3" |
DSLR-Standardverhältnis |
"4:5" / "5:4" |
Instagram-Einzelbilder |
"21:9" |
Ultra-Breitbild-Kino-Look |
"1:4" / "4:1" |
Lange Banner |
"1:8" / "8:1" |
Extreme Langformate für Spezialzwecke |
Häufige Kombinationen → Pixel-Mapping
| imageSize | aspectRatio | Ungefähre Pixel-Ausgabe |
|---|---|---|
1K |
1:1 |
1024 × 1024 |
1K |
16:9 |
1024 × 576 |
1K |
9:16 |
576 × 1024 |
2K |
1:1 |
2048 × 2048 |
2K |
16:9 |
2048 × 1152 |
4K |
1:1 |
4096 × 4096 |
4K |
9:16 |
2304 × 4096 |
4K |
21:9 |
4096 × 1728 |
Hinweis: Die tatsächlichen Pixelmaße können aufgrund modellinterner Ausrichtungsregeln um ±N Pixel variieren, was jedoch die visuelle Schärfestufe nicht beeinträchtigt.
Hier ist die Übersetzung des technischen Leitfadens für die Nano Banana Pro API:
Korrekter Aufrufcode für die Nano Banana Pro API
Im Folgenden finden Sie minimale, ausführbare Beispiele in drei Programmiersprachen. Alle drei Beispiele führen dieselbe Aufgabe aus: Eingabe eines Originalbildes + einer Eingabeaufforderung, Ausgabe eines Bildes im 1K 1:1 Format.
curl-Version (am anschaulichsten, ideal für das Debugging)
curl -X POST \
"https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
-H "Authorization: Bearer DEIN-APIYI-SCHLÜSSEL" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"parts": [
{
"inline_data": {
"mime_type": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgAA...(Originalbild-Base64)"
}
},
{
"text": "Ändere dieses Bild in einen Cyberpunk-Stil und behalte die Pose der Person bei"
}
]
}],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": {
"aspectRatio": "1:1",
"imageSize": "1K"
}
}
}'
Python-Version (Empfehlung: Verwenden Sie direkt requests, ohne Abhängigkeit von einem SDK)
import base64
import requests
with open("input.png", "rb") as f:
img_b64 = base64.b64encode(f.read()).decode()
resp = requests.post(
"https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
headers={
"Authorization": "Bearer DEIN-APIYI-SCHLÜSSEL",
"Content-Type": "application/json",
},
json={
"contents": [{
"parts": [
{"inline_data": {"mime_type": "image/png", "data": img_b64}},
{"text": "Ändere dieses Bild in einen Cyberpunk-Stil und behalte die Pose der Person bei"},
]
}],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": {
"aspectRatio": "1:1",
"imageSize": "1K",
},
},
},
timeout=120,
)
data = resp.json()
out_b64 = data["candidates"][0]["content"]["parts"][0]["inline_data"]["data"]
with open("output.png", "wb") as f:
f.write(base64.b64decode(out_b64))
Node.js-Version (Natives fetch verwenden, um zu verhindern, dass das SDK imageConfig verschluckt)
import fs from "node:fs";
const imgB64 = fs.readFileSync("input.png").toString("base64");
const resp = await fetch(
"https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
{
method: "POST",
headers: {
"Authorization": "Bearer DEIN-APIYI-SCHLÜSSEL",
"Content-Type": "application/json",
},
body: JSON.stringify({
contents: [{
parts: [
{ inline_data: { mime_type: "image/png", data: imgB64 } },
{ text: "Ändere dieses Bild in einen Cyberpunk-Stil und behalte die Pose der Person bei" },
],
}],
generationConfig: {
responseModalities: ["IMAGE"],
imageConfig: {
aspectRatio: "1:1",
imageSize: "1K",
},
},
}),
},
);
const data = await resp.json();
const outB64 = data.candidates[0].content.parts[0].inline_data.data;
fs.writeFileSync("output.png", Buffer.from(outB64, "base64"));
🔧 Warum wir dringend natives
fetch/requestsempfehlen: Es ist bekannt, dass einige SDKs (einschließlich früherer Versionen von LiteLLM oder bestimmte Versionen des Google Node SDK)imageConfigals unbekanntes Feld herausfiltern, wodurchimageSize/aspectRatiowirkungslos werden. Durch das direkte Konstruieren des JSON-Request-Bodys umgehen Sie dieses Problem zu 100 %. Wenn Sie unbedingt ein SDK verwenden möchten, aktualisieren Sie es auf die neueste Version und geben Sie den finalen Body über einen Request-Interceptor in der Konsole aus, um dies zu überprüfen.
Checkliste zur Fehlervermeidung: Die 6 häufigsten Fehler
Fehler 1: Übermittlung des OpenAI-Style size-Parameters
// ❌ Fehler: 'size' ist kein gültiges Feld im Gemini-Protokoll
{
"contents": [...],
"size": "1024x1024",
"generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" } }
}
// ✅ Korrekt: 'size' entfernen, nur 'imageConfig' beibehalten
{
"contents": [...],
"generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" }, "responseModalities": ["IMAGE"] }
}
Fehler 2: Verwendung von Unterstrichen / snake_case bei Feldnamen
Die Felder in imageConfig der Gemini 3 Image-API verwenden CamelCase: imageSize, aspectRatio, responseModalities. Häufige Fehler:
- ❌
image_size/aspect_ratio/response_modalities - ✅
imageSize/aspectRatio/responseModalities
Fehler 3: imageConfig wird vom SDK stillschweigend entfernt
Wie bereits erwähnt, filtern einige SDK-Versionen unbekannte Felder. Vorgehensweise zur Fehlerbehebung:
- Den tatsächlichen HTTP-Body vor und nach dem SDK-Aufruf ausgeben.
- Den tatsächlichen ausgehenden Request mit
mitmproxyoderCharlesabfangen. - Wenn
imageConfigfehlt, auf nativesfetch/requestsumsteigen.
Fehler 4: responseModalities vergessen
// ❌ Wenn 'responseModalities' nicht gesetzt ist, wird evtl. nur Text statt eines Bildes zurückgegeben
{ "generationConfig": { "imageConfig": {...} } }
// ✅ Es muss explizit deklariert werden, dass die Antwortmodalität 'IMAGE' enthält
{ "generationConfig": { "imageConfig": {...}, "responseModalities": ["IMAGE"] } }
Fehler 5: Kein exponentielles Backoff bei 429-Fehlern (Rate Limiting)
Wenn die Last des Upstream-Dienstes gesättigt ist, wird folgende Meldung zurückgegeben:
{ "error": { "message": "Upstream-Last gesättigt, bitte später erneut versuchen", "type": "upstream_error", "code": 429 } }
Die korrekte Vorgehensweise ist ein exponentielles Backoff-Retry (3s → 6s → 12s). Versuchen Sie es nicht sofort erneut, da dies die Überlastung nur verschlimmert:
import time
for attempt in range(3):
resp = requests.post(url, json=body, headers=headers, timeout=120)
if resp.status_code != 429:
break
time.sleep(3 * (2 ** attempt)) # 3s, 6s, 12s
Fehler 6: Falsche Platzierung mehrerer Referenzbilder
Nano Banana Pro unterstützt die Eingabe mehrerer Bilder (Originalbild + mehrere Referenzbilder). Alle Bilder sollten als einzelne inline_data-Einträge im parts-Array enthalten sein, wobei der Text-Prompt am Ende des Arrays steht:
// ✅ Korrekt: Bilder zuerst, Text zuletzt
"parts": [
{ "inline_data": { "mime_type": "image/png", "data": "Originalbild-Base64" } },
{ "inline_data": { "mime_type": "image/png", "data": "Referenzbild1-Base64" } },
{ "inline_data": { "mime_type": "image/png", "data": "Referenzbild2-Base64" } },
{ "text": "Bitte migriere den Stil des Originalbildes auf den Farbton von Referenzbild 1 und nutze die Komposition von Referenzbild 2" }
]
🧰 Zusammenfassung: Erstellen Sie aus diesen 6 Punkten eine "Nano Banana Pro Checkliste" für Ihr Team. Wenn Sie diese vor jedem neuen API-Aufruf durchgehen, vermeiden Sie über 90 % der trivialen Bugs. Der Nano Banana Pro Endpunkt von APIYI (apiyi.com) folgt vollständig dem Gemini-Protokoll, daher sind alle diese Tipps universell anwendbar.
title: "Analyse des Aufruf-Workflows: Wo treten die meisten Fehler auf?"
Analyse des Aufruf-Workflows: Wo treten die meisten Fehler auf?
Viele der von Lesern geposteten Protokolle stimmen fast exakt mit dem von Ihnen beschriebenen Ablauf überein:
Frontend POST /api/generate
→ server.js extrahiert Parameter
→ Prüfe modelKey.startsWith('nano-banana')
→ _generateViaGemini() baut Request-Body zusammen
→ POST https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent
→ Rückgabe / Wiederholung
Hier markieren wir die fehleranfälligsten Stellen:
| Schritt | Häufiges Problem | Empfehlung |
|---|---|---|
| Frontend-Parameter | Übermittlung von size: "1024x1024" |
In imageSize + aspectRatio aufteilen |
| server.js Body-Assemblierung | size-Feld wird versehentlich an Gemini weitergereicht |
size in der Assemblierungsfunktion explizit löschen |
| Modell-Routing | nano-banana wurde auf 1.5 statt 3 Pro geroutet |
Modellname strikt als gemini-3-pro-image-preview setzen |
| Request-Versand | SDK-Version mit Schema-Validierung verwendet | Natives fetch nutzen oder SDK aktualisieren |
| Fehlerbehandlung | 429-Fehler direkt an User weitergegeben | Exponentielles Backoff (3 Versuche) implementieren |
| Antwort-Parsing | Standardmäßig als text ausgelesen, obwohl IMAGE |
Korrekter Pfad: candidates[0].content.parts[0].inline_data.data |
📋 Kurz gefasst: Ihr Workflow-Struktur ist korrekt. Wenn Sie das überflüssige
size-Feld bei der Parameter-Extraktion entfernen und sicherstellen, dassserver.jses nicht außerhalb dergenerationConfigwieder einfügt, ist die Kette sauber.
FAQ – Häufig gestellte Fragen
Q1: Sind Nano Banana Pro und Nano Banana 2 dasselbe?
Ja. In der Community wird Gemini 3 Pro Image (gemini-3-pro-image-preview) oft als Nano Banana 2 oder Nano Banana Pro bezeichnet. Alle drei Begriffe meinen dasselbe Modell. Bei APIYI (apiyi.com) ist der Modellname gemäß der offiziellen Dokumentation maßgeblich.
Q2: Was passiert, wenn ich keine imageConfig übermittle?
Das Modell verwendet interne Standardwerte (meist 1K + 1:1). Wenn Ihnen die Auflösung egal ist, können Sie sie weglassen; wenn Sie spezifische Anforderungen an das Bildformat haben, müssen Sie imageConfig explizit übergeben.
Q3: Kann ich das Gemini-Protokoll nutzen und gleichzeitig size wie bei OpenAI übergeben?
Das ist nicht zuverlässig. Das Gemini-Protokoll kennt kein size-Feld; eine Mischung führt zu unvorhersehbarem Verhalten. Die Verwendung von imageConfig.imageSize + imageConfig.aspectRatio ist der sicherste Weg.
Q4: Ist die Bildqualität bei 4K zwingend besser?
Die Details sind reichhaltiger, aber die Kosten verdoppeln sich fast (~$0,24 vs. $0,134) und die Generierungszeit steigt. Für Web-/App-Bilder reichen 1K oder 2K meist aus. Testen Sie reale Anwendungsfälle und entscheiden Sie nach visuellem Vergleich.
Q5: Was ist der Unterschied zwischen dem Aufruf von Nano Banana Pro über APIYI (apiyi.com) und der Google-API?
APIYI bietet eine einheitliche Authentifizierung im OpenAI-Stil (Bearer Token), einen aus dem Inland erreichbaren Endpunkt und eine zentrale Abrechnung. Das Protokoll selbst entspricht exakt dem nativen Gemini-Format. Das bedeutet, dass imageConfig / aspectRatio / responseModalities aus der Google-Doku bei APIYI identisch funktionieren.
Q6: Warum erhalte ich trotz imageSize: "2K" nur 1K?
Die 3 häufigsten Gründe: (1) Verwendung eines SDKs, das unbekannte Felder filtert, (2) Feldname fälschlicherweise als image_size geschrieben, (3) falsche Verschachtelungsebene in generationConfig. Prüfen Sie den tatsächlichen Netzwerk-Request, um sicherzustellen, dass der Body den Spezifikationen entspricht, bevor Sie den Server-Code debuggen.
Q7: Was tun bei 429-Rate-Limiting?
Implementieren Sie ein exponentielles Backoff (3s/6s/12s). Wenn Ihre Anwendung latenzempfindlich ist, können Sie im APIYI-Arbeitsbereich zwischen Gruppen wechseln oder ein höheres Kontingent beantragen. Vermeiden Sie Endlosschleifen mit sofortigen Wiederholungen, da dies zu einer dauerhaften Drosselung führt.
Q8: Gibt es ein Limit für die Anzahl der Eingabebilder?
Die Gemini 3 Image-Schnittstelle begrenzt die Gesamtgröße der Bilder pro Anfrage (meist in MB, siehe offizielle Doku). Wir empfehlen maximal 4-5 Referenzbilder, die jeweils auf eine angemessene Größe skaliert wurden (erst resizen, dann Base64), um 413-Fehler oder Timeouts zu vermeiden.
Zusammenfassung: Die "Zwei-Parameter-Methode für die Auflösung" verinnerlichen
Wenn Sie sich nur einen einzigen Satz merken wollen, dann diesen:
Die endgültige Ausgabeauflösung von Nano Banana Pro =
imageConfig.imageSize×imageConfig.aspectRatio. Übergeben Sie keinesfalls mehr das OpenAI-typischesize-Feld.
Vollständige Checkliste:
- ✅ Modellname:
gemini-3-pro-image-preview - ✅ Endpunkt:
/v1beta/models/.../generateContent - ✅
generationConfig.imageConfig.imageSize∈512/1K/2K/4K - ✅
generationConfig.imageConfig.aspectRatio∈1:1/16:9/9:16/4:3/3:4/21:9/ … - ✅
generationConfig.responseModalitiesmuss"IMAGE"enthalten - ✅ Eingaben mit mehreren Bildern gehören in das
parts-Array, der Text-Prompt kommt zuletzt - ✅ Bei 429-Rate-Limiting exponentielles Backoff verwenden (3s/6s/12s)
- ❌ Übergeben Sie kein
size: "1024x1024" - ❌ Schreiben Sie nicht
image_size/aspect_ratio(snake_case ist hier falsch) - ❌ Verlassen Sie sich nicht auf alte SDKs, die unbekannte Felder ignorieren; prüfen Sie den Datenverkehr (Sniffing) zur Bestätigung
📢 Ein letzter Hinweis: Wenn Sie Nano Banana Pro über APIYI (apiyi.com) anbinden, kopieren Sie einfach die in diesem Artikel bereitgestellten Code-Vorlagen für cURL, Python oder Node.js. Alle Parameter entsprechen strikt dem nativen Gemini-Protokoll: Kopieren & Einfügen → API-Schlüssel anpassen → Fertig.
Autor: APIYI Team · Kontinuierliche Zusammenstellung bewährter Methoden für den Aufruf von KI-Großsprachmodellen · apiyi.com
