So verwendest du die Nano Banana 2 Lite API: curl, Python und eine lauffähige Anfrage

Nano-Banana-2-Lite ist die kostengünstige Variante der Nano-Banana-Bildmodellfamilie auf hiapi: Sie nutzt denselben aufgabenbasierten Workflow wie ihre größeren Geschwister, kostet aber weniger pro Bild und unterstützt sowohl Text-zu-Bild als auch Bearbeitung mit Referenzbildern. Diese Anleitung führt dich durch einen vollständigen, lauffähigen Integrationsablauf – Aufgabe erstellen, Aufgabe abfragen, Ergebnis herunterladen – demonstriert in curl und Python, und erklärt die Schema-Details, in denen es sich von Nano-Banana-2 und Nano-Banana-Pro unterscheidet.

Was du baust und was du vorbereiten musst

Ziel: einen Prompt an Nano-Banana-2-Lite senden, auf die Bilderzeugung warten und das Bild auf der Festplatte speichern.

Du brauchst nur eine Sache: einen hiapi API-Key (sk-...). Den bekommst du in deinem hiapi dashboard. Die Kosten pro Bild findest du auf der pricing page und auf der Nano Banana 2 Lite Modellseite.

Alle Bildmodelle auf hiapi laufen über die einheitliche Async-Task-API: Du erstellst eine Aufgabe mit POST /v1/tasks und fragst dann entweder GET /v1/tasks/{id} ab oder erhältst einen Webhook, wenn die Aufgabe abgeschlossen ist.

Minimale lauffähige Anfrage (curl)

Aufgabe erstellen:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Nano-Banana-2-Lite",
    "input": {
      "prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
      "aspect_ratio": "3:2"
    }
  }'

Die Task-ID in der Antwort steht unter data.taskId. Frage sie ab:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Wenn data.status gleich "success" ist, steht die Bild-URL unter data.output[0].url. Lade sie sofort herunter – Ausgabe-URLs sind signiert und laufen ab (expireAt), speichere also die Bytes, nicht den Link.

Zwei Schema-Regeln, in die man leicht hineintappt, direkt aus der Validierung der API selbst:

• Die Modell-ID ist groß-/kleinschreibungssensitiv. "model": "nano-banana-2-lite" gibt 400 MODEL_UNAVAILABLE zurück ("model not available via /v1/tasks"). Verwende die exakte ID Nano-Banana-2-Lite.
• prompt und aspect_ratio sind beide Pflichtfelder. Wenn eines davon fehlt, erhältst du 400 INVALID_REQUEST mit der Meldung missing required field. Gültige aspect_ratio-Werte: auto, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1.

Derselbe Ablauf in Python

Kein SDK nötig – die Task-API ist reines JSON über HTTPS:

import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

# 1. Aufgabe erstellen
resp = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json={
        "model": "Nano-Banana-2-Lite",
        "input": {
            "prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
            "aspect_ratio": "3:2",
        },
    },
    timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Abfragen, bis die Aufgabe einen Endzustand erreicht
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(
        f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30
    ).json()["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} did not finish in 10 minutes")

# 3. Sofort herunterladen – Ausgabe-URLs sind signiert und laufen ab
image_url = task["output"][0]["url"]
with open("lighthouse.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved lighthouse.png")

Bearbeitung mit Referenzbildern: image_urls, nicht image_input

Nano-Banana-2-Lite unterstützt Bildbearbeitung, aber sein Referenzbild-Feld ist image_urls – ein Array mit bis zu 10 öffentlich zugänglichen URLs:

{
  "model": "Nano-Banana-2-Lite",
  "input": {
    "prompt": "Replace the background with a clean white studio backdrop, keep the product unchanged",
    "aspect_ratio": "auto",
    "image_urls": ["https://your-cdn.com/product-photo.jpg"]
  }
}

Das ist die häufigste Stolperfalle in dieser Familie: Nano-Banana-2 und Nano-Banana-Pro verwenden image_input für denselben Zweck, während Lite dieses Feld ablehnt (additional properties 'image_input' not allowed). Feldnamen wie input_urls, images oder reference_images werden bei allen drei Modellen abgelehnt. Wenn du Code zwischen den Tiers verschiebst, ist die einzige nötige Änderung in der Regel genau diese Feldumbenennung.

Lite vs. Nano-Banana-2 vs. Pro: die wichtigen Schema-Unterschiede

	Nano-Banana-2-Lite	Nano-Banana-2	Nano-Banana-Pro
Pflichteingaben	prompt, aspect_ratio	prompt	prompt
Referenzbilder	image_urls (≤10)	image_input	image_input
resolution-Steuerung	Nicht akzeptiert	Akzeptiert	Akzeptiert

Lite hält die Schnittstelle bewusst minimal: Prompt, Seitenverhältnis, optional Referenzbilder. Es gibt kein resolution, seed, n oder negative_prompt – wenn du eines davon sendest, schlägt die Validierung mit additional properties ... not allowed fehl. Wenn du explizite Auflösungskontrolle (1K/2K/4K) oder ein Tier mit höherer Detailtreue brauchst, wechsle zu Nano-Banana-2 oder Nano-Banana-Pro; wenn du in großem Umfang generierst – Thumbnails, Entwürfe, Iterationsschleifen, Massenvarianten – sind die niedrigeren Kosten pro Bild von Lite genau der Punkt.

Absicherung für die Produktion

Verwende nach Möglichkeit Webhooks statt Polling. Füge beim Erstellen der Aufgabe einen callback-Block hinzu, und hiapi sendet das Endergebnis per POST an deinen Endpoint:

{
  "model": "Nano-Banana-2-Lite",
  "input": { "prompt": "...", "aspect_ratio": "1:1" },
  "callback": { "url": "https://your-app.com/webhooks/hiapi", "when": "final" }
}

when akzeptiert nur "final" – du erhältst genau einen Callback, egal ob Erfolg oder Fehler. Polling eignet sich für Skripte und Notebooks; Callbacks sind für Server besser geeignet, weil du dann keine Polling-Schleifen und Timeouts verwalten musst. Wenn du doch pollst, reichen ein Intervall von 2–5 Sekunden und eine harte Deadline (wie im Python-Beispiel) aus.

Behandle Fehler auf zwei Ebenen. Fehler auf Anfrageebene werden als HTTP-Fehler zurückgegeben – ein ungültiger oder nicht autorisierter Key liefert 401 mit {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}, Schemafehler liefern 400 INVALID_REQUEST mit der genauen Validierungsmeldung. Fehler auf Aufgabenebene kommen als status: "fail" mit einem error-Objekt an der Aufgabe selbst; behandle in deinem Code beide Pfade.

Mache Wiederholungen idempotent. Das Erstellen von Aufgaben ist nicht idempotent – ein erneuter Versuch einer zeitlich abgelaufenen Erstellungsanfrage kann zwei Aufgaben (und zwei Abrechnungen) erzeugen. Speichere die taskId sofort nach Erhalt und frage nach einem Neustart die bestehende ID weiter ab, statt blind neu zu erstellen.

Speichere Bytes, keine URLs. Ausgabe-URLs laufen ab. Lade das Bild herunter und lege es in deinem eigenen Speicher ab, bevor du irgendetwas anderes damit machst.

Weiterführende Lektüre

• Nano Banana 2 Lite Modellseite — Parameter, Live-Preise, Playground
• GPT Image 2 vs Nano Banana 2: direkter Vergleich mit demselben Prompt
• Charakterkonsistenz mit Nano-Banana auf hiapi wahren
• hiapi Dokumentation und Preise

FAQ

Warum erhalte ich "model not available via /v1/tasks"? Die Modell-ID ist groß-/kleinschreibungssensitiv. Verwende exakt Nano-Banana-2-Lite; die kleingeschriebene Variante wird mit 400 MODEL_UNAVAILABLE abgelehnt.

Unterstützt Nano-Banana-2-Lite Bild-zu-Bild-Bearbeitung? Ja. Übergib Referenzbilder im image_urls-Array (bis zu 10 URLs). Es können Hintergrundersetzung, Stilübertragung und prompt-gesteuerte instruktionsbasierte Bearbeitungsworkflows verarbeitet werden.

Warum schlägt mein Nano-Banana-2-Code bei Lite mit "additional properties 'image_input' not allowed" fehl? Verschiedene Tiers verwenden unterschiedliche Feldnamen für Referenzbilder: Lite erwartet image_urls, während Nano-Banana-2 und Pro image_input erwarten. Benenne das Feld beim Wechsel des Tiers um.

Kann ich resolution, seed oder die Anzahl der Bilder festlegen? Bei Lite nicht – sein Eingabeschema akzeptiert nur prompt, aspect_ratio und image_urls. Für 1K/2K/4K-resolution-Steuerung verwende Nano-Banana-2 oder Nano-Banana-Pro.

Wie lange sind die Ausgabe-Bild-URLs gültig? Es sind signierte URLs mit einem Ablaufzeitstempel (expireAt im Ausgabeobjekt). Lade die Bytes sofort herunter und speichere sie in deinem eigenen Speicher; verlinke niemals direkt auf Aufgabenausgaben.

Was bedeutet 401 permission_denied? Dein API-Key ist ungültig oder er ist für dieses Modell nicht zugelassen. Prüfe den Key in deinem dashboard und stelle sicher, dass du ihn im Format Authorization: Bearer sk-... sendest.

Wie viel kostet Nano-Banana-2-Lite pro Bild? Die Abrechnung erfolgt nutzungsbasiert pro Bild, positioniert als das kostengünstigste Tier der Nano-Banana-Familie. Die aktuellen Preise findest du auf der pricing page.