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

TL;DR

• FLUX.3 Image est un modèle d'image publié par Black Forest Labs en octobre 2026, sous le nom flux-3-image. Un seul nom de modèle gère à la fois la génération texte-image et la retouche ; la retouche accepte jusqu'à 10 images de référence. Ouvrez la page du modèle pour l'essayer en ligne.
• Facturation à l'image : 1K (par défaut) $0.048, 2K $0.10, 4K $0.607, avec 20 % de réduction sur toutes les résolutions jusqu'au 31 octobre. Chaque tâche produit 1 image.
• La méthode la plus rapide : POST /v1/tasks avec prompt, puis interrogez jusqu'à success et téléchargez output[0].url. Pensez à indiquer explicitement resolution, et vérifiez à la fois les états d'échec fail et failed.

Qu'est-ce que FLUX.3 Image et qu'apporte-t-il de nouveau ?

• Génération et retouche avec un seul nom de modèle. Sans image_urls, c'est de la génération texte-image ; avec 1 à 10 images de référence, on retouche autour de ces images, en précisant dans le prompt le rôle de chaque image.
• Cinq résolutions : de 768 ($0.041) à 4K ($0.607) ; 15 formats d'image de 21:9 à 9:21, plus auto.
• Recherche web pour enrichir les détails. grounding est activé par défaut : avant la génération, une recherche de pages web et d'images peut compléter les informations visuelles.
• 9e du classement texte-image d'Artificial Analysis.

Une image d'intérieur en 1.5K, 3:2 :

Architectural interior photograph of a cedar alpine reading cabin,
floor-to-ceiling window opening onto a misty mountain lake, linen armchair and a
small brass lamp, warm wood grain, quiet morning atmosphere, restrained
Scandinavian design, no text.

Générer avec ce prompt → (1.5K, 3:2)

flux-3-image, 1.5K, 3:2, $0.07.

Deux parcours pour démarrer

Essai en ligne (sans code) :

1. Ouvrez la page du modèle FLUX.3 Image et connectez-vous (200 crédits offerts à l'inscription).
2. Collez le prompt, choisissez la résolution et le format, et téléversez des images de référence si besoin.
3. Cliquez sur générer et téléchargez le résultat.

Appel API :

1. Créez une clé API dans la console.
2. POST /v1/tasks, avec "model": "flux-3-image".
3. Interrogez GET /v1/tasks/{taskId} ou recevez un callback, puis enregistrez output[0].url.

curl : générez la première image

1K, 4:3, $0.048 :

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-image",
    "input": {
      "prompt": "A refined still life of a terracotta architectural model on ivory paper, brass desk lamp, olive leaves, soft late-afternoon sunlight, no text",
      "resolution": "1K",
      "aspect_ratio": "4:3"
    }
  }'

La réponse contient data.taskId. Interrogez GET /v1/tasks/{taskId} ; une fois status passé à success, téléchargez output[0].url.

Python : soumettre, interroger, télécharger

# pip install requests; export HIAPI_KEY=votre clé
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(timeout_s=300, **inp):
    # Réutilisez le même Idempotency-Key lors d'un nouvel essai de la même soumission : une seule facturation
    r = requests.post(API, json={"model": "flux-3-image", "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(5)
    raise TimeoutError(task_id)

url = generate(
    prompt="A cinematic rainy Tokyo side street at blue hour, a small bookstore with warm amber windows, a red bicycle outside, no readable signs",
    resolution="2K", aspect_ratio="16:9",
)
ext = url.split("?")[0].rsplit(".", 1)[-1]  # enregistrez selon le type de fichier renvoyé
with open(f"street.{ext}", "wb") as f:
    f.write(requests.get(url).content)

Retoucher avec des images de référence

Passez image_urls (1 à 10 liens publics) et précisez dans le prompt ce que fournit chaque image et ce qu'il ne faut pas en reprendre. L'exemple ci-dessous combine trois images : l'image 1 fournit le sujet, l'image 2 le décor, l'image 3 ne prête que sa palette de couleurs.

Create a refined product photograph. Use the cobalt blue ceramic teapot and
walnut handle from Image 1 as the main subject, place it on a pale stone side
table inside the cedar reading cabin from Image 2. Borrow only the subtle teal
and amber lighting palette from Image 3. Preserve the teapot shape and glaze,
keep the lake window visible in the background, realistic scale, no lettering.

url = generate(
    prompt=open("teapot_prompt.txt").read(),
    image_urls=[
        "https://your-cdn.example.com/teapot.jpg",   # image 1 : sujet
        "https://your-cdn.example.com/cabin.jpg",    # image 2 : décor
        "https://your-cdn.example.com/street.jpg",   # image 3 : palette uniquement
    ],
    resolution="1K", aspect_ratio="3:2",
)

flux-3-image, trois images de référence, 3:2, $0.048. Les images de référence ne coûtent rien de plus.

Mémo des paramètres

Champ	Valeurs	Description
prompt	chaîne, obligatoire, 5000 caractères max	Décrivez la scène, ou précisez quoi modifier et quoi conserver
image_urls	1 à 10 liens publics, facultatif	Sans ce champ, c'est de la génération texte-image
resolution	768 / 1K / 1.5K / 2K / 4K, par défaut 1K	Détermine le prix ; la largeur et la hauteur réelles varient selon le format
aspect_ratio	21:9 2:1 16:9 3:2 7:5 4:3 5:4 1:1 4:5 3:4 5:7 2:3 9:16 1:2 9:21 auto, par défaut auto	Pour un emplacement fixe, choisissez explicitement un ratio
safety_tolerance	0 à 4, par défaut 2	0 est le plus strict
grounding	booléen, par défaut true	Recherche web et images avant la génération

À vérifier avant la mise en production

• Indiquez toujours resolution. Une faute de frappe en 4K fait passer une image de $0.048 à $0.607.
• Vérifiez à la fois fail et failed. La documentation indique failed, mais vérifier les deux est plus sûr.
• Utilisez un callback plutôt que l'interrogation répétée : ajoutez au même niveau que input "callback": {"url": "https://your-app.example.com/hiapi/callback"}, et dédupliquez par taskId.
• Enregistrez le résultat immédiatement. output[0].url a une durée de validité ; téléchargez rapidement ou choisissez le stockage permanent à la création de la tâche.
• Ajoutez l'en-tête Idempotency-Key : en cas de nouvel essai, la même clé ne crée la tâche qu'une seule fois.

Questions fréquentes

Combien d'images par tâche ?

1. Pour plusieurs directions, soumettez des tâches séparées.

Peut-on choisir PNG ou JPEG ?

Ce modèle ne propose pas de choix de format. Si un format précis est nécessaire, convertissez après téléchargement.

Quand désactiver la recherche web ?

Lorsque vous avez déjà vos propres images de référence et une direction créative définie. Écrivez grounding: false, le prix ne change pas.

Une génération échouée est-elle facturée ?

Non. Seule une génération réussie est facturée.

Voir les prix par palier sur Prix de l'API FLUX.3 Image, d'autres prompts sur Exemples de prompts FLUX.3 Image, et une comparaison avec la génération précédente sur le même prompt sur FLUX.3 Image vs FLUX.2. Vous pouvez aussi générer cette cabane en cèdre directement sur la page du modèle.