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 auf die Schaltfläche „Acquire“ klicken, um die für Anfragen benötigten Zugangsdaten zu erhalten:

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:

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:

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:

{
  "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:

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:

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:

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:

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:<mime>;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

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:

{
  "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

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.

​

Grundlegende Nutzung

Nun können Sie die API mit Code aufrufen. Hier ein Beispiel mit CURL:

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:

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:

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.

​

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/, die eine URL bereitstellt, z. B.:

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:

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:

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

Nach kurzer Zeit können Sie auf der Webhook-URL das Ergebnis der Bildbearbeitung sehen, z. B.:

{
  "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

{
  "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.