Skip to main content
Dieser Artikel beschreibt die Integration und Nutzung der Nano Banana Images API. Diese Schnittstelle unterstützt zwei Funktionen: Bildgenerierung (generate) und Bildbearbeitung (edit).

Antragsprozess

Um die Nano Banana Images API zu nutzen, müssen Sie zunächst Ihr API-Token im Ace Data Cloud Dashboard abrufen und für zukünftige Verwendung aufbewahren. Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach Abschluss werden Sie automatisch zur aktuellen Seite zurückgeleitet. Ein API-Token reicht aus, um alle Dienste der Plattform zu nutzen, es ist nicht erforderlich, für jeden Dienst separat zu beantragen. Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, um die Dienste kostenlos auszuprobieren; wenn das Kontingent erschöpft ist, können Sie im Dashboard Ihr Guthaben aufladen.
📘 Vollständige Dokumentation: Nano Banana Images API →

Schnittstellenübersicht

  • Basis-URL: https://api.acedata.cloud
  • Endpunkt: POST /nano-banana/images
  • Authentifizierungsmethode: HTTP-Header mit authorization: Bearer {token}
  • Anforderungsheader:
    • accept: application/json
    • content-type: application/json
  • Aktion (action):
    • generate: Bild basierend auf Textvorgaben generieren
    • edit: Bild basierend auf einem gegebenen Bild bearbeiten
  • Modell (model) (optional):
    • nano-banana (Standard): Basierend auf Gemini 2.5 Flash Image, schnell und kostengünstig
    • nano-banana-2-lite: Basierend auf Gemini 3.1 Flash Lite Image, unterstützt nur 1K, schnelle Generierung
    • nano-banana-2: Basierend auf Gemini 3.1 Flash Image Preview, Pro-Qualität + Flash-Geschwindigkeit
    • nano-banana-pro: Basierend auf Gemini 3 Pro Image Preview, höchste Qualität
    • nano-banana:official, nano-banana-2-lite:official, nano-banana-2:official, nano-banana-pro:official: Offizielle Versionen der entsprechenden Modelle, bessere Bildqualität und Stabilität, unterschiedliche Abrechnung
  • Asynchrone Rückrufe: Optional, um über callback_url Benachrichtigungen über den Abschluss von Aufgaben und Ergebnisse zu erhalten
  • Bildanzahl: Optional, durch count 1–4 Bilder angeben, Standard ist 1 Bild; bei teilweise fehlerhaften Anfragen werden nur erfolgreiche Bilder zurückgegeben und abgerechnet

Schnellstart: Bild generieren (action=generate)

Minimale erforderliche Parameter: action, prompt Wenn Sie nur ein Bild basierend auf den Vorgaben generieren möchten, setzen Sie action auf generate und geben Sie ein klares prompt an.

Anforderungsbeispiel (cURL)

Anforderungsbeispiel (Python)

Erfolgreiche Rückgabe Beispiel

Feldbeschreibung

  • success: Ob die Anfrage erfolgreich war.
  • task_id: Aufgaben-ID.
  • trace_id: Verfolgungs-ID, um Probleme zu diagnostizieren.
  • count: Anzahl der angeforderten generierten oder bearbeiteten Bilder, unterstützt 1–4, Standard ist 1. Bei teilweise fehlerhaften Anfragen enthält data nur erfolgreiche Bilder.
  • data[]: Ergebnisliste.
    • prompt: Die zur Generierung verwendeten Vorgaben (Echo).
    • image_url: Direkter URL-Link zum generierten Bild.
Hinweis: /nano-banana/images benötigt nur action und prompt, um ein Bild zu generieren.

Bild bearbeiten (action=edit)

Wenn Sie ein vorhandenes Bild bearbeiten möchten, setzen Sie action auf edit und übergeben Sie eine Liste von Bild-URLs (1 oder mehrere) über image_urls, während Sie eine Beschreibung des Bearbeitungsziels in prompt angeben. Zum Beispiel können wir hier ein Foto einer Person und ein Foto eines Kleidungsstücks bereitstellen, um die Person in diesem Kleidungsstück darzustellen. Sie können die Bild-URLs gleichzeitig übergeben und die Aktion auf edit setzen. Die URLs können HTTP-URLs sein, die über das https- oder http-Protokoll öffentlich zugänglich sind, oder auch Base64-kodierte Bilder, wie data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....

Anforderungsbeispiel (cURL)

Anforderungsbeispiel (Python)

Erfolgreiche Rückgabe Beispiel

Feldbeschreibung

  • image_urls[]: Liste der URLs der zu bearbeitenden Bilder (muss öffentlich zugänglich sein). Es können mehrere Bilder übergeben werden, der Dienst wird diese Materialien mit dem prompt kombinieren, um die Bearbeitung abzuschließen.
  • Die anderen Felder sind wie bei der Rückgabe „Bild generieren“.

Asynchrone Rückrufe (optional, empfohlen)

Die Generierung oder Bearbeitung kann eine gewisse Zeit in Anspruch nehmen. Um lange Verbindungen zu vermeiden, wird empfohlen, über callback_url Webhook-Rückrufe zu verwenden:
  1. Fügen Sie im Anfragekörper callback_url hinzu, z. B. die Webhook-Adresse Ihres Servers (muss öffentlich zugänglich sein, unterstützt POST JSON).
  2. Die API wird sofort eine Antwort mit der task_id zurückgeben (oder mit den grundlegenden Ergebnissen).
  3. Wenn die Aufgabe abgeschlossen ist, sendet die Plattform das vollständige JSON per POST an die callback_url. Sie können die Anfrage mit dem Ergebnis über die task_id verknüpfen.
Beispiel für Rückrufpayload (Feldstruktur entspricht der synchronen erfolgreichen Rückgabe):

Fehlerbehandlung

Bei einem fehlgeschlagenen Aufruf wird ein Standardfehlerformat mit der Verfolgungs-ID zurückgegeben. Häufige Fehler sind:
  • 400 token_mismatched: Anfrage ist ungültig oder Parameterfehler.
  • 400 api_not_implemented: Schnittstelle nicht implementiert (bitte kontaktieren Sie den Support).
  • 401 invalid_token: Authentifizierung fehlgeschlagen oder Token fehlt.
  • 429 too_many_requests: Anfragerate überschreitet das Limit.
  • 500 api_error: Serverfehler.

Fehlerantwort Beispiel


Parameterübersicht und Hinweise

  • Pflichtfelder: action, prompt
  • Bearbeitungsspezifisch: image_urls (Array, mindestens 1 Element)
  • Optional: model (Standard nano-banana, optional nano-banana-2-lite, nano-banana-2, nano-banana-pro oder entsprechende :official offizielle Kanalversion), aspect_ratio (Seitenverhältnis, z. B. 1:1, 16:9), resolution (Auflösung, z. B. 1K, 2K, 4K; nano-banana-2-lite unterstützt nur 1K), callback_url (für asynchrone Rückrufe)
  • Headers: authorization: Bearer {token} muss bereitgestellt werden; accept sollte auf application/json gesetzt werden
  • Zugänglichkeit der Bilder: image_urls müssen direkte Links sein, die öffentlich zugänglich sind (HTTP/HTTPS), es wird empfohlen, HTTPS zu verwenden
  • Idempotenz und Verfolgung: Bewahren Sie task_id und trace_id auf, um die Fehlersuche und die Zuordnung von Ergebnissen zu erleichtern