> ## 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. # OpenAI Images Edits API Beantragung und Nutzung > OpenAI generation 集成指南 - XHuoAPI Der OpenAI Bildbearbeitungsdienst ermöglicht das Hochladen beliebig vieler Bilder und Anweisungen und gibt die bearbeiteten Bilder aus. Die Schnittstelle unterstützt derzeit gleichzeitig `dall-e-2`, `gpt-image-1`, das neueste **`gpt-image-2`** sowie über dieselbe Schnittstelle angebundene Modelle der **`nano-banana` / `nano-banana-2` / `nano-banana-pro`** Serie. Dieses Dokument beschreibt hauptsächlich den Nutzungsprozess der OpenAI Images Edits API. Damit können wir die offizielle OpenAI Bildbearbeitungsfunktion einfach verwenden. ## Beantragungsprozess Um die OpenAI Images Edits API zu nutzen, können Sie zunächst auf der Seite [OpenAI Images Edits API](https://api.xhuoapi.ai/documents/251f1efa-aaa6-462e-8af4-66854b1bc94d) den Button „Acquire“ anklicken, um die für Anfragen benötigten Zugangsdaten zu erhalten: ![](https://cdn.xhuoapi.ai/nyq0xz.png) Wenn Sie noch nicht eingeloggt oder registriert sind, werden Sie automatisch zur Login-Seite weitergeleitet, um sich zu registrieren und anzumelden. Nach der Anmeldung kehren Sie automatisch auf diese Seite zurück. Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, mit dem Sie die API kostenlos nutzen können. ## GPT-Image-2 Modell `gpt-image-2` bietet im Bildbearbeitungsszenario gegenüber `gpt-image-1` deutliche Verbesserungen: * **Stabilere Struktur**: Beim Ändern von Skin, Farbgebung oder Hintergrund wird das Layout und die Komposition des Originalbildes kaum zerstört. * **Genauere Texterhaltung**: Bei Infografiken, Postern, Menüs und anderen Bildern mit Text bleibt der Text nach der Bearbeitung klar und lesbar. * **Unterstützt direkte URL-Übergabe**: Neben dem traditionellen Upload per `multipart/form-data` unterstützt `gpt-image-2` **zusätzlich die Übergabe von Bild-URLs im JSON-Format**, ohne dass das Bild vorher lokal heruntergeladen werden muss – ideal für serverseitige Pipelines. * **Unterstützt hochauflösendes Neuzeichnen**: Sie können ein 1K-Originalbild hochladen und über den Parameter `size` eine 2K- oder 4K-Ausgabe anfordern; das Modell vergrößert das Bild während der Bearbeitung. ### Unterstützte `size` Werte und Abrechnungsstufen Die Beschränkungen für `size` im Bearbeitungs-API sind identisch mit denen der Generierungs-API – `gpt-image-2` akzeptiert nur `size` als `auto`, leer oder im Format `WIDTHxHEIGHT`. Andere Werte führen zu einem 400 Fehler. Die Abrechnung erfolgt in zwei Stufen, unabhängig von der Originalauflösung, nur basierend auf dem angefragten `size` Wert: * **1K Standardpreis**: Beliebige 1K-Empfehlungsgrößen aus der Tabelle oder gängige 1K-Ausgabe-Aliase (`1254x1254`, `1672x941`, `941x1672`). * **Andere Stufen (1,5×)**: Empfohlene 2K / 4K Voreinstellungen aus der Tabelle sowie beliebige benutzerdefinierte `WIDTHxHEIGHT` Werte. Die gleichen harten Beschränkungen der Original-API gelten: Breite und Höhe müssen Vielfache von 16 sein, die lange Seite ≤ 3840, die Gesamtpixelzahl ≤ 8.294.400. | Seitenverhältnis | 1K (Standardpreis) | 2K Empfehlung (×1,5) | 4K Empfehlung (×1,5) | | ---------------- | ------------------ | -------------------- | -------------------- | | 1:1 | `1024x1024` | `2048x2048` | `2880x2880` | | 4:3 | `1536x1024` | `2048x1536` | `3264x2448` | | 3:4 | `1024x1536` | `1536x2048` | `2448x3264` | | 16:9 | `1792x1024` | `2048x1152` | `3840x2160` | | 9:16 | `1024x1792` | `1152x2048` | `2160x3840` | > Beispiel: Wenn das Originalbild `1024x1024` ist und `size` auf `2048x2048` gesetzt wird, zeichnet das Modell das Bild gemäß der Bearbeitungsanweisung neu und gibt ein 2K-Bild aus, das nach der „anderen“ Stufe abgerechnet wird; bei `3840x2160` wird ein 4K Querformat-Bild ausgegeben, ebenfalls nach „anderer“ Stufe abgerechnet; bei `auto` oder leer erfolgt die Abrechnung zum 1K Standardpreis. > **Zum Parameter `n`** > > Die `gpt-image-2` Bearbeitungs-API **unterstützt derzeit kein `n > 1`**: Dieser Parameter wird stillschweigend ignoriert, egal ob `n=1` oder `n=10` übergeben wird, es wird immer nur ein Bild pro Anfrage zurückgegeben und nur für ein Bild abgerechnet. Wenn Sie mehrere Kandidatenbilder gleichzeitig erhalten möchten, müssen Sie **mehrere Anfragen parallel senden**. Diese Einschränkung gilt auch für `gpt-image-1` / `gpt-image-1.5` sowie die `nano-banana` / `nano-banana-2` / `nano-banana-pro` Serien. `dall-e-2` ist derzeit das einzige native Bearbeitungsmodell, das `n > 1` unterstützt. Im Folgenden zeigen wir anhand zweier realer Beispiele aus unterschiedlichen Perspektiven die Bearbeitungsfähigkeiten von `gpt-image-2`. ### Aufrufmethode 1: JSON + Bild-URL (empfohlen) Senden Sie die Anfrage direkt als `application/json` mit dem Feld `image`, das eine Bild-URL enthält. Das Modell lädt das Bild herunter und bearbeitet es gemäß dem `prompt`. Zum Beispiel ist das folgende Originalbild eine mit `gpt-image-2` generierte Infografik:

Wir möchten es in einen „Nachtmodus“-Farbstil ändern. Der Aufruf sieht so aus: ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "size": "1024x1536" }' ``` Oder mit Python: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Die Rückgabe sieht folgendermaßen aus: ```json theme={null} { "success": true, "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753", "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8", "created": 1777048863, "data": [ { "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "url": "https://platform.cdn.xhuoapi.ai/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` Das bearbeitete Bild sieht so aus:

Man sieht, dass Modulstruktur, Informationsbereiche und Schriftbild strikt erhalten bleiben, nur die Farbgebung wurde in ein dunkles Thema invertiert. > **Hinweis**: Das Feld `image` unterstützt auch ein Array, z. B. `"image": ["url1", "url2", "url3"]`, mit bis zu 16 Referenzbildern, die das Modell bei der Bearbeitung berücksichtigen kann. ### Aufrufmethode 2: JSON + mehrere Referenzbilder `gpt-image-2` unterstützt auch die gleichzeitige Referenzierung mehrerer Bilder zur Erzeugung des Endergebnisses, z. B. das Kombinieren mehrerer Produktfotos in einen Geschenkkorb: ```python theme={null} payload = { "model": "gpt-image-2", "image": [ "https://example.com/item1.png", "https://example.com/item2.png", "https://example.com/item3.png" ], "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.", "size": "1024x1024" } ``` ### Anwendungsbeispiel: Stilwechsel + Struktur erhalten Hier ein weiteres Beispiel, bei dem ein hölzernes Bücherregal durch ein modernes schwebendes Regal ersetzt wird, dabei aber die Anzahl und Anordnung der Bücher auf jeder Ebene strikt erhalten bleibt. Originalbild (mit `gpt-image-2` generiertes hölzernes Regal):

Aufruf: ```python theme={null} payload = { "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png", "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.", "size": "1024x1024" } ``` Bearbeitungsergebnis (`task_id`: `e9544dba-727e-44a2-81e1-223d49869380`):

Man sieht, dass Stil und Umgebung gemäß dem Prompt vollständig ersetzt wurden, aber die Buchanzahl pro Ebene (1 / 3 / 7) strikt erhalten blieb und zusätzlich eine kleine Sukkulente auf dem oberen Regal hinzugefügt wurde. ### Aufrufmethode 3: multipart/form-data (kompatibel mit OpenAI SDK) Wenn Sie bereits das offizielle OpenAI Python SDK verwenden, ist die bisherige Upload-Methode per `multipart/form-data` weiterhin gültig, ändern Sie einfach `model` auf `gpt-image-2`: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() result = client.images.edit( model="gpt-image-2", image=[open("test.png", "rb")], prompt="Convert this image to dark mode while keeping the layout intact." ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) with open("edited.png", "wb") as f: f.write(image_bytes) ``` Beim Einsatz des SDK müssen zwei Umgebungsvariablen gesetzt werden: `OPENAI_BASE_URL` auf `https://api.xhuoapi.ai/v1/openai` und `OPENAI_API_KEY` auf das beantragte Token: ```shell theme={null} export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai export OPENAI_API_KEY={token} ``` ## Nano Banana Serienmodelle Die `nano-banana` Serie ist ebenfalls über `/openai/images/edits` angebunden, ändern Sie einfach `model` auf einen der folgenden Werte: | Modell | Abrechnung (Credits / Anfrage) | Anwendungsbereich | | ----------------- | ------------------------------ | ------------------------------------------------------------------ | | `nano-banana` | 0.14 | Normale Bildbearbeitung, schnellste und kostengünstigste Variante | | `nano-banana-2` | 0.28 | Deutlich verbesserte Qualität und Details | | `nano-banana-pro` | 0.35 | Flaggschiff der Serie, beste Erhaltung von Struktur, Text und Stil | > **Wichtig: Unterstützte Parameter** > > Nano Banana ist über eine Adaptionsschicht an das OpenAI-Protokoll angebunden und unterstützt nur folgende Parameter: `model`, `prompt`, `image`. > > * `image` kann entweder per `multipart/form-data` als Datei hochgeladen werden (intern wird es in `data:;base64,...` umgewandelt und an den Upstream gesendet) oder als Bild-URL-String im Formularfeld. > * Parameter wie `mask`, `n`, `size`, `response_format` werden nicht unterstützt und ignoriert. > * Die Rückgabestruktur folgt dem OpenAI-Format (`data[].url`), `created` ist immer `0`, es gibt kein `b64_json` und `revised_prompt` entspricht immer dem ursprünglichen `prompt`. ### Aufruf per Formular + Bild-URL ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=nano-banana" \ -F "prompt=add a green leaf on top of the apple" \ -F "image=https://platform.cdn.xhuoapi.ai/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` Die Antwort: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.xhuoapi.ai/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg", "revised_prompt": "add a green leaf on top of the apple" } ] } ``` Das bearbeitete Bild:

### Aufruf per Formular + lokale Datei ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/openai/images/edits" headers = { "authorization": "Bearer {token}" } files = { "image": open("apple.png", "rb"), } data = { "model": "nano-banana-pro", "prompt": "add a green leaf on top of the apple" } response = requests.post(url, headers=headers, files=files, data=data) print(response.text) ``` ### Asynchrone Callback Das `callback_url` asynchrone Callback-Verfahren funktioniert auch bei nano-banana, der Ablauf ist identisch mit anderen Modellen, siehe Abschnitt [Asynchrones Callback](#asynchrones-callback). ## Grundlegende Nutzung Nun können Sie die API per Code aufrufen, hier ein Beispiel mit CURL: ```curl theme={null} curl -s -D >(grep -i x-request-id >&2) \ -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \ -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F 'prompt=Create a lovely gift basket with these this items in it' ``` Beim ersten Gebrauch der Schnittstelle müssen mindestens vier Angaben gemacht werden: `authorization` (kann aus Dropdown ausgewählt werden), `model` (Modelltyp, siehe unsere Modellübersicht), `prompt` (Textbeschreibung für die Bildgenerierung) und `image` (Pfad zum zu bearbeitenden Bild). Das Beispielbild sieht so aus:

Das äquivalente Python-Beispiel: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() prompt = """ Generate a photorealistic image of a gift basket on a white background labeled 'Relax & Unwind' with a ribbon and handwriting-like font, containing all the items in the reference pictures. """ result = client.images.edit( model="gpt-image-1", image=[ open("test.png", "rb") ], prompt=prompt ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) # Speichern des Bildes with open("gift-basket.png", "wb") as f: f.write(image_bytes) ``` Für die Python-Nutzung müssen zwei Umgebungsvariablen gesetzt werden: `OPENAI_BASE_URL` auf `https://api.xhuoapi.ai/v1/openai` und `OPENAI_API_KEY` auf das erhaltene Token. Unter Mac OS: ```shell theme={null} export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai export OPENAI_API_KEY={token} ``` Nach dem Aufruf wird im aktuellen Verzeichnis eine Datei `gift-basket.png` erzeugt, das Ergebnis sieht so aus:

Damit haben Sie die Bildbearbeitung erfolgreich durchgeführt. Die Edits-Schnittstelle unterstützt derzeit drei Modelle: `dall-e-2`, `gpt-image-1` und `gpt-image-2`. Das empfohlene Modell ist `gpt-image-2`, siehe Abschnitt [GPT-Image-2 Modell](#gpt-image-2-modell). ## Asynchrones Callback Da die Bildbearbeitung mit der OpenAI Images Edits API relativ lange dauern kann, würde eine lange Wartezeit auf die HTTP-Antwort unnötige Systemressourcen binden. Deshalb unterstützt die API auch asynchrone Callbacks. Der Ablauf ist: Der Client sendet bei der Anfrage zusätzlich ein Feld `callback_url` mit. Die API antwortet sofort mit einem Ergebnis, das ein `task_id` enthält, die aktuelle Aufgaben-ID. Nach Abschluss der Bearbeitung sendet die API das Ergebnis per POST-JSON an die angegebene `callback_url`, inklusive der `task_id`, sodass die Aufgabe eindeutig zugeordnet werden kann. Ein Beispiel: Zunächst ist der Webhook ein HTTP-Endpunkt, den Sie selbst bereitstellen sollten. Zur Demonstration verwenden wir die öffentliche Webhook-Seite [https://webhook.site/](https://webhook.site/), wo Sie eine URL erhalten, z. B.: ![](https://cdn.xhuoapi.ai/cjjfly.png) Diese URL kopieren Sie und verwenden sie als `callback_url`, z. B. `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`. Dann senden Sie die Anfrage mit `callback_url`: ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F "prompt=Create a lovely gift basket with these items in it" \ -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab" ``` Sie erhalten sofort eine Antwort mit `task_id`: ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` Nach kurzer Zeit sehen Sie auf der Webhook-Seite das Ergebnis: ```json theme={null} { "success": true, "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c", "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc", "data": { "created": 1721626477, "data": [ { "b64_json": "iVBORw0KGgo..." } ] } } ``` Das Ergebnis enthält ein `task_id` Feld und das `data` Feld mit dem gleichen Bildbearbeitungsergebnis wie bei synchronem Aufruf. Über `task_id` können Sie die Aufgabe eindeutig zuordnen. ## Fehlerbehandlung Bei Fehlern gibt die API entsprechende Fehlercodes und Meldungen zurück, z. B.: * `400 token_mismatched`: Ungültige Anfrage, möglicherweise fehlende oder falsche Parameter. * `400 api_not_implemented`: Ungültige Anfrage, möglicherweise fehlende oder falsche Parameter. * `401 invalid_token`: Nicht autorisiert, ungültiges oder fehlendes Token. * `429 too_many_requests`: Zu viele Anfragen, Rate Limit überschritten. * `500 api_error`: Interner Serverfehler. ### Beispiel einer Fehlerantwort ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Fazit Mit diesem Dokument haben Sie gelernt, wie Sie die OpenAI Images Edits API nutzen, um die offizielle OpenAI Bildbearbeitungsfunktion einfach einzusetzen. Wir hoffen, dass Ihnen dieses Dokument bei der Integration und Nutzung der API hilft. Bei Fragen wenden Sie sich gerne an unser technisches Support-Team.