Blog

Tutorial

So verwendest du Nano-Banana über die HiAPI API: curl, Python und lauffähige Anfragen

Nov 12, 2026
Abstrakte, geschichtete halbtransparente Glasebenen, die einen hellgrauen Hintergrund in kühle blaue Streifen brechen, verwendet als Titelbild für ein Tutorial
Auf dieser Seite

Was Nano-Banana als API für Entwickler bietet

Nano-Banana ist ein Bildgenerierungsmodell, das über die HiAPI API bereitgestellt wird. Du sendest einen Prompt – auf Wunsch mit einem oder mehreren Referenzbildern – und erhältst ein generiertes Bild. Das mentale Modell ist so einfach. Kein lokales Hosting des Modells, keine GPU, keine zusätzliche SDK zum Erlernen: Die Art der Authentifizierung, der Anfragekapselung und des asynchronen Aufgabenmechanismus, die du bei anderen HiAPI-Modellen verwendest, gelten auch hier.

Bevor du Code schreibst, ist es hilfreich, klarzustellen, was der Bildgenerierungs-Endpunkt ist und was nicht. Es ist ein kreativer Endpunkt: Derselbe Prompt kann bei mehreren Läufen unterschiedliche Ergebnisse liefern, und du solltest deine Pipeline so gestalten, dass sie das toleriert. Er ist keine deterministische Transformation wie Skalierung oder Formatkonvertierung. Wenn du pixelgenaue Reproduzierbarkeit benötigst, speichere die Ausgaben, die du akzeptiert hast, im Cache, anstatt anzunehmen, dass eine erneute Generierung dasselbe Ergebnis liefert.

Eine typische Integration umfasst drei Phasen:

  1. Absenden einer Generierungsanfrage mit dem Prompt und allen optionalen Eingaben.
  2. Warten auf den Abschluss der generierten Aufgabe, da die Bildgenerierung länger dauert als eine einfache Textvervollständigung.
  3. Abrufen der Ausgabe, Speichern und Entscheiden, ob sie akzeptiert oder der Prompt angepasst und erneut versucht wird.

Zwei Dinge sollten von Anfang an entschieden werden, da sie alles andere beeinflussen: ob dein Prompt reiner Text ist oder Referenzbilder verwendet (was die Anfrage-Payload ändert) und ob du die Konsistenz von Charakteren über mehrere Generierungen hinweg benötigst (was fast immer den Einsatz von Referenzbildern bedeutet). Die folgenden Abschnitte gehen von der Anfragestruktur nach außen vor, und du kannst die Beispiele entsprechend anpassen.

Struktur einer Nano-Banana-Anfrage

Jede Anfrage an Nano-Banana über HiAPI hat dasselbe Grundgerüst. Nur die Payload ändert sich.

Endpunkt und Authentifizierung

Die Anfrage wird an die Basis-URL von HiAPI gesendet, und das konkrete Modell wird in der Anfrage-Payload angegeben, nicht in einer manuell zusammengesetzten Upstream-URL. Du authentifizierst dich mit einem API-Schlüssel im Authorization-Header. Bewahre den Schlüssel in einer Umgebungsvariable auf – niemals inline im Quellcode oder im Repository eingecheckt.

Modellname

Der Modellidentifikator ist ein Feld in deinem JSON-Anfragekörper. Behandle ihn als einen String, den du wörtlich aus der Modellliste kopierst, und nicht als etwas, das du selbst zusammenbaust, damit Namensänderungen deinen Code nicht unbemerkt brechen.

Prompt-Payload

Du musst mindestens einen Text-Prompt senden, der das Zielbild beschreibt. Hier hat die Prompt-Qualität einen weit größeren Einfluss auf die Ausgabequalität als jedes andere Feld. Sei konkret in Bezug auf Motiv, Komposition, Beleuchtung und Stil. Vage Prompts erzeugen vage Bilder, und keine Parametereinstellung kann einen Prompt retten, der nicht klar sagt, was du eigentlich willst.

Optionale Referenzbilder

Wenn du Referenzbilder einfügst, gehören sie zum selben Anfragekörper – üblicherweise als Bild-URL oder kodierte Bilddaten, je nachdem, welches Format das Modell akzeptiert. Referenzbilder können Dinge wie das Gesicht, die Kleidung oder den gesamten Kunststil eines Charakters verankern. Lass sie bei reiner Text-zu-Bild-Generierung weg; füge sie ein, wenn die Ausgabe einem bestimmten Objekt ähneln soll.

Ausgabebezogene Felder

Einige Felder beeinflussen die Form des Ergebnisses und nicht den Inhalt: zum Beispiel die angeforderte Ausgabegröße oder das Seitenverhältnis. Behandle sie am besten als angeforderte Werte und nicht als garantierte Werte – die vom Modell zurückgegebene Größe kann leicht abweichen. Nachgelagerter Code sollte die tatsächlich zurückgegebenen Abmessungen lesen, anstatt anzunehmen, dass du bekommst, was du angefordert hast.

Hier ist die konzeptionelle Struktur mit Platzhalterwerten:

{
  "model": "<nano-banana-model-id>",
  "prompt": "Ein Rotfuchs sitzt in hohem Gras zur goldenen Stunde, geringe Schärfentiefe",
  "reference_images": [],
  "size": "1024x1024"
}

Konsultiere die Parameterdokumentation des Modells für die genauen akzeptierten Feldnamen und Formate – die obige Struktur ist nur ein allgemeines Muster und ersetzt keine Spezifikation.

Lauffähige curl-Anfrage

Der schnellste Weg, um zu bestätigen, dass der Schlüssel funktioniert und die Payload gültig ist, ist ein curl-Aufruf. Richte zuerst die Umgebung ein:

export HIAPI_API_KEY="your-api-key-here"

Sende dann die Generierungsanfrage:

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<nano-banana-model-id>",
    "prompt": "Ein Rotfuchs sitzt in hohem Gras zur goldenen Stunde, geringe Schärfentiefe",
    "size": "1024x1024"
  }'

Die Rolle der einzelnen Teile:

  • URL – der Bildgenerierungspfad von HiAPI. Eine Basis-URL bedient alle Modelle; das Modell wird im Anfragekörper angegeben.
  • Authorization – dein Schlüssel, aus der Umgebung gelesen, damit er nicht in der Shell-Historie oder der Quellcodeverwaltung landet.
  • Content-Type – muss application/json sein; ein häufiger Anfängerfehler ist, ihn nicht zu setzen, was zu Parsing-Fehlern führt.
  • Anfragekörper – die JSON-Payload aus dem vorherigen Abschnitt, die den eigentlichen Prompt enthält.

Die Antwort interpretieren

Die Antwort teilt dir mit, was passiert ist. Zwei Ergebnisse sind relevant:

  • Synchrones Ergebnis – einige Aufrufe geben direkt Bilddaten oder eine Bild-URL zurück. Wenn du eine URL siehst, rufe sie so bald wie möglich ab und speichere sie, anstatt dich auf ihre langfristige Verfügbarkeit zu verlassen.
  • Aufgaben-Handle – wenn die Generierung asynchron ist, enthält die Antwort einen Identifikator zum Abfragen des Status. Das ist das Thema des folgenden Asynchron-Abschnitts.

Wenn du neben dem Antwortkörper auch die HTTP-Statuszeile und die Header sehen möchtest, füge -i zum curl-Befehl hinzu – bei Fehlern ist das sehr nützlich, um zu unterscheiden, ob es ein Authentifizierungs- oder ein Payload-Problem ist.

Derselbe Aufruf in Python

Für alles außer Einmal-Skripten verwende Python. Die requests-Bibliothek hält die Beispiele abhängigkeitsarm und macht die HTTP-Ebene explizit sichtbar.

import os
import requests

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

payload = {
    "model": "<nano-banana-model-id>",
    "prompt": "Ein Rotfuchs sitzt in hohem Gras zur goldenen Stunde, geringe Schärfentiefe",
    "size": "1024x1024",
}

response = requests.post(
    f"{BASE_URL}/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)

Einige Gewohnheiten, die du dir von Anfang an aneignen solltest:

  • Timeout setzen. Die Bildgenerierung ist langsam; ohne Timeout kann dein Worker-Prozess unbegrenzt hängen. Für synchrone Aufrufe ist ein großzügiger Timeout ein vernünftiger Ausgangspunkt, passe ihn aber an deine Last an.
  • raise_for_status() verwenden. Es wandelt 4xx- und 5xx-Antworten in abfangbare Ausnahmen um, anstatt stillschweigend den Fehlerantwortkörper als Ergebnis zu parsen.
  • In eine Funktion kapseln. Der obige Ausschnitt ist ein Skript; in einem Dienst brauchst du eine Funktion, die einen Prompt entgegennimmt und Bilddaten oder ein Aufgaben-Handle zurückgibt, damit der Rest deines Codes sich nicht um HTTP-Details kümmern muss.

Wenn die Antwort eine Bild-URL enthält, lade sie sofort herunter und speichere sie:

for item in data.get("data", []):
    url = item.get("url")
    if url:
        img = requests.get(url, timeout=60)
        img.raise_for_status()
        with open("output.png", "wb") as f:
            f.write(img.content)

Die echte Datenquelle deiner Anwendung sollte dein eigener Speicher sein – nicht eine temporäre Remote-URL.

Asynchrone Aufgaben verarbeiten

Die Bildgenerierung dauert oft länger, als eine einzelne HTTP-Rundreise die Verbindung offen halten sollte. HiAPI-Modelle, die diesen Ansatz verwenden, geben beim Absenden einen Aufgabenidentifikator zurück; anschließend fragst du den Status-Endpunkt ab, bis der Job abgeschlossen ist. Dieses Muster gilt für alle asynchronen Modelle der Plattform, also lerne es einmal.

Erst absenden, dann abfragen

Dein anfänglicher POST gibt etwas wie eine Aufgaben-ID zurück. Dann fragst du mit dieser ID den Status-Endpunkt ab. Die benötigte Logik ist:

import time

def poll_task(task_id, api_key, interval=2, max_wait=300):
    headers = {"Authorization": f"Bearer {api_key}"}
    deadline = time.time() + max_wait
    while time.time() < deadline:
        r = requests.get(
            f"https://api.hiapi.ai/v1/tasks/{task_id}",
            headers=headers,
            timeout=30,
        )
        r.raise_for_status()
        body = r.json()
        status = body.get("status")
        if status in ("succeeded", "completed", "failed", "error"):
            return body
        time.sleep(interval)
    raise TimeoutError(f"Aufgabe {task_id} wurde nicht innerhalb von {max_wait} Sekunden abgeschlossen")

Drei Regeln, die dir Sackgassen ersparen

  1. Begrenze immer die Gesamtwartezeit. Ein Job, der nie abgeschlossen wird, darf deinen Worker nicht blockieren. Das obige max_wait ist dein Ausstieg.
  2. Backoff verwenden. Ein festes kurzes Intervall ist für interaktive Nutzung in Ordnung; bei Batch-Jobs erhöhe das Intervall mit zunehmender Wartezeit, um den Status-Endpunkt nicht zu überlasten.
  3. Endzustände verifizieren. succeeded bedeutet, dass du die Ausgabe lesen kannst; failed bedeutet, dass du die Fehler-Payload lesen und nicht blind wiederholen solltest. Das Wiederholen einer fehlerhaften Payload kostet nur Zeit.

Persistiere die Aufgaben-ID zusammen mit deinen eigenen Job-Datensätzen. Wenn dein Prozess mitten im Polling neu startet, kannst du das Polling fortsetzen, anstatt erneut abzusenden und für eine doppelte Generierung zu bezahlen.

Referenzbilder und Charakterkonsistenz

Reine Text-Prompts sind für Einzelbilder in Ordnung, aber wenn du denselben Charakter in zehn verschiedenen Szenen benötigst, stoßen sie an ihre Grenzen. Ein Gesicht mit Worten zu beschreiben und dann zu hoffen, dass das Modell es stabil reproduziert, funktioniert fast nie – kleine Formulierungsänderungen erzeugen unterschiedliche Personen.

Referenzbilder lösen dieses Problem. Du fügst eine oder mehrere Bilddateien zusammen mit dem Text-Prompt in die Anfrage ein, und das Modell verwendet sie als visuelle Anker. Die Charakterkonsistenz ist der zentrale Anwendungsfall:

  • Charakter-Sheet – ein sauberes Referenzbild, mehrere Szenen-Prompts, konsistentes Gesicht und konsistente Kleidung.
  • Stilverankerung – das Referenzbild legt die visuelle Sprache fest, der Prompt lenkt den Inhalt.
  • Produktbilder – ein Referenzbild des Objekts hält sein Design über verschiedene Hintergründe hinweg stabil.

In der Anfrage bedeutet das, das Referenzbildfeld auszufüllen, anstatt einen leeren Wert zu senden. Stelle Bilder als URL oder kodierte Daten bereit, je nachdem, was die Parameter-Spezifikation des Modells unterstützt, und halte die Referenzbilder sauber: Ein klares Motiv ist besser als eine überladene Szene, denn das Modell erfasst alles im Bild, nicht nur den Teil, der dich interessiert.

Ein praktisches Muster für die Pipeline:

  1. Generiere einen Charakter aus einem detaillierten Text-Prompt.
  2. Prüfe ihn, akzeptiere oder generiere neu, bis du zufrieden bist.
  3. Verwende dieses akzeptierte Bild als Referenz für jede nachfolgende Szene.

Das ist der Nano-Banana-API-Python-Workflow im Kern: den Charakter einmal festlegen und dann nur den Szenenteil des Prompts ändern. Rechne mit Iteration – Referenzbilder verbessern die Konsistenz, erreichen aber keine Perfektion, also baue einen Prüfschritt ein, anstatt anzunehmen, dass jede Ausgabe verwendbar ist.

Ausgabeauflösung und praktische Grenzen

Die Auflösung ist der Bereich, in dem Annahmen am häufigsten zu Problemen führen, also sei vorsichtig.

Angeforderte vs. tatsächliche Größe

Du kannst eine Ausgabegröße anfordern, solltest sie aber als Hinweis betrachten. Die vom Modell zurückgegebene Größe kann von deiner Anforderung abweichen – besonders bei ungewöhnlichen Seitenverhältnissen. Der robuste Ansatz besteht darin, die tatsächlichen Abmessungen des empfangenen Bildes zu lesen und generisch zu verarbeiten: Dein Speicher, deine Thumbnails und dein Layout sollten auf der echten Datei basieren, nicht auf den angeforderten Werten.

Was die Qualität bestimmt

Die Ausgabequalität wird hauptsächlich durch den Prompt bestimmt und, falls verwendet, durch die Referenzbilder. Ein gut komponierter Prompt mit klarem Motiv und klarer Beleuchtung erzeugt ein besseres Bild als ein vager Prompt, der eine größere Größe anfordert. Verwende die Auflösung nicht, um einen unzureichend beschriebenen Prompt zu kompensieren.

Planung im Hinblick auf Grenzen

  • Keine fest codierten Größen im nachgelagerten Code. Lies sie aus dem zurückgegebenen Bild.
  • Vor dem Speichern validieren. Wenn deine Anwendung eine Mindestgröße erfordert, prüfe nach der Generierung die tatsächliche Größe; generiere bei Bedarf neu – gehe nicht davon aus, dass die Anforderung erzwungen wurde.
  • Dateigröße beachten. Ausgaben mit höherer Auflösung bedeuten größere Payloads; lade sie gestreamt oder gepuffert herunter, anstatt in einer Schleife alles in den Speicher zu laden.
  • Vorsichtig batch-verarbeiten. Gleichzeitige Limits gelten pro Konto; wenn du viele Bilder generieren willst, füge einen kleinen Worker-Pool mit Backoff-Wiederholungen hinzu, anstatt in einer unbegrenzten Schleife Anfragen abzufeuern.

Für die maßgeblichen Fähigkeiten und akzeptierten Werte von Nano-Banana konsultiere die Dokumentation des Modells – nicht die Beispiel-Payloads in diesem Artikel. Die Abrechnung folgt dem normalen nutzungsbasierten Abrechnungsmodell der Plattform; aktuelle Tarife findest du im Preispaneel, nicht in diesem Tutorial.

Häufige Fehler beheben

Die meisten fehlgeschlagenen Ersteintegrationen fallen in einige wenige Kategorien. Hier sind die Prüfpunkte für jede.

401 / 403 – Authentifizierung

Dein Schlüssel fehlt, ist falsch formatiert oder wird nicht gesendet. Stelle sicher, dass der Authorization-Header vorhanden ist, das Präfix Bearer enthält und die Umgebungsvariable tatsächlich in die Shell oder den Prozess exportiert wurde, die bzw. der den Code ausführt. Ein zusätzlicher Zeilenumbruch am Ende des kopierten Schlüssels verursacht dieses Problem häufiger als erwartet.

400 – Fehlerhafte Payload

Meist ist es eines der folgenden Probleme: ungültiges JSON (überzählige Anführungszeichen oder nachfolgende Kommas), falscher Content-Type, fehlende Pflichtfelder (wie prompt oder model) oder ein Referenzbildfeld, das in einem vom Modell nicht akzeptierten Format gesendet wird. Gib den genauen Anfragekörper aus, den du tatsächlich sendest, und vergleiche ihn Feld für Feld mit der Parameterspezifikation.

404 – Pfad- oder Modellfehler

Der Endpunktpfad ist falsch, oder der Modellidentifikator stimmt mit keinem Modell auf der Plattform überein. Kopiere den Modellnamen wörtlich aus der Liste, anstatt ihn aus dem Gedächtnis einzugeben.

Timeouts und Polling-Stillstand

Bei synchronen Aufrufen unterbricht ein zu kurzer Timeout einen Job, der sonst erfolgreich gewesen wäre. Bei asynchronen Jobs bedeutet ein Polling-Stillstand meist, dass deine Polling-Logik vorzeitig beendet wird oder die Prüfung des Endzustands nicht mit den tatsächlich von der API zurückgegebenen Status-Strings übereinstimmt – protokolliere die Rohstatuswerte und verifiziere sie. Behalte immer eine maximale Wartezeit bei, damit hängende Jobs laut fehlschlagen und nicht hängen bleiben.

Leere Ergebnisse

Eine 200-Antwort ohne Bild ist fast immer ein Inhaltsproblem und kein Bug: Der Prompt könnte zu vage sein oder gefiltert worden sein. Prüfe das Fehler- oder Ursachenfeld im Antwortkörper, bevor du annimmst, dass die API fehlerhaft ist, und präzisiere dann den Prompt.

Fehlschläge bei Wiederholungen

Wenn dieselbe Payload manchmal erfolgreich ist und manchmal fehlschlägt, hast du wahrscheinlich ein Rate-Limit ausgelöst oder einen vorübergehenden Serverfehler erlebt. Füge um das Absenden und Polling herum exponentielles Backoff hinzu und wiederhole keine 400 – korrigiere die Payload.

Im Zweifelsfall ist die schnellste Diagnose ein minimaler curl-Aufruf mit einem einfachen Prompt. Wenn er funktioniert, liegt das Problem in deiner Payload oder deinem Code, nicht in den Anmeldeinformationen.

Ä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