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

# Vue d'ensemble de l'API Krea 3

> API Krea 3 : un modèle d'édition d'images rapide qui suit vos instructions. Endpoint, paramètres, modes de réflexion, éditions régionales et tarifs.

Krea 3 est un modèle d'édition d'images rapide. Il suit des instructions en langage naturel : vous indiquez ce qui doit changer et ce qui doit rester identique, et Krea 3 réalise l'édition en quelques secondes. Vous pouvez aussi l'utiliser pour la génération texte vers image.

<Info>
  L'API Krea 3 est en **accès anticipé**. Seuls les espaces de travail inscrits à la bêta Krea 3 peuvent l'appeler. Pour demander l'accès, contactez [sales@krea.ai](mailto:sales@krea.ai).
</Info>

## Endpoint

| Modèle | Endpoint |
| - | - |
| **Krea 3** | `POST /generate/image/krea/krea-3` |

L'endpoint suit le [cycle de vie d'un job](/docs/fr/developers/job-lifecycle) standard : il renvoie un `job_id`, puis vous interrogez `GET /jobs/{job_id}` (ou utilisez un [webhook](/docs/fr/developers/webhooks)) jusqu'à ce que le job soit terminé. L'image générée se trouve dans `result.urls[0]`.

## Démarrage rapide : votre première édition d'image

Toutes les requêtes nécessitent un token Bearer. Consultez [Clés API & Facturation](/docs/fr/developers/api-keys-and-billing) si vous n'en avez pas encore.

<Steps>
  <Step title="Importer une référence">
    `POST /assets` avec votre image d'entrée. La réponse renvoie `image_url`. Vous pouvez aussi passer directement une URL d'image externe ou une data URI base64 dans `image_urls`.
  </Step>

  <Step title="Créer une édition">
    `POST /generate/image/krea/krea-3` avec votre prompt et votre référence. Conservez le `job_id` renvoyé dans la réponse.
  </Step>

  <Step title="Récupérer le résultat">
    Interrogez `GET /jobs/{job_id}` jusqu'à ce que `status` vaille `completed`. Le résultat se trouve dans `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>
  Gardez votre token API sur votre serveur. Ne l'intégrez jamais dans du code côté client.
</Tip>

## Paramètres

| Champ | Type | Remarques |
| - | - | - |
| `prompt` | string | **Obligatoire.** L'instruction d'édition. Décrivez ce qui doit changer et ce qui doit rester identique. |
| `image_urls` | array of strings | Facultatif. Images de référence en entrée, jusqu'à 8. Incluez-en au moins une pour une édition ; omettez-le pour la génération texte vers image. Accepte une `image_url` issue de `POST /assets`, une URL externe ou une data URI base64. |
| `thinking_mode` | enum | Facultatif. `fast` (par défaut) ou `high`. Voir [Modes de réflexion](#thinking-modes). |
| `resolution` | enum | `1k` ou `2k`. Obligatoire, sauf si vous fournissez à la fois `width` et `height`. Ne le combinez pas avec `width` et `height`. |
| `aspect_ratio` | enum | Facultatif. L'une des valeurs `1:1`, `4:5`, `3:4`, `2:3`, `9:16`, `5:4`, `4:3`, `3:2`, `16:9`, `21:9`. À utiliser avec `resolution`. Omettez-le pour un cadrage automatique. |
| `width` / `height` | integers | Facultatif. Dimensions souhaitées, entiers positifs jusqu'à 4096 chacun. Fournissez les deux, sans `resolution` ni `aspect_ratio`. |
| `seed` | integer | Facultatif. Omettez-le pour utiliser une seed aléatoire. |
| `negative_prompt` | string | Facultatif. Ce qu'il faut éviter, jusqu'à 1 024 caractères. |
| `regional_edit` | boolean | Facultatif. Définissez-le sur `true` pour une édition locale qui conserve le reste de l'image à l'identique. Nécessite au moins une image dans `image_urls`. Voir [Éditions régionales](#regional-edits). |

<Note>
  Avec `width` et `height`, le résultat est arrondi au ratio d'aspect pris en charge le plus proche et à un canevas 1k ou 2k. Les dimensions exactes en pixels ne sont pas garanties.

  Réutiliser une `seed` ne garantit pas des résultats identiques, car l'étape d'expansion du prompt peut varier d'une exécution à l'autre.
</Note>

<h2 id="thinking-modes">
  Modes de réflexion
</h2>

Avant de générer, Krea 3 interprète votre prompt. `thinking_mode` détermine l'ampleur de cette planification.

| Mode | Ce qui se passe | Usage recommandé |
| - | - | - |
| `fast` | Krea développe rapidement le prompt, puis génère. Le plus rapide. **Par défaut et recommandé.** | Éditions claires et simples, et la plupart des demandes courantes. |
| `high` | Krea utilise un moteur de raisonnement plus puissant pour planifier des éditions plus complexes à partir du prompt et des images de référence, puis génère. Plus lent. | Éditions complexes ou en plusieurs étapes, plusieurs références à combiner, ou un résultat `fast` qui n'a pas respecté la demande. |

Si vous omettez `thinking_mode`, l'API utilise `fast`. Les deux modes prennent en charge `regional_edit`.

<h2 id="regional-edits">
  Éditions régionales
</h2>

Avec `regional_edit: true`, Krea 3 régénère uniquement les parties de l'image qui doivent changer. Tout le reste demeure exactement identique : vous pouvez donc éditer la même image encore et encore sans perte de qualité.

**Utilisez-le pour les éditions locales**, lorsque le reste de l'image doit rester identique au pixel près : recolorer ou remplacer un objet, ajouter ou supprimer un élément, corriger un détail ou modifier le texte d'un panneau. C'est la méthode sûre pour enchaîner les éditions sur le dernier résultat.

**Ne l'utilisez pas pour les éditions globales**, qui doivent recalculer toute l'image : changement de style, d'éclairage, de saison ou de moment de la journée, recadrage, ou combinaison de plusieurs images en une nouvelle scène. Les éditions classiques recalculent toute l'image, si bien que des artefacts peuvent s'accumuler si vous continuez à éditer le dernier résultat.

Les éditions régionales nécessitent au moins une image dans `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
}
```

## Rédaction des prompts

Krea 3 est un éditeur qui suit vos instructions. Rédigez l'édition en langage naturel :

* Commencez par la modification. N'ajoutez que les détails utiles à sa réalisation.
* Terminez par une phrase de préservation lorsque le reste de l'image doit rester identique. Ne listez pas tout ce qui doit rester inchangé.
* Lorsque le prompt utilise plusieurs images, désignez chaque image par ce qu'elle montre. Par exemple : « Mets la basket de la deuxième image à la personne de la première image. »

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

## Images de référence

* Krea 3 utilise chaque référence à sa résolution d'import. Une référence de plus de 4 MP est redimensionnée à 4 MP.
* Environ 1 MP suffit pour la plupart des éditions. N'agrandissez pas une référence avant de l'envoyer.
* Lorsque les détails fins comptent (petit texte, logos, tissus, visages dans un plan large), envoyez la version de l'image avec la plus haute résolution dont vous disposez.
* Avec cinq références ou plus dans une même requête, chaque référence est redimensionnée à 1536 px maximum sur son côté le plus long. Pour des références en pleine résolution, envoyez-en quatre ou moins.

## Zero Data Retention

Krea 3 prend en charge [Zero Data Retention](/docs/fr/developers/zdr) pour les espaces de travail entreprise. Envoyez l'en-tête `X-Api-Zero-Data-Retention: 1`. Avec Zero Data Retention :

* Chaque image dans `image_urls` doit être une data URI base64.
* `thinking_mode` peut valoir `fast` ou `high`.
* Une requête peut utiliser au maximum 4 images de référence.

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

## Tarifs

Le prix par image dépend de la résolution de sortie, du mode de réflexion et des images de référence.

| Composante tarifaire | Sortie 1K | Sortie 2K |
| - | - | - |
| Prix de base | \$0.03 | \$0.06 |
| Chaque image de référence 1K | +\$0.02 | +\$0.02 |
| Chaque image de référence 2K | +\$0.07 | +\$0.07 |
| Mode de réflexion `high` | +\$0.02 par génération | +\$0.02 par génération |

## Voir aussi

<CardGroup cols={2}>
  <Card title="Cycle de vie d'un job" icon="arrows-rotate" href="/docs/fr/developers/job-lifecycle">
    États des jobs, polling et résultats.
  </Card>

  <Card title="Webhooks" icon="bell" href="/docs/fr/developers/webhooks">
    Soyez notifié à la fin d'un job au lieu de faire du polling.
  </Card>
</CardGroup>


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