Générer des visuels produits e-commerce avec grok-imagine/text-to-image via l'API hiapi

La plupart des pipelines de visuels produits s'effondrent dès qu'il faut tirer d'une même photo trois formats différents : le carré pour la grille du catalogue, le recadrage vertical pour la page produit (PDP) mobile, et le format large pour la bannière hero de la page d'accueil. Recadrer un seul visuel hero donne rarement un bon résultat dans tous les ratios — soit le produit est rogné, soit des zones vides gênantes apparaissent. grok-imagine/text-to-image contourne le problème : il génère nativement dans le ratio demandé, y compris deux formats larges conçus pour ce type de bannière (2:1 et 20:9), à un tarif uniforme de 0,03 $ par image sur l'API hiapi, quelle que soit la résolution.

Ce guide présente la structure réelle des requêtes, les pièges de schéma rencontrés lors de nos tests, un script de génération par lot exécutant une liste complète de prises de vue pour un même brief produit, et un décompte honnête des coûts à l'échelle d'un catalogue.

Positionnement tarifaire

Vérifié sur la page de tarifs de hiapi au moment de la rédaction :

Modèle	Prix par image	Résolution	Contrôle du ratio d'aspect
grok-imagine/text-to-image	0,03 $ uniforme	1K ou 2K, même prix	13 ratios, dont 2:1, 20:9
grok-imagine-quality/text-to-image	0,07 $ (1K) / 0,10 $ (2K)	Tarification par palier de résolution	Même jeu de ratios

La version qualité apporte un gain réel sur les détails fins — reflets, texture des tissus, petits textes — et vaut le surcoût pour les quelques véritables visuels hero. Pour l'essentiel des images d'un catalogue (vignettes de grille, variantes lifestyle, autres angles), le modèle de base est déjà suffisamment proche, et l'écart de prix de 2 à 3 fois ne se justifie pas en production de masse.

La requête qui fonctionne réellement

Toutes les images de cette page proviennent du même endpoint :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "input": {
      "prompt": "matte ceramic pour-over coffee dripper on a pale oak table, soft morning window light from the left, small negative space top-right, no text, no logo, product photography",
      "aspect_ratio": "1:1",
      "resolution": "2k"
    }
  }'

Cela renvoie un taskId ; interrogez GET /v1/tasks/{taskId} jusqu'à ce que status passe à success, puis récupérez output[0].url et téléchargez — cette URL est signée et expire, il faut donc sauvegarder les octets immédiatement plutôt que de pointer directement vers elle.

Trois détails de schéma nous ont posé problème pendant les tests, et il vaut la peine de les connaître avant de construire votre propre intégration :

• aspect_ratio est une énumération stricte de 13 valeurs, pas un champ libre.Toute autre valeur renvoie une 400 avec la liste complète : 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2. Les deux ratios utiles aux bannières sont 2:1 et 20:9 — la plupart des modèles d'image sur hiapi plafonnent à 21:9, ou n'offrent aucune option ultra-large.
• resolution n'accepte que les minuscules — utilisez "2k", pas "2K". La forme majuscule est rejetée telle quelle, sans conversion silencieuse.
• Le schéma d'entrée est strict.Un champ superflu ou mal orthographié (un negative_prompt résiduel, une clé style copiée d'un exemple d'un autre modèle) fait échouer toute la requête au lieu d'être ignoré.

Rédiger des prompts pour des images propres à l'échelle du catalogue

Le plus grand levier pour obtenir une sortie de catalogue cohérente est de préciser explicitement ce que vous ne voulez pas. Pour le visuel hero sur fond blanc ci-dessus, le prompt efficace est :

"Filtre à café pour-over en céramique mate posé sur un fond blanc pur sans raccord, éclairage studio softbox, centré, aucune dégradé d'ombre hormis une douce ombre de contact, sans texte, sans filigrane, sans accessoire, photographie produit e-commerce, mise au point nette"

Pour une variante lifestyle destinée aux images secondaires de PDP ou aux bannières e-mail, remplacez le fond et les indications de lumière, mais conservez la même discipline « sans texte / sans filigrane / sans autre accessoire que celui spécifié » — c'est précisément ce qui empêche grok-imagine d'ajouter des objets parasites ou des étiquettes illisibles sur le produit lui-même :

"Le même filtre à café pour-over en céramique posé sur un plan de travail de cuisine en bois, à côté d'une tasse fumante, lumière matinale chaude, faible profondeur de champ, arrière-plan de cuisine chaleureux et doucement flouté, sans texte, sans logo"

Workflow pour bannières ultra-larges

Quand le besoin est une bannière d'accueil ou de catégorie plutôt qu'une vignette de catalogue, 2:1 et 20:9 sont exactement les deux ratios qui rendent grok-imagine particulièrement pertinent. L'astuce consiste à décrire directement l'espace négatif au lieu d'espérer qu'un recadrage tombe juste — précisez où se trouve le produit dans le cadre et quelles zones doivent rester vides :

"Filtre à café pour-over en céramique mate placé dans le tiers droit du cadre, lumière extérieure d'heure dorée, généreux espace négatif vide sur les deux tiers gauches de l'image pour superposer le texte de titre, composition large cinématographique, sans texte, sans logo"

{
  "model": "grok-imagine/text-to-image",
  "input": {
    "prompt": "matte ceramic pour-over coffee dripper positioned in the right third of frame, golden-hour outdoor light, generous empty negative space across the left two-thirds of the image for headline text overlay, cinematic wide composition, no text, no logo",
    "aspect_ratio": "20:9",
    "resolution": "2k"
  }
}

Si votre CMS exige des dimensions en pixels exactes plutôt qu'un ratio, générez au ratio supporté le plus proche, puis recadrez sans perte à partir de cette image — consultez nos notes sur les dimensions exactes via l'API pour le calcul des marges.

Générer par lot une liste complète de prises de vue

Un brief produit unique nécessite généralement plus d'une image. Le script ci-dessous reproduit celui utilisé pour générer les quatre images de cette page — il soumet une tâche par image, attend la fin du traitement, puis enregistre sur disque :

import os
import time
import requests

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

SHOTS = [
    {
        "name": "hero",
        "prompt": "matte ceramic pour-over coffee dripper on a pure white seamless "
                  "background, studio softbox lighting, centered, e-commerce product "
                  "photography, no text, no watermark",
        "aspect_ratio": "1:1",
    },
    {
        "name": "lifestyle",
        "prompt": "same ceramic pour-over dripper on a wooden kitchen counter next to "
                  "a steaming mug, warm morning light, shallow depth of field, no text",
        "aspect_ratio": "4:3",
    },
    {
        "name": "banner",
        "prompt": "ceramic pour-over dripper in the right third of frame, soft studio "
                  "light, empty negative space across the left two-thirds for headline "
                  "text, no text, no logo",
        "aspect_ratio": "2:1",
    },
]


def create_task(shot):
    payload = {
        "model": "grok-imagine/text-to-image",
        "input": {"prompt": shot["prompt"], "aspect_ratio": shot["aspect_ratio"], "resolution": "2k"},
    }
    resp = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id, poll_interval=5, timeout_s=300):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


for shot in SHOTS:
    task_id = create_task(shot)
    url = wait_for_result(task_id)
    image_bytes = requests.get(url, timeout=120).content
    with open(f"{shot['name']}.jpg", "wb") as f:
        f.write(image_bytes)
    print(f"{shot['name']}: saved {len(image_bytes)} bytes")

Si vous lancez un lot complet multi-SKU, soumettez d'abord les trois tâches, puis sondez-les en parallèle (un petit asyncio ou un pool de threads suffit) — chaque tâche se termine généralement en moins d'une minute, et une exécution séquentielle ne fait qu'ajouter des temps d'attente inutiles.

Coût réel d'une exécution à l'échelle d'un catalogue

À 0,03 $ uniforme par image, l'ensemble de trois images ci-dessus (hero + lifestyle + bannière) revient à 0,09 $ par SKU. En montée en charge :

• 50 SKU × 3 images = 150 images → 4,50 $
• 500 SKU × 3 images = 1 500 images → 45 $
• En réservant l'upgrade grok-imagine-quality aux seules images hero 2K (0,10 $ au lieu de 0,03 $), le total pour 500 SKU passe à 80 $ — une fraction du coût d'un seul shooting produit traditionnel.

grok-imagine face au reste de la gamme

Si une image doit s'animer — par exemple un clip produit animé de 6 secondes pour une publicité sociale plutôt qu'une bannière statique — la même gamme le couvre via grok-imagine-image-to-video, qui utilise l'une de ces images statiques comme première frame ; nous détaillons ce workflow séparément dans le guide sur la vidéo courte. Pour les équipes qui comparent avec un pipeline catalogue basé sur Nano-Banana, notre guide e-commerce Nano-Banana est la référence côte à côte la plus proche — même structure d'API de tâches, atouts de modèle différents.

Questions fréquentes

grok-imagine/text-to-image accepte-t-il des images de référence (i2i), et pas seulement des prompts textuels ? Oui — mais il s'agit d'une variante de modèle distincte (grok-imagine/image-to-image), avec son propre schéma d'entrée. Ce guide couvre uniquement le parcours texte-vers-image.

Pourquoi ma requête renvoie-t-elle une 400 avec une erreur « additional properties » ? Le schéma d'entrée est strict. Vérifiez que vous n'envoyez que prompt, aspect_ratio et, éventuellement, resolution — ne transportez pas de champs supplémentaires copiés d'exemples d'autres modèles.

Puis-je obtenir un ratio exact comme 1200×630 au lieu de choisir dans l'énumération ? Générez au ratio supporté le plus proche (16:9 est proche de nombreux formats de bannière web), puis recadrez sans perte en post-traitement — consultez le guide sur les dimensions exactes lié plus haut pour la méthode de remplissage.

La résolution 2K vaut-elle l'attente par rapport à 1K ? Ce modèle facture les deux résolutions au même prix, donc utilisez 2K par défaut, sauf si vous avez un budget de latence strict — vous gagnez du détail gratuitement.

Essayez par vous-même

Tous les accès API ici passent par une clé hiapi standard — consultez la documentation pour l'authentification et la référence complète du polling des tâches, et vérifiez la page de tarifs pour les tarifs à jour de toute la gamme avant de vous engager sur une exécution à grande échelle.