Guide d'utilisation
Générer des images de produits e-commerce avec qwen-image-2.1-turbo via l'API HiAPI
Workflow de visuels catalogue rapide pour développeurs : sortie PNG transparente et requête API exécutable
Sur cette page
Cas d'usage de qwen-image-2.1-turbo
La gestion des visuels d'un catalogue produits est en apparence un problème créatif, mais c'est en réalité un problème de débit. Une image principale peut être retouchée manuellement, mais une boutique comptant des milliers de SKU a besoin d'une composition cohérente, de délais de livraison prévisibles et de sorties qui s'intègrent directement dans le pipeline d'assets existant. Le modèle d'image que vous choisissez détermine le nombre d'éléments de pipeline que vous devrez reconstruire.
Trois critères guident généralement cette décision :
- La latence sous charge. Les tâches de catalogue nocturnes sont des tâches batch ; un modèle qui performe bien en interaction peut rendre pénible le rafraîchissement de 10 000 SKU.
- L'adéquation du format de sortie. Si votre étape de composition exige un canal alpha et que le modèle ne renvoie que des images opaques, vous devez ajouter vous-même une étape de détourage.
- Le comportement sur les prompts descriptifs de produits. Les prompts produits sont courts, spécifiques et répétitifs — un modèle qui les traite de manière fiable l'emporte sur un modèle brillant sur des prompts artistiques ouverts.
Ce guide se concentre sur les deux premiers critères et sur le modèle de requête qui les relie. Nous examinerons où se situe la variante turbo dans un pipeline d'images produits, comment la sortie PNG transparente modifie votre chaîne de post-traitement, et nous fournirons une requête directement utilisable dans un worker. Nous aborderons enfin les points à surveiller lors du passage à l'échelle batch, et comparerons brièvement avec les approches image-vers-image lorsque la génération textuelle ne convient pas.

Sortie PNG transparente et votre chaîne de post-traitement
On peut voir le pipeline d'images produits comme quatre étapes : construction de la requête → génération → traitement de la sortie → publication. La variante turbo est un pari délibéré : rendre la deuxième étape suffisamment rapide et économique pour soutenir l'échelle d'un catalogue, afin que vous puissiez investir votre budget d'ingénierie dans les première et troisième étapes.
Quand c'est le bon premier choix
Choisissez qwen-image-2.1-turbo lorsque :
- Vos prompts sont structurés et répétables — un modèle par catégorie, avec des emplacements pour la matière, la couleur, l'angle et l'intention de fond.
- Vous devez générer de nombreuses variantes par SKU (angles, palettes, mises en scène) plutôt qu'une seule image soigneusement dirigée artistiquement.
- Votre composition en aval est déjà automatisée, si bien qu'un détourage propre a plus de valeur qu'une scène finie complète.
- Vous souhaitez obtenir une base textuelle avant d'introduire des images de référence.
Quand il faut un modèle plus puissant
Si un SKU exige une composition très spécifique correspondant strictement à une photo de référence, ou si le goulot d'étranglement est la qualité de sortie sur des scènes complexes plutôt que le volume, le niveau turbo n'est pas le choix par défaut approprié. Dans ce cas, conservez turbo pour la majorité des variantes de catalogue et confiez les quelques visuels principaux à un chemin de génération plus lourd — la forme du pipeline reste identique, seul l'identifiant du modèle change.
Concevoir un emplacement de modèle interchangeable
Comme le niveau turbo vise l'échelle, traitez le nom du modèle comme une configuration plutôt que comme une constante codée en dur dispersée dans la base de code. Lire une variable d'environnement IMAGE_MODEL au démarrage du worker signifie que vous pouvez tester un autre modèle en A/B sur certaines catégories sans modifier le code des requêtes. C'est cette décision qui rend le reste de ce guide portable.

Une requête HiAPI de images produits exécutable
Le PNG transparent est le choix de sortie à plus fort levier dans un pipeline de catalogue, car il déplace l'étape coûteuse — séparer le produit du fond — en amont, au niveau de la génération. Au lieu de segmenter un rendu opaque, vous recevez un asset avec canal alpha, puis vous le composez vous-même.
Ce qui change en aval
Avec un canal alpha, le fond devient une préoccupation de rendu plutôt qu'une préoccupation de modélisation. Le même détourage peut être placé sur un fond de studio blanc pour l'image principale de la PDP, dans une scène lifestyle pour un emplacement marketing, ou sur une couleur de marque unie pour une vignette de catégorie — le tout à partir d'une seule génération. C'est là l'économie centrale : un seul asset produit, plusieurs variantes publiées.
En pratique, prévoyez les étapes suivantes :
- Valider le canal alpha. Vérifiez que l'image possède bien un canal alpha non trivial et que le sujet n'est pas rogné au bord du cadre. Un détourage qui touche la bordure est un échec de génération, pas un problème de composition.
- Normaliser le canevas. Avant la composition, redimensionnez et remplissez le détourage sur un canevas cohérent, afin que la position des différents SKU soit prévisible.
- Composer séparément par emplacement de publication. Stockez les préréglages de fond sous forme de données (dimensions, couleurs, assets de fond optionnels) et générez chaque emplacement de publication à partir du même PNG source.
- Stocker le fichier source, publier les rendus. Conservez l'image transparente d'origine comme asset de référence et considérez chaque variante composée comme un dérivé régénérable.
Attention au compromis sur la taille des fichiers : le canal alpha alourdit les PNG, et le stockage du catalogue multiplie ce poids par le nombre de variantes. Si votre CDN sert du WebP ou de l'AVIF, convertissez à la publication tout en conservant le fichier PNG source.

Passage à l'échelle batch et évitement des pièges d'intégration
Tout ce qui suit s'exécute sur l'interface unifiée de HiAPI — une URL de base, un identifiant, une forme de requête cohérente entre les modèles. Avant de figer le schéma, récupérez la liste exacte des paramètres et les noms de champs actuels depuis la page du modèle qwen-image-2.1-turbo ; ce qui importe ici, c'est le schéma lui-même.
Forme de la requête
Un appel d'image produit se compose d'un prompt et de spécifications de sortie. Construisez le prompt à partir d'un modèle afin que chaque SKU ne fournisse que ses propres variables :
import os, requests
HIAPI_KEY = os.environ["HIAPI_API_KEY"]
MODEL = os.environ.get("IMAGE_MODEL", "qwen-image-2.1-turbo")
def product_prompt(sku):
return (
f"studio product photo of {sku['name']}, {sku['material']}, "
f"{sku['color']} finish, three-quarter view, soft even lighting, "
"centered on a plain background, no text, no props"
)
def generate(sku):
resp = requests.post(
"https://api.hiapi.ai/v1/images/generations",
headers={"Authorization": f"Bearer {HIAPI_KEY}"},
json={
"model": MODEL,
"prompt": product_prompt(sku),
"transparent_background": True,
"n": 1,
},
timeout=120,
)
resp.raise_for_status()
return resp.json()
Deux remarques sur le corps de la requête. Premièrement, demandez explicitement un fond transparent — c'est un paramètre de l'appel, et non quelque chose que l'on déduit après le téléchargement. Deuxièmement, gardez un n faible à chaque appel et parallélisez au niveau de la tâche ; une série de requêtes à image unique se réessaie bien plus proprement qu'une requête de vingt images où l'échec d'une seule fait perdre tout le lot.
Traiter la réponse de manière défensive
La réponse contient les données d'image (URL ou payload encodé, selon les paramètres envoyés). Traitez la récupération comme un domaine de défaillance distinct de la génération : une fois la génération renvoyée, téléchargez, validez et envoyez vers votre propre stockage. À partir de là, votre pipeline référence votre bucket, et non un résultat temporaire — c'est précisément ce qui rend les réessais et les rendus à nouveau maîtrisables.
Comparaison avec l'approche image-vers-image
L'écart entre un script exécutable et une tâche de catalogue exécutable apparaît presque toujours dans les parties les plus ingrates.
Modéliser les prompts comme des données
Placez les fragments de prompt dans des fichiers de configuration par catégorie, et non dans le code. Chaque SKU fournit les emplacements ; la catégorie fournit la structure de phrase et les contraintes négatives ("no text, no watermarks, no props"). Quand la composition d'une catégorie est mauvaise, vous corrigez un modèle, pas des milliers de lignes de données.
Réessayer avec discernement
Distinguez les échecs réessayables (timeouts, erreurs serveur temporaires, limitations de débit) des échecs définitifs (paramètres invalides, prompts rejetés). Réessayez les premiers avec un backoff exponentiel et une limite de tentatives ; échouez immédiatement sur les seconds en exposant la cause, car réessayer une requête mal formée ne fait que consommer la file. L'idempotence compte ici — utilisez le SKU plus un hachage du prompt comme clé de chaque tâche, afin qu'une tâche réessayée écrase au lieu de dupliquer.
Valider avant l'affichage en boutique
Insérez une étape de validation entre la génération et la publication. Des contrôles automatiques peu coûteux capturent la plupart des sorties défectueuses :
- Canal alpha présent, sujet non rogné sur les bords.
- Résolution conforme au minimum requis pour votre plus grand emplacement de publication.
- Hachage perceptuel comparé aux assets actuels pour signaler les quasi-doublons inattendus.
Dirigez les éléments qui échouent vers une file de révision plutôt que de les jeter. Les échecs silencieux sont précisément la manière dont un catalogue se remplit discrètement de produits aux mauvaises couleurs.
Surveiller les limites de concurrence
Les tâches batch atteignent souvent les limites de débit par pics plutôt que progressivement. Fixez la concurrence des workers sous la limite que vous estimez, rendez cette limite configurable, et laissez la file absorber l'arriéré. Un pipeline bridé mais qui termine vaut mieux qu'un pipeline qui oscille.
Budgéter par sortie, non par requête
La facturation suit les sorties générées ; suivez donc le nombre d'assets générés par SKU comme signal de coût. Lorsqu'une catégorie commence à générer beaucoup de variantes par produit, c'est une décision de conception de prompt que vous devez prendre sciemment, et non découvrir sur la facture.
Comparaison avec l'approche image-vers-image
Lorsqu'aucune photo exploitable du produit n'existe encore — nouveau SKU non photographié, nouveau coloris jamais shooté, ou assets provisoires pour la publication — la génération textuelle est le choix par défaut approprié. Le prompt décrit entièrement le résultat, et la sortie transparente vous fournit un asset composite sans étape de segmentation.
L'approche image-vers-image inverse les entrées. Vous fournissez une image de référence, le modèle travaille à partir d'elle, ce qui est nécessaire lorsque la fidélité au produit réel n'est pas négociable : coutures exactes, finitions matérielles réelles, teinte précise que recevra le client. Dans ce mode, l'image de référence est la contrainte qui garde la génération honnête.
Pour la plupart des catalogues, une répartition pratique :
- Texte-vers-image turbo pour l'échelle — variantes, fonds, vignettes de catégorie, visuels provisoires de mise en ligne précoce.
- Image-vers-image pour tout cas où le client s'appuiera sur le visuel pour décider d'un achat et où l'exactitude visuelle est critique.
Les deux partagent le même squelette de pipeline, si bien que le basculement ne demande qu'un identifiant de modèle et un champ d'entrée, pas une réécriture. Lorsque vous avez besoin d'une sortie pilotée par référence, le modèle image-vers-image qwen-image-3.0 peut se brancher sur le même worker, en joignant simplement l'image de référence au prompt.
Lancez d'abord le chemin turbo sur une seule catégorie, mesurez le taux de réussite de la validation, puis étendez progressivement — la page du modèle liste les champs à intégrer.
Articles similaires
Voir tous les articles →-
Guide d'utilisation
Guide de prise en main de Tripo H3.1 : trois modes d'entrée, paramètres et choix tarifaires
Décision d'intégration et maîtrise des coûts de la génération 3D pour les développeurs
-
Guide d'utilisation
Utiliser topaz-upscale/video via l'API HiAPI : un flux de travail pour améliorer la qualité des vidéos courtes
Interpolation d'images, réglages d'amélioration et une requête HiAPI exploitable pour une vidéo verticale
-
Guide d'utilisation
Générer des images de produits e-commerce avec gpt-image-2.5-sunburst/image-to-image via l'API HiAPI
Images de référence, remplacement d'arrière-plan, scènes de vie, et une requête HiAPI fonctionnelle