Viele Entwickler, die die Bildbearbeitungs-Schnittstelle von gpt-image-2 integrieren, stoßen immer wieder auf dasselbe Problem: Man durchsucht die API-Referenzseite für images/edit und findet zwar den Hinweis, dass „GPT-Image-Modelle bis zu 16 Bilder verarbeiten können“, aber die Größenbeschränkung pro Bild bleibt unauffindbar. Gibt es keine Begrenzung? Oder wurde sie in der Dokumentation schlicht vergessen?
Die Antwort lautet: Die Begrenzung existiert und ist eindeutig – jedes Bild muss kleiner als 50 MB sein. Unterstützt werden die Formate PNG, WebP und JPG. Diese Regel steht jedoch nicht in der Parameter-Tabelle der Referenzseite, sondern in einem separaten Leitfaden zur Bildgenerierung. Diese Fragmentierung der Informationen führt bei vielen Entwicklern zu unnötiger Fehlersuche.
In diesem Artikel klären wir die Upload-Beschränkungen der gpt-image-2-API ein für alle Mal: Anzahl, Größe, Formate, Masken-Regeln, Auflösungskonstrukte und ein praxisrelevantes Problem, das noch wichtiger ist als das 50-MB-Limit – warum wir davon abraten, tatsächlich Bilder mit 50 MB zu übertragen.
Bild-Upload-Beschränkungen der gpt-image-2-API: Offizielle Spezifikationen
Fangen wir mit dem Wichtigsten an. gpt-image-2 empfängt Eingabebilder über den Endpunkt v1/images/edits. Die offiziellen Beschränkungen sind in der folgenden Tabelle zusammengefasst.
Kurzübersicht: Bild-Upload-Beschränkungen für gpt-image-2
| Einschränkung | Offizielle Spezifikation | Dokumentationsquelle |
|---|---|---|
| Max. Bilder pro Anfrage | 16 Bilder (GPT-Image-Modellreihe) | API-Referenz: images/edit |
| Dateigröße pro Bild | < 50 MB | Leitfaden zur Bildgenerierung |
| Unterstützte Formate | PNG, WebP, JPG | Leitfaden zur Bildgenerierung |
| Übertragungsmethode | image_url oder file_id (entweder/oder) |
API-Referenz: images/edit |
| Masken (Mask) | Gleiches Format/Größe wie Original, < 50 MB, Alpha-Kanal erforderlich | Leitfaden zur Bildgenerierung |
| Anzahl der Generierungen (n) | 1–10 Bilder | API-Referenz: images/edit |
Das bedeutet, theoretisch kann eine einzelne Edit-Anfrage bis zu 16 Bilder mit einer Größe von jeweils fast 50 MB enthalten. Aber „theoretisches Limit“ und „praktische Anwendung“ sind zwei verschiedene Dinge, auf die wir später noch eingehen werden.
Ein häufiger Fehler, der hier erwähnt werden sollte: Der images-Parameter der neuen API akzeptiert ein Array von Objekten, wobei jedes Objekt entweder eine image_url oder eine file_id bereitstellt. Die file_id stammt aus einem Vorab-Upload über die Files-API und eignet sich ideal für wiederverwendbare Assets; image_url unterstützt öffentliche URLs oder Base64-Data-URLs, was für einmalige Anfragen praktisch ist. Die 50-MB-Beschränkung gilt für beide Methoden gleichermaßen.
🎯 Tipp für schnelle Tests: Wenn Sie sich nicht sicher sind, ob Ihre Bilder die Beschränkungen auslösen, ist der direkteste Weg, eine echte Anfrage zu senden und die Fehlermeldung zu prüfen. Wir empfehlen, für solche Grenztests die OpenAI-kompatible Schnittstelle von APIYI (apiyi.com) zu verwenden. Das Protokoll-Panel der Plattform zeigt Ihnen die Größe des Request-Bodys und die Fehlerdetails vollständig an, was die Fehlersuche deutlich intuitiver macht als bei direkten Aufrufen der offiziellen Schnittstelle.
Warum die Upload-Größe für gpt-image-2 in der Dokumentation „nicht zu finden“ ist
Kommen wir zurück zur ursprünglichen Frage: Warum erwähnt die Referenzseite nur die 16 Bilder, aber nicht die Dateigröße? Dies ist eine bewusste Designentscheidung in der Struktur der OpenAI-Dokumentation. Die Referenzseite für images/edit ist nach einem „Parameter-Schema“ aufgebaut. Die images-Parameter sind auf Schema-Ebene lediglich ein Array von Objekten; die Obergrenze der Anzahl ist eine Array-Beschränkung und wurde daher dort aufgenommen. Dateigröße und Format hingegen unterliegen der „Laufzeitprüfung“ und wurden daher in den beschreibenden Text der Anleitung zur Bilderzeugung (Image Generation) eingeordnet.
Es gibt noch einige weitere Regeln, die „in der Anleitung versteckt“ sind. Diese sollten Sie unbedingt prüfen, bevor Sie Funktionen zur Bildbearbeitung implementieren:
- Drei Anforderungen an die Maske: Sie muss das gleiche Format und die gleiche Größe wie das zu bearbeitende Bild haben, ebenfalls kleiner als 50 MB sein und zwingend einen Alpha-Kanal enthalten. Die Verwendung eines JPG als Maske ist die häufigste Fehlerursache, da JPGs keinen Alpha-Kanal unterstützen.
- Auflösung ist nicht beliebig: Der
size-Parameter von gpt-image-2 unterstützt zwar benutzerdefinierte Auflösungen, unterliegt aber harten Beschränkungen: Die längste Seite darf 3840 px nicht überschreiten, Breite und Höhe müssen jeweils ein Vielfaches von 16 px sein, das Seitenverhältnis darf maximal 3:1 betragen und die Gesamtpixelzahl muss zwischen 655.360 und 8.294.400 liegen. - Eingabebilder kosten: Referenzbilder in einer Edit-Anfrage werden nach Bild-Input-Token abgerechnet. Bei
input_fidelity: highsteigt der Verbrauch an Input-Token deutlich an.
Einschränkungen für Auflösung und size-Parameter bei gpt-image-2
| Einschränkungsdimension | Regel | Beispiel |
|---|---|---|
| Längste Seite | ≤ 3840 px | 3840×2160 (4K Querformat) möglich |
| Kantenausrichtung | Breite & Höhe Vielfache von 16 px | 1024, 1536, 2048 sind zulässig |
| Seitenverhältnis | ≤ 3:1 | 2048×1152 zulässig, 3072×1024 zulässig |
| Gesamtpixel | 655.360 – 8.294.400 | Unterhalb von 768×854 wird abgelehnt |
| Gängige Presets | 1024×1024 / 1536×1024 / 2048×2048 / 3840×2160 | Hochformat analog umgekehrt |
Wenn Ihre Anwendung häufig zwischen verschiedenen Auflösungen wechselt, empfehle ich, diese Constraint-Tabelle für eine lokale Validierung vor dem Absenden der Anfrage zu nutzen. So können Sie ungültige Formate bereits auf Client-Seite abfangen und sparen sich den Roundtrip, bis die API einen 400-Fehler zurückgibt. Im Dokumentationszentrum von APIYI (apiyi.com) haben wir ebenfalls eine Checkliste für die Parameterprüfung von gpt-image-2 zusammengestellt, die Sie direkt für die Implementierung verwenden können.
gpt-image-2 in der Praxis: 50 MB sind das Limit, 1,5 MB der „Sweet Spot“
Nachdem wir das harte Limit von 50 MB kennen, stellt sich die wichtigere Frage: Welche Bildgröße sollte in der Praxis tatsächlich übertragen werden? Unsere Empfehlung lautet: Kontrollieren Sie die Größe pro Bild auf etwa 1,5 MB und überschreiten Sie möglichst nicht 5 MB. Das ist keine willkürliche Zahl, sondern hat drei gute Gründe.
Erstens: Die Base64-Aufblähung. Wenn Sie Bilder als Data-URL einbetten, vergrößert die Base64-Kodierung das Volumen um etwa 33 % – ein 40-MB-Original nähert sich nach der Kodierung fast 53 MB. Zusammen mit der JSON-Struktur kann das Request-Limit schnell überschritten werden. Bei 16 Bildern, die alle per Base64 eingebettet sind, potenziert sich dieses Problem um den Faktor 16. Nutzen Sie für große Datenmengen unbedingt den file_id-Kanal für den Vorab-Upload.
Zweitens: Übertragungs- und Dekodierungsdauer. Ab einer Größe von 5 MB steigen die Upload-Zeit und die serverseitige Dekodierung nicht-linear an. Bei Netzwerkschwankungen kommt es zudem häufiger zu Timeouts und Retries, was die gesamte Bilderzeugung verlangsamt. Bilder um die 1,5 MB sind bei einem Standard-Breitbandanschluss in 1–2 Sekunden hochgeladen – ein idealer Kompromiss zwischen Stabilität und Qualität.
Drittens: Abnehmender Grenznutzen bei der Bildqualität. gpt-image-2 führt bei der Verarbeitung eine interne Vorverarbeitung durch. Wenn die Eingabeauflösung weit über der Ausgabeauflösung liegt, sind die zusätzlichen Pixel im Grunde verschwendet. Ein JPG mit einer langen Kante von 3840 px, das auf unter 2 MB komprimiert wurde, unterscheidet sich in der Bearbeitung kaum von einem 40 MB großen, verlustfreien PNG – bei einem Bruchteil der Kosten und Zeit.
Empfehlungen für die Bildgröße bei gpt-image-2
| Originalzustand | Empfohlene Verarbeitung | Erwartetes Ergebnis |
|---|---|---|
| < 1,5 MB | Direkt hochladen | Beste Geschwindigkeit und Stabilität |
| 1,5 MB – 5 MB | Direkt möglich, Konvertierung zu JPG/WebP empfohlen | Akzeptable Geschwindigkeit |
| 5 MB – 20 MB | Komprimierung auf lange Kante ≤ 3840 px + Qualität 85 | Nahezu verlustfreie Qualität, deutlich schnellere Verarbeitung |
| 20 MB – 50 MB | Komprimierung zwingend, Nutzung von file_id | Vermeidung von Base64-Limitüberschreitungen |
| > 50 MB | Überschreitet das harte Limit, zwingende Komprimierung | Andernfalls direkte Fehlermeldung |
💡 Tipp für Batch-Szenarien: Bei hochfrequenten Aufgaben wie dem Freistellen von E-Commerce-Bildern oder der Stapelverarbeitung von Stilen empfehlen wir, die Bilder vor dem Upload mit
sharpoderPilloweinheitlich auf "lange Kante 3840 px + JPG-Qualität 85" vorzukomprimieren. Wir haben dies bei Unternehmenskunden von APIYI (apiyi.com) validiert: Dieser Schritt reduziert die End-to-End-Dauer einer einzelnen Edit-Anfrage um über 40 %, bei null Beschwerden über die Bildqualität.
gpt-image-2 API-Schnellstart: Codebeispiel für die Bearbeitung mehrerer Bilder
gpt-image-2 nutzt das Standard-OpenAI-Schnittstellenprotokoll. Hier ist ein einfaches Beispiel für eine Bearbeitung mit mehreren Referenzbildern. Bei der Nutzung über APIYI müssen Sie lediglich die base_url anpassen:
import base64
from openai import OpenAI
client = OpenAI(
api_key="sk-your-apiyi-key",
base_url="https://api.apiyi.com/v1" # APIYI einheitliche Schnittstelle
)
def to_data_url(path):
with open(path, "rb") as f:
b64 = base64.b64encode(f.read()).decode()
return f"data:image/jpeg;base64,{b64}"
result = client.images.edit(
model="gpt-image-2",
image=[to_data_url("product.jpg"), to_data_url("style-ref.jpg")],
prompt="Verschmelze das Produktbild mit dem Neon-Cyber-Stil des Referenzbildes, behalte das Hauptobjekt bei",
input_fidelity="high", # Hohe Wiedergabetreue für Details, verbraucht mehr Eingabe-Token
size="2048x2048",
quality="high"
)
print(result.data[0].b64_json[:64]) # Gibt das base64-kodierte Ergebnisbild aus
Einige Parameter-Hinweise: Wenn input_fidelity auf high gesetzt ist, werden Details wie Gesichter oder Logos deutlich besser beibehalten, allerdings auf Kosten eines höheren Token-Verbrauchs für die Bildeingabe. quality und size sind die Haupthebel für die Kosten der Ausgabe. Der Parameter n erlaubt die Erzeugung von bis zu 10 Bildern pro Anfrage. Die Abrechnung erfolgt bei gpt-image-2 nach Token: Texteingabe 5 $/M, Bildeingabe 8 $/M (Cache-Treffer 2 $/M), Bildausgabe 30 $/M. Umgerechnet auf ein einzelnes Bild kostet die Stufe "low" bei 1024×1024 ca. 0,006 $, "medium" ca. 0,05 $ und "high" ca. 0,21 $. Die Ausgabeseite ist dabei immer der größte Kostenfaktor.
Beachten Sie außerdem, dass die offiziellen Ratenbegrenzungen (Rate Limits) je nach Kontostufe variieren: Tier 1 erlaubt nur 5 Bilder/Minute, Tier 4 150 Bilder/Minute und Tier 5 250 Bilder/Minute. Neue Konten haben eine niedrige Stufe, wodurch Batch-Aufgaben schnell an die Grenzen stoßen können. Der Aufruf über Aggregator-Plattformen wie APIYI (apiyi.com) umgeht diese kontospezifischen Beschränkungen und ist ideal für Produktionsumgebungen mit hohem Durchsatz.
Unterschiede bei den Upload-Beschränkungen zwischen gpt-image-2 und Vorgängermodellen
Falls Sie Ihr Projekt von gpt-image-1 oder DALL·E 2 migrieren, sollten Sie einige generationsübergreifende Unterschiede beachten. Die größte Veränderung fand zwischen DALL·E 2 und der GPT-Image-Serie statt: Die Edit-Schnittstelle von DALL·E 2 akzeptierte nur ein quadratisches PNG mit einer Größe von unter 4 MB. Mit der GPT-Image-Serie wurde dies auf 16 Bilder, 50 MB und drei Formate erweitert. Die in vielen alten Projekten fest kodierte Vorverarbeitungslogik für "PNG + 4 MB Komprimierung" kann nach der Migration also deutlich vereinfacht werden.
Das Upgrade von gpt-image-1 auf gpt-image-2 zeigt sich vor allem bei der Auflösung und den Kosten. gpt-image-1 unterstützte nur drei feste Ausgabeformate: 1024×1024, 1536×1024 und 1024×1536. gpt-image-2 bietet nun eine benutzerdefinierte Auflösung mit einer 4K-Ausgabe bei einer maximalen Seitenlänge von 3840 px. Bei den Kosten sinkt der Preis für die Bildeingabe bei gpt-image-2 von 10 $/M auf 8 $/M und für die Bildausgabe von 40 $/M auf 30 $/M. Zudem gibt es eine neue Cache-Treffer-Stufe von 2 $/M, was die Kosten bei Szenarien mit wiederholten Referenzbildern deutlich senkt.
Vergleich der Upload-Beschränkungen: gpt-image-2 vs. Vorgängermodelle
| Vergleichspunkt | DALL·E 2 | gpt-image-1 | gpt-image-2 |
|---|---|---|---|
| Anzahl der Eingabebilder | 1 Bild | Bis zu 16 Bilder | Bis zu 16 Bilder |
| Max. Größe pro Bild | < 4 MB | < 50 MB | < 50 MB |
| Eingabeformate | Nur quadratisches PNG | PNG/WebP/JPG | PNG/WebP/JPG |
| Ausgabeauflösung | Festes Quadrat | 3 feste Größen | Benutzerdefiniert, max. 3840 px |
| Kosten Bildausgabe | Pro Bild | 40 $/M Tokens | 30 $/M Tokens (Cache-Eingabe 2 $/M) |
| input_fidelity | Nicht unterstützt | Unterstützt | Unterstützt, höhere Detailtreue |
Bei der Migration des Codes müssen Sie im Wesentlichen nur den model-Parameter anpassen. Es empfiehlt sich jedoch, die Validierung der Auflösung und die Komprimierungsstrategie gemäß der oben genannten Tabelle zu aktualisieren. Wenn Sie die Migrationsergebnisse vor der Anpassung des Produktionscodes testen möchten, können Sie auf APIYI (apiyi.com) dieselben Materialien verwenden, um beide Modellgenerationen aufzurufen und die Bearbeitungsqualität sowie die tatsächlichen Kosten direkt zu vergleichen.
FAQ: Häufige Fragen zum Bild-Upload bei gpt-image-2
F1: Wie groß darf ein einzelnes Bild bei gpt-image-2 maximal sein?
Die harte Obergrenze liegt bei 50 MB; unterstützt werden PNG, WebP und JPG. Diese Einschränkung finden Sie in den Nutzungsrichtlinien zur Bilderzeugung von OpenAI, nicht in der Referenztabelle für images/edit, weshalb sie auf der Referenzseite oft übersehen wird. Für die Praxis empfehlen wir eine Größe zwischen 1,5 und 5 MB für eine optimale Performance.
F2: Wie funktioniert die Begrenzung auf 16 Bilder?
Der Parameter images akzeptiert bis zu 16 Bildobjekte, wobei jedes Objekt über image_url oder file_id definiert wird. Das Modell verwendet mehrere Bilder als gemeinsame Referenz, was ideal für Szenarien wie "Produktbild + Stilvorlage + Kompositionsreferenz" ist. Beachten Sie, dass 16 die Eingabeobergrenze ist; die Anzahl der Ausgaben wird über den Parameter n gesteuert (maximal 10 Bilder).
F3: Was ist die Ursache für die Fehlermeldung "invalid mask"?
In neun von zehn Fällen liegt ein Problem mit dem Alpha-Kanal vor. Die Maske muss dasselbe Format und dieselben Abmessungen wie das zu bearbeitende Bild haben und zwingend einen Alpha-Kanal enthalten. Da JPG keine Alpha-Kanäle unterstützt, muss für die Maske zwingend PNG verwendet werden. Transparente Bereiche markieren die "zu bearbeitenden" Stellen, während undurchsichtige Bereiche unverändert bleiben.
F4: Was ist besser: Base64-Upload oder file_id-Upload?
Für kleine Bilder (< 5 MB) und einmalige Anfragen ist die Base64-Daten-URL am einfachsten. Für große Bilder oder Materialien, die mehrfach verwendet werden sollen, empfiehlt sich der Upload über die Files API, um eine file_id zu erhalten. Dies vermeidet die 33-prozentige Volumenausdehnung von Base64 und ermöglicht die Wiederverwendung über mehrere Anfragen hinweg. Wenn Sie unsicher sind, können Sie beide Methoden in der APIYI (apiyi.com) Konsole testen und die Laufzeiten vergleichen, bevor Sie sich entscheiden.
Zusammenfassung: Die drei entscheidenden Zahlen für Upload-Limits bei gpt-image-2
Kommen wir zurück zur Ausgangsfrage: Die Upload-Beschränkungen der gpt-image-2 Bildbearbeitungs-API lassen sich auf drei Zahlen reduzieren: 16 Bilder (maximale Anzahl pro Eingabe, laut Referenz), 50 MB (maximale Größe pro Bild, laut Benutzerhandbuch) und 1,5 MB (die ideale Größe für die praktische Anwendung). Dass die Dokumentation Anzahl und Größe auf zwei verschiedene Seiten aufteilt, ist der Grund für die Verwirrung um die „16-Bilder-Grenze“.
Die Empfehlung für die Praxis ist simpel: Komprimieren Sie Bilder vor dem Hochladen einheitlich auf eine maximale Kantenlänge von 3840 px und eine JPG-Qualität von etwa 85. Verwenden Sie für Masken immer PNGs mit Alpha-Kanal und übertragen Sie große Assets über den file_id-Kanal. Wenn Sie diese drei Schritte als standardmäßige Vorverarbeitung vor jeder Anfrage etablieren, gehören Fehlermeldungen beim Upload der Vergangenheit an.
Falls Sie gpt-image-2 innerhalb Chinas stabil aufrufen möchten oder die Ratenbegrenzung auf ein produktionsreifes Niveau heben wollen, können Sie dies über die einheitliche Schnittstelle von APIYI (apiyi.com) tun. Diese ist mit der nativen OpenAI-SDK-Syntax kompatibel – eine einfache Änderung der base_url genügt für die Migration.
Referenzmaterial: OpenAI API Reference: developers.openai.com/api/reference/resources/images/methods/edit
Autor: APIYI Team
Wir konzentrieren uns auf die Aggregation von APIs für große Sprachmodelle und Best Practices. Weitere Modellbewertungen und Integrationsleitfäden finden Sie unter APIYI apiyi.com.
