> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Nano Banana Images API Integrationsanleitung > Nano Banana Image Generation 集成指南 - XHuoAPI 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 XHuoAPI Plattform [Nano Banana Images API](https://api.xhuoapi.ai/documents/23985a11-d713-41d1-ad84-24b021805b3d) 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.xhuoapi.ai/v1` * **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) ```bash theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/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) ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/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 ```json theme={null} { "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.xhuoapi.ai/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) ```bash theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/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.xhuoapi.ai/v8073y.png", "https://cdn.xhuoapi.ai/44xlah.png" ], "count": 1 }' ``` ### Anfragebeispiel (Python) ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/v8073y.png", "https://cdn.xhuoapi.ai/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.xhuoapi.ai/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): ```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.xhuoapi.ai/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 ```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 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