So verwenden Sie Nano-Banana-2-Lite über die HiAPI-API: curl, Python und eine funktionierende Anfrage

Was Nano-Banana-2-Lite ist und wann man es einsetzt

Nano-Banana-2-Lite ist die besonders kostengünstige Stufe innerhalb der Nano-Banana-Familie auf HiAPI. Sie richtet sich an Szenarien der Bildgenerierung mit hoher Parallelität und Kostenempfindlichkeit, in denen vorhersehbare Ausgaben und schnelle Iteration wichtiger sind als maximale Detailtreue. Wenn Sie ein Feature prototypisieren, Thumbnails oder Varianten in großem Umfang erzeugen oder Hintergrundaufgaben ausführen, die ein schlankeres Modell tolerieren, ist diese Stufe der passende Einstiegspunkt.

Verwenden Sie sie, wenn die Ausgabe nur ein Glied einer größeren Pipeline ist: Entwurfsvisualisierungen, Platzhalterbilder, Batch-Experimente oder A/B-Tests, bei denen Sie viele Kandidaten zu geringen Kosten benötigen. Für finales Key-Visual-Material oder Szenarien, die höchste Detailtreue erfordern, wechseln Sie zu einer größeren Stufe. Die API-Schnittstelle bleibt gleich, sodass Sie die Integration nicht neu schreiben müssen, um das Modell zu wechseln.

Voraussetzungen und Aufbau der Anfrage

Bevor Sie Nano-Banana-2-Lite aufrufen, stellen Sie sicher, dass Sie Folgendes haben:

• Ein HiAPI-Konto und einen API-Schlüssel. Bewahren Sie ihn in einer Umgebungsvariablen auf, etwa HIAPI_API_KEY; committen Sie ihn niemals in die Versionsverwaltung.
• Ein Terminal mit curl für den ersten Test sowie Python 3.8+ und die Bibliothek requests für die Skriptversion.
• Einen Prompt, der das gewünschte Bild beschreibt. Beginnen Sie einfach; Referenzeingaben können später ergänzt werden.

Jede Anfrage an HiAPI folgt demselben Aufbau: ein POST mit einem JSON-Body an den Modellendpunkt senden. Der Body enthält den Modellnamen, den Prompt sowie alle optionalen Parameter. Da die Generierung asynchron erfolgt, liefert der Übermittlungsaufruf eine Aufgaben-ID zurück, die Sie anschließend abfragen. Die Antwort ist JSON; Fehler enthalten einen Statuscode und eine Meldung, die Sie protokollieren können.

Ihr Payload muss mindestens model auf nano-banana-2-lite setzen und einen prompt bereitstellen. Optionale Felder wie reference_images und Ausgabeeinstellungen werden in den folgenden Abschnitten behandelt.

Eine funktionierende curl-Anfrage

Das Folgende ist ein vollständiges, direkt kopierbares Beispiel zum Übermitteln einer einfachen Aufgabe. Ersetzen Sie den Platzhalter-Prompt durch Ihren eigenen Inhalt.

curl -X POST https://api.hiapi.ai/v1/images/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1"
  }'

Die Antwort enthält die Aufgaben-id und ein Feld status. Neu übermittelte Aufgaben liefern üblicherweise queued oder processing. Speichern Sie die id; Sie benötigen sie im Abfrageschritt. Wenn Sie 401 erhalten, prüfen Sie, ob HIAPI_API_KEY in Ihrer Shell exportiert wurde. Bei 422 lesen Sie die Fehlermeldung, um das problematische Feld zu finden.

Dieselbe Anfrage in Python senden

Portieren Sie den curl-Aufruf nach Python, um ihn in ein Skript oder einen Dienst einzubetten. Dieses Beispiel verwendet requests und liest den Schlüssel aus einer Umgebungsvariablen.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
print(job["id"], job["status"])

Halten Sie den Request-Body in einem Dictionary, damit Sie ihn später um optionale Felder erweitern können, ohne den Aufruf neu zu schreiben. Ein Timeout von 30 Sekunden ist für den Übermittlungsschritt angemessen, da die eigentliche Arbeit asynchron erfolgt.

Optionale Referenzeingaben hinzufügen

Referenzeingaben ermöglichen es Ihnen, die Generierung mit visuellem Kontext zu lenken. Auf HiAPI fügen Sie sie als Array reference_images im selben JSON-Body hinzu. Jeder Eintrag ist eine öffentlich zugängliche URL oder ein base64-Daten-URI. Verwenden Sie Referenzbilder, wenn Sie die Komposition beibehalten, einen Stil angleichen oder ein Produktbild über mehrere Varianten hinweg konsistent halten möchten.

{
  "model": "nano-banana-2-lite",
  "prompt": "Same layout, but in a warm sunset palette",
  "reference_images": [
    "https://example.com/reference/layout.png"
  ]
}

Fügen Sie Referenzbilder nur dann hinzu, wenn sie tatsächlich nützliche Signale liefern. Jedes Referenzbild sind zusätzliche zu übertragende Daten und kann einen einfachen Prompt verwässern. Bei reinen Text-zu-Bild-Aufgaben lassen Sie das Feld vollständig weg. Wenn Sie Referenzbilder verwenden, halten Sie sie relevant und zahlenmäßig klein; ein oder zwei sorgfältig ausgewählte Bilder übertreffen in der Regel eine große Sammlung.

Asynchrone Ergebnisse abfragen

Die Bildgenerierung ist asynchron: Sie übermitteln eine Aufgabe und fragen dann den Aufgaben-Endpunkt ab, bis der Status einen Endzustand erreicht. Das Muster ist in curl und Python identisch.

Mit curl prüfen Sie die Aufgabe über die Aufgaben-ID:

curl https://api.hiapi.ai/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

In Python verpacken Sie die Abfrage in eine Schleife mit Verzögerung, damit die API nicht zu häufig angefragt wird:

import time

def wait_for_job(job_id, interval=2, max_attempts=30):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    for _ in range(max_attempts):
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError("Job did not finish in time")

Beginnen Sie mit einem kurzen Intervall und erhöhen Sie es schrittweise, wenn Sie viele Aufgaben abfragen. Legen Sie stets eine maximale Anzahl von Versuchen fest, damit eine hängende Aufgabe Ihren Worker nicht dauerhaft blockiert. Behandeln Sie failed als Endzustand und protokollieren Sie die Fehlermeldung.

Ausgabe herunterladen und prüfen

Wenn eine Aufgabe erfolgreich ist, enthält die Antwort eine oder mehrere Ausgabe-URLs. Rufen Sie die Datei ab, speichern Sie sie lokal und prüfen Sie anschließend, was Sie erhalten haben.

result = wait_for_job(job["id"])
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
    img = requests.get(image_url, timeout=60)
    img.raise_for_status()
    with open("output.png", "wb") as f:
        f.write(img.content)

Führen Sie eine grundlegende Prüfung der heruntergeladenen Inhalte durch: Bestätigen Sie, dass der Inhaltstyp ein Bild ist, prüfen Sie, dass die Dateigröße nicht null und plausibel ist, und öffnen Sie sie einmal, um sicherzustellen, dass sie Ihrem Prompt entspricht. Protokollieren Sie die Aufgaben-ID zusammen mit dem lokalen Dateinamen, damit jedes Material bis zu seiner Anfrage zurückverfolgt werden kann.

Checkliste für Kosten und Fehler vor dem Produktivbetrieb

Nano-Banana-2-Lite ist in der besonders kostengünstigen Stufe bepreist; die Abrechnung folgt der standardmäßigen Messung für Bildgenerierung der Plattform. Prüfen Sie die aktuelle Preistabelle auf der Website, um genaue Tarife zu erhalten, statt Annahmen fest zu kodieren.

Bevor Sie live gehen, machen Sie sich folgende Gewohnheiten zu eigen:

• Wiederholungen mit Backoff. Wiederholen Sie vorübergehende Fehler (Timeouts, 5xx) einige Male mit zunehmender Verzögerung; wiederholen Sie 4xx-Validierungsfehler nicht.
• Abfragen begrenzen. Verwenden Sie ein festes Intervall und eine maximale Anzahl von Versuchen. Protokollieren Sie den Endstatus und die Dauer.
• Aufgaben-IDs und Prompts protokollieren. Speichern Sie Aufgaben-ID, Prompt, Modell und alle Referenzeingaben zusammen mit jeder Ausgabe, um Läufe reproduzieren oder prüfen zu können.
• Eingaben früh validieren. Prüfen Sie Prompt-Länge und Referenz-URLs vor der Übermittlung, um verschwendete Aufgaben zu vermeiden.

Mit diesen Prüfungen ist Nano-Banana-2-Lite ein vorhersehbares, kostengünstiges Arbeitstier für Batch- und Hintergrundgenerierung. Besuchen Sie die Modellseite auf HiAPI für die neuesten Parameter- und Tarifdetails.