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

La réussite d'un catalogue e-commerce tient entièrement à la cohérence. Un vendeur avec 40 SKU n'a pas besoin de 40 séances photo différentes — il a besoin d'un beau décor de fond et d'une méthode pour y intégrer rapidement chaque produit. C'est exactement le cas d'usage réel de l'édition d'image guidée par image de référence, et c'est précisément ce que grok-imagine/image-to-image sur l'API hiapi sait faire : donnez-lui une scène et une photo de produit, et il fusionne les deux en une image propre et fidèle à votre image de marque — sans masque manuel ni étape de détourage séparée.

Ce guide couvre le schéma de requête réel et testé de ce modèle (pas du marketing), la tarification réellement facturée, un script de traitement par lots pour appliquer un même fond à tout un catalogue, ainsi qu'une astuce pratique : contrôler le rapport d'aspect de sortie entre les différentes plateformes e-commerce qui exigent toutes des recadrages différents.

Ce que fait réellement le modèle

grok-imagine/image-to-image reçoit un prompt textuel et quelques images de référence, et les fusionne en une nouvelle image. Pour la photographie produit, cela signifie :

• Uniformisation du fond — placez chaque photo de SKU devant une même scène stylisée (une table, une étagère, un fond de studio), sans rien rephotographier.
• Composition de scène — combinez un détourage de produit avec une image de référence d'environnement, en faisant correspondre l'éclairage et la composition.
• Transfert de style entre images de référence — importez l'étalonnage des couleurs ou les accessoires d'une image dans une autre, tout en laissant le produit lui-même intact.

Tout cela s'accomplit en un seul appel de tâche, facturé par image de sortie, plus un petit frais pour chaque image de référence envoyée.

Le schéma réel (vérifié contre l'API en ligne, pas contre la page de tarification)

Nous avons sondé directement POST /v1/tasks avec grok-imagine/image-to-image, et le schéma d'entrée de ce modèle accepte exactement deux champs :

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "string, required",
    "image_urls": ["array of public image URLs, required, max 3"]
  }
}

C'est tout — pas de resolution, pas de aspect_ratio, pas de paramètre strength. Tout autre contenu dans le payload est rejeté par le schéma strict.

Une erreur à corriger mérite d'être signalée : la page de tarification hiapi affirme actuellement que ce modèle prend en charge « jusqu'à 6 » images de référence. Nous avons testé directement en envoyant respectivement 6 et 7 URL d'images dans la même requête, et les deux ont été rejetées :

{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 6, want 3"}
{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 7, want 3"}

À la date de rédaction, la limite réellement appliquée est de 3 images par appel, et non 6. Si vous construisez un pipeline autour de ce modèle, prévoyez 3 images et considérez tout texte marketing contraire comme obsolète — avant de publier une automatisation qui dépend de cette limite, confirmez-la toujours via un appel POST /v1/tasks en direct, car ces limites évoluent avec la plateforme.

Rapport d'aspect automatique : le ratio de sortie suit votre première image de référence

Le modèle n'a pas de champ d'entrée aspect_ratio, alors d'où vient la forme de la sortie ? Nous avons réalisé un test contrôlé pour le découvrir : même prompt, mêmes deux images de référence, en inversant uniquement l'ordre des image_urls.

Dans ce rendu, la photo du produit (le sac à dos) était listée en premier dans image_urls, suivie de la scène de fond. La sortie a été renvoyée en 1248×832 — une image paysage 3:2 correspondant au propre ratio de la photo du produit.

Même prompt, mêmes deux images — mais cette fois la scène de fond était listée en premier. La sortie a été renvoyée en 1024×1024, un recadrage carré correspondant au rapport d'aspect propre de l'image de référence de scène, et non à celui du produit.

La règle est la suivante : le rapport d'aspect de sortie de grok-imagine/image-to-image est hérité de l'URL placée en tête de image_urls. Il ne lit pas les indications de composition dans votre prompt (« photo produit » ou « scène large ») — c'est purement positionnel. Une fois cela su, c'est un levier réellement utile : pour viser le recadrage préféré d'une plateforme e-commerce donnée, il suffit de réorganiser le tableau d'images de référence. Pour une fiche produit carrée à la Instagram, placez une référence carrée en premier ; pour un bandeau large, placez une référence paysage en premier.

Tarification (vérifiée contre la grille tarifaire en ligne)

Modèle	Type d'appel	Prix
grok-imagine/text-to-image	Texte → image	0,03 $ / image
grok-imagine/image-to-image	Édition guidée par image de référence (ce guide)	0,03 $ / image + 0,003 $ par image de référence
grok-imagine-quality/text-to-image	Texte → image, gamme supérieure	0,07 $ / image (1K)
grok-imagine-quality/image-to-image	Édition guidée par image de référence, gamme supérieure	0,08 $ / image (1K), 0,10 $ / image (2K), + 0,015 $ par image de référence

La gamme de base grok-imagine/image-to-image utilisée dans ce guide ne varie pas selon la résolution et s'applique à tarif forfaitaire — vous ne payez pas de supplément 2K/4K comme avec la gamme -quality. Pour une mise à jour de catalogue consistant à composer des dizaines de SKU sur une même scène, 0,036 $ par image (une photo produit plus une référence de scène) est le chiffre à retenir pour votre budget. Consultez toujours à nouveau /en/pricing avant de lancer des lots importants, car les tarifs peuvent évoluer.

Si vous avez besoin de détails plus nets sur chaque image et acceptez une augmentation de prix d'environ 3 fois, la gamme grok-imagine-quality est la version haute fidélité du même flux de travail. Pour des rendus produits purement text-to-image sans aucune photo de référence, consultez le tutoriel text-to-image de la gamme de base.

Script de traitement par lots : une scène, tout un catalogue

Voici une boucle Python minimale qui prend une scène de fond réutilisable, la compose avec chaque photo produit d'un dossier, soumet chacune comme tâche distincte et interroge jusqu'à l'achèvement. Elle utilise le schéma confirmé ci-dessus et place la photo produit en premier, de sorte que chaque sortie hérite du rapport d'aspect de la photo produit elle-même — si vous voulez le ratio de la scène, inversez l'ordre.

import os
import time
import requests

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

SCENE_URL = "https://static.hiapi.ai/blog/grok-imagine-image-to-image-ecommerce/scene-base.jpg"
PROMPT = (
    "Composite the product from the first reference photo naturally into the "
    "second reference's studio scene, matching its lighting and shadow direction. "
    "Keep the product's shape, color, and texture unchanged."
)


def submit(product_url: str) -> str:
    payload = {
        "model": "grok-imagine/image-to-image",
        "input": {
            "prompt": PROMPT,
            "image_urls": [product_url, SCENE_URL],  # product first -> output follows its ratio
        },
    }
    resp = requests.post(f"{API_BASE}/tasks", headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


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


if __name__ == "__main__":
    product_urls = [
        "https://your-storage.example.com/catalog/dripper-raw.jpg",
        "https://your-storage.example.com/catalog/sneaker-raw.jpg",
        "https://your-storage.example.com/catalog/backpack-raw.jpg",
    ]
    for url in product_urls:
        task_id = submit(url)
        output_url = wait_for_result(task_id)
        print(f"{url} -> {output_url}")

Pour un pipeline de production, enregistrez un callback.url sur la tâche plutôt que d'interroger en boucle — consultez le catalogue de modèles hiapi pour la structure complète du payload de callback. Stockez le taskId avec le SKU de votre produit, afin que les tâches échouées puissent être relancées sans soumettre à nouveau tout le lot.

Exemples de vraies photos produit

Ces deux images ont été générées avec la même image de référence de scène, en changeant uniquement la photo produit entre les appels — l'éclairage, la table et les plantes du fond restent cohérents dans tout le « catalogue », ce qui est précisément tout l'intérêt du flux de travail à scène réutilisable.

Questions fréquentes

Peut-on utiliser plus de 3 images de référence par appel ? Non. Le schéma en ligne impose maxItems: 3 pour image_urls — confirmé par test direct de l'API, quel que soit ce que peut dire le marketing ailleurs. Concevez vos prompts pour au maximum 3 images de référence (généralement : produit + scène, ou produit + scène + référence de style).

Comment contrôler le rapport d'aspect de la sortie ? Le modèle n'a pas de paramètre aspect_ratio. La sortie hérite du rapport d'aspect de l'image placée en premier dans image_urls — réorganisez vos images de référence selon le ratio voulu.

Prend-il en charge la génération purement textuelle sans image de référence ? Non — image_urls est un champ obligatoire. Pour des rendus produits purement textuels, utilisez plutôt grok-imagine/text-to-image, à 0,03 $/image.

Existe-t-il une version haute fidélité de ce modèle ? Oui, grok-imagine-quality/image-to-image exécute le même flux de travail guidé par image de référence à 0,08 $/image (1K) ou 0,10 $/image (2K), plus 0,015 $ par image de référence, pour des détails plus nets.

Essayez dès maintenant

Obtenez une clé API depuis votre tableau de bord hiapi, préparez une scène de fond, lancez vos premiers lots sur quelques SKU avant de décider de renouveler tout le catalogue — à 0,036 $ par image, tester ce flux de travail sur 10 produits coûte moins d'un dollar.