> ## Documentation Index
> Fetch the complete documentation index at: https://www.krea.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Krea 3 API: Überblick

> Krea 3 API: ein schnelles Bildbearbeitungsmodell, das Anweisungen präzise umsetzt. Endpunkt, Parameter, Denkmodi, regionale Bearbeitungen und Preise.

Krea 3 ist ein schnelles Bildbearbeitungsmodell. Es folgt Anweisungen in natürlicher Sprache: Du sagst, was sich ändern und was gleich bleiben soll, und Krea 3 setzt die Bearbeitung in Sekunden um. Du kannst es auch für die Text-zu-Bild-Generierung verwenden.

<Info>
  Die Krea 3 API befindet sich im **Early Access**. Nur Workspaces in der Krea-3-Beta können sie aufrufen. Um Zugang anzufragen, kontaktiere [sales@krea.ai](mailto:sales@krea.ai).
</Info>

## Endpunkt

| Modell | Endpunkt |
| - | - |
| **Krea 3** | `POST /generate/image/krea/krea-3` |

Der Endpunkt folgt dem standardmäßigen [Job-Lebenszyklus](/docs/de/developers/job-lifecycle): Er gibt eine `job_id` zurück, und du fragst `GET /jobs/{job_id}` per Polling ab (oder nutzt einen [Webhook](/docs/de/developers/webhooks)), bis der Job abgeschlossen ist. Das Ausgabebild findest du in `result.urls[0]`.

## Schnellstart: deine erste Bildbearbeitung

Alle Anfragen benötigen einen Bearer-Token. Siehe [API-Schlüssel & Abrechnung](/docs/de/developers/api-keys-and-billing), falls du noch keinen hast.

<Steps>
  <Step title="Referenz hochladen">
    `POST /assets` mit deinem Eingabebild. Die Antwort enthält `image_url`. Du kannst in `image_urls` auch direkt eine externe Bild-URL oder eine Base64-Data-URI übergeben.
  </Step>

  <Step title="Bearbeitung erstellen">
    `POST /generate/image/krea/krea-3` mit deinem Prompt und deiner Referenz. Speichere die `job_id` aus der Antwort.
  </Step>

  <Step title="Ergebnis abrufen">
    Frage `GET /jobs/{job_id}` per Polling ab, bis `status` den Wert `completed` hat. Die Ausgabe findest du in `result.urls[0]`.
  </Step>
</Steps>

<CodeGroup>
  ```bash cURL theme={null}
  # Bash + curl + jq. Set KREA_API_TOKEN to your API token first.
  set -euo pipefail
  : "${KREA_API_TOKEN:?Set your Krea API token}"

  # 1. Upload a reference
  ASSET=$(curl --fail-with-body --silent --show-error --max-time 60 \
    https://api.krea.ai/assets \
    -H "Authorization: Bearer $KREA_API_TOKEN" \
    -F "file=@reference.png")

  IMAGE_URL=$(printf '%s' "$ASSET" | jq -er '.image_url')

  # 2. Create an edit
  PAYLOAD=$(jq -n --arg image "$IMAGE_URL" '{
    prompt: "Place the product on a clean studio background",
    thinking_mode: "fast",
    image_urls: [$image],
    resolution: "2k"
  }')

  JOB=$(curl --fail-with-body --silent --show-error --max-time 60 \
    https://api.krea.ai/generate/image/krea/krea-3 \
    -H "Authorization: Bearer $KREA_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d "$PAYLOAD")

  JOB_ID=$(printf '%s' "$JOB" | jq -er '.job_id')

  # 3. Get the result
  for attempt in $(seq 1 150); do
    JOB=$(curl --fail-with-body --silent --show-error --max-time 30 \
      "https://api.krea.ai/jobs/$JOB_ID" \
      -H "Authorization: Bearer $KREA_API_TOKEN")
    STATUS=$(printf '%s' "$JOB" | jq -er '.status')
    case "$STATUS" in
      completed)
        printf '%s' "$JOB" | jq -er '.result.urls[0]'
        exit 0 ;;
      failed|cancelled)
        printf 'Job ended: %s\n' "$STATUS" >&2; exit 1 ;;
      scheduled|processing|queued|backlogged|sampling|intermediate-complete)
        sleep 2 ;;
      *) printf 'Unexpected status: %s\n' "$STATUS" >&2; exit 1 ;;
    esac
  done
  printf 'Polling timed out\n' >&2
  exit 1
  ```

  ```python Python theme={null}
  # Python 3 + requests: pip install requests
  # Set KREA_API_TOKEN to your API token first.
  import os
  import time
  import requests

  api = "https://api.krea.ai"
  headers = {"Authorization": f"Bearer {os.environ['KREA_API_TOKEN']}"}

  # 1. Upload a reference
  with open("reference.png", "rb") as image:
      response = requests.post(
          f"{api}/assets", headers=headers,
          files={"file": image}, timeout=60,
      )
  response.raise_for_status()
  image_url = response.json()["image_url"]

  # 2. Create an edit
  response = requests.post(
      f"{api}/generate/image/krea/krea-3",
      headers=headers,
      json={
          "prompt": "Place the product on a clean studio background",
          "thinking_mode": "fast",
          "image_urls": [image_url],
          "resolution": "2k",
      },
      timeout=60,
  )
  response.raise_for_status()
  job_id = response.json()["job_id"]

  # 3. Get the result
  pending = {"scheduled", "processing", "queued", "backlogged",
             "sampling", "intermediate-complete"}
  deadline = time.monotonic() + 300

  while time.monotonic() < deadline:
      response = requests.get(
          f"{api}/jobs/{job_id}", headers=headers, timeout=30,
      )
      response.raise_for_status()
      job = response.json()
      if job["status"] == "completed":
          print(job["result"]["urls"][0])
          break
      if job["status"] not in pending:
          raise RuntimeError(f"Job ended: {job['status']}")
      time.sleep(2)
  else:
      raise TimeoutError("Polling timed out")
  ```

  ```javascript Node.js theme={null}
  // Node.js 22+. Save as example.mjs.
  // Set KREA_API_TOKEN to your API token first.
  import { readFile } from "node:fs/promises";

  const token = process.env.KREA_API_TOKEN;
  if (!token) throw new Error("Set your Krea API token");
  const api = "https://api.krea.ai";
  const headers = { Authorization: `Bearer ${token}` };

  async function request(path, options = {}) {
    const response = await fetch(`${api}${path}`, {
      ...options,
      headers: { ...headers, ...options.headers },
      signal: AbortSignal.timeout(60_000),
    });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  }

  // 1. Upload a reference
  const form = new FormData();
  form.append("file", new Blob([await readFile("reference.png")]), "reference.png");
  const asset = await request("/assets", { method: "POST", body: form });

  // 2. Create an edit
  const job = await request("/generate/image/krea/krea-3", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      prompt: "Place the product on a clean studio background",
      thinking_mode: "fast",
      image_urls: [asset.image_url],
      resolution: "2k",
    }),
  });

  // 3. Get the result
  const pending = new Set([
    "scheduled", "processing", "queued", "backlogged",
    "sampling", "intermediate-complete",
  ]);
  const deadline = Date.now() + 300_000;
  let imageUrl;

  while (Date.now() < deadline) {
    const result = await request(`/jobs/${job.job_id}`);
    if (result.status === "completed") {
      imageUrl = result.result.urls[0];
      break;
    }
    if (!pending.has(result.status)) {
      throw new Error(`Job ended: ${result.status}`);
    }
    await new Promise((resolve) => setTimeout(resolve, 2_000));
  }
  if (!imageUrl) throw new Error("Polling timed out");
  console.log(imageUrl);
  ```
</CodeGroup>

<Tip>
  Bewahre deinen API-Token auf deinem Server auf. Liefere ihn niemals in clientseitigem Code aus.
</Tip>

## Parameter

| Feld | Typ | Hinweise |
| - | - | - |
| `prompt` | string | **Erforderlich.** Die Bearbeitungsanweisung. Beschreibe, was sich ändern und was gleich bleiben soll. |
| `image_urls` | array of strings | Optional. Eingabebilder als Referenzen, bis zu 8. Gib für eine Bearbeitung mindestens eines an; lass das Feld für die Text-zu-Bild-Generierung weg. Akzeptiert eine `image_url` aus `POST /assets`, eine externe URL oder eine Base64-Data-URI. |
| `thinking_mode` | enum | Optional. `fast` (Standard) oder `high`. Siehe [Denkmodi](#thinking-modes). |
| `resolution` | enum | `1k` oder `2k`. Erforderlich, sofern du nicht sowohl `width` als auch `height` angibst. Kombiniere es nicht mit `width` und `height`. |
| `aspect_ratio` | enum | Optional. Einer der Werte `1:1`, `4:5`, `3:4`, `2:3`, `9:16`, `5:4`, `4:3`, `3:2`, `16:9`, `21:9`. Verwende es zusammen mit `resolution`. Lass es für eine automatische Bildaufteilung weg. |
| `width` / `height` | integers | Optional. Gewünschte Abmessungen, positive Ganzzahlen bis jeweils 4096. Gib beide an, ohne `resolution` oder `aspect_ratio`. |
| `seed` | integer | Optional. Lass es weg, um einen zufälligen Seed zu verwenden. |
| `negative_prompt` | string | Optional. Was vermieden werden soll, bis zu 1.024 Zeichen. |
| `regional_edit` | boolean | Optional. Setze es auf `true` für eine lokale Bearbeitung, bei der der Rest des Bildes exakt erhalten bleibt. Erfordert mindestens ein Bild in `image_urls`. Siehe [Regionale Bearbeitungen](#regional-edits). |

<Note>
  Mit `width` und `height` wird die Ausgabe auf das nächstgelegene unterstützte Seitenverhältnis und eine 1k- oder 2k-Leinwand gerundet. Exakte Pixelabmessungen sind nicht garantiert.

  Die Wiederverwendung eines `seed` garantiert keine identischen Ergebnisse, da der Schritt der Prompt-Erweiterung zwischen Durchläufen variieren kann.
</Note>

<h2 id="thinking-modes">
  Denkmodi
</h2>

Vor der Generierung interpretiert Krea 3 deinen Prompt. `thinking_mode` legt fest, wie viel Planung dabei stattfindet.

| Modus | Was passiert | Geeignet für |
| - | - | - |
| `fast` | Krea erweitert den Prompt schnell und generiert dann. Am schnellsten. **Standard und empfohlen.** | Klare, einfache Bearbeitungen und die meisten alltäglichen Anfragen. |
| `high` | Krea nutzt eine leistungsstärkere Reasoning-Engine, um komplexere Bearbeitungen anhand des Prompts und der Referenzbilder zu planen, und generiert dann. Langsamer. | Komplexe oder mehrstufige Bearbeitungen, mehrere zu kombinierende Referenzen oder ein `fast`-Ergebnis, das die Anfrage verfehlt hat. |

Wenn du `thinking_mode` weglässt, verwendet die API `fast`. Beide Modi unterstützen `regional_edit`.

<h2 id="regional-edits">
  Regionale Bearbeitungen
</h2>

Mit `regional_edit: true` generiert Krea 3 nur die Bildbereiche neu, die sich ändern müssen. Alles andere bleibt exakt so, wie es war. So kannst du dasselbe Bild immer wieder bearbeiten, ohne an Qualität zu verlieren.

**Verwende es für lokale Bearbeitungen**, bei denen der Rest des Bildes pixelgenau erhalten bleiben muss: ein Objekt umfärben oder austauschen, ein Element hinzufügen oder entfernen, ein Detail korrigieren oder den Text auf einem Schild ändern. Das ist der sichere Weg, um Bearbeitungen an der jeweils neuesten Ausgabe aneinanderzureihen.

**Lass es bei globalen Bearbeitungen weg**, die das gesamte Bild neu rendern sollen: Stil oder Beleuchtung ändern, Jahres- oder Tageszeit wechseln, den Bildausschnitt neu wählen oder mehrere Bilder zu einer neuen Szene kombinieren. Reguläre Bearbeitungen rendern das gesamte Bild neu, daher können sich Artefakte ansammeln, wenn du die neueste Ausgabe immer weiter bearbeitest.

Regionale Bearbeitungen erfordern mindestens ein Bild in `image_urls`.

```json theme={null}
{
  "prompt": "Change the mug to red, keeping everything else the same",
  "image_urls": ["IMAGE_URL"],
  "thinking_mode": "fast",
  "resolution": "2k",
  "regional_edit": true
}
```

## Prompting

Krea 3 ist ein Editor, der Anweisungen präzise umsetzt. Formuliere die Bearbeitung in natürlicher Sprache:

* Beginne mit der Änderung. Füge nur Details hinzu, die bei der Umsetzung helfen.
* Schließe mit einem Satz zur Beibehaltung ab, wenn der Rest des Bildes gleich bleiben soll. Liste nicht alles auf, was gleich bleiben soll.
* Wenn der Prompt mehr als ein Bild verwendet, bezeichne jedes Bild anhand dessen, was es zeigt. Zum Beispiel: „Zieh der Person im ersten Bild den Sneaker aus dem zweiten Bild an.“

```text theme={null}
Change the mug to red, keeping everything else the same.
```

## Referenzbilder

* Krea 3 verwendet jede Referenz in ihrer hochgeladenen Auflösung. Eine Referenz mit mehr als 4 MP wird auf 4 MP verkleinert.
* Etwa 1 MP reicht für die meisten Bearbeitungen aus. Skaliere eine Referenz vor dem Senden nicht hoch.
* Wenn es auf feine Details ankommt (kleiner Text, Logos, Stoffe, Gesichter in einer Totalen), sende die Version des Bildes mit der höchsten Auflösung, die du hast.
* Bei fünf oder mehr Referenzen in einer Anfrage wird jede Referenz an ihrer längsten Seite auf höchstens 1536 px verkleinert. Für Referenzen mit vollem Detailgrad sende vier oder weniger.

## Zero Data Retention

Krea 3 unterstützt [Zero Data Retention](/docs/de/developers/zdr) für Enterprise-Workspaces. Sende den Header `X-Api-Zero-Data-Retention: 1`. Mit Zero Data Retention gilt:

* Jedes Bild in `image_urls` muss eine Base64-Data-URI sein.
* `thinking_mode` kann `fast` oder `high` sein.
* Eine Anfrage kann höchstens 4 Referenzbilder verwenden.

```bash theme={null}
IMAGE_DATA_URI="data:image/png;base64,$(base64 < ./reference.png | tr -d '\n')"

curl -X POST https://api.krea.ai/generate/image/krea/krea-3 \
  -H "Authorization: Bearer $KREA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Api-Zero-Data-Retention: 1" \
  -d '{
    "prompt": "Change the mug to red, keeping everything else the same",
    "image_urls": ["'"$IMAGE_DATA_URI"'"],
    "thinking_mode": "fast",
    "resolution": "2k"
  }'
```

## Preise

Der Preis pro Bild hängt von der Ausgabeauflösung, dem Denkmodus und den Referenzbildern ab.

| Preiskomponente | 1K-Ausgabe | 2K-Ausgabe |
| - | - | - |
| Grundpreis | \$0.03 | \$0.06 |
| Jedes 1K-Referenzbild | +\$0.02 | +\$0.02 |
| Jedes 2K-Referenzbild | +\$0.07 | +\$0.07 |
| Denkmodus `high` | +\$0.02 pro Generierung | +\$0.02 pro Generierung |

## Verwandte Themen

<CardGroup cols={2}>
  <Card title="Job-Lebenszyklus" icon="arrows-rotate" href="/docs/de/developers/job-lifecycle">
    Job-Status, Polling und Ergebnisse.
  </Card>

  <Card title="Webhooks" icon="bell" href="/docs/de/developers/webhooks">
    Lass dich benachrichtigen, wenn ein Job abgeschlossen ist, statt Polling zu nutzen.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.