> ## Documentation Index
> Fetch the complete documentation index at: https://gccai.heqingsong.uk/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.

```bash cURL theme={null}
curl --request POST \
  --url https://gccai.heqingsong.uk/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://gccai.heqingsong.uk/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://gccai.heqingsong.uk/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());
```

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

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

**Authorization** `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://gccai.heqingsong.uk/keys), puis ajoutez-la à l'en-tête de la requête :

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Corps de la requête

**model** `string` *required*

Nom du modèle :

* `flux-kontext-pro`
* `flux-kontext-max`

**nsfw\_check** `boolean` (default: false)

Indique s'il faut modérer le contenu avant d'envoyer la tâche d'image.

* `true` : vérifier les prompts et les images d'entrée avec `omni-moderation-latest`
* `false` ou omis : ne pas envoyer de requête de modération, sans coût ni latence de modération supplémentaires (par défaut)

**prompt** `string` *required*

Description textuelle de l'image à générer ou de la modification à appliquer aux images de référence.

**image\_urls** `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.

**size** `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 d’aspect et mode automatique 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`
* `auto` - Reprendre le rapport d’aspect de l’image de référence

Lorsque `size` vaut `auto`, la sortie reprend le rapport d’aspect de l’image de référence si le champ `image_urls` est fourni. Sans image de référence, le rapport par défaut `1:1` est utilisé.

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.

**output\_format** `string` (default: png)

Format d'encodage de l'image de sortie. Valeurs prises en charge : `png`, `jpeg` et `webp`.

**response\_format** `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.

**n** `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.

**seed** `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.

**prompt\_upsampling** `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.

**safety\_tolerance** `integer` (default: 2)

Tolérance de sécurité comprise entre `0` et `6`. Une valeur élevée est plus permissive.

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

**code** `integer`

Code d'état de la réponse.

**data** `array`

Tableau contenant le résultat de la soumission.

**Propriétés**

**status** `string`

État de la soumission. Une tâche acceptée avec succès renvoie `submitted`.

**task\_id** `string`

Identifiant unique de la tâche. Utilisez-le pour interroger le point de terminaison des tâches.

## 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](https://gccai.heqingsong.uk/fr/api-reference/tasks/status.md) 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.gccai.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`.


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