> ## Documentation Index > Fetch the complete documentation index at: https://gccai.heqingsong.uk/llms.txt > Use this file to discover all available pages before exploring further. # GPT-Image-2.5 Bildgenerierung > - Auswahl zwischen gpt-image-2.5-flare und gpt-image-2.5-sunburst - Asynchrone Verarbeitung mit task_id für spätere Abfragen - Text-zu-Bild und Bildbearbeitung mit bis zu 16 Referenzbildern - Lokales Inpainting mit transparenten PNG-Masken - 15 Seitenverhältnisse, exakte Pixelmaße sowie 1K / 2K / 4K - Qualitätsstufen low / medium / high / xhigh / max > [!NOTE] > > **Modellwahl:** `gpt-image-2.5-flare` ist schneller und eignet sich für hochwertige Alltagsbilder, Serienproduktion und schnelle Prototypen. `gpt-image-2.5-sunburst` priorisiert Bearbeitungspräzision für finale Produktbilder, Werbemittel und detaillierte mehrstufige Bearbeitung. Beide Modelle werden gleich abgerechnet. ```bash cURL theme={null} curl --request POST \ --url https://gccai.heqingsong.uk/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "gpt-image-2.5-flare", "prompt": "eine gemütliche Leseecke an einem regnerischen Fenster, warmes Lampenlicht", "size": "1:1", "resolution": "1k", "quality": "medium", "n": 1 }' ``` ```json 200 theme={null} { "code": 200, "data": [ { "status": "submitted", "task_id": "task_01KXXXXXXXXXXXXXXX" } ] } ``` ```json 400 theme={null} { "error": { "code": 400, "message": "Ungültige Anfrageparameter", "type": "invalid_request_error" } } ``` ```json 401 theme={null} { "error": { "code": 401, "message": "Authentifizierung fehlgeschlagen. API-Schlüssel prüfen.", "type": "authentication_error" } } ``` ```json 402 theme={null} { "error": { "code": 402, "message": "Kontoguthaben nicht ausreichend", "type": "payment_required" } } ``` ## Authentifizierung **Authorization** `string` *required* Alle Endpunkte verwenden Bearer-Token-Authentifizierung. Den Schlüssel erhalten Sie auf der [API-Schlüssel-Seite](https://gccai.heqingsong.uk/keys). ``` Authorization: Bearer YOUR_API_KEY ``` ## Modell auswählen | Modell | Stärke | Empfohlene Verwendung | | - | - | - | | `gpt-image-2.5-flare` | Schnellere Standardvariante | Social Media, Produktbilder, visuelle Suche, Prototypen und Seriengenerierung | | `gpt-image-2.5-sunburst` | Höhere Bearbeitungspräzision | Finale Produktbilder, Werbemittel und detaillierte mehrstufige Bearbeitung | Tokenverbrauch und Preis sind bei gleichen Parametern identisch. Die Wahl hängt nur von Geschwindigkeit und Qualität ab. Gegenüber `gpt-image-2` kommen `xhigh` und `max` hinzu; `medium` und `high` benötigen ungefähr ein Viertel der Ausgabe-Token der gleichnamigen Vorgängerstufen. ## Anfrageparameter **model** `string` *required* Modellname: `gpt-image-2.5-flare` oder `gpt-image-2.5-sunburst`. **prompt** `string` *required* Textbeschreibung des zu erzeugenden oder zu bearbeitenden Bildes. Beschreiben Sie Motiv, Szene, Komposition, Stil, Beleuchtung und gewünschte Änderungen. **size** `string` (default: auto) Seitenverhältnis oder exakte Pixelmaße. * `auto`: automatische Wahl anhand von Prompt oder Referenzbildern * Verhältnis: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `2:1`, `1:2`, `21:9`, `9:21`, `3:1`, `1:3` * Exakte Maße, zum Beispiel `1600x1200` > [!TIP] > > Bei Bild-zu-Bild-Anfragen sollte `size` entfallen. Der Dienst berechnet die Maße aus dem Eingabeverhältnis und `resolution`. **resolution** `string` (default: 1k) Auflösungsstufe: `1k`, `2k` oder `4k`. Bei exakten Pixelmaßen wird dieses Feld ignoriert. **quality** `string` (default: auto) Bildqualität: `low`, `medium`, `high`, `xhigh`, `max` oder `auto`. > [!WARNING] > > `xhigh` und `max` werden nur von GPT-Image-2.5 unterstützt. Bei `gpt-image-2` führt dies zu HTTP 400; es gibt keine automatische Herabstufung. **n** `integer` (default: 1) Anzahl der Bilder: `1` bis `4`. Als Zahl, nicht als Zeichenkette, senden. **output\_format** `string` (default: png) Ausgabeformat: `png`, `jpeg` oder `webp`. **output\_compression** `integer` Kompressionsstärke von `0` bis `100`, nur für `jpeg` und `webp`. **background** `string` Hintergrund: `transparent`, `opaque` oder `auto`. > [!WARNING] > > `transparent` erfordert `png` oder `webp`; JPEG besitzt keinen Alphakanal. **moderation** `string` (default: low) Moderationsstufe: `auto` oder `low`. Ohne Angabe sendet GccAi ausdrücklich `low`; ein angegebenes `auto` wird unverändert weitergegeben. **image\_urls** `string[]` Referenzbilder für Bild-zu-Bild oder Bearbeitung, maximal `16`. Dieses Feld aktiviert automatisch den Bearbeitungsmodus. Es werden nur öffentlich erreichbare HTTP(S)-URLs akzeptiert. Lokale Bilder zuerst über `POST /v1/uploads/images` hochladen und anschließend die zurückgegebene `url` verwenden. **mask\_url** `string` Maske für lokales Inpainting. Sie wirkt nur, wenn auch `image_urls` angegeben ist. Sowohl `gpt-image-2.5-flare` als auch `gpt-image-2.5-sunburst` unterstützen diesen Parameter. Übergeben Sie eine einzelne Zeichenfolge in einem der folgenden Formate: * Eine HTTP(S)-Bild-URL, die der Server direkt herunterladen kann * Eine PNG-Data-URL im Format `data:image/png;base64,...` Anforderungen an die Maske: * PNG mit transparentem Alphakanal verwenden; PNG wird auch für das Quellbild empfohlen * Die Pixelmaße müssen exakt mit `image_urls[0]` übereinstimmen. Maßgeblich ist das erste Eingabebild, nicht die Ausgabegröße `size` * Vollständig transparente Pixel (`alpha=0`) markieren den zu ändernden Bereich; der übrige Bereich dient zur Erhaltung * Pro Anfrage nur eine Maske. Bei mehreren Referenzbildern wirkt sie ausschließlich auf das erste Eingabebild * Der allgemeine Dateigrößenleitfaden nennt weniger als `50 MB`, die Beschreibung des Parameters `mask` weniger als `4 MB`. Bis zur Überprüfung gilt die strengere Grenze von `4 MB` > [!WARNING] > > Ein gewöhnliches Schwarzweißbild ohne Alphakanal kann nicht direkt als Maske verwendet werden. GccAi ergänzt keinen Alphakanal und prüft derzeit nicht vorab, ob Maske und Quellbild dieselben Maße haben; der aufrufende Client muss beides sicherstellen. > [!NOTE] > > Eine HTTP(S)-URL muss ohne Cookies oder zusätzliche Authentifizierungsheader erreichbar sein. Signierte URLs müssen während Warteschlange und Ausführung gültig bleiben. Standardmäßig gelten ein Downloadlimit von `20 MB` und ein Timeout von `60` Sekunden; die Bereitstellung kann diese Standardwerte überschreiben. > > Die Maske steuert die Bearbeitung, das Modell garantiert jedoch nicht, dass Pixel außerhalb der Maskengrenze vollständig unverändert bleiben. ## Größenregeln * Breite und Höhe müssen Vielfache von `16` sein * Keine Seite darf `3840` Pixel überschreiten * Das Verhältnis von langer zu kurzer Seite darf höchstens `3:1` betragen * Die Gesamtpixelzahl muss zwischen `655.360` und `8.294.400` liegen > [!WARNING] > > Auflösungen über 2560×1440 sind experimentell und können weniger stabil sein. ### Verhältnis- und Auflösungszuordnung | `size` | `1k` | `2k` | `4k` | | - | - | - | - | | `1:1` | 1024×1024 | 2048×2048 | 2880×2880 | | `3:2` | 1536×1024 | 2048×1360 | 3520×2336 | | `2:3` | 1024×1536 | 1360×2048 | 2336×3520 | | `4:3` | 1024×768 | 2048×1536 | 3312×2480 | | `3:4` | 768×1024 | 1536×2048 | 2480×3312 | | `5:4` | 1280×1024 | 2560×2048 | 3216×2576 | | `4:5` | 1024×1280 | 2048×2560 | 2576×3216 | | `16:9` | 1536×864 | 2048×1152 | 3840×2160 | | `9:16` | 864×1536 | 1152×2048 | 2160×3840 | | `2:1` | 2048×1024 | 2688×1344 | 3840×1920 | | `1:2` | 1024×2048 | 1344×2688 | 1920×3840 | | `21:9` | 2016×864 | 2688×1152 | 3840×1648 | | `9:21` | 864×2016 | 1152×2688 | 1648×3840 | | `3:1` | 1536×512 | 3072×1024 | 3840×1280 | | `1:3` | 512×1536 | 1024×3072 | 1280×3840 | Andere exakte Maße sind möglich, sofern sie alle Größenregeln erfüllen. ## Bearbeitungsbeispiel ```json theme={null} { "model": "gpt-image-2.5-sunburst", "prompt": "Produkt und Verpackungstext beibehalten, Hintergrund durch ein cremefarbenes Studio ersetzen und natürlichen Schatten hinzufügen", "image_urls": ["https://example.com/product.png"], "resolution": "2k", "quality": "xhigh" } ``` ### Lokales Inpainting mit Maske Dieses Beispiel bearbeitet nur den vollständig transparenten Bereich der Maske. Ihre Maße müssen mit `product.png` übereinstimmen. ```json theme={null} { "model": "gpt-image-2.5-sunburst", "prompt": "nur den Bereich der transparenten Maske durch ein goldenes Band ersetzen und Produkt sowie übrigen Hintergrund erhalten", "image_urls": [ "https://example.com/product.png" ], "mask_url": "https://example.com/product-mask.png", "quality": "xhigh" } ``` ## Übermittlung und Aufgabenabfrage Nach erfolgreicher Übermittlung enthält das Array `data` die neue Aufgaben-ID unter `data[0].task_id`. Fragen Sie sie über den [Aufgabenstatus-Endpunkt](https://gccai.heqingsong.uk/de/api-reference/tasks/status.md) alle 2–5 Sekunden ab, bis `completed` oder `failed` erreicht ist. Für mehrere Aufgaben steht `POST /v1/tasks/batch` bereit. ```json theme={null} { "code": 200, "data": { "id": "task_01KXXXXXXXXXXXXXXX", "status": "completed", "progress": 100, "cost": 0.01325, "result": { "images": [ { "url": ["https://upload.gccai.ai/f/image/example.png"], "expires_at": 1789000000 } ] }, "usage": { "input_tokens": 16, "output_tokens": 439, "total_tokens": 455 } } } ``` Bild-URLs stehen unter `data.result.images[].url[]`. Laden Sie die Dateien zeitnah herunter und speichern Sie sie dauerhaft. | Status | Bedeutung | | - | - | | `submitted` | Aufgabe übermittelt | | `processing` | Generierung läuft | | `completed` | Erfolgreich; `result.images` ist verfügbar | | `failed` | Fehlgeschlagen; `error.message` prüfen; reservierter Betrag wird erstattet | ## Abrechnung GPT-Image-2.5 wird nach tatsächlichem Tokenverbrauch abgerechnet. Aktuelle Kontopreise finden Sie auf der [Preisseite](https://gccai.heqingsong.uk/pricing) oder unter `/api/pricing`. | Posten | Preis pro 1 Mio. Token | | - | - | | Bildausgabe | \$30.00 | | Bildeingabe | \$8.00 | | Bildeingabe aus Cache | \$2.00 | | Texteingabe | \$5.00 | | Texteingabe aus Cache | \$1.25 | | `quality` bei 1024×1024 | Ausgabe-Token | Offizielle Ausgabekosten | | - | - | - | | `low` | 196 | \$0.00588 | | `medium` | 439 | \$0.01317 | | `high` | 1756 | \$0.05268 | | `xhigh` | 3122 | \$0.09366 | | `max` | 7024 | \$0.21072 | > [!WARNING] > > Bei `quality: "auto"` reserviert der Dienst zunächst den Betrag der teuersten Stufe `max` für die gewählte Größe. Nach Abschluss wird anhand des tatsächlichen Verbrauchs abgerechnet und die Differenz freigegeben. Bei `n > 1` steigt die Reservierung linear. Fehlgeschlagene Aufgaben werden automatisch erstattet. ## Grenzen und häufige Fehler | Punkt | Grenze oder Lösung | | - | - | | Bilder pro Anfrage | 1–4 | | Referenzbilder | Maximal 16 | | Ausgabeformat | PNG / JPEG / WebP | | Transparenter Hintergrund | Nur PNG / WebP | | Teilbilder im Stream | Nicht unterstützt | | Ungültige Qualität | `xhigh` / `max` erfordern GPT-Image-2.5 | | Ungültige Pixelmaße | Vielfache von 16 innerhalb der Pixel- und Verhältnisgrenzen verwenden | ## Response **code** `integer` Antwortstatuscode; 200 bei erfolgreicher Übermittlung. **data** `array` Daten der Übermittlungsantwort. **Array-Element** **status** `string` Anfangsstatus: `submitted`. **task\_id** `string` Eindeutige Aufgaben-ID für Status- und Ergebnisabfragen. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.