> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/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
- 15 Seitenverhältnisse, exakte Pixelmaße sowie 1K / 2K / 4K
- Qualitätsstufen low / medium / high / xhigh / max 

<Info>
  **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.
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --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
    }'
  ```
</RequestExample>

<ResponseExample>
  ```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"
    }
  }
  ```
</ResponseExample>

## Authentifizierung

<ParamField header="Authorization" type="string" required>
  Alle Endpunkte verwenden Bearer-Token-Authentifizierung. Den Schlüssel erhalten Sie auf der [API-Schlüssel-Seite](https://apimart.ai/keys).

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## 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

<ParamField body="model" type="string" required>
  Modellname: `gpt-image-2.5-flare` oder `gpt-image-2.5-sunburst`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Textbeschreibung des zu erzeugenden oder zu bearbeitenden Bildes. Beschreiben Sie Motiv, Szene, Komposition, Stil, Beleuchtung und gewünschte Änderungen.
</ParamField>

<ParamField body="size" type="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`.
  </Tip>
</ParamField>

<ParamField body="resolution" type="string" default="1k">
  Auflösungsstufe: `1k`, `2k` oder `4k`. Bei exakten Pixelmaßen wird dieses Feld ignoriert.
</ParamField>

<ParamField body="quality" type="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.
  </Warning>
</ParamField>

<ParamField body="n" type="integer" default="1">
  Anzahl der Bilder: `1` bis `4`. Als Zahl, nicht als Zeichenkette, senden.
</ParamField>

<ParamField body="output_format" type="string" default="png">
  Ausgabeformat: `png`, `jpeg` oder `webp`.
</ParamField>

<ParamField body="output_compression" type="integer">
  Kompressionsstärke von `0` bis `100`, nur für `jpeg` und `webp`.
</ParamField>

<ParamField body="background" type="string">
  Hintergrund: `transparent`, `opaque` oder `auto`.

  <Warning>
    `transparent` erfordert `png` oder `webp`; JPEG besitzt keinen Alphakanal.
  </Warning>
</ParamField>

<ParamField body="moderation" type="string" default="low">
  Moderationsstufe: `auto` oder `low`. Ohne Angabe sendet APIMart ausdrücklich `low`; ein angegebenes `auto` wird unverändert weitergegeben.
</ParamField>

<ParamField body="image_urls" type="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.
</ParamField>

## 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.
</Warning>

### 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"
}
```

## Ü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](/de/api-reference/tasks/status) 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.apimart.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://apimart.ai/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.
</Warning>

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

<ResponseField name="code" type="integer">
  Antwortstatuscode; 200 bei erfolgreicher Übermittlung.
</ResponseField>

<ResponseField name="data" type="array">
  Daten der Übermittlungsantwort.

  <Expandable title="Array-Element">
    <ResponseField name="status" type="string">
      Anfangsstatus: `submitted`.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Eindeutige Aufgaben-ID für Status- und Ergebnisabfragen.
    </ResponseField>
  </Expandable>
</ResponseField>