Nano Banana API-Leitfaden: Aufruf von nano-banana, nano-banana-2 und nano-banana-pro auf HiAPI

Was die Nano-Banana-Modellfamilie bietet

Bildgenerierung bleibt selten bei einer einzigen Einstellung. In der frühen Projektphase braucht man schnelle Entwürfe, um Ideen zu erkunden; später präzise Renderings für die Auslieferung. Die Nano-Banana-Familie auf HiAPI ist genau um diese Realität herum gebaut: eine Schnittstelle, drei Varianten, jede auf einen anderen Punkt auf der Kurve zwischen Qualität und Geschwindigkeit abgestimmt.

Die Benennung ist bewusst gewählt. nano-banana ist die Basisoption – verwenden Sie sie, wenn Sie beim Ausarbeiten von Prompts oder Layouts noch schnelles visuelles Feedback benötigen. nano-banana-2 geht bei Treue und Prompt-Befolgung einen Schritt weiter und ist meist die Wahl, wenn die Ausgabe fast final ist, Sie aber noch weiter iterieren möchten. nano-banana-pro ist die treueste Variante der Familie und eignet sich für finale Renderings, bei denen Details und Komposition am wichtigsten sind.

Was sie teilen, ist ebenso wichtig wie das, was sie unterscheidet. Alle drei werden über denselben HiAPI-Endpunkt aufgerufen. Sie authentifizieren sich einmal, bauen die Anfrage einmal auf und ändern beim Wechsel nur den Modellbezeichner. Das bedeutet, eine Anwendung kann Anfragen mit dem Basismodell starten und später denselben Prompt mit einer stärkeren Variante erneut ausführen, ohne den Transportcode anzupassen.

Eine solche Familie hält auch Ihre Architektur einfach. Statt für jede Qualitätsstufe einen separaten Anbieter anzubinden, behalten Sie einen einzigen Client, einen einzigen Fehlerbehandlungspfad und einen einzigen Beobachtungspunkt für die Nutzung. Die Modellwahl wird zu einem Parameter statt zu einer Integration.

Warum eine Familie statt eines einzelnen Modells

Verschiedene Schritte im Workflow haben unterschiedliche Anforderungen. Prompt-Erkundung, Layout-Entwürfe und Kunden-Vorschauen legen Wert auf Geschwindigkeit; Key Visuals und Marketingmaterialien auf Treue. Wenn Sie die Modellwahl als Laufzeitentscheidung behandeln, können Sie jeden Schritt der passenden Variante zuordnen, ohne die Pipeline neu aufzubauen.

Auswahl zwischen nano-banana, nano-banana-2 und nano-banana-pro

Wählen Sie die Variante, indem Sie zwei Fragen stellen: Wie nah ist diese Ausgabe an der finalen Version, und wie viele Versuche braucht es dorthin? Alles Weitere folgt daraus.

nano-banana: für Batch-Verarbeitung und Erkundung

Verwenden Sie das Basismodell, solange Sie noch entscheiden, wie das Bild aussehen soll. Prompt-Umformulierungen, Stiltests und Layout-Miniaturen profitieren von schneller Bearbeitung, und grobe Renderings beantworten Ihre Fragen oft besser als eine Beschreibung. Behalten Sie es während der Entwicklung als Standardoption bei.

nano-banana-2: für die Iteration nahe am Finale

Wechseln Sie zu nano-banana-2, wenn die Komposition stabil ist und Sie Details verfeinern – Abstände, Subjekttreue, wie eng die Ausgabe dem Prompt folgt. Dies ist die pragmatische Mittelwahl: deutlich stärkere Befolgung, ohne für jede Vorschau den Weg der höchsten Treue zu gehen.

nano-banana-pro: für finale Renderings

Bewahren Sie nano-banana-pro für Ausgaben auf, die ausgeliefert werden. Key Visuals, Produktbilder und alles, was Kunden genau prüfen, verdienen die stärkere Variante. Machen Sie sie nicht zum Standard – sparen Sie sie für den letzten Schritt auf, damit Ihre erkundenden Iterationen kostengünstig bleiben.

Eine praktische Routing-Regel

Eine einfache Eskalationsstrategie funktioniert für die meisten Teams:

• Alle neuen Prompts standardmäßig mit nano-banana starten.
• Wenn die Struktur stimmt, aber die Qualität nicht ausreicht, den Prompt auf nano-banana-2 hochstufen.
• Sobald der Prompt feststeht, die finale Version einmal mit nano-banana-pro ausführen.

So bleiben Iterationen schnell und vorhersehbar, und Ihre Nutzungsmuster sind leicht nachvollziehbar. Die Abrechnung folgt der Nutzung und variiert je nach Variante; prüfen Sie daher die aktuellen Tarife und Limits in der Live-Modell-Dokumentation, statt Zahlen im Code fest zu verdrahten.

Varianteübergreifende Prompt-Muster

Das Teuerste, was Sie tun können, ist, Prompts zu schreiben, die nur bei einem Modell funktionieren. Gestalten Sie sie so, dass eine einzeilige Änderung zum Wechsel ausreicht.

Der vierteilige Prompt

Schreiben Sie jeden Prompt als vier gekennzeichnete Abschnitte, in dieser Reihenfolge:

1. Subjekt – was im Bild ist, schlicht ausgedrückt.
2. Stil – die visuelle Behandlung: Foto, Illustration, Aquarell, 3D-Rendering.
3. Komposition – Bildausschnitt, Kamerawinkel, Position, Negativraum.
4. Einschränkungen – was vermieden werden soll und alle harten Anforderungen.

Ein ausgefülltes Beispiel:

Subject: a ceramic coffee mug on a wooden desk, steam rising
Style: soft natural light, shallow depth of field, editorial photography
Composition: centered, 50mm equivalent, generous negative space at top
Constraints: no text, no logos, neutral background

Da die Abschnitte unabhängig voneinander sind, können Sie den Stil verstärken oder die Komposition lockern, ohne den gesamten Prompt neu zu schreiben – und die gleiche Struktur ist für jede Variante der Familie leicht verständlich.

Prompts modellunabhängig halten

Vermeiden Sie Formulierungen, die eine bestimmte Modelleigenschaft voraussetzen. Beschreiben Sie das gewünschte Ergebnis, nicht die Schritte, die ein konkretes Modell gehen soll. Wenn Sie Varianten vergleichen müssen, ändern Sie nur die Modell-ID und halten den Prompt bytegenau identisch, damit der Vergleich aussagekräftig ist.

Prompts wie Code versionieren

Speichern Sie Prompts als Strings in einer Konfigurationsdatei oder einer kleinen Prompt-Bibliothek, indiziert nach Name und Version. Wenn eine Variante durch eine Feinabstimmung bessere Ausgaben liefert, dokumentieren Sie die Änderung. Genau das ermöglicht es, Prompts bei der Auslieferung von nano-banana auf nano-banana-pro zu migrieren, ohne Überraschungen.

Negative Einschränkungen sind wichtig

Wenn ein Prompt immer wieder Text, Logos oder unerwünschte Objekte erzeugt, nehmen Sie diese ausdrücklich in den Einschränkungsabschnitt auf. Über Varianten hinweg sind klare negative Einschränkungen oft zuverlässiger als clevere Formulierungen.

Funktionierende Anfragen auf HiAPI aufbauen

Jede Variante wird über denselben HiAPI-Endpunkt aufgerufen. Eine Anfrage hat vier variable Teile: die Basis-URL, den Authentifizierungs-Header, das Modellfeld und die Payload.

Die Form der Anfrage

Ein minimaler Bildgenerierungsaufruf sieht so aus:

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",
    "prompt": "Subject: a ceramic coffee mug on a wooden desk, steam rising\nStyle: soft natural light, editorial photography\nComposition: centered, negative space at top\nConstraints: no text, no logos",
    "n": 1
  }'

Bewahren Sie den API-Schlüssel in einer Umgebungsvariable oder einem Secret-Manager auf – niemals im Quellcode. Das Feld model ist das Einzige, was beim Wechsel der Variante geändert werden muss; das Feld prompt trägt die vierteilige Struktur aus dem vorigen Abschnitt.

In Python benötigt derselbe Aufruf nur wenige Zeilen:

import os, requests

def generate(prompt, model="nano-banana-2"):
    resp = requests.post(
        "https://api.hiapi.ai/v1/images/generations",
        headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
        json={"model": model, "prompt": prompt, "n": 1},
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()

Was die Antwort enthält

Die Antwort enthält das Bildergebnis – üblicherweise eine URL oder eine kodierte Payload – sowie Metadaten, die das Modell kennzeichnen, das die Anfrage verarbeitet hat. Lesen Sie das Modellfeld zurück und protokollieren Sie es: Das ist die günstigste Art, im Nachhinein festzustellen, welche Variante ein bestimmtes Asset erzeugt hat.

Parameter vor der Auslieferung bestätigen

Die genaue Menge optionaler Parameter variiert je nach Variante und entwickelt sich mit der Zeit weiter. Bevor Sie etwas anderes als model und prompt fest verdrahten, prüfen Sie die Live-Modell-Dokumentation auf aktuelle Feldnamen und zulässige Werte. Behandeln Sie alles, was nicht dokumentiert ist, als nicht unterstützt, statt zu raten.

Antworten, Fehler und Wiederholungen behandeln

Bildgenerierung ist ein Netzwerkaufruf mit einem Modell dahinter, also planen Sie die fehleranfälligen Teile mit ein.

Erst validieren, dann vertrauen

Prüfen Sie nach jeder Antwort drei Dinge: den HTTP-Status, ob eine Bild-Payload vorhanden ist und ob das zurückgegebene Modell mit dem angeforderten übereinstimmt. Lassen Sie jede Abweichung ausdrücklich fehlschlagen, statt fehlerhafte Assets weiterzugeben.

Nur wiederholungswürdige Fehler wiederholen

Nicht jeder Fehler ist es wert, wiederholt zu werden. Ein fehlerhafter Prompt oder ein ungültiger Modellname schlägt jedes Mal auf die gleiche Weise fehl – korrigieren Sie die Anfrage. Vorübergehende Fehler wie Timeouts, Verbindungsabbrüche und Rate-Limit-Antworten verdienen eine Wiederholung.

Verwenden Sie begrenztes exponentielles Backoff mit Jitter:

import time, random

def call_with_retry(fn, retries=3):
    for attempt in range(retries):
        try:
            return fn()
        except (TimeoutError, ConnectionError):
            if attempt == retries - 1:
                raise
            time.sleep((2 ** attempt) + random.random())

Begrenzen Sie die Gesamtzahl der Versuche, damit eine fehlerhafte Anfrage nicht endlos läuft, und protokollieren Sie Modell und Prompt-Hash jedes Versuchs, um zu erkennen, ob eine bestimmte Variante instabil ist.

Bewusstes Fallback

Wenn eine Variante wiederholt fehlschlägt, kann ein Fallback auf ein anderes Mitglied der Familie die Pipeline am Leben halten. Da alle drei dieselbe Anfrageform teilen, ist der Fallback lediglich ein anderer model-Wert beim erneuten Versuch. Legen Sie die Reihenfolge im Voraus fest – zum Beispiel von nano-banana-pro auf nano-banana-2 zurückfallen, wenn Aufrufe mit hoher Treue wiederholt fehlschlagen – und protokollieren Sie, wann ein Fallback ausgelöst wird, damit Sie Muster bemerken.

Fehler sichtbar machen

Validieren Sie die zurückgegebene Payload, bevor Sie sie speichern, und stellen Sie Metriken für Wiederholungen und Fallbacks bereit. Wenn die Fehlerrate steigt, möchten Sie das wissen, bevor ein Stapel von Aufgaben stillschweigend leere Ergebnisse produziert.

Härtung vor der Auslieferung

Gehen Sie diese Checkliste durch, bevor Sie die Bildgenerierung Nutzern zugänglich machen.

IDs und Parameter bestätigen

Modellbezeichner ändern sich. Prüfen Sie die aktuellen Modellnamen der Nano-Banana-Familie erneut und bestätigen Sie jeden optionalen Parameter anhand der Live-Dokumentation. Liefern Sie keine Werte aus, die nur in alten Beispielen existieren.

Konfiguration zentralisieren

Legen Sie Modell-IDs, Prompt-Vorlagen und Wiederholungslimits in einem Konfigurationsmodul ab. Wenn Sie einen Prompt von nano-banana auf nano-banana-pro hochstufen, sollte das eine Konfigurationsänderung sein und keine Codeänderung, die über mehrere Dateien verstreut ist.

Wichtige Informationen protokollieren

Protokollieren Sie für jeden Aufruf Modell, Prompt-Version, Antwortstatus, Latenz sowie ob eine Wiederholung oder ein Fallback stattgefunden hat. Hashen Sie lange Prompts, damit die Logs lesbar bleiben. Genau das ermöglicht die Antwort auf die Frage „Warum sah dieses Bild gestern anders aus?“

Nutzung beim Skalieren überwachen

Da die Abrechnung der Nutzung folgt, achten Sie auf Aufrufzahlen und die Variantenzusammensetzung. Wenn jede Anfrage stillschweigend auf nano-banana-pro hochgestuft wird, kann aus einem Erkundungswerkzeug ein Kostenproblem werden. Routen Sie bewusst: günstige Varianten für Iterationen, stärkere Varianten für die finale Ausgabe.

Den Endpunkt testen

Schreiben Sie einen kleinen Smoke-Test, der jede Variante einmal mit einem festen Prompt aufruft und eine gültige Antwort prüft. Führen Sie ihn vor jeder Veröffentlichung gegen die aktuelle Dokumentation aus, damit Modelländerungen Sie nie unvorbereitet in der Produktion überraschen.

Mit einem einzigen Client, einer gemeinsamen Prompt-Bibliothek und einer bewussten Routing-Strategie wird die Nano-Banana-Familie auf HiAPI Ihre einzige Abhängigkeit, um vom Entwurf bis zum finalen Rendering zu skalieren, ohne die Integration neu zu schreiben.