> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Nano Banana Images API Integrationsanleitung

> Nano Banana Image Generation API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications) abrufen und für zukünftige Verwendung aufbewahren.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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](https://platform.acedata.cloud/console/coin) Ihr Guthaben aufladen.

> 📘 Vollständige Dokumentation: [Nano Banana Images API →](https://platform.acedata.cloud/documents/nano-banana-images)

## 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)

```bash theme={null}
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": "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
  }'
```

### Anforderungsbeispiel (Python)

```python theme={null}
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": (
        "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

```json theme={null}
{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "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://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}
```

### 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)

```bash theme={null}
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
  }'
```

### Anforderungsbeispiel (Python)

```python theme={null}
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

```json theme={null}
{
  "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 „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):

```json theme={null}
{
  "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 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

```json theme={null}
{
  "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 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