Zum Hauptinhalt springen

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.

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 den Button „Acquire“ anklicken, um die für Anfragen benötigten Zugangsdaten zu erhalten: 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ältnis1K (Standardpreis)2K Empfehlung (×1,5)4K Empfehlung (×1,5)
1:11024x10242048x20482880x2880
4:31536x10242048x15363264x2448
3:41024x15361536x20482448x3264
16:91792x10242048x11523840x2160
9:161024x17921152x20482160x3840
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: 
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: 
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: 
{
  "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: 
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: 
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: 
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: 
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:
ModellAbrechnung (Credits / Anfrage)Anwendungsbereich
nano-banana0.14Normale Bildbearbeitung, schnellste und kostengünstigste Variante
nano-banana-20.28Deutlich verbesserte Qualität und Details
nano-banana-pro0.35Flaggschiff 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:<mime>;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

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

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.

​
Grundlegende Nutzung

Nun können Sie die API per 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.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -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: 
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: 
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.

​
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/, wo Sie eine URL erhalten, z. B.: 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: 
curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -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: 
{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}
Nach kurzer Zeit sehen Sie auf der Webhook-Seite das Ergebnis: 
{
  "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

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