Comment utiliser l'API FLUX.1 Kontext Max ? Générez votre première image en 5 minutes

TL;DR

• Qu'est-ce que c'est : FLUX.1 Kontext Max, développé par Black Forest Labs, où la génération à partir de texte et l'édition d'une seule image partagent un même ID de modèle. Déjà disponible sur HiAPI, ouvrez la page du modèle et saisissez un prompt pour générer ; les nouveaux utilisateurs reçoivent 200 crédits à l'inscription, soit environ 1,4 image.
• Combien ça coûte : $0.0715 par image (143 crédits), même prix pour la génération et l'édition ; $10 permettent environ 139 images ; les tâches échouées sont remboursées de la préautorisation.
• Comment appeler l'API : POST https://api.hiapi.ai/v1/tasks, avec model défini sur flux-1-kontext-max ; récupérez le taskId, puis interrogez en boucle ou attendez le callback, et téléchargez le résultat depuis data.output[0].url.

Depuis le lancement de FLUX.1 Kontext Max, deux questions reviennent souvent : peut-on modifier une image en ne touchant qu'à un seul endroit, et combien de temps faut-il pour l'intégrer à son propre produit. Commençons par les capacités, puis voyons deux parcours de prise en main.

Qu'est-ce que FLUX.1 Kontext Max, et qu'apporte-t-il de nouveau ?

• Un seul ID de modèle gère deux types de tâches. Si vous ne passez pas d'image dans input, c'est de la génération à partir de texte ; si vous passez input_image, c'est de l'édition — sans avoir à maintenir deux jeux de code.
• L'édition suit la logique « quoi changer, quoi garder ». Matières et styles, ajout ou suppression d'éléments, couleurs et lumière, texte dans l'image : tout est modifiable ; les parties non mentionnées dans le prompt sont conservées autant que possible.
• Six formats d'image, et l'édition peut conserver le ratio de l'original. aspect_ratio accepte 21:9, 16:9, 4:3, 1:1, 3:4 et 9:16 ; en édition, laissez vide pour conserver le ratio de l'image source, les pixels étant ajustés à un multiple de 32 — 1280×720 devient 1328×752.
• Sortie en jpeg ou png, environ 1 million de pixels par image. La limite de prompt est de 4 000 caractères ; les prompts en chinois sont automatiquement traduits en anglais avant la génération.

Génération à partir de texte, 16:9. Le prompt complet est celui du curl ci-dessous, à copier tel quel.

Générer avec ce prompt →

Deux parcours de prise en main : essai en ligne ou API ?

Pour voir le rendu, passez par l'essai en ligne ; pour intégrer à un produit, passez par l'API. Les deux utilisent le même modèle et les mêmes tarifs.

Essai en ligne (environ 1 minute)

1. Ouvrez la page du modèle FLUX.1 Kontext Max, ou cliquez sur le lien sous l'image ci-dessus : le prompt sera prérempli.
2. Inscrivez-vous ou connectez-vous ; un nouveau compte dispose de 200 crédits.
3. Choisissez 16:9, puis cliquez sur Générer.
4. Téléchargez si le résultat vous convient ; pour modifier une image, importez l'original sur la même page et saisissez un prompt d'édition.

Intégration API (environ 5 minutes)

1. Créez une clé API (sk-...) dans la console HiAPI.
2. POST /v1/tasks pour créer une tâche ; la réponse contient data.taskId.
3. Interrogez avec GET /v1/tasks/{taskId} ou attendez la notification callback.url ; une fois data.status passé à success, téléchargez l'image depuis data.output[0].url.

$0.0715 par image, soit environ 139 images pour $10 — de quoi peaufiner vos prompts jusqu'à satisfaction. La liste complète des paramètres se trouve dans la documentation en chinois.

Première image : version curl

Créer une tâche :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-kontext-max",
    "input": {
      "prompt": "A quiet reading corner by a tall window at golden hour: a linen armchair, a stack of art books and a ceramic cup on a walnut side table, warm afternoon light, soft shadows, editorial interior photography.",
      "aspect_ratio": "16:9",
      "output_format": "jpeg",
      "prompt_upsampling": false
    }
  }'

L'ID de tâche renvoyé se trouve dans data.taskId :

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Interroger le résultat :

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Seul prompt est obligatoire. output_format vaut jpeg par défaut, prompt_upsampling est désactivé par défaut et safety_tolerance vaut 2 par défaut (0 étant le plus strict).

Première image : version Python

Création, interrogation et téléchargement en un seul script : remplacez la clé et c'est prêt à tourner.

import requests, time

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "flux-1-kontext-max",
    "input": {
        "prompt": "A quiet reading corner by a tall window at golden hour: a linen armchair, a stack of art books and a ceramic cup on a walnut side table, warm afternoon light, soft shadows, editorial interior photography.",
        "aspect_ratio": "16:9",
    },
}

task_id = requests.post(API, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

if data["status"] == "success":
    image_url = data["output"][0]["url"]
    with open("flux-1-kontext-max.jpg", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(data.get("error"))

Mode édition : ajoutez simplement input_image

Ajoutez input_image dans input, et la même requête passe de la génération à l'édition. Ci-dessous, on prend le coin lecture ci-dessus comme image source, on remplace le fauteuil et on ajoute un lampadaire :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-kontext-max",
    "input": {
      "prompt": "Change the linen armchair to a deep forest-green velvet armchair, add a slim brass floor lamp beside it, and keep the window, books, cup, table and afternoon light unchanged.",
      "input_image": "https://static.hiapi.ai/admin-assets/flux-1-kontext-max/2026/10/26/1793005013365-132a4d4eb55e0852-f-t2i-golden.jpg"
    }
  }'

input_image accepte une URL d'image accessible publiquement. En édition, si vous n'indiquez pas aspect_ratio, la sortie conserve le ratio de l'image source ; pour fusionner plusieurs images, choisissez l'édition d'image GPT Image 2, qui accepte de 1 à 16 images de référence.

Comment rédiger un prompt d'édition : d'abord ce qu'on change, puis ce qu'on garde

1. Formulez la modification comme une instruction claire. Soyez précis sur l'objet et son nouvel état : remplacer linen armchair par deep forest-green velvet armchair.
2. Nommez chaque élément à conserver. Fenêtre, livres, tasse, table, lumière de l'après-midi : citez tout ce qui compte dans l'image d'origine et terminez par keep ... unchanged.
3. Les modifications liées peuvent tenir en une phrase. Changer le fauteuil tout en ajoutant un lampadaire en laiton : le modèle traite les deux ensemble ; les modifications sans rapport doivent être soumises séparément pour faciliter la vérification du résultat.
4. Pour modifier le texte de l'image, précisez aussi la mise en page. Par exemple, remplacer KYOTO par OSAKA sur une affiche en indiquant que la mise en page, les blancs et le style typographique restent identiques.
5. Le chinois est accepté directement. Le système le traduit d'abord en anglais avant de générer ; gardez le prompt sous 4 000 caractères.

4 points à vérifier avant la mise en production

1. Utilisez un callback côté serveur. Ajoutez "callback": {"url": "https://yourapp.com/webhook", "when": "final"} dans le corps de la requête : la tâche notifie automatiquement à l'état final, ce qui évite l'interrogation en boucle.
2. En cas de timeout, ne renvoyez pas le POST. Chaque création génère une nouvelle tâche facturée séparément ; enregistrez d'abord le taskId et dédupliquez dans votre propre système avant de réessayer.
3. Les liens des résultats expirent. data.output[0].url est un lien temporaire : téléchargez dès réception et copiez le fichier dans votre propre stockage.
4. Les pixels sont alignés sur un multiple de 32. En édition, laissez aspect_ratio vide pour conserver le ratio de l'image source avec un ajustement des pixels au multiple de 32 : 1280×720 donne 1328×752 ; si vous spécifiez un ratio, l'image est recadrée ou complétée selon ce ratio.

Questions fréquentes

Faut-il changer de modèle entre génération et édition ? Non. C'est toujours le même flux-1-kontext-max ; la présence ou non de input_image détermine le mode, et le prix est identique.

Combien d'images de référence peut-on transmettre à la fois ? Une seule. Pour fusionner plusieurs images, choisissez l'édition d'image GPT Image 2, qui accepte de 1 à 16 images de référence.

Peut-on utiliser des prompts en chinois ? Oui. La limite est de 4 000 caractères ; le chinois est automatiquement traduit en anglais avant la génération.

Le format change-t-il après édition ? Sans aspect_ratio, le ratio de l'image source est conservé avec un ajustement des pixels au multiple de 32 ; avec un ratio spécifié, l'image est recadrée ou complétée selon ce ratio.

Une tâche échouée est-elle facturée ? La facturation se fait selon le nombre d'images générées avec succès, une par requête ; les tâches échouées sont remboursées de la préautorisation.

Copiez le prompt du coin lecture ci-dessus dans la page du modèle FLUX.1 Kontext Max, choisissez 16:9, cliquez une fois sur Générer : observez d'abord comment il traite la lumière et les matières, puis décidez si vous l'intégrez à votre projet.