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

# Génération et retouche d'images avec FLUX Kontext

> Soumettez des tâches asynchrones FLUX Kontext de génération ou de retouche d'images. L'API renvoie un identifiant de tâche ; interrogez ensuite le point de terminaison des tâches pour obtenir l'image générée.

<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 the hair color to blue",
      "image_urls": ["https://example.com/portrait.jpg"],
      "size": "1:1",
      "output_format": "png"
    }'
  ```

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

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

  payload = {
      "model": "flux-kontext-pro",
      "prompt": "Change the hair color to blue",
      "image_urls": ["https://example.com/portrait.jpg"],
      "size": "1:1",
      "output_format": "png"
  }

  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 the hair color to blue",
    image_urls: ["https://example.com/portrait.jpg"],
    size: "1:1",
    output_format: "png"
  };

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  });

  console.log(await response.json());
  ```
</RequestExample>

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

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "Authentication failed, please check your API key",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "Insufficient balance, please top up",
      "type": "payment_required"
    }
  }
  ```
</ResponseExample>

## Modèles pris en charge

| Modèle             | Description                                                                        |
| ------------------ | ---------------------------------------------------------------------------------- |
| `flux-kontext-pro` | Génération et retouche d'images sensibles au contexte pour les workflows courants. |
| `flux-kontext-max` | Génération et retouche d'images sensibles au contexte avec une qualité supérieure. |

Les deux modèles prennent en charge la génération texte-vers-image sans image de référence ainsi que la retouche avec des images de référence.

## Authentification

<ParamField header="Authorization" type="string" required>
  Tous les points de terminaison nécessitent une authentification par jeton Bearer.

  Obtenez une clé API sur la page [Gestion des clés API](https://apimart.ai/keys), puis ajoutez-la à l'en-tête de la requête :

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

## Corps de la requête

<ParamField body="model" type="string" required>
  Nom du modèle :

  * `flux-kontext-pro`
  * `flux-kontext-max`
</ParamField>

<ParamField body="prompt" type="string" required>
  Description textuelle de l'image à générer ou de la modification à appliquer aux images de référence.
</ParamField>

<ParamField body="image_urls" type="array">
  Images de référence utilisées pour la retouche. Les URL d'images accessibles publiquement et les entrées Base64 sont prises en charge.

  * Maximum : 4 images
  * Le total formé par l'image de sortie et toutes les images de référence ne doit pas dépasser 9 MP

  Si une URL de référence n'est pas accessible publiquement, la tâche peut uniquement renvoyer `temporarily unavailable dependency`. Dans ce cas, vérifiez d'abord la protection contre le hotlinking, les autorisations d'accès et l'expiration de la signature.
</ParamField>

<ParamField body="size" type="string" default="1:1">
  Rapport d'aspect de l'image de sortie. Une chaîne de dimensions telle que `1024x1536` est également acceptée, mais Kontext la convertit vers le rapport pris en charge le plus proche au lieu de produire exactement ces dimensions. Rapports pris en charge :

  * `1:1` (valeur par défaut)
  * `4:3`
  * `3:4`
  * `16:9`
  * `9:16`
  * `3:2`
  * `2:3`
  * `21:9`
  * `9:21`
</ParamField>

Kontext ne prend pas en charge `width` ni `height` ; fournir l'un de ces champs fait échouer la tâche. Utilisez `size` pour contrôler le rapport d'aspect. `resolution` est sans effet pour Kontext, dont la sortie reste d'environ 1 MP.

<ParamField body="output_format" type="string" default="png">
  Format d'encodage de l'image de sortie. Valeurs prises en charge : `png`, `jpeg` et `webp`.
</ParamField>

<ParamField body="response_format" type="string">
  Champ de forme de réponse compatible avec OpenAI. Il accepte uniquement `url` ou `b64_json` et ne modifie pas l'encodage de l'image. Si les deux champs sont fournis, `output_format` est prioritaire.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Nombre d'images générées par tâche. La seule valeur prise en charge est `1` ; soumettez plusieurs tâches en parallèle si vous avez besoin de plusieurs images.
</ParamField>

<ParamField body="seed" type="integer">
  Graine aléatoire. Réutilisez la même graine et les mêmes paramètres pour obtenir un résultat reproductible ; omettez-la pour utiliser une graine aléatoire.
</ParamField>

<ParamField body="prompt_upsampling" type="boolean" default="false">
  Indique s'il faut enrichir et reformuler le prompt avant la génération.

  Définissez explicitement ce paramètre sur `false` pour désactiver la reformulation du prompt.
</ParamField>

<ParamField body="safety_tolerance" type="integer" default="2">
  Tolérance de sécurité comprise entre `0` et `6`. Une valeur élevée est plus permissive.
</ParamField>

## Rapports d'aspect pris en charge

| Rapport d'aspect | Orientation         |
| ---------------- | ------------------- |
| `1:1`            | Carré (par défaut)  |
| `4:3`            | Paysage             |
| `3:4`            | Portrait            |
| `16:9`           | Paysage grand écran |
| `9:16`           | Portrait vertical   |
| `3:2`            | Paysage classique   |
| `2:3`            | Portrait classique  |
| `21:9`           | Paysage ultra-large |
| `9:21`           | Portrait ultra-haut |

### Dimensions de sortie réelles

| Rapport | Dimensions réelles |
| ------- | ------------------ |
| `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           |

## Exemples d'utilisation

### Génération texte-vers-image

```json theme={null}
{
  "model": "flux-kontext-pro",
  "prompt": "A cozy reading nook with warm lamplight",
  "size": "4:3"
}
```

### Retouche d'image

```json theme={null}
{
  "model": "flux-kontext-max",
  "prompt": "Replace the background with a beach while preserving the person",
  "image_urls": ["https://example.com/portrait.jpg"],
  "size": "16:9",
  "output_format": "webp"
}
```

### Plusieurs images de référence

```json theme={null}
{
  "model": "flux-kontext-pro",
  "prompt": "Place the product from the first image into the room from the second image",
  "image_urls": [
    "https://example.com/product.jpg",
    "https://example.com/room.jpg"
  ],
  "size": "4:3"
}
```

## Réponse

<ResponseField name="code" type="integer">
  Code d'état de la réponse.
</ResponseField>

<ResponseField name="data" type="array">
  Tableau contenant le résultat de la soumission.

  <Expandable title="Propriétés">
    <ResponseField name="status" type="string">
      État de la soumission. Une tâche acceptée avec succès renvoie `submitted`.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Identifiant unique de la tâche. Utilisez-le pour interroger le point de terminaison des tâches.
    </ResponseField>
  </Expandable>
</ResponseField>

## Récupérer le résultat

Interrogez `GET /v1/tasks/{task_id}` jusqu'à ce que la tâche atteigne l'état `completed` ou `failed`. Consultez l'[API d'état des tâches](/fr/api-reference/tasks/status) pour connaître le schéma complet de la réponse.

États de la tâche :

| État                    | Signification                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| `submitted` / `pending` | Tâche acceptée ou en attente ; poursuivez l'interrogation.                                      |
| `processing`            | Génération en cours ; poursuivez l'interrogation.                                               |
| `completed`             | Génération réussie ; l'image se trouve dans `result.images`.                                    |
| `failed`                | Échec de la génération ; consultez `data.error.message`. La tâche est intégralement remboursée. |

Une tâche terminée contient une image générée :

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

L'URL de l'image se trouve dans `data.result.images[0].url[0]`. Sa date d'expiration est définie par l'horodatage Unix `data.result.images[0].expires_at` ; téléchargez l'image avant cette échéance.

### Paramètres non valides et tâches en échec

Les paramètres de modèle non valides ne produisent pas de réponse 4xx synchrone. La soumission renvoie tout de même HTTP 200 avec un `task_id` ; poursuivez l'interrogation jusqu'à l'état `failed`, puis consultez la raison précise dans `data.error.message`. Les tâches en échec sont intégralement remboursées.

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

`error.code` vaut toujours `task_failed` ; la raison précise se trouve dans `error.message`.

## Remarques

1. Les tâches sont traitées de manière asynchrone. La réponse à la soumission renvoie un `task_id` permettant d'interroger leur état.
2. `n` vaut `1` par défaut et c'est la seule valeur prise en charge.
3. Les images de référence peuvent être fournies via des URL accessibles publiquement ou en Base64.
4. Jusqu'à 4 images de référence sont prises en charge, dans la limite totale de 9 MP pour les images d'entrée et de sortie.
5. Définissez explicitement `prompt_upsampling: false` pour désactiver la reformulation du prompt.
6. L'expiration de l'URL du résultat est déterminée par la valeur `expires_at` renvoyée dans la réponse de la tâche.
7. `width` et `height` font échouer la tâche ; `resolution` ne modifie pas la sortie d'environ 1 MP ; un `size` sous forme de dimensions en pixels est converti vers le rapport pris en charge le plus proche.
8. Les paramètres de modèle non valides sont renvoyés de manière asynchrone : interrogez la tâche jusqu'à `failed`, puis consultez `data.error.message`.