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

# Flux Kontext Bildgenerierung

> - Asynchrone Verarbeitung; nach dem Absenden wird eine Aufgaben-ID zur späteren Abfrage zurückgegeben

- Pro und Max unterstützen sowohl Text-zu-Bild als auch die Bearbeitung mit Referenzbildern

- `expires_at` im Generierungsergebnis gibt den Ablaufzeitpunkt des Bildlinks an


<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": "flux-kontext-pro",
      "prompt": "Change hair color to blue",
      "image_urls": ["https://upload.apimart.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
      "size": "16:9"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "flux-kontext-pro",
      "prompt": "Change hair color to blue",
      "image_urls": ["https://upload.apimart.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
      "size": "16:9"
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "flux-kontext-pro",
    prompt: "Change hair color to blue",
    image_urls: ["https://upload.apimart.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
    size: "16:9"
  };

  const headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
  })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error("Error:", error));
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2"
      }
    ]
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "Authentifizierung fehlgeschlagen. Überprüfen Sie Ihren API-Key.",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "Unzureichendes Guthaben. Bitte laden Sie Ihr Konto auf.",
      "type": "payment_required"
    }
  }
  ```
</ResponseExample>

## Unterstützte Modelle

| Modell             | Beschreibung                                                            |
| ------------------ | ----------------------------------------------------------------------- |
| `flux-kontext-pro` | Flux Kontext Pro für Bildgenerierung und -bearbeitung                   |
| `flux-kontext-max` | Flux Kontext Max für Bildgenerierung und -bearbeitung in hoher Qualität |

## Autorisierung

<ParamField header="Authorization" type="string" required>
  Alle Endpunkte erfordern eine Authentifizierung mit einem Bearer-Token.

  API-Key abrufen:

  Rufen Sie die [API-Key-Verwaltung](https://apimart.ai/keys) auf, um Ihren API-Key zu erhalten.

  Fügen Sie ihn dem Anfrage-Header hinzu:

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  Modellname:

  * `flux-kontext-pro` – Kontext Pro für Bildgenerierung und -bearbeitung
  * `flux-kontext-max` – Kontext Max für Bildgenerierung und -bearbeitung in hoher Qualität
</ParamField>

<ParamField body="prompt" type="string" required>
  Textbeschreibung für die Generierung oder Bearbeitung des Bildes.
</ParamField>

<ParamField body="image_urls" type="array">
  Liste der Referenzbilder. Ohne Angabe wird ein Bild aus Text generiert; mit Angabe werden die Bilder bearbeitet.

  **Einschränkungen:**

  * Maximal 4 Bilder
  * Öffentlich erreichbare URLs oder Base64-kodierte Eingabebilder werden unterstützt
  * Die Gesamtpixelzahl des Ausgabebildes und aller Referenzbilder darf 9 MP nicht überschreiten
</ParamField>

<ParamField body="size" type="string" default="1:1">
  Seitenverhältnis des Bildes.

  Unterstützte Seitenverhältnisse:

  * `1:1` – Quadrat (Standard)
  * `4:3` – Querformat 4:3
  * `3:4` – Hochformat 3:4
  * `16:9` – Breitbild im Querformat
  * `9:16` – Breitbild im Hochformat
  * `3:2` – Querformat 3:2
  * `2:3` – Hochformat 2:3
  * `21:9` – Ultra-Breitbild
  * `9:21` – Ultra-Hochformat

  Eine Pixelangabe wie `1024x1536` wird auf das nächstgelegene unterstützte Seitenverhältnis abgebildet und nicht als exakte Pixelgröße ausgegeben. `width` und `height` werden von Kontext nicht unterstützt und führen zum Fehlschlagen der Aufgabe. `resolution` hat bei Kontext keine Wirkung; die Ausgabe liegt bei ungefähr 1 MP.
</ParamField>

<ParamField body="output_format" type="string" default="png">
  Kodierungsformat des Ausgabebildes:

  * `png` – PNG-Format (Standard)
  * `jpeg` – JPEG-Format
  * `webp` – WebP-Format
</ParamField>

<ParamField body="response_format" type="string">
  Kompatibilitätsparameter für die Antwortform. Zulässige Werte sind `url` und `b64_json`. Dieser Parameter ändert die Bildkodierung nicht; dafür ist `output_format` maßgeblich und hat Vorrang.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Anzahl der zu generierenden Bilder. Der Wert muss `1` sein. Für mehrere Bilder müssen mehrere Aufgaben übermittelt werden.
</ParamField>

<ParamField body="seed" type="integer">
  Zufalls-Seed. Ein fester Seed erzeugt bei unveränderten übrigen Parametern dasselbe Ergebnis; ohne Angabe wird er zufällig gewählt.
</ParamField>

<ParamField body="prompt_upsampling" type="boolean" default="false">
  Legt fest, ob die Prompt-Erweiterung aktiviert wird:

  * `true` – aktiviert
  * `false` – deaktiviert (Standard)

  > Setzen Sie den Wert ausdrücklich auf `false`, um die Prompt-Umformulierung zu deaktivieren.
</ParamField>

<ParamField body="safety_tolerance" type="integer" default="2">
  Toleranzstufe der Inhaltsprüfung.

  Bereich: 0–6. Höhere Werte bedeuten eine weniger strenge Prüfung.
</ParamField>

### Tatsächliche Ausgabemaße

| Verhältnis | Tatsächliche Ausgabegröße |
| ---------- | ------------------------- |
| `1:1`      | 1024×1024                 |
| `4:3`      | 1184×880                  |
| `3:4`      | 880×1184                  |
| `16:9`     | 1392×752                  |
| `9:16`     | 752×1392                  |
| `3:2`      | 1248×832                  |
| `2:3`      | 832×1248                  |
| `21:9`     | 1568×672                  |
| `9:21`     | 672×1568                  |

## Anwendungsbeispiele

**Bildbearbeitung mit Eingabebild**

```json theme={null}
{
  "model": "flux-kontext-pro",
  "prompt": "Change the background to a beach",
  "image_urls": ["https://example.com/photo.jpg"],
  "size": "16:9",
  "output_format": "png"
}
```

**Reine Text-zu-Bild-Generierung**

```json theme={null}
{
  "model": "flux-kontext-max",
  "prompt": "A blue cat",
  "size": "1:1",
  "seed": 12345
}
```

**Bearbeitung mit mehreren Referenzbildern**

```json theme={null}
{
  "model": "flux-kontext-max",
  "prompt": "Place the person from image 1 into the scene from image 2 and harmonize the lighting",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/scene.jpg"
  ],
  "size": "4:3"
}
```

## Response

<ResponseField name="code" type="integer">
  Statuscode der Antwort.
</ResponseField>

<ResponseField name="data" type="array">
  Array der Antwortdaten.

  <Expandable title="Eigenschaften">
    <ResponseField name="status" type="string">
      Aufgabenstatus:

      * `submitted` – übermittelt
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Eindeutige Aufgaben-ID zur späteren Abfrage des Ergebnisses.
    </ResponseField>
  </Expandable>
</ResponseField>

## Aufgabenergebnis abfragen

Fragen Sie nach erfolgreicher Übermittlung den Aufgabenstatus über `GET /v1/tasks/{task_id}` ab. Weitere Informationen finden Sie unter [Aufgabenstatus abfragen](/de/api-reference/tasks/status).

### Beispiel einer erfolgreichen Antwort

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2",
    "status": "completed",
    "progress": 100,
    "created": 1785133674,
    "completed": 1785133683,
    "actual_time": 9,
    "estimated_time": 15,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/xxxxxxxx-flux-kontext.png"
          ],
          "expires_at": 1785220083
        }
      ]
    }
  }
}
```

Das Bild befindet sich unter `data.result.images[0].url[0]`. `expires_at` ist der Unix-Zeitstempel, zu dem dieser Link abläuft. Speichern Sie das Bild vor diesem Zeitpunkt.

### Aufgabenstatus

| Status                  | Bedeutung                                                                          |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `submitted` / `pending` | Die Aufgabe wurde angenommen oder wartet auf die Verarbeitung; weiter abfragen     |
| `processing`            | Die Generierung läuft; weiter abfragen                                             |
| `completed`             | Die Generierung war erfolgreich; das Ergebnis befindet sich unter `result.images`  |
| `failed`                | Die Generierung ist fehlgeschlagen; Einzelheiten stehen unter `data.error.message` |

### Ungültige Modellparameter und fehlgeschlagene Aufgaben

Ungültige Modellparameter werden asynchron gemeldet: Die Übermittlung liefert HTTP 200 und eine `task_id`. Erst beim Abfragen der Aufgabe erscheint der Endstatus `failed` mit dem konkreten Grund unter `data.error.message`. Deshalb muss bis zu einem Endstatus abgefragt werden.

```json theme={null}
{
  "code": 200,
  "data": {
    "status": "failed",
    "error": {
      "type": "task_failed",
      "code": "task_failed",
      "message": "width/height are not supported by flux-kontext-pro"
    }
  }
}
```

`data.error.code` lautet bei solchen Fehlern immer `task_failed`; der konkrete Grund steht in `message`. Fehlgeschlagene Aufgaben werden vollständig erstattet.

## Hinweise

1. **Asynchrone Verarbeitung**: Nach dem Absenden wird eine `task_id` zurückgegeben. Fragen Sie `/v1/tasks/{task_id}` ab, um das Ergebnis zu erhalten.
2. **Referenzbilder**: Es werden maximal 4 Referenzbilder als öffentlich erreichbare Bild-URLs oder Base64-kodierte Eingabebilder unterstützt. Zusammen mit dem Ausgabebild dürfen sie höchstens 9 MP umfassen.
3. **Größenregeln**: Das Standardverhältnis ist `1:1`. Pixelangaben werden auf das nächstgelegene unterstützte Verhältnis abgebildet; `width`/`height` werden abgelehnt und `resolution` hat keine Wirkung. Kontext gibt ungefähr 1 MP aus.
4. **Bildanzahl**: `n` muss `1` sein; pro Anfrage wird genau ein Bild generiert.
5. **Prompt-Umformulierung**: Setzen Sie ausdrücklich `prompt_upsampling: false`, um die Prompt-Umformulierung zu deaktivieren.
6. **Ergebnislink**: Die Gültigkeit der Bild-URL richtet sich nach dem zugehörigen Unix-Zeitstempel `expires_at`. Speichern Sie das Bild rechtzeitig.
7. **Nicht erreichbare Referenz-URL**: Die Meldung `temporarily unavailable dependency` kann auf eine nicht erreichbare Referenzdatei hinweisen. Prüfen Sie in diesem Fall zuerst, ob die URL öffentlich erreichbar ist und weder Zugriffsschutz noch eine abgelaufene Signatur verwendet.