Wie verwende ich die Nano Banana 2 API? In 5 Minuten zum ersten Bild

TL;DR

• Was ist das: Nano Banana 2 von Google – Text-zu-Bild und Referenzbild-Bearbeitung teilen sich eine Modell-ID nano-banana-2, pro Anfrage bis zu 14 Referenzbilder. Bereits auf HiAPI verfügbar, Modellseite öffnen, Prompt eingeben und generieren – neue Nutzer erhalten bei Registrierung 200 Credits.
• Was kostet es: Abrechnung pro Bild, 1K $0.036, 2K $0.057, 4K $0.086, Referenzbilder ohne Aufpreis, bei Fehlern automatische Rückerstattung.
• Wie ruft man die API auf: POST https://api.hiapi.ai/v1/tasks, model auf nano-banana-2 setzen, nach Erhalt der taskId abfragen oder auf den Callback warten, dann data.output[0].url herunterladen.

Was kann Nano Banana 2?

• Ein Modell, zwei Verwendungsarten. Nur mit Prompt ist es Text-zu-Bild, mit image_input wird daraus Referenzbild-Bearbeitung – kein Wechsel von Schnittstelle oder Modus nötig.
• Bis zu 14 Referenzbilder pro Anfrage. Produktbilder aus mehreren Winkeln, Modelbilder und Szenenbilder gemeinsam übergeben – ideal für gleiches Motiv in neuer Szene, Outfit-Wechsel und Marken-Bilderserien.
• 14 feste Seitenverhältnisse plus auto. Neben den gängigen 1:1, 4:5, 16:9, 21:9 gibt es auch 1:4, 4:1, 1:8, 8:1; bei Unsicherheit das Standard-auto verwenden.
• Drei Stufen: 1K, 2K, 4K. 1K zum Ausprobieren von Prompts, 2K und 4K für das finale Bild; Standardausgabe ist PNG.

Das folgende Bild ist ein Beispiel von der Nano-Banana-2-Modellseite, 4:3, 1K:

A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography, 4:3

Mit diesem Prompt generieren →

Zwei Einstiegswege: Online-Test oder API?

Zum Ausprobieren wählen Sie den Online-Test, zur Integration ins Produkt die API. Beide Wege nutzen dasselbe Modell und dieselbe Preisstruktur.

Online-Test (ca. 1 Minute)

1. Öffnen Sie die Nano-Banana-2-Modellseite oder direkt den Link unter dem obigen Bild – der Prompt wird automatisch eingefügt.
2. Registrieren oder anmelden, neue Konten erhalten 200 Credits.
3. Seitenverhältnis und Auflösung wählen, zum regulären Preis kostet 1K 72 Credits pro Bild.
4. Auf Generieren klicken, bei Zufriedenheit herunterladen.

API-Integration (ca. 5 Minuten)

1. Im HiAPI-Konsolenbereich einen API-Key erstellen (sk-...).
2. POST /v1/tasks zum Erstellen der Aufgabe aufrufen und aus der Antwort data.taskId entnehmen.
3. Mit GET /v1/tasks/{id} abfragen oder im Request-Body callback.url mitgeben und auf die Benachrichtigung warten.
4. Sobald data.status auf success steht, das Bild von data.output[0].url herunterladen.

1K kostet $0.036 pro Bild, für $10 erhält man etwa 277 Bilder – genug, um Prompts in Ruhe abzustimmen. Alle Parameter finden Sie in der chinesischen Dokumentation.

Das erste Bild: curl-Version

Aufgabe erstellen:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography",
      "aspect_ratio": "4:3",
      "resolution": "1K",
      "output_format": "png"
    }
  }'

Die zurückgegebene Task-ID steht in data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Ergebnis abfragen:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Pflicht ist nur prompt. aspect_ratio ist standardmäßig auto, resolution standardmäßig 1K, output_format standardmäßig png (optional jpg).

Das erste Bild: Python-Version

Installieren Sie zuerst requests (python3 -m pip install requests) und setzen Sie im Terminal HIAPI_API_KEY (export HIAPI_API_KEY="sk-YOUR_KEY"). Das folgende Beispiel erstellt eine Aufgabe, fragt bis zu 10 Minuten lang ab und lädt dann das Bild herunter; nach Timeout behalten Sie die taskId und fragen weiter ab:

import os
import time
import uuid
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
HEADERS["Idempotency-Key"] = str(uuid.uuid4())  # Save with this business task before submitting.

payload = {
    "model": "nano-banana-2",
    "input": {
        "prompt": "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography",
        "aspect_ratio": "4:3",
        "resolution": "1K",
        "output_format": "png",
    },
}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


task_id = task_data(requests.post(API, headers=HEADERS, json=payload, timeout=30))["taskId"]
print(f"taskId: {task_id}", flush=True)  # Save this ID for later queries.

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    task = task_data(requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30))
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        with open("nano-banana-2.png", "wb") as f:
            f.write(image.content)
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task {task_id} failed: {task}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")

Referenzbild-Bearbeitung: image_input hinzufügen genügt

Fügen Sie in input ein image_input hinzu, und dieselbe Anfrage wird zur Bearbeitung. Im Folgenden wird ein Produktbild einer Serumflasche vor weißem Hintergrund auf eine Badezimmerablage gestellt:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "Place this exact serum bottle, unchanged, on a white marble bathroom counter next to a folded beige linen towel, soft warm morning window light",
      "image_input": ["https://static.hiapi.ai/blog/nano-banana-ecommerce-product-images-hiapi/shot-1-listing.jpg"],
      "aspect_ratio": "4:3",
      "resolution": "1K"
    }
  }'

image_input ist ein URL-Array mit maximal 14 Einträgen; es müssen öffentlich direkt erreichbare Bildlinks sein, SVG wird nicht unterstützt. Schreiben Sie im Prompt klar, was erhalten bleiben soll (this exact serum bottle, unchanged) – dann bleiben Produktetikett und Flaschenform stabiler. Die vollständigen Prompts und Ergebnisbilder für diese Szenenwechsel mit gleichem Motiv finden Sie im Nano-Banana-2-Prompt-Leitfaden.

Drei Dinge vor dem Go-Live

1. Auf dem Server Callbacks verwenden. Fügen Sie auf oberster Ebene des Request-Bodys "callback": {"url": "https://yourapp.com/webhook", "when": "final"} hinzu – die Aufgabe wird automatisch benachrichtigt; sowohl Erfolg als auch Fehler werden gecallt, dedupliziert wird nach taskId.
2. Bei Wiederholungen Idempotenz-Key mitgeben. Jeder POST /v1/tasks erstellt standardmäßig eine neue Aufgabe und wird separat berechnet. Fügen Sie den Header Idempotency-Key hinzu, erzeugen und speichern Sie einen Key für dieselbe fachliche Aufgabe; bei Netzwerk-Timeout wiederholen Sie mit demselben Konto, demselben Key und exakt demselben Request-Body – die Aufgabe wird nur einmal erstellt.
3. Nach Erhalt des Ergebnisses zuerst herunterladen. Ausgabelinks haben eine Gültigkeitsdauer; speichern Sie das Bild zuerst im eigenen Storage und führen Sie danach die Weiterverarbeitung aus.

Häufige Fehler, einer pro Zeile

• 400 additional properties ... not allowed → Feldname falsch geschrieben oder Feld eines anderen Modells verwendet (z. B. image_urls von Nano Banana 2 Lite, oder size) → auf image_input, resolution ändern.
• 400, aspect_ratio-Wert ungültig → Seitenverhältnis außerhalb der Liste übergeben → eines der 15 gültigen Werte wählen.
• 401 permission_denied → Key fehlt, falsch geschrieben oder widerrufen → Header Authorization: Bearer sk-... prüfen und bei Bedarf in der Konsole neu erstellen.
• 402 → Guthaben reicht nicht, Aufgabe wurde nicht erstellt und es wird nichts berechnet → nach Aufladen erneut versuchen.
• Aufgabe status ist fail → Anfrage gemäß zurückgegebenem error anpassen, nicht unverändert wiederholen; der vorab einbehaltene Betrag wird automatisch vollständig zurückerstattet.

Häufige Fragen

Wie schreibe ich die Modell-ID? Schreiben Sie nano-banana-2. Die Parameternamen sind identisch mit Nano Banana 2.1; mit gemini-nano-banana-2.1 wechseln Sie auf 2.1.

Kosten Referenzbilder extra? Nein. Der Preis hängt nur von der Ausgabauflösung ab – ob 1 oder 14 Referenzbilder übergeben werden, ist gleich.

Wie viele Bilder pro Anfrage? Eine Aufgabe erzeugt ein Bild. Für mehrere Bilder erstellen Sie mehrere Aufgaben parallel – Abrechnung pro Bild.

Wie erhalte ich den Aktionspreis? Ohne Codeänderung. Zum Programmierer-Tag 50 % Rabatt bis 2026-11-09 00:00 Uhr Pekinger Zeit; API und Online-Test werden automatisch mit 50 % Rabatt berechnet, 1K kostet $0.018 pro Bild.

Nano-Banana-2-Artikelserie

• Nano-Banana-2-Modellseite: online generieren, bei Registrierung 200 Credits gratis
• Was kostet die Nano-Banana-2-API: Stückpreise für 1K/2K/4K und Monatsbudget
• GPT Image 2.5 vs Nano Banana 2: 9 Bilder mit demselben Prompt im Vergleich
• Nano-Banana-2-Prompt-Sammlung: 5 Szenarien zum direkten Kopieren und Generieren
• Nano-Banana-2.1-API-Preise: wie viel günstiger als NB 2
• Nano-Banana-Pro-API-Preise: was kostet ein Bild
• Chinesische Nano-Banana-2-Integrationsdokumentation: alle Parameter

Jetzt ausprobieren: Klicken Sie unter dem obigen Regenwald-Bild auf Mit diesem Prompt generieren → – der Prompt ist bereits eingefügt, wählen Sie 4:3 und 1K, starten Sie und laden Sie das Ergebnis herunter, zum regulären Preis von $0.036 pro Bild.