Images produits e-commerce avec Imagen 4 : prompts, code de traitement par lots et contrôle qualité

En bref

• Imagen 4 standard s'exécute sur HiAPI sous l'identifiant imagen-4.0, au prix de 0,06 $ par image, avec une image générée par requête et uniquement en texte-vers-image. Ouvrez la page du modèle Imagen 4 pour essayer un prompt.
• Pour un catalogue produits, il convient bien à la génération d'images produits sur fond blanc et d'images de mise en situation, qui nécessiteraient sinon une prise de vue distincte pour chaque coloris. Il ne peut pas reproduire votre SKU réel, car il n'accepte aucune image de référence en entrée.
• aspect_ratio est obligatoire (aucune valeur par défaut), et seed doit être une chaîne numérique. Lors de nos tests, "seed": "sku-dripper-01" a passé la validation, mais environ une seconde plus tard, chaque tâche a échoué avec TASK_FAILED.
• Prévoyez une étape de contrôle qualité. Sur un lot de 4 images, nous avons obtenu une carafe en verre non demandée, un émail brillant là où un rendu mat était demandé, et de faux textes d'étiquettes sur les accessoires, malgré negative_prompt: "text, logo".

Contenu de ce guide

Il s'agit d'un workflow pratique destiné aux boutiques en ligne, pour générer un ensemble d'images pour une gamme de produits : une image catalogue sur fond blanc par SKU, une image de mise en situation pour la page produit et un recadrage vertical pour les stories mobiles. Tout ce qui suit a été exécuté le 2026-11-04 contre l'API en production, avec un produit fictif : un dripper à café en céramique vert sauge et sa tasse assortie.

Si vous souhaitez simplement faire aboutir votre première requête, commencez par Comment utiliser l'API Imagen 4. Pour les modèles de prompts génériques, consultez Prompts Imagen 4. Ce guide traite de la génération par lots d'un ensemble d'images boutique et de leur vérification avant mise en ligne.

Choisir le palier avant d'écrire les prompts

Les trois paliers d'Imagen 4 sur HiAPI sont tous en texte-vers-image et partagent la même structure de requête : il suffit de changer l'identifiant model pour passer d'un palier à l'autre. Les prix proviennent de la tarification HiAPI au jour du test.

Palier	Identifiant du modèle	Prix par image	Page du modèle
Fast	imagen-4.0-fast	0,03 $	Imagen 4 Fast
Standard	imagen-4.0	0,06 $	Imagen 4
Ultra	imagen-4.0-ultra	0,09 $	Imagen 4 Ultra

Pour un catalogue produits, le calcul est simple. 200 SKU × (1 image produit + 1 image de mise en situation) = 400 images, soit 24 $ en palier Standard, 12 $ en Fast et 36 $ en Ultra, sans compter les éventuelles nouvelles tentatives. Seul le palier Standard a été testé dans cet article ; nous ne formulons donc aucune affirmation sur la qualité de Fast ou d'Ultra. Pour le détail complet des tarifs, consultez Tarification de l'API Imagen 4.

La requête : quatre champs, dont deux sources d'erreurs

Le schéma d'entrée d'imagen-4.0 est fermé. Voici les cas limites rencontrés lors de la construction de notre traitement par lots, avec les messages d'erreur exacts :

Champ	Règle	Résultat observé
prompt	chaîne obligatoire	—
aspect_ratio	obligatoire, l'une des valeurs 1:1, 16:9, 9:16, 3:4, 4:3, auto	Omis : aspect_ratio: missing required field "aspect_ratio". "2:1" : value must be one of '1:1', '16:9', '9:16', '3:4', '4:3', 'auto'
negative_prompt	chaîne facultative	Accepté. Réduit le texte sur les accessoires, sans l'éliminer (voir le contrôle qualité)
seed	chaîne facultative	Nombre (12) : seed: got number, want string. Chaîne non numérique ("sku-dripper-01") : acceptée avec un HTTP 200, puis la tâche se termine par TASK_FAILED. Chaîne numérique ("1042") : fonctionne normalement
Tout autre contenu	Rejeté	additional properties 'foo' not allowed

Le problème du seed nous a coûté un tour supplémentaire. Utiliser le code SKU comme seed pour assurer la traçabilité en cas de nouvelle exécution est tentant, et le validateur l'acceptait. Les quatre tâches de notre premier lot ont toutes renvoyé ceci :

{"code":200,"data":{"error":{"code":"TASK_FAILED","message":"task failed"},"model":"imagen-4.0","status":"fail"}}

Nous avons ensuite retiré les champs un par un. Le même prompt avec uniquement negative_prompt réussit, avec uniquement "seed": "sku-dripper-01" il échoue, et avec "seed": "1042" il réussit. Gardez donc le seed numérique et conservez la correspondance des SKU dans votre propre table de tâches.

Les dimensions de sortie dépendent du ratio. Lors de nos tests, 1:1 renvoie du 1024×1024, 4:3 du 1152×864 et 9:16 du 720×1280, toujours en WebP. Si votre vitrine a besoin d'images agrandies à 2000 px, prévoyez une étape d'agrandissement. La sortie elle-même n'atteint pas cette taille.

Prompts pour l'ensemble d'images catalogue

Rédigez vos modèles de prompts par type de prise de vue plutôt que par produit, puis insérez la description du produit. Gardez l'éclairage, l'angle de caméra et le fond identiques d'un SKU à l'autre pour que la grille de vignettes ressemble à un même catalogue.

Image produit (1:1). Précisez le fond, la composition, une seule direction de lumière et l'ombre souhaitée :

Studio packshot of a matte sage-green ceramic coffee mug with a thin loop handle
on a seamless pure white background, centered, handle pointing right, eye-level view,
soft diffused key light from the left, gentle contact shadow, e-commerce catalog photography

Le rendu de la tasse est propre : l'anse pointe bien vers la droite comme demandé, l'ombre est douce et le fond uniforme. Aucune retouche n'a été nécessaire.

Image de mise en situation (4:3). Indiquez le sujet principal, la surface, la direction de la lumière et quels accessoires doivent être hors de la zone de netteté. Puis rappelez que le produit est le sujet net :

Lifestyle product photo: a matte sage-green ceramic pour-over dripper sitting on a glass carafe
on a light oak kitchen counter, morning window light from the right, a bag of coffee beans and a
gooseneck kettle softly out of focus in the background, warm natural tones, shallow depth of field,
the dripper is the sharp hero of the frame

Ce prompt a produit l'image en haut de cet article.

Image verticale pour story (9:16). Si un titre doit figurer en haut, demandez explicitement de l'espace négatif :

Vertical lifestyle product photo for a mobile story: overhead flat lay of a matte sage-green ceramic
pour-over dripper on a linen napkin, scattered roasted coffee beans, a small ceramic cup of black coffee,
on a pale stone surface, soft even daylight, generous empty space in the top third for a headline

Le tiers supérieur est bien vide, comme demandé. Mais remarquez les grains de café entiers posés à l'intérieur du dripper : personne ne prépare son café ainsi, et les acheteurs de café le remarqueront. Plus de détails ci-dessous.

Code de traitement par lots asynchrone

La génération d'images HiAPI est asynchrone : POST /v1/tasks renvoie un taskId, puis vous interrogez GET /v1/tasks/{taskId} jusqu'à ce que status passe à success ou fail (voir la documentation de l'API asynchrone). Pour un catalogue produits, soumettez toutes les tâches en une fois et interrogez-les en parallèle. Voici le script que nous avons exécuté, avec des prompts raccourcis. Les deux images de mise en situation proviennent directement de ce script. Les deux images produit ont été générées une par une avec les mêmes prompts, lors du diagnostic de l'échec lié au seed décrit plus haut (image produit du dripper sans seed).

import os, time, json, concurrent.futures as cf
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
           "Content-Type": "application/json"}

NEG = "text, logo, watermark, hands, people, clutter, reflections of camera"

JOBS = [
    {"sku": "dripper-white", "aspect_ratio": "1:1", "seed": "1041", "prompt": "Studio packshot of ..."},
    {"sku": "mug-white",     "aspect_ratio": "1:1", "seed": "1042", "prompt": "Studio packshot of ..."},
    {"sku": "dripper-scene", "aspect_ratio": "4:3", "seed": "2041", "prompt": "Lifestyle product photo: ..."},
    {"sku": "dripper-story", "aspect_ratio": "9:16", "seed": "3041", "prompt": "Vertical lifestyle product photo ..."},
]

def submit(job):
    body = {"model": "imagen-4.0",
            "input": {"prompt": job["prompt"], "aspect_ratio": job["aspect_ratio"],
                      "negative_prompt": NEG, "seed": job["seed"]}}  # seed: digits only
    r = requests.post(API, headers=HEADERS, json=body, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait(task_id, timeout_s=300):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        data = r.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(4)
    raise TimeoutError(task_id)

def run(job):
    t0 = time.time()
    task_id = submit(job)
    data = wait(task_id)
    if data["status"] != "success":
        return {"sku": job["sku"], "status": "fail", "error": data.get("error")}
    url = data["output"][0]["url"]
    img = requests.get(url, timeout=60).content
    path = f"{job['sku']}.webp"
    open(path, "wb").write(img)          # download now: output URLs expire
    return {"sku": job["sku"], "status": "success", "task_id": task_id,
            "seconds": round(time.time() - t0, 1), "bytes": len(img), "file": path}

with cf.ThreadPoolExecutor(max_workers=4) as pool:
    for result in pool.map(run, JOBS):
        print(json.dumps(result))

Trois détails importants en production :

1. Les tâches en échec renvoient quand même un HTTP 200. Vérifiez data.status == "fail" et data.error.code. Ne vous fiez pas uniquement à raise_for_status().
2. Téléchargez immédiatement. output[0].url est un lien temporaire accompagné d'un horodatage expireAt (environ 7 jours dans nos réponses). Copiez les octets dans votre propre stockage ou CDN. Ne faites pas de hotlinking de cette URL depuis votre boutique.
3. Enregistrez l'identifiant de tâche à côté du SKU. Lorsqu'un relecteur rejette une image, vous devez pouvoir retrouver le prompt, le seed et l'identifiant de tâche qui l'ont générée.

Lors de nos tests, une tâche individuelle s'est terminée en 7 à 8 secondes côté serveur (created → completed). Les deux tâches de mise en situation parallèles ont pris 31 et 42 secondes en temps réel, intervalle d'interrogation de 4 secondes et téléchargement compris. Avec max_workers=4, c'est la charge d'interrogation, plus que le temps de génération, qui domine sur les petits lots.

Contrôle qualité : ce qu'il faut vérifier avant de mettre les images en ligne

La génération texte-vers-image produit des articles plausibles, pas la photo de l'article qui se trouve dans votre entrepôt. Chaque image doit être vérifiée, manuellement ou automatiquement, par rapport au SKU réel. Voici les problèmes que nous avons relevés sur un lot de 4 images :

Point de contrôle	Situation dans notre lot	Correction
Uniquement le produit listé dans l'image	L'image produit du dripper incluait en plus une carafe en verre vert assortie avec anse, jamais demandée dans le prompt (voir l'image ci-dessus).	Ajoutez « single object, nothing else in frame » et relancez. Ne publiez jamais un ensemble que vous ne vendez pas.
Rendu de surface et matière	Nous avions demandé un émail « mat ». Les deux images du dripper présentent un rendu brillant. La tasse se rapproche davantage d'un satiné.	Considérez les termes de matière comme des suggestions. Comparez au produit réel et rejetez en cas de non-concordance.
Texte sur les accessoires	Le sachet de café de la mise en situation portait un marquage rappelant un logo et un texte d'étiquette illisible, malgré negative_prompt: "text, logo".	Évitez les accessoires étiquetés dans le prompt, ou floutez-les ou recadrez-les. Ne laissez jamais de faux texte entrer dans une fiche produit.
Logique produit	La vue de dessus montre des grains de café entiers à l'intérieur du dripper.	Faites relire les images de mise en situation par une personne qui connaît la catégorie de produit.
Cohérence entre les images	Le motif de nervures et la forme de la base du dripper diffèrent entre l'image produit, la mise en situation et la vue de dessus.	À moins qu'elles ne correspondent à l'objet réel, ne mélangez pas sur une même fiche produit des images générées du « même » SKU.
Dimensions et ratios	Toutes les sorties respectent le ratio demandé (1024², 1152×864, 720×1280).	Vérifiez automatiquement la taille en pixels après téléchargement.

Ce dernier point est une décision clé pour une boutique. Réservez Imagen 4 aux bannières de catégorie, aux visuels d'ambiance lifestyle, aux créations publicitaires et aux images de remplacement pour les produits qui n'existent que sous forme de fiche technique. Pour les photos de fiche produit qui doivent montrer exactement votre article, partez de photos réelles du produit et passez à un modèle image-vers-image. Notre guide e-commerce image-vers-image avec Seedream 4.5 détaille ce workflow.

Questions fréquentes

imagen-4.0 peut-il placer mon vrai produit dans une nouvelle scène ? Non. Sur HiAPI, il n'accepte que prompt, aspect_ratio, negative_prompt et seed. Il n'y a pas de champ d'entrée image, donc votre photo produit ne peut pas servir de référence.

negative_prompt supprime-t-il tout le texte ? Dans nos tests, non. Cela vaut la peine de l'envoyer, mais de faux textes d'étiquettes apparaissent encore sur les accessoires de fond des mises en situation. La solution fiable consiste à éviter les accessoires étiquetés.

Pourquoi ma tâche échoue-t-elle immédiatement avec TASK_FAILED ? Vérifiez d'abord votre seed. Une chaîne non numérique comme "sku-dripper-01" passe la validation, mais dans nos tests chaque tâche échouait. Utilisez un nombre sous forme de chaîne, par exemple "1042".

Google-Imagen4 est-il un autre modèle ? Dans nos tests, les requêtes envoyées avec "model": "Google-Imagen4" ont réussi, tandis que la charge utile de la tâche indiquait "model": "imagen-4.0". Utilisez imagen-4.0 dans votre nouveau code.

Pour aller plus loin

Choisissez un produit, rédigez les trois modèles de prompts ci-dessus pour celui-ci et exécutez le script de traitement par lots sur le modèle Imagen 4. Si vous souhaitez l'intégrer à votre pipeline de catalogue, la documentation de l'API asynchrone couvre l'authentification et l'interrogation.