Générer des images produits e-commerce avec z-image via l'API hiapi

La plupart des modèles d'image savent dessiner un produit. Mais beaucoup moins savent à la fois le dessiner correctement et orthographier correctement le prix. Pour l'e-commerce — étiquettes de prix, bannières promotionnelles, cartes de réduction, étiquettes d'emballage — le texte dans l'image est l'élément décisif : un seul caractère illisible et le visuel est rejeté.

z-image est un modèle de génération d'images à partir de texte de niveau Turbo sur hiapi, conçu précisément pour ce segment : génération rapide d'images photoréalistes, texte dans l'image (anglais et chinois) précis, au prix de $0.008 par image — moins d'un tiers du prix de la plupart des alternatives. Chaque image de ce guide a été générée avec exactement le même prompt que celui affiché juste à côté, via le même appel /v1/tasks que vous copierez ci-dessous, chaque rendu prenant environ 30 à 60 secondes de bout en bout.

Pourquoi choisir z-image pour les images produits

Trois propriétés comptent pour une chaîne de production e-commerce, et z-image excelle sur les trois :

• Rendu du texte. En suivant les règles de prompt ci-dessous, les cartes promotionnelles, bannières logistiques et étiquettes de bouteilles reviennent avec chaque mot correctement orthographié.
• Vitesse. C'est un modèle ajusté Turbo ; nos rendus de test se terminaient chaque fois bien en moins d'une minute, ce qui permet de traiter des centaines d'images de SKU le temps de boire un café.
• Prix. À $0.008/image (vérifié sur la page de tarification), rafraîchir un catalogue de 1 000 images coûte $8. La même tâche avec gpt-image-2 ($0.03/image) coûterait $30.

Si vous voulez un aperçu plus complet du modèle — configuration des clés, exemples génériques, quand il ne faut pas l'utiliser — consultez Z-Image API : tarification, clés API, exemples et cas d'usage. Ce guide se concentre sur le flux de travail e-commerce.

Interface API vérifiée

z-image fonctionne sur le point de terminaison de tâches asynchrones de hiapi. Vous soumettez une tâche, interrogez jusqu'au succès, puis téléchargez le résultat. Nous avons confirmé deux faits de schéma contre l'API en ligne (tous deux diffèrent de certains autres modèles de la plateforme) :

1. input n'accepte que prompt et aspect_ratio. Envoyer un champ resolution renvoie HTTP 400 (additional properties not allowed) — contrairement à gpt-image-2, qui exige ce champ.
2. aspect_ratio doit être l'une des valeurs 1:1, 4:3, 3:4, 16:9, 9:16. Toute autre valeur (nous avons essayé 3:2) est rejetée par un 400, qui liste les valeurs valides.

La résolution de sortie est fixe selon le ratio — nos rendus sont revenus en PNG : 1536×1536 (1:1), 1344×768 (16:9), 928×1232 (3:4) et 1728×1296 (4:3).

Soumettre une tâche

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "Studio e-commerce product photo: a matte black insulated steel water bottle on a seamless light-gray background...",
      "aspect_ratio": "1:1"
    }
  }'

La réponse contient un identifiant de tâche :

{"code": 200, "data": {"taskId": "tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG"}}

Interroger et télécharger

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Interrogez toutes les quelques secondes jusqu'à ce que data.status soit success et que data.output existe ; considérez fail comme un état terminal. Un conseil pratique : juste après la génération, la tâche peut brièvement signaler un état intermédiaire (nous avons observé archiving) avant que le tableau output n'apparaisse, donc votre boucle doit se baser sur la présence de l'URL de sortie, pas seulement sur la chaîne de statut.

import os, time, requests

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

def generate(prompt: str, ratio: str = "1:1") -> bytes:
    r = requests.post(API, headers=HEADERS, json={
        "model": "z-image",
        "input": {"prompt": prompt, "aspect_ratio": ratio},
    }, timeout=60)
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        output = task.get("output") or []
        if output and output[0].get("url"):
            return requests.get(output[0]["url"], timeout=120).content
        if task.get("status") == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...your product prompt...", "1:1")
open("product.png", "wb").write(png)

Téléchargez immédiatement. output[0].url est un lien temporaire avec un horodatage expireAt — persistez les octets dans votre propre stockage (S3/R2/CDN) dès que la tâche réussit. Si une tâche semble bloquée, voici comment diagnostiquer une tâche hiapi bloquée ou expirée.

Cinq recettes e-commerce, avec les résultats réels

Toutes les images ci-dessous sont de vrais rendus z-image générés à partir des prompts exactement tels qu'ils sont affichés. Aucune retouche.

1. Image principale avec étiquette de prix

Studio e-commerce product photo: a matte black insulated steel water bottle centered
on a seamless light-gray background with soft shadow. A rectangular coral paper card
leans against the bottle. The card contains ONLY these two lines of bold clean
sans-serif text and no other words: "SUMMER SALE" on line one, "$19.99" on line two.
Text flat-on to camera, large, perfectly legible. Photorealistic.

Remarquez la formulation : le texte affiché est entre guillemets et le prompt précise que la carte contient uniquement ces mots. Lors de notre premier essai, nous avions décrit le texte en ligne (« ...reads exactly: SUMMER SALE on the first line and $19.99 on the second line ») et le modèle a fidèlement composé le mot « ON » entre les deux lignes — les mots d'instruction avaient fui dans le rendu. Citez les chaînes littérales ; placez les instructions en dehors des guillemets.

2. Bannière promotionnelle large

Wide e-commerce promo banner, photorealistic flat-lay of white sneakers and a kraft
shipping box on a pastel blue background. On the right side, bold navy sans-serif
text with exactly these four words and amount, nothing else: "FREE SHIPPING OVER $50".
All four words must appear. Text large, straight, perfectly legible. Clean commercial
studio lighting.

16:9 vous donne une bannière de 1344×768, directement utilisable dans le visuel principal de la page d'accueil de la boutique.

3. Carte de réduction verticale pour réseaux sociaux

Vertical social-media product card: a small brown glass cosmetic dropper bottle on a
warm beige podium, soft daylight. Above the bottle, bold black modern sans-serif
headline text reads exactly: 30% OFF TODAY ONLY. Text flat to camera, large and
perfectly legible. Minimalist premium e-commerce style, photorealistic.

3:4 (928×1232) est le ratio le plus proche du format des posts de fil ; recadrez en 4:5 en aval si votre plateforme l'exige.

4. Étiquette d'emballage lisible

Macro e-commerce product photo of a frosted glass skincare bottle with a clean white
label. The label text, printed in elegant dark sans-serif, reads exactly: GLOW SERUM
on the first line and VITAMIN C 10% on the second line. Straight-on angle, label
fully visible and sharp, soft studio lighting, photorealistic, white background.

C'est le test le plus difficile de la série — du petit texte sur du verre courbe — et l'étiquette est revenue très propre, y compris « 10% ».

5. Gamme de coloris (sans texte)

E-commerce catalog photo: three identical ceramic coffee mugs lined up left to right
in sage green, terracotta orange, and navy blue, on a plain white studio background
with soft even shadows. No text anywhere in the image. Photorealistic, consistent
product geometry across all three mugs.

La géométrie cohérente entre les variantes est précisément ce qui la rend utilisable comme bandeau de catalogue — z-image a maintenu la forme des trois mugs identique en une seule génération.

Règles de prompt pour que le texte survive

Synthèse de ce qui a fonctionné (et échoué) lors de nos tests réels :

1. Placez les chaînes littérales entre guillemets. text reads exactly: "SUMMER SALE" — le modèle traite les mots environnants non cités comme des candidats au texte.
2. Ajoutez « and no other words » (et aucun autre mot). Sinon le modèle peut inventer du texte de badge supplémentaire pour remplir l'espace.
3. Gardez le texte bien face à la caméra. Notre seul rendu illisible était du texte suspendu en angle sur une étiquette ; le même texte sur une carte plate est parfait. La déformation en perspective est le premier endroit où les glyphes se cassent.
4. Un à deux blocs de texte par image. Chaque bloc de texte supplémentaire multiplie la probabilité d'échec ; composez les mises en page complexes en aval.
5. Vérifiez avant publication. À ce prix, vous pouvez vous permettre une boucle de nouvelle tentative : générez, faites un OCR ou une inspection visuelle du texte, régénérez en cas de non-concordance. Même avec une nouvelle tentative par image échouée, le coût reste une fraction de celui des modèles alternatifs.

Coût par lot

Un scénario concret : 200 SKU × 3 visuels par SKU (image de fiche produit, bannière promotionnelle, carte sociale) = 600 images.

Modèle	Prix/image	600 images	Remarques
z-image	$0.008	$4.80	Vitesse Turbo, bon rendu du texte dans l'image
flux-schnell	$0.005	$3.00	Le moins cher, mais pas axé sur le rendu du texte
qwen-image-2.0	$0.025	$15.00	Bonne qualité générale
gpt-image-2	$0.03	$18.00	Nécessite le champ resolution ; guide e-commerce ici

(Prix relevés sur la page de tarification hiapi au moment de la publication.)

Le mode par lot consiste simplement à placer la fonction generate() ci-dessus dans une boucle — soumettez quelques tâches en parallèle, collectez les identifiants de tâche, puis interrogez par groupes. Si vous comptez augmenter fortement le volume, lisez d'abord comment hiapi gère les limites de débit et les pics de trafic.

Pour commencer

Récupérez une clé API depuis votre console, puis pointez l'extrait de code ci-dessus vers votre propre catalogue produits — la page du modèle z-image contient la fiche du modèle, et la documentation hiapi couvre en détail l'API de tâches. À $0.008 par rendu, le moyen le moins cher de savoir s'il convient à votre chaîne de production est de le tester cet après-midi sur vos dix SKU les plus difficiles.