Anleitung zur Integration der Nano Banana Images API

​

Antragsprozess

📘 Vollständige Dokumentation: Nano Banana Images API →

​

Schnittstellenübersicht

• Base URL: https://api.acedata.cloud
• Endpoint: POST /nano-banana/images
• Authentifizierungsmethode: authorization: Bearer {token} im HTTP-Header mitführen
• Request-Header:
  • accept: application/json
  • content-type: application/json
• Aktion (action):
  • generate: Bilder anhand von Text-Prompts generieren
  • edit: Bilder auf Grundlage vorgegebener Bilder bearbeiten
• Modell (model) (optional):
  • nano-banana (Standard): Basiert auf Gemini 2.5 Flash Image, schnell und kostengünstig
  • nano-banana-2-lite: Basiert auf Gemini 3.1 Flash Lite Image, unterstützt nur 1K und generiert schnell
  • nano-banana-2: Basiert auf Gemini 3.1 Flash Image Preview, Pro-Qualität + Flash-Geschwindigkeit
  • nano-banana-2.1: Effizientes Bildmodell der neuen Generation, unterstützt 1K-, 2K- und 4K-Bildgenerierung und -bearbeitung
  • nano-banana-pro: Basiert 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 Kanalversionen der entsprechenden Modelle, mit besserer Bildqualität und Stabilität sowie abweichender Abrechnung
• Asynchroner Callback: Optional, über callback_url können Benachrichtigungen über den Aufgabenabschluss und Ergebnisse empfangen werden
• Bildanzahl: Optional, über count können 1–4 Bilder angegeben werden, Standard ist 1 Bild; jedes Bild wird durch einen unabhängigen Generierungsaufruf erstellt; gewöhnliche technische Fehler oder Sicherheitsablehnungen des Anbieters betreffen nur den jeweiligen Aufruf, während andere erfolgreich generierte Bilder normal zurückgegeben und nach der tatsächlich erfolgreichen Bildanzahl abgerechnet werden

​

Schnellstart: Bilder generieren (action=generate)

​

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",
    "model": "nano-banana-pro",
    "prompt": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
    "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",
    "model": "nano-banana-pro",
    "prompt": (
        "A photorealistic close-up portrait of an elderly Japanese ceramicist "
        "with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully "
        "inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched "
        "workshop. The scene is illuminated by soft, golden hour light streaming through "
        "a window, highlighting the fine texture of the clay. Captured with an 85mm "
        "portrait lens, resulting in a soft, blurred background (bokeh). The overall mood "
        "is serene and masterful. Vertical portrait orientation."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

​

Beispiel einer erfolgreichen Antwort

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
      "image_url": "https://cdn.acedata.cloud/assets/examples/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336-34b3dc2195e8.png"
    }
  ]
}

​

Feldbeschreibung

• success: Ob diese Anfrage erfolgreich war.
• task_id: Aufgaben-ID.
• trace_id: ID zur Ablaufverfolgung, die die Fehlerbehebung erleichtert.
• count: Anzahl der zur Generierung oder Bearbeitung angeforderten Bilder, unterstützt 1–4, Standard ist 1. data enthält nur erfolgreich generierte Bilder, und die Abrechnung erfolgt gemäß der tatsächlich zurückgegebenen Anzahl. Jeder Generierungsaufruf verwendet zwingend die nativen Sicherheitsrichtlinien des Anbieters; die Ablehnung eines Aufrufs beeinträchtigt keine anderen erfolgreichen Aufrufe. Wenn alle Aufrufe abgelehnt werden, wird 403 zurückgegeben.
• data[]: Ergebnisliste.
  • prompt: Der zur Generierung verwendete Prompt (Echo).
  • image_url: Die direkte URL des generierten Bildes.

Hinweis: Für /nano-banana/images sind zur Bildgenerierung nur action und prompt erforderlich.

​

Bilder bearbeiten (action=edit)

​

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": "let this man wear on this T-shirt",
    "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": "let this man wear on this T-shirt",
    "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())

​

Beispiel für eine erfolgreiche Rückgabe

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

​

Feldbeschreibung

• image_urls[]: URL-Liste der zu bearbeitenden Bilder (muss öffentlich zugänglich sein). Es können mehrere Bilder übergeben werden; der Dienst kombiniert diese Materialien mit prompt, um die Bearbeitung abzuschließen.
• Die übrigen Felder entsprechen der Rückgabe von „Bild generieren“.

​

Asynchroner Rückruf (optional, empfohlen)

1. Füge dem Anfragekörper callback_url hinzu, zum Beispiel die Webhook-Adresse deines Servers (muss öffentlich zugänglich sein und POST JSON unterstützen).
2. Die API gibt sofort eine Antwort mit task_id zurück (oder mit grundlegenden Ergebnissen).
3. Wenn die Aufgabe abgeschlossen ist, sendet die Plattform das vollständige JSON per POST an callback_url. Du kannst die Anfrage und das Ergebnis über task_id verknüpfen.

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}

​

Fehlerbehandlung

• 400 token_mismatched: Die Anfrage ist ungültig oder die Parameter sind fehlerhaft.
• 400 api_not_implemented: Die Schnittstelle ist nicht implementiert (bitte den Support kontaktieren).
• 401 invalid_token: Authentifizierung fehlgeschlagen oder Token fehlt.
• 403 forbidden: Die native Sicherheitsrichtlinie des Anbieters hat die Anfrage oder das Generierungsergebnis abgelehnt. Dieser Aufruf gibt kein Bild zurück und wird nicht abgerechnet; bei Mehrbildanfragen können andere erfolgreiche Aufrufe dennoch zurückgegeben und abgerechnet werden.
• 429 too_many_requests: Das Anfragelimit wurde überschritten.
• 500 api_error: Serverausnahme.

​

Beispiel für eine Fehlerantwort

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

​

Parameterübersicht und Hinweise

• Erforderlich: action, prompt
• Nur für die Bearbeitung: image_urls (Array, mindestens 1 Eintrag)
• Optional: model (standardmäßig nano-banana, optional nano-banana-2-lite, nano-banana-2, nano-banana-2.1, nano-banana-pro; außer für nano-banana-2.1 gibt es auch entsprechende offizielle Kanalversionen mit :official), 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 angegeben werden; accept sollte auf application/json gesetzt werden
• Bildzugänglichkeit: image_urls müssen direkt zugängliche öffentliche Links (HTTP/HTTPS) sein; HTTPS wird empfohlen
• Idempotenz und Nachverfolgung: Bewahre task_id und trace_id auf, um die Fehlerbehebung und Ergebniszuordnung zu erleichtern