Nano Banana API-Handbuch: Bildgenerierung und -bearbeitung auf TokenLab

Die Nano Banana API bietet drei kostenpflichtige Modell-IDs auf TokenLab, wobei die günstigste etwa halb so viel pro Bild kostet wie die mittlere. Der teure Fehler ist selten die Wahl des Modells. Er besteht darin, eine Bearbeitungsanfrage an den falschen Endpunkt zu senden oder einen Create-Aufruf zu wiederholen, der bereits eine Aufgabe erstellt hat. Dieses Handbuch behandelt die genauen IDs, einen funktionierenden Text-zu-Bild-Aufruf, einen Referenzbild-Aufruf, asynchrones Polling, erwartete Fehler und wie die Abrechnung festgelegt wird. Preise und Feldlisten wurden am 03.10.2026 eingelesen; bestätigen Sie diese daher erneut, bevor Sie Ihre Anwendung veröffentlichen.

Wichtige Erkenntnisse

• Senden Sie die exakte ID: nano-banana-2, nano-banana-2-lite oder nano-banana-pro. Anzeigenamen sind keine Aliasse für Anfragen.
• Referenzbild-Arbeiten für Nano Banana gehen an POST /v1/images/generations mit operation: "image-to-image" und image_urls. Sie gehen nicht an /v1/images/edits oder /v1/chat/completions.
• Die Basispreise, die wir am 03.10.2026 gelesen haben, liegen bei 0,0168 $, 0,0335 $ und 0,067 $ pro Bild für die Lite-, Standard- und Pro-IDs. Jedes Modell hat eine Preisspanne, prüfen Sie daher die genaue Stufe unter „Usage“.
• Eine Create-Antwort mit task_id, status: "pending" oder poll_url bedeutet, dass Sie GET /v1/tasks/{id} abfragen müssen, bis der Status completed oder failed lautet.
• Ein Status-Lesevorgang gibt HTTP 200 zurück, selbst wenn die Aufgabe fehlgeschlagen ist. Unterscheiden Sie anhand des status-Feldes der Aufgabe, nicht anhand des HTTP-Codes.
• Die endgültigen Gebühren finden Sie unter „Usage“ und in der billing_transaction_id, nicht in einer kopierten Preistabelle.

Nano Banana API-Modelle, Preiseinheiten und Verwendungszweck

Als wir den früheren Entwurf dieses Handbuchs mit der aktuellen Dokumentation verglichen haben, fanden wir drei Probleme. Es wurden Modelle ohne Preise aufgelistet. Es wurde eine Nano-Banana-Bearbeitung über Chat-Completions gesendet. Es wurde der Katalog mit einem Filter abgefragt, den das Bild-Handbuch nicht verwendet. Die folgende Tabelle korrigiert den ersten Punkt. Die späteren Abschnitte korrigieren die anderen beiden.

Modell-ID	Am besten geeignet für	Preiseinheit	TokenLab-Preis (USD)	Quelle, beobachtet
nano-banana-2	Text-zu-Bild und Bild-zu-Bild mit aspect_ratio und resolution (1k, 2k, 4k). Veröffentlicht am 26.02.2026.	per_image	0,0335 $ pro Anfrage. Bereich 0,0225 $ bis 0,0755 $.	Live-Modell-API, 03.10.2026
nano-banana-2-lite	Günstigstes Text-zu-Bild und Bild-zu-Bild. Der von uns gesehene Preiseintrag deckt die 1k-Stufe ab.	per_image	0,0168 $ pro Anfrage. Min. und Max. jeweils 0,0168 $.	Live-Modell-API, 03.10.2026
nano-banana-pro	Text-zu-Bild, Bild-zu-Bild und Bildbearbeitung mit aspect_ratio und resolution.	per_image	0,067 $ pro Anfrage. Bereich 0,067 $ bis 0,12 $.	Live-Modell-API, 03.10.2026
nano-banana	Text-zu-Bild nur mit aspect_ratio. Keine öffentliche resolution-Auswahl.	Nicht in unseren Daten	Überprüfen Sie die Modellseite oder den Preis-Endpunkt	Katalog, 02.10.2026; Create Image-Dokumentation, 03.10.2026

Alle oben genannten Preise enthalten is_lock_price: true und wurden am 02.10.2026 um 16:53:30.068Z aktualisiert. Drei Details sind wichtig, bevor Sie sich für eines entscheiden:

• Auflösungsstufen beeinflussen den Preis. Die Live-API zeigt einen Bereich für nano-banana-2 und nano-banana-pro, aber unsere Daten ordnen nicht jede Stufe einer Auflösung zu. Gehen Sie nicht davon aus, dass 1k der Basispreis ist. Lesen Sie die Preiseinträge für Ihr Modell.
• Textausgabe hat einen eigenen Token-Preis. Sowohl nano-banana-2 als auch nano-banana-pro enthalten einen native-gemini-text-output-Eintrag. Dieser gilt, wenn outputModality auf text gesetzt ist. Für nano-banana-2 sind 0,25 Input und 1,5 Output gelistet. Für nano-banana-pro sind 1 Input und 6 Output gelistet. Die Einheit ist per_token. Bestätigen Sie die Skalierung unter GET /v1/models/:model/pricing, bevor Sie Ihr Budget darauf ausrichten.
• Lite listet kein akzeptiertes Anfrageformat. Der Live-Datensatz für nano-banana-2-lite besagt „nicht gelistet“. Lesen Sie die Details, bevor Sie darauf aufbauen.

Für ein grobes Budget multiplizieren wir den Basispreis mit dem Volumen. Dies sind Schätzungen zum Basispreis, keine Angebote:

• 100 Bilder mit nano-banana-2-lite: 100 × 0,0168 $ = 1,68 $.
• 100 Bilder mit nano-banana-2: 100 × 0,0335 $ = 3,35 $.
• 100 Bilder mit nano-banana-pro: 100 × 0,067 $ = 6,70 $.

Höhere Auflösungsstufen erhöhen diese Zahlen.

Um aktuelle Bildmodelle selbst aufzulisten, rufen Sie den Endpunkt auf, den das Handbuch zur Bilderzeugung verwendet. Der frühere Entwurf verwendete category=image, was im Handbuch nicht dokumentiert ist.

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

Für Operationen, Preise und Lebenszyklus eines Modells verwenden Sie Get a Model. Sie können auch das TokenLab-Modellverzeichnis durchsuchen.

Senden einer Text-zu-Bild-Anfrage mit der Nano Banana API

Erstellen Sie einen API-Schlüssel im TokenLab-Dashboard und exportieren Sie ihn:

export TOKENLAB_API_KEY="your-tokenlab-api-key"

Senden Sie immer das model. Die Create Image-Referenz besagt, dass Bild-APIs kein Standardmodell wählen. Ein fehlendes Modell gibt einen 400-Fehler mit param: "model" zurück.

Diese Anfrage verwendet nur Felder, die in der Dokumentation für Google-Bildfamilien aufgeführt sind. Wir haben resolution auf 1k belassen, da nano-banana-2 die Werte 1k, 2k und 4k dokumentiert.

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  --max-time 120 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A minimalist ceramic vase on a natural wooden table, studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "response_format": "url"
  }'

Das Flag --max-time 120 entspricht der Dokumentation. Dort heißt es, dass hochauflösende Anfragen fast eine Minute oder länger dauern können, setzen Sie also Ihr Client-Timeout auf mindestens 120 Sekunden. Die Dokumentation besagt, dass size ein Kompatibilitäts-Alias für Google-Bildfamilien ist, sie empfehlen jedoch, direkt aspect_ratio zu verwenden.

Ein synchroner Erfolg gibt das fertige Bild inline zurück. Die Platzhalterwerte unten zeigen nur die dokumentierte Form:

{
  "created": 1700000000,
  "data": [
    { "url": "https://example.com/generated-image.png" }
  ]
}

Lesen Sie es in dieser Reihenfolge:

1. Wenn der Body task_id, status: "pending" oder poll_url enthält, haben Sie eine Aufgabe, kein Bild. Gehen Sie zum Abschnitt „Polling“.
2. Andernfalls lesen Sie data[0].url. Bei response_format: "b64_json" lesen Sie stattdessen data[0].b64_json.
3. created ist ein Unix-Zeitstempel. revised_prompt erscheint nur, wenn das Modell einen zurückgibt, fordern Sie ihn also nicht zwingend an.
4. Speichern Sie die Bild-URL, Ihre eigene Job-ID, das Modell und die request_id aus den Antwort-Headern.

Generierte Bild-URLs können 30 Tage lang als Medienkopien aufbewahrt werden. Überprüfen Sie media_retention.items auf den Status jedes Elements und expires_at. Ausstehende oder fehlgeschlagene Kopien sind nicht garantiert; kopieren Sie die Datei daher in Ihren eigenen Speicher, wenn Sie sie länger benötigen. Das Handbuch zur Datenaufbewahrung enthält die Details.

Bildbearbeitung mit einer Referenz-URL

Stellen Sie sich ein Katalogteam vor, das dieselbe Produktaufnahme auf einem sauberen Studiohintergrund möchte. Der verlockende Schritt ist /v1/images/edits. Die Dokumentation schließt dies aus. Nano-Banana-Referenzbildanfragen werden über /v1/images/generations mit operation: "image-to-image" abgewickelt. /v1/images/edits ist nicht der richtige Pfad dafür.

Diese Anfrage stammt aus dem Handbuch zur Bilderzeugung, mit nano-banana-2 als Modell:

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

Regeln, die wir bei dieser Form befolgen:

• Senden Sie genau die dokumentierten Referenzfelder. Verwenden Sie image_url, image_urls oder reference_image_urls im JSON. Senden Sie kein Top-Level images[] oder file_id. Diese gehören zum Edit-Flow und werden an diesem Endpunkt abgelehnt.
• Verwenden Sie öffentliche URLs. Sie müssen http oder https sein, ohne eingebettete Anmeldeinformationen, ohne Fragmente und ohne Hosts in privaten Netzwerken. Vermeiden Sie signierte URLs, die ablaufen könnten, bevor die Verarbeitung beginnt.
• Verwenden Sie Multipart für private Quellen. Die Dokumentation bietet eine Multipart-image-Datei für Quellen, die privat oder Header-geschützt sind.
• Passen Sie resolution an das Modell an. Die Dokumentation besagt, dass nano-banana-pro sie enthalten kann und nano-banana-edit sie weglassen sollte. Die Dokumentation nennt auch nano-banana-edit als Referenzbildmodell, aber diese ID ist nicht in dem Katalog enthalten, den wir am 02.10.2026 abgerufen haben. Überprüfen Sie jede ID gegen /v1/models, bevor Sie sie verwenden.

Das Beispiel für die Bildbearbeitung via Chat-Completions aus dem Quellartikel ist nicht mehr vorhanden. Der Live-Datensatz listet gemini_generate_content als akzeptiertes Format für nano-banana-2 und nano-banana-pro auf. Unsere Daten dokumentieren keinen Pfad für Bildbearbeitung via Chat-Completions.

Maskenbasiertes Inpainting und Parameter wie strength sind in unseren Daten für Nano Banana nicht dokumentiert. Überprüfen Sie GET /v1/models/{model}, bevor Sie diese senden.

Wann eine Bildanfrage zu einer Aufgabe wird und wie man sie abfragt

Ein Bild-Create-Aufruf ist entweder synchron oder asynchron, und die Antwort verrät Ihnen, welcher Typ vorliegt. Das Handbuch für asynchrone Jobs listet die Trigger-Felder auf: task_id, status: "pending" oder poll_url. Wenn eines davon erscheint, ist das data[]-Array leer und die Arbeit läuft noch.

Unsere Daten dokumentieren das async: true-Anfrage-Flag nur für gpt-image-2 und offizielle FLUX/BFL-Bildmodelle. Es ist für die Nano-Banana-IDs nicht dokumentiert. Fügen Sie es nicht zu einer Nano-Banana-Anfrage hinzu. Behandeln Sie eine Aufgabenantwort, falls eine zurückkommt, und prüfen Sie die Modelldetails, wenn Sie asynchrones Verhalten benötigen.

Stellen Sie sich einen Browser-Refresh vor, der den Create-Aufruf nach einer langsamen Antwort erneut sendet. Sie bezahlen nun für zwei Generationen. Die Dokumentation besagt, dass die meisten doppelten Generationen durch diesen Retry entstehen. Befolgen Sie diese Reihenfolge:

1. Speichern Sie IDs sofort. Speichern Sie id oder task_id, poll_url, das Modell, den Endpunkt und Ihre eigene Job-ID. id und task_id sind derselbe Wert.
2. Fragen Sie die URL ab. Verwenden Sie poll_url, wenn vorhanden. Andernfalls rufen Sie die feste Route auf:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

1. Fragen Sie alle 5–10 Sekunden ab. Das Handbuch sagt, dass dies normalerweise für lange Medienjobs ausreicht.
2. Kennen Sie die Status. Sie lauten pending, processing, completed und failed. Eine abgebrochene Aufgabe zeigt failed mit cancelled: true an.
3. Stoppen Sie bei einem terminalen Status. Bei completed lesen Sie data[].url. Asynchrone Bildergebnisse sind nur URLs, niemals b64_json. Bei failed lesen Sie error und error_details.
4. Behandeln Sie Timeouts sicher. Wenn ein Create-Aufruf ein Timeout hat, bevor Sie eine Antwort sehen, prüfen Sie die request_id und suchen Sie nach einer Aufgabe, bevor Sie es erneut versuchen. Wenn Sie eine Aufgaben-ID gespeichert haben, setzen Sie das Polling fort. Wenn ein Status-Polling fehlschlägt, wiederholen Sie dieses Polling mit Backoff und erstellen Sie nicht neu.

Ein Status-Lesevorgang gibt HTTP 200 auch für eine fehlgeschlagene Aufgabe zurück. Fehlgeschlagene Aufgaben können error_details mit status, type, code, message, param und retryable enthalten. Zum Beispiel bedeutet error_details.status: 400 mit param: "size", dass die Anfrage korrigiert werden muss. Es bedeutet nicht, dass das Polling selbst fehlgeschlagen ist. Das Wiederholen einer fehlgeschlagenen Generierung erstellt eine neue Aufgabe und kann eine neue Gebühr verursachen.

Zu erwartende Fehler und Vorgehensweise

Behandeln Sie Fehler anhand des HTTP-Status und des code, niemals anhand der message. Das Handbuch zur Fehlerbehandlung besagt, dass sich die Nachricht ohne Vorankündigung ändern kann. Chat-Completions und Responses verwenden ein error-Objekt im OpenAI-Stil, während Gemini- und Anthropic-Formate ihre eigenen Formen beibehalten. Verwenden Sie nicht denselben Parser für alle TokenLab-APIs.

Status / Code	Mögliche Ursache	Vorgehensweise
400, param: "model"	Kein explizites Modell	Senden Sie model. Listen Sie IDs mit /v1/models?recommended_for=image auf.
400 unsupported field, oder unsupported_parameter	Ein Feld, das das Modell nicht dokumentiert, z. B. resolution bei einem Modell ohne diese Funktion	Entfernen Sie das Feld oder wechseln Sie das Modell. Wiederholen Sie es nicht unverändert.
400 bei einem Referenzbild	Falscher Endpunkt oder eine private/abgelaufene URL	Verwenden Sie /v1/images/generations mit image_urls. Verwenden Sie eine öffentliche, stabile URL.
401 invalid_api_key oder expired_api_key	Fehlender, widerrufener oder abgelaufener Schlüssel	Ersetzen Sie den Schlüssel.
402 insufficient_balance oder quota_exceeded	Guthaben zu niedrig oder Limit des Schlüssels erreicht	Guthaben aufladen, Schlüssel-Limit erhöhen oder ein günstigeres Modell wählen.
403 model_not_allowed	Der Schlüssel darf dieses Modell nicht verwenden	Aktualisieren Sie die Modellliste des Schlüssels.
404 model_not_found	Unbekannte oder nicht verfügbare ID	Lesen Sie /v1/models und verwenden Sie eine aktuelle ID.
413 payload_too_large	Anfrage oder Datei zu groß	Reduzieren Sie den Input.
429 rate_limit_exceeded	Zu viele Anfragen im Zeitfenster	Warten Sie auf Retry-After, dann erneut versuchen.
500–504, all_channels_failed	Dienst- oder Versorgungsproblem	Wiederholen Sie nur, wenn retryable auf true steht. Beachten Sie retry_after und begrenzen Sie die Versuche.

Ein 503 all_channels_failed bedeutet nicht immer einen Ausfall. Wenn retryable auf false steht und retry_after fehlt, gibt es für die Operation in der ausgewählten Delivery-Stufe kein Angebot. Das Wiederholen der Anfrage hilft nicht, prüfen Sie daher zuerst GET /v1/models.

Das Aufgaben-Polling hat eigene Fehler:

• 404 async_task_not_found: die Aufgabe ist abgelaufen oder weg. Prüfen Sie die gespeicherte task_id und poll_url.
• 403 task_not_owned: die Aufgabe gehört zu einem anderen Workspace. Prüfen Sie, zu welchem Workspace der API-Schlüssel gehört.
• Eine abgeschlossene Aufgabe ohne Medien-URL: behandeln Sie sie als fehlgeschlagen. Behalten Sie die IDs und kontaktieren Sie den Support.

Wenn Sie den Support kontaktieren, senden Sie request_id, task_id, billing_transaction_id (falls vorhanden), Endpunkt, Modell, Zeit und Feldnamen. Senden Sie niemals Schlüssel, private Medien oder signierte URLs.

Wie die Gebühr für eine Bildanfrage bestimmt wird

Alle drei kostenpflichtigen Nano-Banana-IDs verwenden die per_image-Einheit, daher ist die Hauptgebühr der per_request-Preis des Modells. Das Abrechnungshandbuch ergänzt die Regeln dazu:

• Ein Ergebnis, eine Gebühr. Jede abgeschlossene Anfrage wird einmal berechnet, für die Lieferoption, die sie produziert hat. TokenLab Verified verwendet öffentliche TokenLab-Preise. Official verwendet die offizielle Preisstufe. Auto versucht zuerst Verified, dann Official.
• Stufen legen die endgültige Zahl fest. Die Live-Preisspannen (0,0225 $ bis 0,0755 $ für nano-banana-2, 0,067 $ bis 0,12 $ für nano-banana-pro) zeigen, dass ein Pauschalpreis nicht jede Anfrage abdeckt. Auflösungsstufen sind wahrscheinlich der Treiber, aber bestätigen Sie dies in den Preiseinträgen des Modells.
• Aufgaben reservieren zuerst. Eine asynchrone Aufgabe kann bei Annahme ihre geschätzten Kosten reservieren. Eine abgeschlossene Aufgabe wird einmal berechnet, und eine fehlgeschlagene Aufgabe gibt den ausstehenden Betrag frei oder erstattet ihn. Das Abrechnungshandbuch besagt, dass eine fehlgeschlagene Aufgabe nicht berechnet wird.
• Ein Bindestrich ist nicht kostenlos. Auf der Modellseite bedeutet ein Bindestrich in der TokenLab-Preisspalte, dass derzeit kein Verified-Angebot verfügbar ist.

Um eine Gebühr zu bestätigen, verwenden Sie diese Orte:

1. GET /v1/models/:model/pricing oder die Pricing API für den aktuellen Preis.
2. Konsole, die die maximale Schätzung anzeigt, bevor Sie die kostenpflichtige Generierung bestätigen.
3. Usage für die endgültige Gebühr pro Modell.
4. billing_transaction_id in der Antwort oder Aufgabe sowie den X-Billing-Transaction-ID-Header. Streaming und einige native Formate zeigen dies möglicherweise nur im Header an.

Wenn Usage die endgültige Gebühr oder den freigegebenen Betrag nach Abschluss einer Aufgabe nicht anzeigt, senden Sie die Request-ID und Aufgaben-ID an support@tokenlab.sh. Kopieren Sie die Preise in diesem Artikel nicht in Ihren Code. Das Abrechnungshandbuch besagt, dass Sie den aktuellen Preis lesen sollten, wenn Ihre Anwendung Kosten anzeigen oder vergleichen muss.

FAQ

Welche Nano-Banana-Modell-ID sollte ich für Bild-zu-Bild-Anfragen senden?

Die Live-Datensätze listen image-to-image für nano-banana-2, nano-banana-2-lite und nano-banana-pro. Die Dokumentation nennt auch nano-banana-edit, aber diese ist nicht in dem Katalog enthalten, den wir am 02.10.2026 abgerufen haben. Senden Sie die ID mit operation: "image-to-image" und image_urls an /v1/images/generations. Führen Sie einen kleinen Test mit Ihren eigenen Bildern durch, da unsere Daten keinen Qualitätsvergleich enthalten.

Warum hat meine Bildanfrage eine task_id anstelle eines Bildes zurückgegeben?

Der Create-Aufruf wurde als asynchrone Aufgabe ausgeführt. Suchen Sie in der Antwort nach task_id, status: "pending" oder poll_url. Speichern Sie diese Felder und fragen Sie dann poll_url oder GET /v1/tasks/{id} alle 5–10 Sekunden ab, bis der Status completed oder failed lautet. Senden Sie keine zweite Create-Anfrage, während Sie warten.

Kann ich eine Base64-Ausgabe von einem Nano-Banana-Modell erhalten?

Das Feld response_format akzeptiert url oder b64_json, und eine synchrone Anfrage kann data[].b64_json zurückgeben. Asynchrone Bildergebnisse sind nur URLs, unabhängig vom angeforderten Format. Überprüfen Sie die Details des ausgewählten Modells, um zu bestätigen, dass es b64_json akzeptiert, da die Felder je nach Modell variieren.

Wird eine fehlgeschlagene Bildaufgabe berechnet?

Das Abrechnungshandbuch besagt, dass eine fehlgeschlagene Aufgabe nicht berechnet wird und jede ausstehende Reservierung freigegeben oder erstattet wird. Das Wiederholen einer fehlgeschlagenen Generierung erstellt eine neue Aufgabe und kann eine neue Gebühr verursachen. Bestätigen Sie das Ergebnis unter „Usage“ mithilfe der billing_transaction_id und task_id.

Erstellen Sie einen Schlüssel im TokenLab-Dashboard, senden Sie die oben genannte Text-zu-Bild-Anfrage mit nano-banana-2-lite und überprüfen Sie die Gebühr unter „Usage“.