Comment utiliser l'API de génération d'images FLUX.2 ? Paramètres, code et une vraie image générée

TL;DR

• Le nom du modèle FLUX.2 Pro text-to-image sur HiAPI est flux-2/text-to-image, édité par Black Forest Labs ; son point fort est le respect du prompt et le texte dans l'image. Ouvrez la page du modèle pour l'essayer en ligne.
• Facturation par palier de résolution : 0,5 MP $0,0375, 1 MP (par défaut) $0,05, 2 MP $0,075, 4 MP $0,125. Le ratio n'affecte pas le prix.
• La méthode la plus rapide : POST /v1/tasks avec prompt, puis interroger jusqu'à success et télécharger output[0].url. La valeur de resolution contient un espace, il faut écrire "1 MP".

D'abord, une vraie image générée

L'image ci-dessous a été générée avec la requête de cet article, en 2 MP, 16:9 :

A wide overhead flat-lay of a modern developer desk: a matte black mechanical
keyboard on the left, a ceramic mug of steaming coffee on the right, a small
potted succulent in the top corner, and an open spiral notebook in the center
with the handwritten words 'API ready' clearly visible on the page, soft
natural window light falling from the left, a muted teal and warm wood color
palette, no other text or logos anywhere in the frame

Générer avec ce prompt → (16:9, 2 MP)

flux-2/text-to-image, 16:9, 2 MP, $0,075. Le « API ready » sur le carnet est correctement écrit, et l'image ne contient aucun texte superflu.

Référence rapide des paramètres

Champ	Obligatoire	Valeurs	Description
prompt	Oui	Chaîne	Placez les éléments importants en début de phrase ; 30 à 80 mots anglais donnent les meilleurs résultats
aspect_ratio	Non	1:1 16:9 3:2 2:3 4:5 5:4 9:16 3:4 4:3 custom, par défaut 1:1	Avec custom, utilisez en complément width / height
resolution	Non	0.5 MP / 1 MP / 2 MP / 4 MP, par défaut 1 MP	Détermine le prix ; ignoré en mode custom
width / height	Uniquement avec custom	256–2048	Arrondi automatique au multiple de 16
output_format	Non	webp (par défaut) / jpg / png
output_quality	Non	0–100, par défaut 80	Effectif uniquement pour webp et jpg
seed	Non	Entier	Une fois fixé, permet de reproduire le même résultat
safety_tolerance	Non	1–5, par défaut 2	1 est le plus strict

Les paramètres sont validés de manière stricte : un champ supplémentaire absent de la documentation renvoie directement une erreur HTTP 400 (additional properties ... not allowed). Ce point d'entrée n'accepte que du texte ; pour modifier une image avec une image de référence, utilisez flux-2/image-to-image.

curl : réussir sa première image

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/text-to-image",
    "input": {
      "prompt": "A matte charcoal coffee bag on a rustic oak counter, kraft paper label reading DAYBREAK ROAST, warm morning window light",
      "aspect_ratio": "4:3",
      "resolution": "1 MP",
      "output_format": "png"
    }
  }'

La réponse ne contient que data.taskId, l'image n'est pas encore générée. Interrogez GET /v1/tasks/{taskId} ; une fois que status passe à success, téléchargez depuis output[0].url.

Python : soumettre, interroger, télécharger

# pip install requests; export HIAPI_KEY=你的 Key
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):
    # 重试同一次提交时复用同一个 Idempotency-Key，只会扣一次费
    r = requests.post(API, json={"model": "flux-2/text-to-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 wide overhead flat-lay of a modern developer desk, an open notebook with the handwritten words 'API ready', soft window light",
    aspect_ratio="16:9", resolution="2 MP", output_format="png", seed=42,
)
with open("desk.png", "wb") as f:
    f.write(requests.get(url).content)

Combien ça coûte

Résolution	Par image	100 images
0.5 MP	$0,0375	$3,75
1 MP (par défaut)	$0,05	$5,00
2 MP	$0,075	$7,50
4 MP	$0,125	$12,50

Tarifs actuels de HiAPI, vérifiés le 18 octobre 2026.

Le ratio, le seed et le format de sortie n'affectent pas le prix ; seul le palier de résolution compte. Les échecs ne sont pas facturés. Pour moins cher, FLUX.2 [klein] 4B 1 MP coûte $0,00143 par image ; comparaison de tous les paliers dans Tarifs de l'API FLUX.2.

À vérifier avant la mise en production

• resolution contient un espace : écrivez "1 MP", et non "1MP" ni "1K" ; une erreur renvoie un 400 en listant les valeurs possibles.
• Les dimensions custom ignorent resolution : lorsque aspect_ratio vaut custom, l'image est générée selon width × height.
• Pour reproduire, fixez le seed : même prompt, même seed, résultat très proche, pratique pour comparer des formulations.
• Enregistrez le résultat immédiatement : output[0].url a une durée de validité ; téléchargez puis stockez dans votre propre stockage.
• 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"}, puis dédupliquez par taskId.

Questions fréquentes

resolution est-il obligatoire ?

Non, la valeur par défaut est 1 MP. Mais il est recommandé de le préciser à chaque fois pour éviter toute confusion avec 4 MP.

Peut-on fournir une image de référence ?

Pas avec ce point d'entrée. Pour modifier une image avec une référence ou fusionner plusieurs images, utilisez flux-2/image-to-image, jusqu'à 8 images de référence ; des prompts prêts à l'emploi sont disponibles dans Prompts de retouche FLUX.2.

Pourquoi la réponse « additional properties not allowed » ?

Vous avez envoyé un champ que ce modèle ne connaît pas, comme strength ou prompt_upsampling. N'utilisez que les champs du tableau des paramètres ci-dessus.

Comment choisir entre FLUX.3 Image et celui-ci ?

FLUX.3 Image génère et modifie des images avec un seul nom de modèle, produit jusqu'en 4K et accepte jusqu'à 10 images de référence ; FLUX.2 Pro propose seed et des dimensions personnalisées, et le 4 MP ne coûte que $0,125. Comparaison sur un même prompt dans FLUX.3 Image vs FLUX.2.

Copiez le prompt du bureau ci-dessus et générez votre première image sur la page du modèle.