Skip to main content
OpenAI Bildbearbeitungsdienst ermöglicht es, beliebig viele Bilder und Anweisungen einzugeben und die bearbeiteten Bilder auszugeben. Derzeit unterstützt die API gleichzeitig dall-e-2, gpt-image-1, das neueste gpt-image-2 sowie die über dieselbe API angebundenen nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro Modellreihe. Dieses Dokument beschreibt hauptsächlich den Ablauf der Nutzung der OpenAI Images Edits API, mit der wir die offiziellen OpenAI Bildbearbeitungsfunktionen einfach nutzen können.

Antragsprozess

Um die OpenAI Images Edits API zu nutzen, gehen Sie zunächst zur Ace Data Cloud Konsole, um Ihr API-Token zu erhalten, das Sie für später aufbewahren sollten. 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 auf alle Dienste der Plattform zuzugreifen, es ist nicht erforderlich, für jeden Dienst separat einen Antrag zu stellen. Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, um es kostenlos auszuprobieren; wenn das Kontingent erschöpft ist, können Sie im Dashboard Ihr Guthaben aufladen.
📘 Vollständige Dokumentation: OpenAI Images Edits API →

GPT-Image-2 Modell

gpt-image-2 hat im Bereich der Bildbearbeitung im Vergleich zu gpt-image-1 deutliche Verbesserungen:
  • Struktur bleibt stabiler: Beim Wechseln von Hauttönen, Farben oder Hintergründen wird das Layout und die Komposition des Originalbildes kaum beeinträchtigt.
  • Text bleibt genauer erhalten: Bilder mit Text wie Infografiken, Plakaten, Menüs usw. sind nach der Bearbeitung weiterhin klar und lesbar.
  • Unterstützt URL-Übertragung: Neben dem traditionellen multipart/form-data Datei-Upload unterstützt gpt-image-2 auch die Übertragung von Bild-URLs im JSON-Format, ohne dass die Bilder zuerst lokal heruntergeladen werden müssen, was sich hervorragend für die Integration in Server-Pipelines eignet.
  • Unterstützt base64-Übertragung: Entsprechend den offiziellen Vorgaben kann das image-Feld auch direkt base64 (z. B. data:image/png;base64,... oder reines base64) übertragen, sodass lokale Bilder nicht zuerst auf einen Bildhost hochgeladen werden müssen, um bearbeitet zu werden.
  • Unterstützt hochauflösende Neuzeichnung: Sie können ein 1K-Originalbild übergeben und mit dem size-Parameter eine 2K / 4K-Ausgabe anfordern, das Modell wird während des Bearbeitungsprozesses gleichzeitig eine Vergrößerung durchführen.

Offizielle Umleitung / Umgekehrte Variante (:official / :reverse)

gpt-image-2 verwendet standardmäßig die umgekehrte Route. Durch den Suffix des Modellnamens können Sie die Route explizit auswählen:
  • gpt-image-2:official: Offizielle Umleitungsroute. Unterstützt n > 1 (gibt mehrere Bilder auf einmal zurück) und echte 2K / 4K, die Abrechnung erfolgt pro Bild, der Preis beträgt das Doppelte des Standardpreises von gpt-image-2. Derzeit wird diese Route nur von openai-hk bereitgestellt, wenn die Route nicht verfügbar ist, wird direkt ein Fehler zurückgegeben, es erfolgt kein Downgrade auf die umgekehrte Route.
  • gpt-image-2:reverse: Vollständig äquivalent zur Standard-gpt-image-2 (umgekehrte Route), der Preis bleibt unverändert.
Die nachfolgende Einschränkung „Über den n-Parameter“ gilt nur für die Standard- / umgekehrte Route; gpt-image-2:official unterstützt n > 1 und wird pro Bild abgerechnet.

Unterstützte size Werte

Die Einschränkungen der Bearbeitungs-API für size sind identisch mit denen der Generierungs-API – gpt-image-2 benötigt nur, dass size auto, leer oder im Format WIDTHxHEIGHT vorliegt, jede andere Form führt zu einem 400-Fehler. Alle Größen (1K / 2K / 4K / benutzerdefiniert) werden einheitlich pro Bild abgerechnet, unabhängig von der Auflösung des Originalbildes und dem angeforderten size-Wert. Die harten Einschränkungen für benutzerdefinierte Größen gelten ebenfalls: Breite und Höhe müssen Vielfache von 16 sein, die lange Seite ≤ 3840, die Gesamtanzahl der Pixel ≤ 8.294.400.
Zum Beispiel: Wenn das Originalbild 1024x1024 ist und size auf 2048x2048 gesetzt wird, wird das Modell gemäß den Bearbeitungsanweisungen neu gezeichnet und ein 2K-Bild ausgegeben; wenn size auf 3840x2160 gesetzt wird, wird ein 4K-Horizontalbild ausgegeben; wenn auto übergeben oder weggelassen wird, wählt das Modell selbst. Die Abrechnung ist bei allen drei gleich.
Über den n-Parameter Die gpt-image-2 Bearbeitungs-API unterstützt derzeit kein n > 1: Dieser Parameter wird stillschweigend ignoriert, unabhängig davon, ob n=1 oder n=10 übergeben wird, eine einzelne Anfrage gibt immer nur 1 Bild zurück und wird nur für 1 Bild abgerechnet. Wenn Sie mehrere bearbeitete Ergebnisse auf einmal erhalten möchten, müssen Sie selbstständig mehrere Anfragen parallel stellen. Diese Einschränkung gilt auch für gpt-image-1 / gpt-image-1.5 sowie die nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro Reihe. dall-e-2 ist derzeit das einzige Modell, das nativ n > 1 unterstützt.
Im Folgenden werden zwei verschiedene reale Beispiele gezeigt, um die Bearbeitungsfähigkeiten von gpt-image-2 zu erleben.

Aufrufmethode eins: JSON + Bild-URL (empfohlen)

Senden Sie die Anfrage direkt im application/json Format, das image-Feld füllt eine Bild-URL aus, das Modell wird das Bild abrufen und gemäß dem prompt bearbeiten. Zum Beispiel, das folgende Originalbild ist eine von gpt-image-2 generierte wissenschaftliche Illustration:

Wir möchten es in eine „Nachtmodus“-Farbgebung ändern. So könnte der Aufruf aussehen:
oder mit Python:
Die Rückgabe sieht wie folgt aus:
Die bearbeitete Bild ist wie folgt:

Man kann sehen, dass die Modulstruktur, die Informationspartition und die Schriftgestaltung strikt beibehalten wurden, nur das Farbschema wurde in ein dunkles Thema umgekehrt.
Hinweis: Das image-Feld unterstützt auch die Eingabe eines Arrays, z. B. "image": ["url1", "url2", "url3"], wobei maximal 16 Referenzbilder gleichzeitig übergeben werden können, damit das Modell mehrere Bilder zur Bearbeitung kombinieren kann.
base64 Direktübertragung: image (und jedes Element im Array) kann neben der URL auch base64 sein — data:image/png;base64,... oder rohes base64 ist ebenfalls möglich, geeignet für lokale Bilder, die nicht zuerst auf einen Bildhost hochgeladen werden sollen. Zum Beispiel:

Aufrufmethode zwei: JSON + mehrere Referenzbilder

gpt-image-2 unterstützt die gleichzeitige Referenzierung mehrerer Bilder zur Erstellung des Endergebnisses, z. B. um mehrere Produktfotos in einen Geschenkkorb zu kombinieren:

Szenario-Beispiel: Stilwechsel + Struktur beibehalten

Hier ist ein weiteres Beispiel, bei dem ein Holzregal durch ein modernes Wandregal ersetzt wird, aber die Anzahl und Anordnung der Bücher auf jeder Ebene strikt beibehalten wird. Ursprüngliches Bild (ein Holzregal, das mit gpt-image-2 generiert wurde):

Aufruf:
Bearbeitungsergebnis (task_id: e9544dba-727e-44a2-81e1-223d49869380):

Man kann sehen, dass Stil und Umgebung gemäß den Vorgaben vollständig ersetzt wurden, aber die Anzahl der Bücher auf jeder Ebene (1 / 3 / 7) weiterhin strikt beibehalten wurde, und es wurde wie gewünscht eine Sukkulente hinzugefügt.

Aufrufmethode drei: multipart/form-data (kompatibel mit OpenAI SDK)

Wenn Sie bereits das offizielle OpenAI Python SDK verwenden, ist die ursprüngliche multipart/form-data-Upload-Methode ebenfalls anwendbar, Sie müssen nur das model auf gpt-image-2 ändern:
Beim Verwenden des SDK müssen zuerst zwei Umgebungsvariablen importiert werden, OPENAI_BASE_URL auf https://api.acedata.cloud/openai und OPENAI_API_KEY auf den beantragten Token setzen:

Nano Banana Modellreihe

Die nano-banana-Reihe hat ebenfalls den Zugriff auf /openai/images/edits in Bearbeitungsszenarien integriert, ändern Sie einfach das model in eines der untenstehenden Modelle.
Wichtig: Unterstützte Parameter Nano Banana verbindet sich über eine Anpassungsschicht mit dem OpenAI-Protokoll und unterstützt nur die folgenden Parameter: model, prompt, image.
  • image kann entweder durch multipart/form-data hochgeladen werden (wird intern in data:<mime>;base64,... umgewandelt und an den Upstream gesendet) oder als Bild-URL-String direkt über ein Formularfeld übergeben werden.
  • Parameter wie mask, n, size, response_format werden nicht unterstützt; sie werden ignoriert, wenn sie ausgefüllt sind.
  • Die Rückgabestruktur folgt dem OpenAI-Format (data[].url), aber created ist fest auf 0 gesetzt, und es wird kein b64_json zurückgegeben, revised_prompt ist immer gleich dem ursprünglichen prompt.

Aufruf über Formular + Bild-URL

Die Rückgabe sieht wie folgt aus:
Das bearbeitete Bild:

Aufruf über Formular + lokale Datei

Asynchrone Rückrufe

Das callback_url asynchrone Rückrufmechanismus funktioniert auch für nano-banana, der Aufrufprozess ist identisch mit anderen Modellen, siehe den Abschnitt Asynchrone Rückrufe weiter unten.

Grundlegende Nutzung

Jetzt können Sie den Code verwenden, um den Aufruf durchzuführen, unten ist der Aufruf über CURL:
Bei der ersten Verwendung dieser Schnittstelle müssen wir mindestens vier Inhalte ausfüllen, einer ist authorization, den Sie einfach aus der Dropdown-Liste auswählen können. Ein weiterer Parameter ist model, model ist die von uns gewählte OpenAI-Modellkategorie, hier haben wir hauptsächlich 1 Modell, Details finden Sie in den bereitgestellten Modellen. Ein weiterer Parameter ist prompt, prompt ist das Stichwort, das wir eingeben, um das Bild zu generieren. Der letzte Parameter ist image, dieser Parameter benötigt den Pfad des zu bearbeitenden Bildes, das wie folgt aussieht:

Ein Beispiel für den gleichen Aufruf in Python:
Um Python aufzurufen, müssen wir zuerst zwei Umgebungsvariablen importieren, eine OPENAI_BASE_URL, die auf https://api.acedata.cloud/openai gesetzt werden kann, und eine Variable für die Anmeldeinformationen OPENAI_API_KEY, dieser Wert stammt aus authorization, und kann unter Mac OS mit folgendem Befehl gesetzt werden:
Nach dem Aufruf stellen wir fest, dass im aktuellen Verzeichnis ein Bild gift-basket.png generiert wird, das Ergebnis sieht wie folgt aus:

So haben wir die Bildbearbeitung abgeschlossen. Der Edits-API unterstützt derzeit drei Modelle: dall-e-2, gpt-image-1 und gpt-image-2, wobei gpt-image-2 das derzeit empfohlene Modell ist, siehe den Abschnitt GPT-Image-2 Modell weiter oben.

Asynchrone Rückrufe

Da die OpenAI Images Edits API möglicherweise längere Zeit für die Bearbeitung von Bildern benötigt, bleibt die HTTP-Anfrage bei längerer Nichtreaktion verbunden, was zu einem zusätzlichen Verbrauch von Systemressourcen führt. Daher bietet diese API auch Unterstützung für asynchrone Rückrufe. Der gesamte Prozess ist: Wenn der Client eine Anfrage stellt, gibt er zusätzlich ein callback_url-Feld an. Nach der API-Anfrage gibt die API sofort ein Ergebnis zurück, das ein task_id-Feld enthält, das die aktuelle Aufgaben-ID darstellt. Wenn die Aufgabe abgeschlossen ist, wird das Ergebnis der Bildbearbeitung in Form von POST JSON an die vom Client angegebene callback_url gesendet, das auch das task_id-Feld enthält, sodass die Aufgabenergebnisse über die ID verknüpft werden können. Lassen Sie uns anhand eines Beispiels verstehen, wie dies konkret funktioniert. Zunächst ist der Webhook-Rückruf ein Dienst, der HTTP-Anfragen empfangen kann. Entwickler sollten die URL ihres eigenen eingerichteten HTTP-Servers ersetzen. Hier verwenden wir zur Demonstration eine öffentliche Webhook-Beispielwebsite https://webhook.site/, auf dieser Website erhalten Sie eine Webhook-URL, wie im Bild gezeigt: Kopieren Sie diese URL, um sie als Webhook zu verwenden. Das Beispiel hier ist https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. Als nächstes können wir das Feld callback_url auf die oben genannte Webhook-URL setzen und die entsprechenden Parameter wie im folgenden Code gezeigt ausfüllen:
Nach dem Aufruf können wir sofort ein Ergebnis erhalten, wie folgt:
Nach einem kurzen Moment können wir das Ergebnis der Bildbearbeitung an der Webhook-URL beobachten, der Inhalt ist wie folgt:
Im Ergebnis sehen wir ein Feld task_id, das Feld data enthält die gleichen Bildbearbeitungsergebnisse wie bei einem synchronen Aufruf. Über das Feld task_id kann die Aufgabe zugeordnet werden.

Fehlerbehandlung

Beim Aufruf der API, wenn ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die Informationen zurück. Zum Beispiel:
  • 400 token_mismatched: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
  • 400 api_not_implemented: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
  • 401 invalid_token: Unbefugt, ungültiger oder fehlender Autorisierungstoken.
  • 429 too_many_requests: Zu viele Anfragen, Sie haben das Rate-Limit überschritten.
  • 500 api_error: Interner Serverfehler, etwas ist auf dem Server schiefgelaufen.

Beispiel für eine Fehlerantwort

Fazit

Durch dieses Dokument haben Sie gelernt, wie Sie die OpenAI Images Edits API nutzen können, um die offiziellen Bildbearbeitungsfunktionen von OpenAI einfach zu verwenden. Wir hoffen, dass dieses Dokument Ihnen hilft, die API besser zu integrieren und zu nutzen. Bei Fragen wenden Sie sich bitte jederzeit an unser technisches Support-Team.