> ## Documentation Index > Fetch the complete documentation index at: https://germeytechnology-docs-remove-4o-image-nav.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Edits API Beantragung und Nutzung > OpenAI generation 集成指南 - Ace Data Cloud Der OpenAI Bildbearbeitungsdienst ermöglicht das Hochladen beliebig vieler Bilder und Anweisungen, um bearbeitete Bilder zu erhalten. Derzeit unterstützt die Schnittstelle gleichzeitig `dall-e-2`, `gpt-image-1`, das neueste **`gpt-image-2`** sowie die über dieselbe Schnittstelle angebundenen Modelle der **`nano-banana` / `nano-banana-2` / `nano-banana-pro`** Serie. Dieses Dokument beschreibt hauptsächlich den Nutzungsprozess der OpenAI Images Edits API, mit der wir die offiziellen OpenAI Bildbearbeitungsfunktionen einfach verwenden können. ## Beantragungsprozess Um die OpenAI Images Edits API zu nutzen, können Sie zunächst auf der Seite [OpenAI Images Edits API](https://platform.acedata.cloud/documents/openai-images-edits) auf die Schaltfläche „Acquire“ klicken, um die für Anfragen benötigten Zugangsdaten zu erhalten: ![](https://cdn.acedata.cloud/nyq0xz.png) Falls Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach der Anmeldung kehren Sie automatisch zur aktuellen 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 im Vergleich zu `gpt-image-1` deutliche Verbesserungen: * **Stabilere Struktur**: Beim Wechsel von Skin, Farbgebung oder Hintergrund wird das Layout und die Komposition des Originalbildes kaum zerstört. * **Genauere Texterhaltung**: Bilder mit Text wie Infografiken, Poster, Menüs behalten den Text nach der Bearbeitung klar und lesbar. * **Unterstützt direkte URL-Übertragung**: Neben dem traditionellen `multipart/form-data` Datei-Upload unterstützt `gpt-image-2` **zusätzlich das Übermitteln von Bild-URLs im JSON-Format**, ohne dass das Bild zuerst lokal heruntergeladen werden muss – ideal für serverseitige Pipelines. * **Unterstützt hochauflösendes Redrawing**: Es kann ein 1K-Originalbild übergeben werden und mittels `size` Parameter eine Ausgabe in 2K / 4K angefordert werden; das Modell vergrößert das Bild während der Bearbeitung. ### Unterstützte `size` Werte Die Größenbeschränkungen der Editier-Schnittstelle entsprechen vollständig denen der Generierungsschnittstelle — `gpt-image-2` akzeptiert nur `size` Werte als `auto`, leer oder im Format `WIDTHxHEIGHT`. Andere Werte führen zu einem 400 Fehler. **Alle Größen (1K / 2K / 4K / benutzerdefiniert) werden pro Bild einheitlich abgerechnet, unabhängig von der Originalauflösung oder dem `size` Wert.** Die gleichen Beschränkungen für benutzerdefinierte Größen gelten: Breite und Höhe müssen Vielfache von 16 sein, die längste Seite ≤ 3840, und die Gesamtpixelzahl ≤ 8.294.400. | Seitenverhältnis | 1K empfohlen | 2K empfohlen | 4K empfohlen | | ---------------- | ------------ | ------------ | ------------ | | 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: Ist das Originalbild `1024x1024` und `size` wird auf `2048x2048` gesetzt, zeichnet das Modell das Bild gemäß der Bearbeitungsanweisung neu und gibt ein 2K-Bild aus; bei `size` `3840x2160` wird ein 4K Querformat ausgegeben; bei `auto` oder Weglassen wählt das Modell die Größe selbst. Die Abrechnung ist bei allen drei Varianten gleich. > **Zum Parameter `n`** > > Die `gpt-image-2` Editier-Schnittstelle **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 auch nur für ein Bild abgerechnet. Wenn Sie mehrere bearbeitete Varianten 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` Serie. `dall-e-2` ist derzeit das einzige native Editiermodell, das `n > 1` unterstützt. Im Folgenden zeigen wir anhand zweier realer Beispiele aus unterschiedlichen Anwendungsfällen 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 und bearbeitet es gemäß dem `prompt`. Beispiel: Das folgende Originalbild ist eine mit `gpt-image-2` generierte Infografik:

Wir möchten es in einen „Nachtmodus“-Look umwandeln. Der Aufruf sieht so aus: ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/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 in Python: ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/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 Antwort sieht so 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.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` Das bearbeitete Bild:

Man sieht, dass die Modulstruktur, Informationsbereiche und Schriftgestaltung 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"]`. Es können bis zu 16 Referenzbilder gleichzeitig übergeben werden, damit das Modell mehrere Bilder für die Bearbeitung berücksichtigt. ### Aufrufmethode 2: JSON + mehrere Referenzbilder `gpt-image-2` unterstützt die gleichzeitige Referenzierung mehrerer Bilder, um ein Endergebnis zu erzeugen, z. B. mehrere Produktfotos zu einem Geschenkkorb zusammenfügen: ```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 beibehalten Ein weiteres Beispiel: Ein hölzernes Bücherregal wird durch ein modernes schwebendes Regal ersetzt, wobei 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.acedata.cloud/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 Anzahl der Bücher pro Ebene (1 / 3 / 7) strikt erhalten blieb und wie gewünscht eine kleine Sukkulente hinzugefügt wurde. ### Aufrufmethode 3: multipart/form-data (kompatibel mit OpenAI SDK) Wenn Sie bereits das offizielle OpenAI Python SDK verwenden, ist die bisherige `multipart/form-data` Upload-Methode weiterhin gültig, Sie müssen nur `model` auf `gpt-image-2` ändern: ```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.acedata.cloud/openai` und `OPENAI_API_KEY` auf den beantragten Token: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/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 | Kosten (Credits / Anfrage) | Anwendungsfall | | ----------------- | -------------------------- | ------------------------------------------------------------------ | | `nano-banana` | 0.14 | Normale Bildbearbeitung, schnellste und kostengünstigste Option | | `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 | > **Wichtiger Hinweis zu unterstützten Parametern** > > Nano Banana ist über eine Adaptionsschicht an das OpenAI-Protokoll angebunden und unterstützt nur die folgenden Parameter: `model`, `prompt`, `image`. > > * `image` kann entweder als Datei via `multipart/form-data` hochgeladen werden (intern wandelt der Worker es in `data:;base64,...` für den Upstream um) oder als Bild-URL im Formularfeld übergeben werden. > * Parameter wie `mask`, `n`, `size`, `response_format` werden nicht unterstützt und ignoriert. > * Die Rückgabe folgt dem OpenAI-Format (`data[].url`), aber `created` ist immer `0`, es wird kein `b64_json` zurückgegeben, und `revised_prompt` entspricht immer dem ursprünglichen `prompt`. ### Aufruf per Formular + Bild-URL ```shell theme={null} curl -X POST "https://api.acedata.cloud/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.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` Antwort: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg", "revised_prompt": "add a green leaf on top of the apple" } ] } ``` Bearbeitetes Bild:

### Aufruf per Formular + lokale Datei ```python theme={null} import requests url = "https://api.acedata.cloud/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 Die `callback_url` asynchrone Callback-Funktionalität gilt auch für nano-banana, der Aufrufprozess ist identisch mit anderen Modellen, siehe Abschnitt [Asynchrone Callback](#asynchrone-callback). ## Grundlegende Nutzung Nun können Sie die API mit 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.acedata.cloud/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 Inhalte ausgefüllt werden: Einmal `authorization`, das Sie direkt aus der Dropdown-Liste wählen können. Dann `model`, das ist die Auswahl des OpenAI-Modells, hier gibt es hauptsächlich ein Modell, Details finden Sie in unserer Modellübersicht. Weiterhin `prompt`, der Text, der die Bildgenerierung beschreibt. Schließlich `image`, der Pfad zum zu bearbeitenden Bild, wie unten gezeigt:

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 in einer Datei 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.acedata.cloud/openai` und `OPENAI_API_KEY` auf den erhaltenen Token. Unter macOS können Sie diese mit folgendem Befehl setzen: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` Nach dem Aufruf wird im aktuellen Verzeichnis eine Bilddatei `gift-basket.png` erzeugt, das Ergebnis sieht so aus:

Damit haben Sie die Bildbearbeitung erfolgreich abgeschlossen. Die Edits-Schnittstelle unterstützt derzeit drei Modelle: `dall-e-2`, `gpt-image-1` und `gpt-image-2`. `gpt-image-2` ist das aktuell empfohlene Modell, siehe oben Abschnitt [GPT-Image-2 Modell](#gpt-image-2-modell). ## Asynchrone Callback Da die Bildbearbeitung mit OpenAI Images Edits API längere Zeit in Anspruch nehmen kann, würde eine lange Wartezeit bei synchronen HTTP-Anfragen zu Ressourcenverbrauch führen. Daher bietet die API auch asynchrone Callback-Unterstützung. Der Ablauf ist: Der Client sendet eine Anfrage mit einem zusätzlichen Feld `callback_url`. Die API antwortet sofort mit einem Ergebnis, das ein `task_id` enthält, welches die aktuelle Aufgabe identifiziert. Nach Abschluss der Bearbeitung sendet die API das Ergebnis per POST-JSON an die angegebene `callback_url`, inklusive des `task_id`, so dass die Aufgabe zugeordnet werden kann. Ein Beispiel zur Veranschaulichung: Ein Webhook ist ein HTTP-Dienst, der Anfragen empfangen kann. Entwickler sollten hier ihre eigene HTTP-Server-URL einsetzen. Für die Demonstration verwenden wir die öffentliche Webhook-Testseite [https://webhook.site/](https://webhook.site/), die eine URL bereitstellt, z. B.: ![](https://cdn.acedata.cloud/cjjfly.png) Kopieren Sie diese URL, z. B. `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`, und verwenden Sie sie als Webhook. Dann setzen Sie das Feld `callback_url` auf diese URL und senden die Anfrage: ```shell theme={null} curl -X POST "https://api.acedata.cloud/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: ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` Nach kurzer Zeit können Sie auf der Webhook-URL das Ergebnis der Bildbearbeitung sehen, z. B.: ```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..." } ] } } ``` Man sieht, dass das Ergebnis ein `task_id` enthält und das Feld `data` die gleichen Bildbearbeitungsergebnisse wie bei synchronem Aufruf enthält. Über `task_id` kann die Aufgabe zugeordnet werden. ## Fehlerbehandlung Bei API-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 offiziellen OpenAI Bildbearbeitungsfunktionen einfach einzusetzen. Wir hoffen, dass dieses Dokument Ihnen hilft, die API besser zu integrieren und zu verwenden. Bei Fragen wenden Sie sich bitte jederzeit an unser technisches Support-Team.