Benutzerhandbuch

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

4 Schritte zum Online-Testen, 4 Schritte zur API-Integration, mit direkt ausführbarem curl und Python, Beispielen zur Bearbeitung mit Referenzbildern und einer Schnellreferenz für häufige Fehlermeldungen.

Oct 12, 2026

TL;DR

Was ist es: Gemini 3 Pro Image von Google, die Flaggschiff-Stufe der Nano-Banana-Reihe; Text-zu-Bild und Bearbeitung mit Referenzbildern nutzen dieselbe Modell-ID nano-banana-pro. Bereits bei HiAPI verfügbar: Modellseite öffnen, Prompt eingeben und generieren. Neue Nutzer erhalten bei der Registrierung 200 Credits, zum regulären Preis reicht das für 1 Bild in 2K.
Was kostet es: Abrechnung pro Bild, 1K und 2K zum gleichen Preis von $0.057, 4K $0.1, berechnet pro ausgegebenem Bild, etwa 57 %–58 % günstiger als der offizielle Google-Standardpreis, Referenzbilder ohne Aufpreis.
Wie ruft man die API auf: POST https://api.hiapi.ai/v1/tasks, model auf nano-banana-pro setzen, nach Erhalt der taskId abfragen oder auf den Callback warten, dann data.output[0].url herunterladen.

Googles Kosten für Input-Tokens werden separat berechnet; der obige Preisvergleich bezieht sich auf den Preis pro ausgegebenem Bild.

Was kann Nano Banana Pro?

2K ohne Aufpreis. 1K und 2K kosten beide $0.057 pro Bild, direkt in 2K ausgeben; 4K kostet $0.1 pro Bild und ist für Druck und Großbildschirme gedacht.
Text ins Bild schreiben. Kurze englische Sätze wie Schilder, Postertitel oder Daten direkt in den Prompt schreiben; die zwei Zeilen des Goldfolien-Schilds unten werden auf Anhieb korrekt geschrieben, ganz ohne Nachbearbeitung.
Bis zu 8 Referenzbilder. Nur mit Prompt ist es Text-zu-Bild, mit image_input wird daraus Bearbeitung oder Fusion mehrerer Bilder, dieselbe Modell-ID, kein zweiter Code-Satz nötig.
10 Seitenverhältnisse plus auto. Gängige Formate wie 1:1, 4:5, 3:4, 9:16, 16:9, 21:9 sind alle dabei. Für lange Formate wie 1:4 oder 8:1 oder mehr als 8 Referenzbilder auf einmal wähle Nano Banana 2 (bis zu 14 Bilder).

Nano Banana Pro Originalbild, unbearbeitet, Ausgabe 1536×2752.

A hand-painted gold-leaf sign in a modern specialty coffee shop window, elegant serif lettering reading 'MORNING BREW CO.' with a small script subtitle 'est. 2024' beneath it, warm natural daylight streaming through the glass, soft bokeh reflections of a city street, photorealistic commercial photography, crisp perfectly legible typography with correct spelling, shallow depth of field, editorial lighting

Mit diesem Prompt generieren →, Seitenverhältnis 9:16 wählen, Auflösung 2K.

Zwei Wege zum Einstieg: Online testen oder API?

Zum Ansehen zuerst online testen, für die Integration ins Produkt die API. Beide Wege nutzen dasselbe Modell und dieselbe Preisstruktur.

Online testen (ca. 1 Minute)

Öffne die Nano Banana Pro Modellseite oder klicke direkt auf den Link unter dem Schildbild oben, der Prompt wird automatisch eingefüllt.
Registrieren oder anmelden, neue Konten erhalten 200 Credits.
Seitenverhältnis und Auflösung wählen, zum regulären Preis kosten 1K und 2K beide 114 Credits pro Bild.
Auf Ausführen klicken, bei Gefallen herunterladen.

API-Integration (ca. 5 Minuten)

Im HiAPI-Konsole einen API-Key erstellen (sk-...).
POST /v1/tasks zum Erstellen einer Aufgabe, in der Antwort erhältst du data.taskId.
Mit GET /v1/tasks/{id} abfragen oder im Request callback.url mitgeben und auf die Benachrichtigung warten.
Sobald data.status zu success wird, das Bild von data.output[0].url herunterladen.

2K kostet $0.057 pro Bild, mit $10 erhältst du etwa 175 Bilder. Zum Programmierer-Tag zeitlich begrenzt 50 % Rabatt bis 2026-11-09 00:00 Uhr Peking-Zeit, in diesem Zeitraum kosten 1K und 2K $0.0285 pro Bild, mit denselben $10 etwa 350 Bilder. Vollständige Parameter findest du 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-pro",
    "input": {
      "prompt": "Minimalist studio product photography, matte-black earbuds case on a warm gradient backdrop, three-point studio lighting",
      "aspect_ratio": "16:9",
      "resolution": "2K",
      "output_format": "png"
    }
  }'

Die zurückgegebene Aufgaben-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"

Nur prompt ist erforderlich. aspect_ratio ist standardmäßig auto, resolution standardmäßig 1K, output_format standardmäßig png, alternativ jpg. 1K und 2K kosten gleich viel, daher empfiehlt es sich, bei jeder Anfrage "resolution": "2K" anzugeben.

Das erste Bild: Python-Version

Zuerst requests installieren (python3 -m pip install requests) und im Terminal HIAPI_API_KEY setzen (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 dem Timeout bleibt die taskId erhalten, um weiter abzufragen:

import os
import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "nano-banana-pro",
    "input": {
        "prompt": "Minimalist studio product photography, matte-black earbuds case on a warm gradient backdrop, three-point studio lighting",
        "aspect_ratio": "16:9",
        "resolution": "2K",
        "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-pro.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")

Bearbeitung mit Referenzbild: ein zusätzliches Feld genügt

Füge im input image_input hinzu, und derselbe Request wird zur Bearbeitung. Unten dient ein von Nano Banana Pro generiertes Wissenschaftsmuseum-Poster als Referenzbild, nur die Datumszeile wird geändert:

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-pro",
    "input": {
      "prompt": "Keep this exact poster: layout, planet, observatory, visitor, colors and headline. Change only the date line to SAT 24 OCT in the same typography and color. No other words.",
      "image_input": ["https://static.hiapi.ai/blog/gpt-image-2-vs-nano-banana-pro/0dba86ff979d-nano-pro-science.png"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

image_input nimmt bis zu 8 öffentliche URLs auf, unterstützt werden JPEG, PNG, WebP. Im Prompt „Was ändern“ und „Was beibehalten“ getrennt schreiben; je konkreter die Beibehaltungspunkte, desto stabiler bleibt das Originalbild.

3 Dinge vor dem Livegang beachten

Serverseitig Callback verwenden. Auf oberster Ebene des Request-Bodys "callback": {"url": "https://yourapp.com/webhook", "when": "final"} hinzufügen, um bei Aufgabenende automatisch benachrichtigt zu werden, das spart Polling; Callbacks können mehrfach eintreffen, per taskId deduplizieren.
Bei Timeout nicht erneut POSTen. Jedes POST /v1/tasks erstellt eine neue Aufgabe und wird separat berechnet. Speichere zuerst die taskId und dedupliziere vor einem erneuten Versuch in deinem eigenen System.
In jeder Anfrage resolution explizit angeben. Der Standard ist 1K, 2K kostet gleich viel, bei der Finalisierung kannst du direkt 2K wählen; 4K hat einen höheren Stückpreis und wird nur für die Auslieferung verwendet.

Häufige Fehlermeldungen, eine pro Zeile

400, Meldung Feld nicht erlaubt → Feldname falsch geschrieben oder ein Feld eines anderen Modells verwendet (z. B. image_urls) → zu image_input ändern.
400, Meldung aspect_ratio ungültiger Wert → Seitenverhältnis außerhalb der Liste verwendet (z. B. 8:1) → eines der 10 Seitenverhältnisse oder auto wählen, für lange Formate Nano Banana 2 verwenden.
401 → Key fehlt, falsch geschrieben oder widerrufen → Request-Header Authorization: Bearer sk-... prüfen, bei Bedarf in der Konsole einen neuen Key erstellen.
Erstellung erfolgreich, Aufgabe jedoch fail → Fehler der Aufgabe einsehen; falls das Referenzbild nicht ladbar oder das Format nicht unterstützt wird, durch ein öffentlich erreichbares JPEG, PNG oder WebP ersetzen und erneut senden.
Bildlink nach Ablauf nicht mehr ladbar → Ausgabelinks haben eine Gültigkeitsdauer → nach Erhalt des Ergebnisses sofort herunterladen und die Datei selbst speichern.

Fehlgeschlagene Aufgaben werden nicht berechnet.

Häufige Fragen

Wie wähle ich zwischen Nano Banana Pro und Nano Banana 2? FÜR 2K sind beide gleich teuer, $0.057 pro Bild. Für lange Formate oder mehr als 8 Referenzbilder wähle Nano Banana 2; für Key-Visuals von Marken in der Flaggschiff-Stufe der Nano-Banana-Reihe wähle Pro.

Werden Referenzbilder extra berechnet? Nein. Der Preis hängt nur von der Ausgabeauflösung ab, ob 1 oder 8 Referenzbilder übergeben werden, ist gleich.

Kann ich direkt von Nano Banana 2 wechseln? Ja. Die Feldnamen sind gleich (prompt, image_input, aspect_ratio, resolution, output_format), setze einfach model auf nano-banana-pro; das Seitenverhältnis muss nur unter den von Pro unterstützten 10 liegen.

Wie viele Bilder pro Aufruf? Eine Aufgabe liefert ein Bild. Für mehrere Bilder mehrere Aufgaben parallel erstellen, Abrechnung pro Bild.

Artikel zur Nano Banana Pro Reihe

Jetzt testen: Klicke oben unter dem Schildbild auf Mit diesem Prompt generieren →, der Prompt ist bereits eingefüllt, wähle 9:16, 2K, ersetze den Text in Anführungszeichen durch deinen eigenen Ladenname und führe es aus.

TagsBildgenerierung api-guide API-Zugriff Tutorial