Zum Hauptinhalt springen
Dieser Artikel beschreibt die Integration und Nutzung der Nano Banana Images API. Diese Schnittstelle unterstützt zwei Funktionen: Bildgenerierung (generate) und Bildbearbeitung (edit).

​
Antragsprozess

Vor der Nutzung bitte im Ace Data Cloud Plattform Nano Banana Images API aufrufen und auf Acquire klicken, um die Aktivierung zu beantragen. Bei der ersten Anfrage stehen in der Regel kostenlose Kontingente zur Verfügung. Nach der Aktivierung können Sie das Bearer Token zur API-Nutzung auf der Plattform abrufen.

​
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: Generierung von Bildern basierend auf Textvorgaben
    • edit: Bearbeitung basierend auf gegebenen Bildern
  • Modell (model) (optional):
    • nano-banana (Standard): Basierend auf Gemini 2.5 Flash Image, schnell und kostengünstig
    • 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
  • Asynchrone Rückmeldung: Optional, um über callback_url Benachrichtigungen und Ergebnisse über den Abschluss der Aufgabe zu erhalten

​
Schnellstart: Bild generieren (action=generate)

Minimale erforderliche Parameter: action, prompt Wenn Sie nur ein Bild basierend auf einer Vorgabe generieren möchten, setzen Sie action auf generate und geben Sie eine klare prompt an.

​
Anfragebeispiel (cURL)

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "prompt": "Ein fotorealistisches Nahaufnahme-Porträt eines älteren japanischen Keramikkünstlers mit tiefen, sonnengeätzten Falten und einem warmen, wissenden Lächeln. Er inspiziert sorgfältig eine frisch glasierte Teeschale. Der Ort ist seine rustikale, sonnenverwöhnte Werkstatt. Die Szene wird von sanftem, goldenem Licht der goldenen Stunde erleuchtet, das durch ein Fenster strömt und die feine Textur des Tons hervorhebt. Mit einem 85-mm-Porträtobjektiv aufgenommen, was zu einem sanften, verschwommenen Hintergrund (Bokeh) führt. Die Gesamtstimmung ist friedlich und meisterhaft. Vertikale Porträtorientierung.",
    "count": 1
  }'

​
Anfragebeispiel (Python)

import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "generate",
    "prompt": (
        "Ein fotorealistisches Nahaufnahme-Porträt eines älteren japanischen Keramikkünstlers "
        "mit tiefen, sonnengeätzten Falten und einem warmen, wissenden Lächeln. Er inspiziert sorgfältig "
        "eine frisch glasierte Teeschale. Der Ort ist seine rustikale, sonnenverwöhnte "
        "Werkstatt. Die Szene wird von sanftem, goldenem Licht der goldenen Stunde erleuchtet, das durch "
        "ein Fenster strömt und die feine Textur des Tons hervorhebt. Mit einem 85-mm "
        "Porträtobjektiv aufgenommen, was zu einem sanften, verschwommenen Hintergrund (Bokeh) führt. Die Gesamtstimmung "
        "ist friedlich und meisterhaft. Vertikale Porträtorientierung."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

​
Erfolgreiche Rückgabe Beispiel

{
  "success": true,
  "task_id": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "data": [
    {
      "prompt": "Ein fotorealistisches Nahaufnahme-Porträt eines älteren japanischen Keramikkünstlers mit tiefen, sonnengeätzten Falten und einem warmen, wissenden Lächeln. Er inspiziert sorgfältig eine frisch glasierte Teeschale. Der Ort ist seine rustikale, sonnenverwöhnte Werkstatt. Die Szene wird von sanftem, goldenem Licht der goldenen Stunde erleuchtet, das durch ein Fenster strömt und die feine Textur des Tons hervorhebt. Mit einem 85-mm-Porträtobjektiv aufgenommen, was zu einem sanften, verschwommenen Hintergrund (Bokeh) führt. Die Gesamtstimmung ist friedlich und meisterhaft. Vertikale Porträtorientierung.",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/69790adb-c85d-4362-ad9e-0c9ba4352cf4.png"
    }
  ]
}

​
Feldbeschreibung

  • success: Ob die Anfrage erfolgreich war.
  • task_id: Aufgaben-ID.
  • trace_id: Verfolgungs-ID, um Probleme zu identifizieren.
  • data[]: Ergebnisliste.
    • prompt: Die zur Generierung verwendete Vorgabe (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 T-Shirts bereitstellen, um die Person in diesem T-Shirt zu zeigen. 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....

​
Anfragebeispiel (cURL)

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "prompt": "lass diesen Mann dieses T-Shirt tragen",
    "image_urls": [
      "https://cdn.acedata.cloud/v8073y.png",
      "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
  }'

​
Anfragebeispiel (Python)

import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "edit",
    "prompt": "lass diesen Mann dieses T-Shirt tragen",
    "image_urls": [
        "https://cdn.acedata.cloud/v8073y.png",
        "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

​
Erfolgreiche Rückgabe Beispiel

{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "lass diesen Mann dieses T-Shirt tragen",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}

​
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 der „Bildgenerierung“.

​
Asynchrone Rückrufe (optional, empfohlen)

Die Generierung oder Bearbeitung kann eine gewisse Zeit in Anspruch nehmen. Um zu vermeiden, dass lange Verbindungen Ressourcen beanspruchen, 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 task_id zurückgeben (oder mit grundlegenden Ergebnissen).
  3. Wenn die Aufgabe abgeschlossen ist, sendet die Plattform das vollständige JSON über POST an callback_url. Sie können die Anfrage mit dem Ergebnis über task_id verknüpfen.
Beispiel für Rückrufpayload (Feldstruktur entspricht der synchronen Erfolgsantwort): 
{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "eine weiße Siamkatze",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}

​
Fehlerbehandlung

Bei einem fehlgeschlagenen Aufruf wird ein standardmäßiges Fehlerformat mit einer 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 Support kontaktieren).
  • 401 invalid_token: Authentifizierung fehlgeschlagen oder Token fehlt.
  • 429 too_many_requests: Anfragerate überschreitet das Limit.
  • 500 api_error: Serverfehler.

​
Beispiel für Fehlerantwort

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Interner Serverfehler."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Parameterübersicht und Hinweise

  • Pflichtfelder: action, prompt
  • Bearbeitungsspezifisch: image_urls (Array, mindestens 1 Eintrag)
  • Optional: model (Standard nano-banana, optional nano-banana-2 oder nano-banana-pro), aspect_ratio (Seitenverhältnis, z. B. 1:1, 16:9), resolution (Auflösung, z. B. 1K, 2K, 4K), callback_url (für asynchrone Rückrufe)
  • Headers: authorization: Bearer {token} muss bereitgestellt werden; accept sollte auf application/json gesetzt werden
  • Zugänglichkeit von Bildern: 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 Verknüpfung von Ergebnissen zu erleichtern