Comment utiliser l'API Recraft V4.1 ? Générer des images avec palette de couleurs en 5 minutes

TL;DR

• La série Recraft V4.1 regroupe deux modèles text-to-image aux paramètres strictement identiques : recraft-v4.1/text-to-image produit un rendu final plus détaillé ($0.05/image), recraft-v4.1-flash/text-to-image sert aux essais rapides ($0.01/image, tarifs complets sur la page tarifs), seule diffère la valeur du champ model. Ouvrez la page du modèle pour essayer ; les nouveaux utilisateurs reçoivent 200 crédits à l'inscription.
• La spécificité est la palette de marque : on passe un jeu de couleurs RGB dans colors, et l'image s'en approche au maximum (non disponible dans le Playground, uniquement via l'API).
• Les appels passent par l'endpoint HiAPI /v1/tasks : soumettre une tâche récupère un taskId, puis on interroge le résultat et, en cas de succès, on télécharge depuis output[0].url.

Ce qu'il sait faire

• Photo, illustration, affiche : images produit réalistes, illustrations vectorielles à plat, affiches avec titre, tout à partir d'une simple description.
• Couleurs maîtrisées : colors définit la palette, background_color le fond, idéal pour respecter la charte graphique sur vos supports de marque.
• 6 formats prédéfinis : square_hd (par défaut), square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9, sans largeur/hauteur personnalisée.
• Essais avec Flash + rendu final avec V4.1 : mêmes paramètres, seul model change ; 10 essais plus 1 rendu final pour $0.15.

Voici un rendu réel produit par V4.1 :

Minimalist brand poster for a specialty coffee brand, huge bold headline "NORTH BEAN" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout

(En français : affiche de marque minimaliste pour une marque de café de spécialité, immense titre en gras sans-serif "NORTH BEAN", palette terracotta chaud et crème, illustration d'un seul grain de café, beaucoup d'espace négatif, mise en page grille suisse. Format choisi : portrait_4_3.)

recraft-v4.1/text-to-image, portrait_4_3, image d'exemple de cet article 896×1216, $0.05.

Générer avec ce prompt →

Comment choisir entre les deux modèles

	recraft-v4.1-flash/text-to-image	recraft-v4.1/text-to-image
Par image	$0.01	$0.05
Positionnement	Essais rapides, choix de direction	Rendu final plus détaillé
Paramètres	Strictement identiques (prompt / image_size / colors / background_color)	Idem
Idéal pour	Exploration en lot, visuels réseaux sociaux, cycles de brouillons	Livrables, supports de marque

Les deux modèles partagent le même pipeline : Flash produit 10 directions pour $0.10, on change le model de celle retenue et on la relance en rendu final V4.1 pour $0.05, soit $0.15 le tout. À l'inverse, pour uniquement des ébauches, tout en Flash revient à $10.00 pour 1 000 images. Pour choisir vos prompts selon le cas d'usage, voir le guide des prompts.

Deux parcours pour démarrer

Navigateur en 3 étapes : ouvrez la page du modèle → collez le prompt, choisissez le format → cliquez sur générer, $0.05 par image V4.1. (colors et background_color nécessitent l'API.) Pour une première fois, mieux vaut lancer une image dans le navigateur, vérifier que le style correspond, puis écrire le code.

API en 3 étapes : POST /v1/tasks pour soumettre → récupérez le taskId → GET /v1/tasks/<taskId> jusqu'au statut success, puis téléchargez.

curl : la première image (avec palette de marque)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "recraft-v4.1-flash/text-to-image",
  "input": {
    "prompt": "Flat vector illustration of a cozy reading nook with an armchair, a tall plant and a round window showing a city skyline at dusk, clean geometric shapes, gentle grain",
    "image_size": "landscape_4_3",
    "colors": [
      {"r": 28, "g": 61, "b": 90},
      {"r": 240, "g": 128, "b": 60},
      {"r": 245, "g": 222, "b": 179}
    ],
    "background_color": {"r": 250, "g": 246, "b": 238}
  }
}'

Cet exemple reprend les paramètres réels de la démo Flash : une palette de trois tons bleu profond, orange et blé, sur fond blanc cassé. Pour le rendu final, remplacez model par recraft-v4.1/text-to-image, le reste ne change pas.

Python : soumission, polling, téléchargement

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "recraft-v4.1/text-to-image",
    "input": {
        "prompt": "Minimalist brand poster for a specialty coffee brand, huge bold headline \"NORTH BEAN\" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout",
        "image_size": "portrait_4_3",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

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

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # adresse temporaire, téléchargez et sauvegardez rapidement
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:
        f.write(img.content)
    print("saved")

Tableau des paramètres (identiques pour les deux modèles)

Champ	Requis	Valeurs	Description
prompt	Oui	1 à 10000 caractères	Description de l'image
image_size	Non	square_hd (par défaut) / square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9	6 formats prédéfinis, pas de largeur/hauteur personnalisée
colors	Non	Tableau d'objets RGB, chaque canal de 0 à 255	Guidage fort de la palette : l'image s'en approche au maximum ; non disponible dans le Playground
background_color	Non	Un seul objet RGB	Couleur de fond ; non disponible dans le Playground

Chaque objet RGB doit contenir les trois clés r/g/b, chacune entre 0 et 255, sans clé supplémentaire. Tout champ hors tableau dans le corps de la requête renvoie immédiatement une erreur 400.

Les erreurs que vous rencontrerez (messages d'origine)

Ce que vous avez fait	Réponse
prompt absent	400 invalid input: prompt: missing required field "prompt"
image_size passé comme objet largeur/hauteur	400 invalid input: image_size: got object, want string
un canal de colors à 256	400 invalid input: colors.0.r: maximum: got 256, want 255
colors sans la clé b	400 invalid input: colors.0.b: missing required field "b"
colors passé comme chaîne	400 invalid input: colors: got string, want array
objet RGB avec une clé en trop	400 invalid input: colors.0: additional properties 'a' not allowed
Solde insuffisant	402 insufficient account balance; top up and retry
Une resoumission avec le même Idempotency-Key renvoie 409 ou 422, réessayez avec une nouvelle clé.

À vérifier avant la mise en production

• Callback : passez "callback": {"url": "https://..."} au niveau supérieur du corps de la requête pour être notifié automatiquement de l'état final.
• Récupérez rapidement : output[0].url est une adresse temporaire ; téléchargez-la dès réception dans votre propre stockage, ne l'utilisez pas comme lien permanent.
• La palette guide, elle ne verrouille pas : si le prompt mentionne des couleurs incompatibles avec colors, le résultat peut mélanger les deux ; pour respecter strictement la palette, ne mentionnez aucune autre couleur dans le prompt.
• Flash→V4.1 : seul model change : les autres paramètres restent identiques, la composition se réutilise telle quelle.

Questions fréquentes

Les paramètres des deux modèles sont-ils identiques ?

Strictement identiques. Seul le champ model change, sans aucune modification du code.

Où définir le paramètre colors ?

Uniquement via l'API. Le Playground ne propose pas les paramètres colors et background_color.

colors garantit-il que seules les couleurs indiquées seront utilisées ?

Non. C'est un guidage fort : l'image s'en approche au maximum, mais ce n'est pas un verrouillage strict.

Combien d'images par requête ?

Une seule. Pour en obtenir plusieurs, soumettez plusieurs tâches ou mettez-les en file.

Combien d'images pour $10 ?

Flash à $0.01/image, $10 donnent 1 000 images. Les échecs ne sont pas facturés.

Prochaine étape : prenez le prompt NORTH BEAN et générez une image sur la page du modèle ; pour appliquer les couleurs de votre marque, ajoutez colors à la requête API ; pour des modèles par cas d'usage, voir le guide des prompts.