Tutorial
Nano-Banana-2 API-Tutorial: Funktionierendes curl und Python Requests mit hiapi
Auf dieser Seite
Vorbereitungen vor dem ersten Aufruf
Bevor Sie eine Anfrage an Nano-Banana-2 senden, bereiten Sie vier Dinge vor. Keines davon kostet viel Zeit, und wenn alle vier bereitliegen, wird die erste Anfrage zu einer Copy-and-Paste-Übung statt zu einer Schatzsuche.
1. hiapi-Konto und API-Schlüssel
Jede Anfrage wird mit einem API-Schlüssel authentifiziert, der an Ihr hiapi-Konto gebunden ist. Erstellen Sie den Schlüssel im Kontodashboard und bewahren Sie ihn sicher auf – in einem Passwortmanager oder als Umgebungsvariable auf Ihrem Rechner. Behandeln Sie ihn wie ein Passwort: niemals in ein Code-Repository committen und nicht in gemeinsam genutzte Dokumente einfügen.
Exportieren Sie ihn auf Ihrem Rechner einmal pro Shell-Sitzung, damit die folgenden Beispiele ihn lesen können, ohne etwas fest zu kodieren:
export HIAPI_API_KEY="your_api_key_here"
2. Die API-Basis-URL
Die Basis-URL ist die Wurzeladresse, auf der alle Anfragen aufbauen. Beim Erstellen eines Endpunkts hängen Sie die Modellroute dahinter. Legen Sie die Basis-URL in einer Konfigurationsvariable in Ihrem Code ab, statt sie über mehrere Dateien zu verteilen – so müssen Sie bei einer Änderung nur eine Zeile anpassen.
3. Ein Client zum Senden der Anfragen
Zu Beginn benötigen Sie nur eines der folgenden:
- curl – mit großer Wahrscheinlichkeit bereits installiert. Verwenden Sie es, um zu bestätigen, dass Ihr Schlüssel und der Anfragekörper korrekt sind, bevor Sie Anwendungscode schreiben.
- Python 3 mit der
requests-Bibliothek (pip install requests). Die meisten Leser werden dies für echte Integrationen nutzen.
Beides parat zu haben ist nützlich: curl isoliert die Anfrage von Ihrem Code, sodass Sie bei Problemen erkennen können, ob der API-Aufruf oder die Anwendung die Ursache ist.
4. Klarheit darüber, was Sie generieren möchten
Nano-Banana-2 unterstützt sowohl Text-zu-Bild als auch Bild-zu-Bild. Entscheiden Sie vorab, welchen Modus Sie benötigen, denn die Struktur des Anfragekörpers unterscheidet sich (mehr dazu weiter unten). Beginnen Sie beim ersten Aufruf mit Text-zu-Bild – es hat die wenigsten variablen Faktoren.
Mit exportiertem Schlüssel, installiertem Client und einem fertigen Prompt können Sie sich nun der Anfrage selbst zuwenden.
Die Bestandteile einer Nano-Banana-2-Anfrage
Ein Nano-Banana-2-Aufruf ist eine POST-Anfrage mit einem JSON-Anfragekörper. Jedes Feld erfüllt einen eigenen Zweck; wenn Sie sie getrennt verstehen, können Sie bei Problemen jeweils nur eine Stelle ändern.
Der Endpunkt
Die Anfrage geht an die hiapi API-Basis-URL, ergänzt um die Nano-Banana-2-Modellroute. Die Methode ist immer POST, da Sie eine zu verarbeitende Nutzlast senden und keine Ressource abrufen.
Die Header
Zwei Header sind wichtig:
Content-Type: application/json– teilt der API mit, wie Ihr Anfragekörper zu parsen ist.Authorization– trägt Ihren API-Schlüssel. Die folgenden Beispiele lesen ihn aus der zuvor exportierten Umgebungsvariable.
Fehlt einer der Header oder ist er fehlerhaft formatiert, schlägt die Anfrage fehl, bevor das Modell sie überhaupt sieht. Dies ist die häufigste einzelne Ursache für verwirrende Fehler.
Die Felder des Anfragekörpers
Eine Text-zu-Bild-Anfrage enthält folgende Felder:
model– gibt an, dass das auszuführende Modell Nano-Banana-2 ist. Geben Sie es explizit an, auch wenn ein Standardwert existiert; das macht Ihren Code selbsterklärend und schützt Sie, falls sich der Standardwert ändert.prompt– beschreibt in natürlicher Sprache das gewünschte Bild. Hier findet der größte Teil Ihrer Iterationsarbeit statt. Seien Sie konkret: Motiv, Komposition, Stil, Licht. Vage Prompts erzeugen vage Ergebnisse.- Bildeingabe – bei Text-zu-Bild leer oder nicht vorhanden. Bei Bild-zu-Bild enthält sie Ihr Referenzbild (mehr dazu im Abschnitt Bild-zu-Bild).
- Ausgabe- und Größenparameter – modellspezifische Felder, die Form oder Seitenverhältnis des zurückgegebenen Ergebnisses beeinflussen. Setzen Sie nur Felder, die die Modelldokumentation als unterstützt ausweist; in strikten APIs bedeutet ein unbekanntes Feld üblicherweise, dass die Anfrage abgelehnt wird, statt stillschweigend ignoriert zu werden.
Was zurückkommt
Die Antwort ist JSON. Je nach Aufbau des Aufrufs erhalten Sie die generierten Bilddaten direkt oder einen Verweis darauf. Ihr Client-Code sollte zuerst den HTTP-Status prüfen und erst dann den Antwortkörper betrachten – gehen Sie nicht davon aus, dass eine Antwort im 200er-Format unbedingt ein Bild enthält, ohne dies zu verifizieren.
Das ist die gesamte Struktur: eine authentifizierte POST-Anfrage mit einem überschaubaren JSON-Anfragekörper. Der Rest dieses Tutorials ist nur eine Variation dieser Form.
Eine funktionierende curl-Anfrage
Dies ist der minimalste vollständige Aufruf, den Sie senden können. Führen Sie ihn in einem Terminal aus, in dem der API-Schlüssel exportiert ist, und innerhalb weniger Sekunden wissen Sie, ob Konto, Schlüssel und Netzwerkpfad alle funktionieren.
curl -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition"
}'
Legen Sie die Basis-URL einmal zusammen mit dem Schlüssel in Ihrer Shell fest:
export HIAPI_BASE_URL="https://api.hiapi.ai"
(Verwenden Sie die Basis-URL, die in Ihrem hiapi-Dashboard angezeigt wird – das ist der maßgebliche Wert für Ihr Konto.)
Die Ausgabe lesen
curl gibt die Rohantwort auf stdout aus. War der Aufruf erfolgreich, sehen Sie JSON mit dem generierten Bild. Leiten Sie es durch python -m json.tool, um die Ausgabe zu verschönern und die Struktur zu bestätigen:
curl -s -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{"model":"nano-banana-2","prompt":"a red fox in fresh snow, side profile, crisp detail"}' \
| python -m json.tool
Interpretieren, was Sie sehen
- Erfolgreiche Antwort – bestätigt, dass Ihr Schlüssel gültig, der Endpunkt korrekt und der Anfragekörper parsbar ist. Speichern Sie diesen funktionierenden Befehl – er ist Ihre Baseline.
- Fehlerantwort – deutet darauf hin, dass einer der drei Header oder der Anfragekörper nicht stimmt. Kopieren Sie den Fehlertext; der Abschnitt zur Fehlerbehebung ordnet häufige Fehler den jeweiligen Lösungen zu.
Der Wert, mit curl zu beginnen, liegt in der Isolation. Schlüssel, Header und JSON sind an einer Stelle sichtbar, sodass ein Fehler auf die Anfrage selbst und nicht auf Ihren Anwendungscode zeigt. Sobald dieser Befehl funktioniert, ist die Portierung nach Python mechanisch.
Dieselbe Anfrage in Python
Hier ist derselbe Aufruf mit requests. Der Anfragekörper ist dasselbe dict, das Sie im curl-Anfragekörper gesehen haben – an der API selbst ändert sich nichts, nur die Art, wie Sie sie senden.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
payload = {
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition",
}
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}",
}
response = requests.post(
f"{BASE_URL}/nano-banana-2",
json=payload,
headers=headers,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
Warum es so geschrieben ist
json=payloadlässtrequestsdas dict für Sie serialisieren und setzt denContent-Type. Sie können den Header trotzdem explizit übergeben; das schadet nicht und macht die Anfrage selbsterklärend.timeout=120– die Bildgenerierung ist nicht sofort abgeschlossen. Ein großzügiger Timeout verhindert, dass der Client aufgibt, während das Modell noch arbeitet. Passen Sie den Wert an Ihren Anwendungsfall an.raise_for_status()wandelt Nicht-2xx-Antworten in Ausnahmen um, sodass Fehler sofort auffallen, statt unbemerkt in Ihre Ergebnisverarbeitung zu fließen.- Umgebungsvariablen halten den Schlüssel aus dem Quellcode heraus. Injizieren Sie ihn in der Produktion aus dem Secret-Speicher der Plattform statt aus einer möglicherweise committeten
.env-Datei.
Das Bild extrahieren
Der Antwortkörper ist JSON. Sehen Sie ihn sich einmal interaktiv an, um die genaue Struktur zu verstehen, und extrahieren Sie dann das Bildfeld explizit:
image_url = data["image_url"] # confirm the key name against a real response
Enthält Ihre Antwort base64-Daten statt einer URL, decodieren Sie sie und schreiben Sie sie in eine Datei:
import base64
with open("output.png", "wb") as f:
f.write(base64.b64decode(data["image_base64"]))
Raten Sie keine Feldnamen – drucken Sie beim ersten erfolgreichen Aufruf die Rohantwort und greifen Sie auf das zu, was tatsächlich vorhanden ist. Diese eine Gewohnheit verhindert die meisten Integrationsfehler.
Text-zu-Bild versus Bild-zu-Bild mit Referenzbild
Bisher war alles Text-zu-Bild: Prompt eingeben, Bild ausgeben. Nano-Banana-2 unterstützt auch Bild-zu-Bild, bei dem Sie ein Referenzbild bereitstellen, das das Modell als Leitfaden nutzt. Zu wissen, wann Sie den Modus wechseln und wie sich der Anfragekörper ändert, ist der Unterschied zwischen einem erfolgreichen Aufruf und einer Ablehnung.
Wann welcher Modus zu verwenden ist
- Text-zu-Bild – Sie haben eine Idee in Worten und kein Ausgangsbild. Am besten für Exploration, Illustration und alles, was von Grund auf generiert wird.
- Bild-zu-Bild – Sie haben ein vorhandenes Bild und möchten eine Variante, eine Umstilisierung oder eine Bearbeitung, die Struktur oder Motiv beibehält. Dies ist der Modus für iteratives Design, das Angleichen eines visuellen Stils oder die Umwandlung eines Fotos.
Wenn Ihr Prompt lautet „Lass es aussehen wie …“ oder „Behalte das Layout, aber …“, dann benötigen Sie Bild-zu-Bild.
Wie das Referenzbild die Anfrage verändert
Endpunkt und Header bleiben unverändert. Was sich ändert, ist der Anfragekörper: Sie fügen neben dem Prompt ein Referenzbildfeld hinzu. Je nachdem, wie das Bild bereitgestellt wird, enthält dieses Feld eine URL oder kodierte Bilddaten. Beachten Sie diese Regeln:
- Wenn Sie einen Link übergeben, verwenden Sie eine öffentlich direkt zugängliche URL. Seiten, die eine Anmeldung erfordern oder über eine authentifizierte Weiterleitung führen, schlagen fehl – die API muss die Bytes direkt abrufen können.
- Halten Sie sich an die erwarteten Formate. Gängige Formate wie PNG und JPEG sind sicher; ungewöhnliche oder beschädigte Dateien sind eine häufige Ursache für abgelehnte Anfragen.
- Prüfen Sie die Größenbeschränkungen vor dem Hochladen. Große Bilder sind oft die Ursache für Anfragekörperfehler.
- Halten Sie den Prompt fokussiert. Mit einem Referenzbild beschreiben Sie die gewünschte Transformation, statt das Referenzbild erneut zu beschreiben.
Ein schematischer Bild-zu-Bild-Anfragekörper sieht so aus:
payload = {
"model": "nano-banana-2",
"prompt": "Same subject, restyled as a graphite sketch with light crosshatching",
"image_url": "https://example.com/your-reference.jpg",
}
Bestätigen Sie wie immer den genauen Feldnamen anhand Ihrer ersten erfolgreichen Antwort. Das Prinzip ist einfach: Text-zu-Bild hat nur einen Prompt, Bild-zu-Bild fügt demselben Anfrageformat ein verifiziertes Referenzbild hinzu. Beweisen Sie zuerst mit Text-zu-Bild, dass die Pipeline funktioniert, und fügen Sie dann das Referenzbild hinzu.
Fehler behandeln und fehlgeschlagene Anfragen debuggen
Fehlgeschlagene Nano-Banana-2-Aufrufe lassen sich in drei Kategorien einteilen. Wenn Sie lernen, jede zu erkennen, können Sie die meisten Probleme innerhalb einer Minute beheben.
Authentifizierungsfehler
Wenn Sie einen Authentifizierungsfehler sehen, ist der Schlüssel nicht korrekt bei der API angekommen. Prüfen Sie in dieser Reihenfolge:
- Ist
HIAPI_API_KEYtatsächlich in der Shell oder Umgebung exportiert, die die Anfrage ausführt? Führen Sieecho $HIAPI_API_KEYaus, um dies zu bestätigen. - Ist der
Authorization-Header vorhanden und korrekt formatiert? Sowohl das Schema als auch der Schlüssel sind wichtig. - Wurde der Schlüssel im Dashboard widerrufen oder rotiert?
- Greifen Sie auf die richtige Basis-URL für Ihr Konto zu?
401 oder 403 bedeutet fast immer eine dieser vier Situationen. Der Schlüssel selbst ist selten das Problem – meist liegt es an der Art, wie er übergeben wird.
Fehlerhaft formatierter Anfragekörper
Fehler der 400er-Klasse bedeuten meist, dass die API Ihren Anfragekörper nicht parsen oder validieren kann:
- Ungültiges JSON – überzählige Kommas, einfache statt doppelte Anführungszeichen oder nicht escapte Zeichen. Die Ausgabe von curl durch
python -m json.toolzu leiten und den Anfragekörper im Code statt manuell zu erstellen, hilft beides. - Fehlende Pflichtfelder –
modelundpromptwerden am häufigsten vergessen; senden Sie beide jedes Mal explizit. - Unbekannte oder nicht unterstützte Felder – strikte APIs lehnen Felder ab, die sie nicht kennen. Entfernen Sie alles Überflüssige, bis die Anfrage durchgeht, und fügen Sie dann jeweils ein Feld wieder hinzu.
- Falsche Werttypen – Zahlen als Strings gesendet oder ein Array, wo ein einzelner Wert erwartet wird. Halten Sie sich strikt an die Typen in der Dokumentation.
Schlechte Bildeingaben
Betrifft nur Bild-zu-Bild, ist aber im Fehlerfall am frustrierendsten: Bild-URLs, die eine Authentifizierung erfordern, URLs hinter Weiterleitungen, URLs, die HTML statt eines Bildes zurückgeben, übermäßig große Dateien oder nicht unterstützte Formate. Stellen Sie sicher, dass die URL in einem Browser ohne Anmeldung direkt lädt, und prüfen Sie Dateityp und -größe vor dem Senden anhand der Beschränkungen.
Eine effektive Debugging-Reihenfolge
- Lesen Sie die Fehlermeldung und den Statuscode wörtlich – sie benennen das Problem meist direkt.
- Reproduzieren Sie die fehlgeschlagene Anfrage in curl mit minimalen Feldern und fügen Sie dann schrittweise Komplexität hinzu.
- Drucken Sie den vollständigen Antwortkörper vor der Verarbeitung; verlassen Sie sich nicht auf Annahmen über seine Struktur.
Wenn der minimierte curl-Aufruf erfolgreich ist und Ihre Anwendung fehlschlägt, liegt der Defekt in Ihrem Code, nicht in der API. Das ist die schnellste mögliche diagnostische Abgrenzung.
In Ihre Anwendung integrieren
Eine funktionierende Anfrage ist ein guter Anfang; eine zuverlässige Integration braucht ein wenig mehr drumherum. So kommen Sie von einem einmaligen Aufruf zu etwas, auf das Sie sich verlassen können.
Den Aufruf in eine Funktion kapseln
Isolieren Sie die Anfrage in einer Funktion, die einen Prompt (optional ein Referenzbild) entgegennimmt und das Ergebnis zurückgibt. Legen Sie Header, Basis-URL und Aufbau des Anfragekörpers in diese Funktion, sodass der Rest Ihrer Codebasis nie damit in Berührung kommt. Wenn sich die API ändert, bearbeiten Sie nur eine Stelle.
Wiederholungen bewusst handhaben
Die Generierung kann aus Gründen vorübergehend fehlschlagen, die nichts mit Ihrem Anfragekörper zu tun haben. Verwenden Sie Wiederholungen mit exponentiellem Backoff, aber nur bei wiederholbaren Fehlern – Timeouts und bestimmte serverseitige Fehler. Wiederholen Sie niemals Authentifizierungs- oder Anfragekörper-Validierungsfehler; sie schlagen jedes Mal gleich fehl und erhöhen nur die Last. Begrenzen Sie die Anzahl der Versuche, damit anhaltende Probleme sichtbar werden, statt hängen zu bleiben.
Timeouts und Nebenläufigkeit
Legen Sie einen für die Generierung großzügigen, aber begrenzten Timeout fest und passen Sie ihn nach Messung der tatsächlichen Antwortzeiten an. Wenn Sie viele Anfragen senden, halten Sie sich an vernünftige Nebenläufigkeitsgrenzen, statt alle auf einmal abzusenden – eine Warteschlange mit einem Worker-Pool ist vorhersehbarer als unbegrenzte parallele Aufrufe.
Speichern, was Sie generieren
Die Antwort liefert Ihnen das generierte Bild. Kopieren Sie es zeitnah in Ihren eigenen Speicher, statt sich darauf zu verlassen, dass die zurückgegebene URL unbegrenzt gültig bleibt. Benennen Sie Dateien deterministisch und protokollieren Sie Prompt und Parameter neben jeder Ausgabe – diese Herkunftsinformation werden Sie beim späteren Iterieren von Prompts benötigen.
Den Schlüssel aus dem Code heraushalten
Lesen Sie den API-Schlüssel in jeder Umgebung aus Umgebungsvariablen oder einem Secret Manager. Rotieren Sie Schlüssel regelmäßig. Wenn ein Schlüssel an einer Stelle auftaucht, an der er nicht hingehört, widerrufen Sie ihn im Dashboard.
Klein anfangen, dann erweitern
Bringen Sie einen Prompt in curl zum Laufen, portieren Sie ihn nach Python, fügen Sie die Fehlerbehandlung aus dem vorigen Abschnitt hinzu und bauen Sie erst dann die umgebenden Warteschlangen und Speichermechanismen. Jeder Schritt liefert den Nachweis für den vorherigen.
Mit einem verifizierten curl-Aufruf, einem passenden Python-Client und den behandelten drei Fehlerkategorien haben Sie den vollständigen Weg vom ersten Aufruf bis zur Produktionsintegration.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen