Blog

Tutorial

So verwenden Sie nano-banana-2 über die HiAPI-API: verfügbare curl- und Python-Requests-Beispiele

Ein Entwicklerleitfaden, der Ihnen zeigt, wie Sie nano-banana-2 in Ihre Bildgenerierungs-Pipeline integrieren

Nov 12, 2026
Minimalistisches Titelbild: Auf einem warmen Sandton sind horizontale Treppenbänder in Terrakotta und Braun wie ein Quecksilberbalkendiagramm nach unten versetzt angeordnet.
Auf dieser Seite

Was nano-banana-2 für Sie tun kann und wann Sie es einsetzen sollten

nano-banana-2 ist ein Bildgenerierungsmodell, das über eine HTTP-API aufgerufen wird. Sie senden einen Prompt, optional mit einem Quellbild, und erhalten ein generiertes Bild zurück. Das ist das gesamte mentale Modell, das Sie benötigen, bevor Sie Code schreiben.

nano-banana-2 sollten Sie einsetzen, wenn Sie Bilder programmatisch in einem bestehenden Produkt oder einer Pipeline generieren müssen, statt über ein Chat-Fenster zu arbeiten: die Erstellung von Marketingmaterial, Thumbnails und Covern, iterative Änderungen auf Basis eines Ausgangsbilds oder Batch-Aufgaben, bei denen die Bildanzahl von Ihren eigenen Daten gesteuert wird. Da seine Schnittstelle eine gewöhnliche Request/Response-API ist, können Sie es hinter einem Queue-Worker, einem Backend-Endpunkt oder einem CLI-Tool platzieren, ohne für jede Sprache ein neues SDK einführen zu müssen.

Zwei Modi decken die meisten Anwendungsfälle ab:

  • Text-zu-Bild – Sie beschreiben mit einem Prompt, was Sie möchten, und erhalten ein Bild.
  • Bild-zu-Bild – Sie übergeben ein Quellbild zusammen mit einem Prompt, der die Transformation beschreibt, und erhalten das bearbeitete Bild zurück.

Beide Modi haben dieselbe Request-Form, sodass ein einziger Client-Wrapper (den wir später in diesem Artikel erstellen) beide verarbeiten kann. Wenn Ihre Pipeline ausschließlich aus Text rendert, können Sie das Feld image vollständig ignorieren. Wenn es in Ihrer Pipeline um die Bearbeitung vorhandener Assets geht, ist Bild-zu-Bild Ihr Einstiegspunkt.

Was nano-banana-2 nicht für Sie erledigt: Es verwaltet weder Ihre Wiederholungsversuche, Timeouts, Speicherung noch Idempotenz. Das sind die Teile, die Sie rund um den Aufruf aufbauen – und genau darauf liegt der Schwerpunkt des restlichen Tutorials, denn ein naiver Aufruf von requests.post in einer Schleife ist die häufigste Ursache für „die Demo läuft, aber in der Produktion nicht“.

Bevor Sie die erste Anfrage senden

Vor dem ersten Aufruf benötigen Sie drei Dinge.

1. Plattform-Anmeldedaten

Sie benötigen API-Zugriff von der HiAPI-Plattform sowie die Anmeldedaten, die Ihrem Konto zugewiesen sind. Behandeln Sie sie als geheim: Laden Sie sie aus Umgebungsvariablen oder einem Secret-Manager, und committen Sie sie niemals in ein Repository und fügen Sie sie niemals in Client-Build-Artefakte ein. Jede Anfrage unten liest den Schlüssel aus einer Umgebungsvariable, sodass im Quellcode keine sensiblen Informationen auftauchen.

export HIAPI_API_KEY="your-key-here"

2. Client-Umgebung

Für curl benötigen Sie lediglich eine Shell, in der curl läuft – die Beispiele verwenden Argumente, die in Standard-Builds enthalten sind. Für Python benötigen Sie Python 3 und die Bibliothek requests:

python3 -m venv .venv
source .venv/bin/activate
pip install requests

3. Ein Ort für die Ausgaben

Die Bildgenerierung gibt Bilddaten zurück – ob inline in der Antwort oder als Referenz, die später abgerufen werden kann, hängt von der Antwortform ab, die Ihr Konto zurückgibt. Entscheiden Sie vorab, ob Sie die Bytes auf die Festplatte schreiben, in einen Objektspeicher hochladen oder dem Aufrufer eine URL zurückgeben möchten. Wenn Sie das jetzt klären, vermeiden Sie den klassischen peinlichen Moment „es läuft in der Shell, aber ich habe keinen Ort, um die Datei abzulegen“.

Um loszulegen, müssen Sie weder Kontingente noch Preise schätzen. Die allgemeine Regel für die erste Integration lautet: Senden Sie die kleinste gültige Anfrage, bestätigen Sie, dass Sie eine gültige Antwort erhalten, und fügen Sie dann Parameter hinzu. Der nächste Abschnitt macht genau das.

Eine minimale funktionierende curl-Anfrage

Hier ist ein vollständiger Text-zu-Bild-Aufruf. Endpunkt, Header und Request-Body sind die einzigen variablen Teile: Der Endpunkt identifiziert Modell und Operation auf der HiAPI-Plattform, die Header tragen Ihre Anmeldedaten, und der JSON-Body trägt die Nutzlast.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "a minimalist isometric workspace, soft daylight, muted palette",
    "n": 1
  }'

Setzen Sie HIAPI_BASE_URL auf die API-Basisadresse, die im Dashboard Ihres HiAPI-Kontos angezeigt wird, damit der Hostname nicht fest in das Skript einprogrammiert wird. Der Request-Body enthält drei Felder, und alle drei sind wichtig:

  • model teilt der Plattform mit, welches Modell ausgeführt werden soll. Behalten Sie es explizit bei, auch wenn Sie anderswo Standardwerte verwenden; so sind Ihre Logs selbsterklärend.
  • prompt ist natürliche Sprache. Beschreiben Sie Motiv, Komposition und Stil konkret; vage Prompts erzeugen vage Bilder.
  • n ist die Anzahl der Bilder, die für diesen Prompt angefordert werden. Beginnen Sie mit 1, wenn Sie prüfen, ob die Verbindung funktioniert.

Eine erfolgreiche Antwort gibt die Bilddaten im Antwort-Body zurück. Prüfen Sie diese, bevor Sie einen Parser schreiben: Leiten Sie die Ausgabe durch jq oder in eine Datei und schauen Sie sich die Schlüssel auf oberster Ebene an. Sie bestätigen damit zwei Dinge – dass die Anfrage akzeptiert wurde und wo die Bildnutzlast in der Antwort tatsächlich liegt.

Fügen Sie beim ersten Aufruf nicht voreilig Parameter hinzu. Eine funktionierende Basislinie, die Sie verstehen, ist besser als ein riesiger Request-Body, den Sie kopiert haben. Sobald dieser Aufruf ein Bild zurückgibt, ist jeder weitere Abschnitt eine Variante davon.

Dieselbe Anfrage, in Python geschrieben

Portieren Sie den curl-Aufruf nach Python, ohne die Nutzlast zu ändern. Eine einzige Quelle der Wahrheit (ein Dict) bedeutet, dass der Request-Body, den Sie in der Shell validiert haben, derselbe ist, den Sie letztendlich in Produktion bringen.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def generate_image(prompt: str, model: str = "nano-banana-2", n: int = 1,
                   timeout: float = 60.0) -> dict:
    """Sendet eine einzelne Text-zu-Bild-Anfrage und gibt die geparste JSON-Antwort zurück."""
    payload = {"model": model, "prompt": prompt, "n": n}
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = generate_image(
        "a minimalist isometric workspace, soft daylight, muted palette"
    )
    print(result.keys())

Drei Details verdienen besondere Hervorhebung, weil sie diejenigen sind, die beim Kopieren von Code-Schnipseln am häufigsten übersehen werden.

Setzen Sie immer einen timeout. Ohne ihn blockiert eine hängende Verbindung Ihren Worker unbegrenzt. Der obige Wert ist nur ein Ausgangspunkt, keine eiserne Regel – passen Sie ihn an die Latenz an, die Sie tatsächlich beobachten.

Verwenden Sie json= statt data=. Wenn Sie ein Dict an json übergeben, wird der Content-Type korrekt gesetzt und serialisiert; wenn Sie einen Rohstring an data übergeben, ist genau das die Ursache für fehlerhafte Request-Body-Formate, die wie Modellfehler aussehen.

Rufen Sie raise_for_status() vor dem Parsen auf. Der Versuch, eine 4xx-Antwort mit .json() in Bildfelder zu parsen, erzeugt verwirrende nachgelagerte Fehler. Legen Sie zuerst den HTTP-Statuscode offen.

Diese Funktion ist der zuvor erwähnte wiederverwendbare Wrapper. Der nächste Abschnitt erweitert seine Nutzlast, statt sie zu ersetzen.

Nutzlasten für Text-zu-Bild und Bild-zu-Bild

Der Unterschied zwischen den beiden Modi besteht nur an einer Stelle: ob der Request-Body ein Quellbild enthält. Alles andere – Endpunkt, Authentifizierungs-Header, Modellname – bleibt unverändert.

Text-zu-Bild

{
  "model": "nano-banana-2",
  "prompt": "a minimalist isometric workspace, soft daylight",
  "n": 1
}

Bild-zu-Bild

{
  "model": "nano-banana-2",
  "prompt": "same scene, but converted to a warm evening palette",
  "image": "<base64-encoded source image>",
  "n": 1
}

Das Konzept, das Sie verinnerlichen sollten: Im Bild-zu-Bild-Modus beschreibt der Prompt die Transformation, nicht die fertige Szene von Grund auf. „In eine warme Abendfarbpalette konvertieren“ ist besser, als das gesamte Bild neu zu beschreiben, weil das Quellbild bereits den Inhalt liefert.

Zwei praktische Hinweise zum Feld image:

  • Kodieren Sie das Quellbild in dem Format, das die API für dieses Feld laut Dokumentation vorschreibt, und halten Sie die kodierte Nutzlast deutlich unter Ihrem Budget für die Anfragegröße. Zu große Eingaben sind eine der Hauptursachen für abgelehnte Anfragen.
  • Wenn Sie Benutzer-Uploads annehmen möchten, validieren Sie Größe und Format vor der Kodierung. Ein schnelles Scheitern auf Ihrer Seite ist viel günstiger als ein Roundtrip, der mit einem 4xx endet.

Fügen Sie dem Python-Wrapper einen optionalen Parameter image hinzu, dann kann eine Funktion beide Modi bedienen:

def generate_image(prompt: str, image: str | None = None, **kwargs) -> dict:
    payload = {"model": "nano-banana-2", "prompt": prompt, **kwargs}
    if image is not None:
        payload["image"] = image
    # ... derselbe Anfrageaufruf wie zuvor

Da die Verzweigung nur ein if ist, entscheidet Ihr aufrufender Code über den Modus, während die Transportschicht unverändert bleibt. Das ist die Belohnung dafür, einen einzigen Wrapper beizubehalten.

Asynchrone Aufgaben und Wiederholungsversuche behandeln

Die Bildgenerierung kann länger dauern als ein typischer JSON-API-Aufruf. Manche Antworten liefern das fertige Bild sofort; andere geben eine Aufgabe zurück, die Sie abfragen müssen, um das Ergebnis zu erhalten. Selbst wenn Ihr erster erfolgreicher Aufruf sofort zurückkehrt, sollten Sie für den Polling-Fall entwerfen – sonst bricht Ihre Pipeline zusammen, wenn eine Generierung zu lange dauert.

Ein robustes Muster besteht aus drei Teilen: einer Polling-Schleife mit Backoff, einer harten Frist und einer Wiederholungsstrategie, die zwischen „noch nicht bereit“ und „fehlgeschlagen“ unterscheidet.

import time
import requests


def poll_job(job_id: str, base_url: str, api_key: str,
             initial_wait: float = 2.0, max_wait: float = 30.0,
             deadline: float = 300.0) -> dict:
    start = time.monotonic()
    wait = initial_wait
    while True:
        if time.monotonic() - start > deadline:
            raise TimeoutError(f"job {job_id} exceeded deadline")

        response = requests.get(
            f"{base_url}/v1/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30.0,
        )
        response.raise_for_status()
        body = response.json()

        status = body.get("status")
        if status == "succeeded":
            return body
        if status == "failed":
            raise RuntimeError(f"job {job_id} failed: {body}")

        time.sleep(wait)
        wait = min(wait * 2, max_wait)

Der Aufgabenpfad und das Statusvokabular sollten mit der API-Referenz Ihres HiAPI-Kontos übereinstimmen – passen Sie die obigen Schlüssel an die entsprechende Form an, aber behalten Sie die Struktur bei.

Regeln, die es in der Produktion gesund halten:

  • Exponentielles Backoff mit Obergrenze. Alle 200 Millisekunden zu pollen verschwendet Kontingent und belastet den Endpunkt; das Verdoppeln der Wartezeit mit einer Obergrenze pendelt sich in der Nähe der tatsächlichen Fertigstellungszeit ein.
  • Gesamtversuche und Gesamtzeit begrenzen. Die deadline ist nicht verhandelbar. Eine unbegrenzte Schleife bedeutet, auf einen langsamen Tag zu warten, der einen Ausfall auslöst.
  • Nur wiederholbare Fehler erneut versuchen. Vorübergehende Netzwerkfehler und 5xx-Antworten sind einen erneuten Versuch mit Jitter wert; 4xx-Antworten nicht – eine fehlerhafte Nutzlast erneut zu senden verschwendet nur Zeit. Verwenden Sie eine kleine begrenzte Anzahl von Wiederholungen (zwei bis drei) und protokollieren Sie jede.
  • Machen Sie Wiederholungen sicher. Wenn Ihr Endpunkt zum Erstellen von Aufgaben Idempotenzschlüssel akzeptiert, senden Sie pro logischer Anfrage einen stabilen Schlüssel, damit ein erneut gesendeter Request keine doppelte Generierung erzeugt.

Mit Frist, Backoff und begrenzter Wiederholungsanzahl wird aus einer langsamen Generierung ein protokolliertes, behandeltes Ereignis statt eines hängenden Workers.

Fehler beheben, auf die Sie tatsächlich stoßen werden

Wenn ein Aufruf fehlschlägt, lesen Sie zuerst den rohen Statuscode und den vollständigen Antwort-Body, bevor Sie irgendeinen Modellparameter ändern. Der Antwort-Body weist normalerweise auf das Problem hin. Raten ist langsamer als Protokollieren.

Authentifizierungsfehler

401 oder 403 bedeutet fast immer eines der folgenden: Der Schlüssel fehlt in der Umgebungsvariable, der Header ist fehlerhaft formatiert oder die Anmeldedaten sind in dieser Umgebung nicht aktiv. Prüfen Sie den tatsächlichen Wortlaut des Headers, den Sie senden – ein fehlendes Präfix Bearer oder ein versehentlicher Zeilenumbruch aus einem kopierten Schlüssel sind häufige Ursachen.

Nutzlastfehler

400 mit einer Meldung über den Request-Body bedeutet, dass das JSON selbst fehlerhaft ist: fehlendes prompt, überflüssige Kommas, in Python data= statt json= verwendet oder das Feld image falsch kodiert. Geben Sie einmal die exakten Bytes aus, die Sie senden, prüfen Sie sie und entfernen Sie dann die Ausgabe.

Eingabe abgelehnt

Bild-zu-Bild-Anfragen, die die Validierung nicht bestehen, hängen normalerweise mit dem Eingabebild zusammen: zu groß, falsches Format oder nicht dekodierbar. Validieren Sie Größe und Kodierung vor dem Senden auf Ihrer Seite und geben Sie der Person, die das Bild bereitstellt, einen klaren Fehler zurück, statt es erneut zu versuchen.

Timeouts und 5xx

Diese fallen in die Kategorie „wiederholbar“. Unterscheiden Sie in den Logs zwischen Verbindungs-Timeout und Serverfehler und stellen Sie sicher, dass Ihre Wiederholungen begrenzt sind – sonst wird aus einem anhaltenden 5xx eine Endlosschleife.

Eine effektive Fehlersuchreihenfolge

  1. Protokollieren Sie für jeden Fehlschlag den HTTP-Statuscode und den rohen Antworttext.
  2. Überprüfen Sie zuerst den Pfad der Anmeldedaten, vor allem anderen.
  3. Spielen Sie die fehlgeschlagene Nutzlast mit curl nach, um Ihren Client-Code aus der Gleichung zu entfernen.
  4. Erst danach passen Sie prompt, image oder andere Modellparameter an.

Wenn der Fehler nach allen vier Schritten weiterhin besteht, erfassen Sie die Request-ID (oder ein entsprechendes Korrelationsfeld) aus der Antwort und fügen Sie sie beim Kontakt mit dem Support bei – das verwandelt einen vagen Bericht in etwas Nachvollziehbares.

Es produktionsbereit machen

Gehen Sie vor dem Start diese Checkliste durch.

  • Geheimnisse: Der API-Schlüssel wird aus Umgebungsvariablen oder einem Secret-Manager geladen und erscheint in keinem Log, keiner Fehlermeldung und keinem Client-Build-Artefakt.
  • Timeouts: Jeder HTTP-Aufruf – Erstellen, Polling und Abrufen des Ergebnisbilds – hat ein explizites Timeout.
  • Grenzen: Polling hat eine Frist, Wiederholungen haben eine maximale Anzahl von Versuchen, und der Code unterscheidet zwischen wiederholbaren und nicht wiederholbaren Fehlern.
  • Observability: Protokollieren Sie für jeden Aufruf die Request-Form (sofern der Prompt Benutzerdaten enthalten könnte, weglassen oder hashen), den Statuscode, die Latenz und die Korrelations-ID.
  • Kostenbewusstsein: Die Abrechnung folgt den von Ihrem HiAPI-Konto definierten Dimensionen, daher sollten Sie verfolgen, wie viele Generierungen und wie viele Ausgaben jede Anfrage erzeugt, und Instrumentierung für Ihre eigenen Nutzungszähler einbauen, damit eine außer Kontrolle geratene Schleife vor der Rechnung sichtbar wird.
  • Speicherung: Generierte Bilder werden an einen persistenten Ort geschrieben – Objektspeicher oder Datenbank – und nicht in einem temporären Verzeichnis belassen, das mit dem Container verschwindet.

Keiner dieser Punkte ist spezifisch für nano-banana-2. Das ist gerade der Punkt: Der Modellaufruf ist der einfache Teil, alles darum herum ist gewöhnliche Hygiene verteilter Systeme. Bauen Sie den Wrapper einmal, bewahren Sie die Nutzlast in einem Dict auf, und sowohl Text-zu-Bild als auch Bild-zu-Bild erhalten Sie gratis.

Beginnen Sie mit dem curl-Aufruf, portieren Sie ihn in den Python-Wrapper, fügen Sie die Polling-Schleife hinzu und arbeiten Sie dann die Checkliste ab. Weitere Modelldetails und die neueste API-Referenz finden Sie in der nano-banana-2-Dokumentation auf der HiAPI-Plattform.

Ähnliche Artikel

Alle Artikel ansehen →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen