Generare immagini di prodotto e-commerce con qwen-image-2.0 tramite l'API hiapi

qwen-image-2.0 è il modello text-to-image di seconda generazione di Alibaba, disponibile tramite l'endpoint /v1/tasks di hiapi al prezzo di $0.025 per immagine, con output predefinito a 2K. Per l'e-commerce ha due aspetti particolarmente interessanti: in questa fascia di prezzo, il rendering del testo cinese è il più pulito tra tutti i modelli text-to-image attuali; inoltre la sua aderenza ai prompt con brief di prodotto lunghi e dettagliati è molto stabile — ed è esattamente ciò di cui hanno bisogno i listing transfrontalieri.

Questa guida è la versione eseguibile di quel workflow. Ogni chiamata API è qualcosa che puoi incollare direttamente nel terminale, i template dei prompt sono stati testati e renderizzati sull'endpoint live, e il prezzo per immagine è il dato reale del listino HiAPI. Qui non c'è nulla di teorico: i numeri di costo assumono i valori size effettivamente accettati da qwen-image-2.0, non cifre di marketing.

Perché scegliere qwen-image-2.0 per le immagini di prodotto transfrontaliere

Quando devi lanciare 200 SKU sul mercato in una volta sola, contano tre cose.

1. Rendering del testo cinese. La maggior parte dei listing e-commerce destinati a Cina continentale, Hong Kong, Taiwan o Sud-est asiatico richiede testo cinese leggibile su confezioni, banner o etichette. qwen-image-2.0 è l'unico modello su hiapi in cui puoi scrivere un prompt come “l'etichetta della bottiglia riporta 玫瑰精华水 in cinese serif in grassetto” e il modello renderizzerà esattamente quei glifi nella posizione esatta che descrivi.
2. Aderenza ai prompt con brief di prodotto lunghi. I brief e-commerce sono lunghi: materiali, codici esadecimali dei colori, finiture, direzione della luce, forma delle ombre, colore dello sfondo, angolazione della camera. Quando il brief si allunga, qwen-image-2.0 mantiene la coerenza complessiva — la modalità di fallimento tipica è solo un oggetto di scena mancante, non un prodotto inventato dal nulla.
3. Una fascia di costo che regge l'esplosione delle varianti. Una tipica pagina SKU vuole 4–6 immagini (packshot, immagine in scena, vista dall'alto, confronto di scala, due varianti). A $0.025 per immagine sono $0.10–$0.15 per SKU. Un lancio di 200 SKU costa $20–$30. È proprio questa fascia di costo a rendere “genera tutto da zero” più economico che commissionare parte del servizio fotografico e completare con le stock.

Per esperimenti di ottimizzazione prompt per prompt, e per sei ricette orientate allo stile anziché all'e-commerce, consulta l'articolo complementare ricette di prompt per qwen-image-2.0. Questo articolo si concentra invece sui casi d'uso da catalogo.

Lo schema di input di qwen-image-2.0 su hiapi

qwen-image-2.0 gira sotto l'interfaccia unificata /v1/tasks, l'unico endpoint immagine attualmente offerto da hiapi. Prima di scrivere qualsiasi codice, c'è una regola speciale da mettere a fuoco subito:

• Il parametro delle dimensioni si chiama size — non aspect_ratio, non resolution, non image_size. Gli altri modelli su hiapi (nano-banana, serie flux) accettano aspect_ratio; qwen-image-2.0 no.
• Il separatore dentro size è *, non x. "size": "2688x1536" restituisce 400; "size": "2688*1536" funziona correttamente.
• Sono accettati solo cinque valori size. Sono tutti a 2K:

Rapporto d'aspetto	Valore size	Utilizzo
16:9 (circa 1,75:1)	2688*1536	Hero image, banner, copertine dei listing
4:3 (circa 1,37:1)	2368*1728	Doppia pagina in stile magazine, spazi pubblicitari a due colonne
1:1	2048*2048	Packshot quadrati, miniature di marketplace
3:4 (circa 0,73:1)	1728*2368	Pagine prodotto mobile-first
9:16 (circa 0,57:1)	1536*2688	Copertine video verticali, frame statici TikTok/Reels

Se invii qualsiasi altro valore, l'API restituisce nell'errore l'elenco letterale dei valori consentiti:

{"code": 400, "message": "invalid input: size: value must be one of '2688*1536', '2368*1728', '2048*2048', '1728*2368', '1536*2688'"}

Considera questo messaggio di errore come fonte di verità autorevole — se in futuro vedrai comparire lì un nuovo valore, significa che la piattaforma ha esteso lo schema.

Una richiesta eseguibile

L'intera superficie di chiamata consiste in soli due endpoint: POST /v1/tasks per accodare, GET /v1/tasks/{taskId} per fare polling. Qui sotto la richiesta minima che produce il packshot mostrato più avanti.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "input": {
      "prompt": "A clear glass cosmetic dropper bottle on a clean off-white seamless paper background, soft daylight from camera left, gentle elliptical shadow, the label reads 玫瑰精华水 in bold serif Chinese with a small line of English Rose Essence Water below, the liquid inside has a faint pink tint, studio product photography, sharp focus on the label, no other props, square 1:1 composition",
      "size": "2048*2048"
    }
  }'

Risposta:

{"code": 200, "data": {"taskId": "tk-hiapi-01KW8R..."}, "message": "success"}

Per il polling:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01KW8R... \
  -H "Authorization: Bearer $HIAPI_TOKEN"

Il campo status passa da handling → archiving → success. Nelle nostre esecuzioni di test, il tempo reale totale per immagine a 2K è stato di 25–45 secondi. Quando lo status è success, output[0].url contiene l'immagine — ma punta a temp.hiapi.ai con un timestamp Unix expireAt, quindi scaricala subito. Non incorporarla in una pagina né fissarla in un database; restituirà 404 entro poche ore.

Eseguito sull'endpoint live, questo prompt packshot genera una boccetta contagocce in vetro con i caratteri cinesi 玫瑰精华水 renderizzati in modo pulito sull'etichetta, e subito sotto l'inglese Rose Essence Water in un peso minore. Il modello posiziona entrambe le righe di testo nell'area dell'etichetta prevista, senza bisogno di alcun indizio di layout nel prompt — la formula “the label reads X” è sufficiente.

Il ciclo Python che trasforma una tabella SKU in packshot caricati

Questo è il ciclo che abbiamo eseguito generando le immagini di questa pagina. Accetta un insieme di tuple (slug, prompt, size), invia in modo concorrente con un limite di parallelismo ridotto, esegue polling di ogni task fino al completamento, scarica i risultati e li carica come webp sul tuo storage. Il pattern è volutamente banale — requests più concurrent.futures — perché la parte interessante è il modello.

import os, time, io, requests, concurrent.futures as cf
from PIL import Image

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


def submit(prompt, size):
    r = requests.post(BASE, headers=H, json={
        "model": "qwen-image-2.0",
        "input": {"prompt": prompt, "size": size},
    }, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]


def wait(task_id, deadline_s=240):
    deadline = time.time() + deadline_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/{task_id}", headers=H, timeout=30)
        d = r.json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {d.get('error')}")
        time.sleep(4)
    raise TimeoutError(f"task {task_id} not done in {deadline_s}s")


def render_one(item):
    slug, prompt, size = item
    task_id = submit(prompt, size)
    url = wait(task_id)
    png = requests.get(url, timeout=60).content
    buf = io.BytesIO()
    Image.open(io.BytesIO(png)).convert("RGB").save(buf, "WEBP", quality=88, method=6)
    return slug, buf.getvalue()


JOBS = [
    ("packshot-rose-water",  "A clear dropper bottle, label 玫瑰精华水…", "2048*2048"),
    ("packshot-tea-canister","A pale grey ceramic tea canister, label 龙井…", "2048*2048"),
    # … 200 more rows from your sheet …
]

with cf.ThreadPoolExecutor(max_workers=6) as pool:
    for slug, webp in pool.map(render_one, JOBS):
        with open(f"out/{slug}.webp", "wb") as f:
            f.write(webp)
        print(f"saved {slug}.webp ({len(webp)} bytes)")

Alcune piccole note su questo codice che non si vedono dal codice stesso.

• max_workers=6 è il valore che abbiamo osservato essere il punto ottimale. A 8–10, la profondità della coda inizia a manifestarsi come latenza aggiuntiva anziché throughput. Il lato modello sembra distribuire la concorrenza equamente per account.
• Prima di salvare convertiamo in webp con qualità 88. Il png 2K prodotto da questo endpoint pesa circa 3–4 MB; il webp scende a 200–400 KB, visivamente identico alle dimensioni di una pagina prodotto. Trasferimento più economico, e il modello ha già codificato molte texture che il JPEG gestisce male.
• L'URL temporaneo può essere scaricato una sola volta. Se il tuo passo di upload fallisce (guasto S3, rete instabile), devi ri-renderizzare — non c'è una seconda occasione per ottenere l'output dello stesso task.

Sei pattern di prompt adatti all'e-commerce

Queste sono le forme di prompt sopravvissute ai nostri confronti A/B interni con alternative più verbose. Sono scritte per utenti di lingua inglese che lavorano con etichette di prodotto in cinese — lo scenario transfrontaliero più comune.

Pattern 1 — Packshot di un singolo prodotto con etichetta cinese

L'immagine di prodotto predefinita. Specifica il colore di sfondo in inglese semplice, specifica il testo dell'etichetta in cinese letterale con la famiglia di font indicata in inglese, e specifica una sola fonte di luce.

A pale grey ceramic tea canister on a clean off-white seamless paper background. The label reads 龙井 in bold black serif Chinese with the small English subtitle Longjing Green Tea below. Soft daylight from camera right, gentle elliptical shadow, no other props. Sharp focus on the label, studio product photography, square 1:1 composition.

I due elementi che funzionano sono “reads X in bold serif Chinese” (qwen-image-2.0 lo colloca nella posizione prevista dell'etichetta) e “sharp focus on the label” (fa trattare al modello il testo come punto focale, non come decorazione).

Pattern 2 — Immagine in scena costruita attorno a un piatto vuoto

Per la fotografia in scena, descrivi prima l'ambiente e inserisci il prodotto per ultimo, non il contrario. Il modello tende a scostarsi più sull'ambiente che sul prodotto, quindi ancora prima la scena.

A wooden Japanese-style table near a wide window in late-morning daylight. The window casts a soft rectangle of light onto the table. In the center of the table is the pale grey ceramic tea canister from the previous shot, with a small wisp of steam rising from a cup beside it. Loose tea leaves are scattered to the right. Wabi-sabi aesthetic, soft shadows, shallow depth of field with focus on the canister. 16:9 widescreen composition.

Nei nostri render di test, la scatola riporta i caratteri 龙井, con l'inglese Longjing Green Tea subito sotto — la stessa disciplina sull'etichetta del packshot — e vapore, foglie sparse e luce della finestra appaiono come descritto.

Pattern 3 — Griglia di varianti di colore in un singolo render

Quando le varianti condividono la stessa geometria del prodotto, puoi renderizzare l'intera griglia in un'unica chiamata invece che tre. Più economico, e l'illuminazione delle celle è coerente per costruzione.

Three pairs of low-top canvas sneakers shot from a slight top-down angle, arranged in one horizontal row on a clean light-grey seamless background. From left to right: dusty rose, sage green, ivory cream. Identical sneaker silhouette, identical lighting, identical shadow. Each pair faces the camera with toes pointing forward. Studio product photography, 1:1 composition, evenly spaced.

Questo pattern ti evita di renderizzare ogni variante separatamente e poi cercare di abbinare l'illuminazione in post. Il vincolo “identical sneaker silhouette, identical lighting, identical shadow” è la chiave per mantenere uniforme l'intera fila.

Pattern 4 — Banner promozionale bilingue

Per le campagne co-branded su Shopee, Lazada e Taobao, di solito serve un titolo cinese e un sottotitolo inglese nella stessa immagine. qwen-image-2.0 è l'unico modello su hiapi in grado di fare bene entrambi nello stesso render.

A horizontal ecommerce promotional banner on a soft pink gradient background. The main headline reads 双十一大促 in large bold black sans-serif Chinese in the center-left. Below the Chinese headline in smaller dark grey English serif: Double 11 Sale — Up to 50% Off. To the right is a clear glass dropper bottle of pink serum with a small white label. Subtle confetti texture in the background, clean and modern, 16:9 widescreen.

Il trucco per renderlo affidabile è mettere il cinese all'inizio del prompt con il qualificatore “large bold”, poi dare all'inglese il qualificatore “smaller”. Se inverti l'ordine, il modello tende a rendere anche l'inglese a dimensione titolo. L'etichetta del prodotto dentro il banner è il punto in cui puoi rilassarti — nei nostri render di test qwen ha scelto per la bottiglia un'etichetta generica “Vitamin C Serum” perché non avevamo scritto i caratteri; per le campagne di brand, o includi nel prompt il testo letterale dell'etichetta, o sovrapponi l'etichetta reale in post-produzione.

Pattern 5 — Scheda listing per marketplace transfrontalieri

Per un asset composito che assomiglia a una tile di listing Amazon o Tmall — prodotto, titolo, prezzo, badge — il prompt deve leggersi come un brief di layout, non come un brief fotografico.

A square ecommerce listing card on a white background. In the top two-thirds, a clear glass dropper bottle of pink rose-essence water labeled 玫瑰精华水 / Rose Essence Water. In the bottom third, on the left, the price 99 元 in large bold black Chinese characters with a small English subtitle Rose Essence 30ml below. On the right, a small green badge that reads 新品 in white. Clean modern layout, soft drop shadow under the product, 4:3 composition.

Per i listing, renderizza in 4:3 (2368*1728), non 1:1 — lo slot hero della maggior parte dei componenti di listing dei marketplace è 4:3, e un quadrato produrrà un ritaglio scomodo.

Pattern 6 — Generazione su richiesta per la personalizzazione

L'ultimo pattern cambia l'economia unitaria. Una volta che ogni render costa meno di tre centesimi, puoi smettere di pre-renderizzare i banner per le campagne e renderizzarli per cliente al momento della richiesta — “Gentile Sig.ra Wang, la sua combinazione mensile è pronta”, con il vero nome del cliente incorporato nel banner. Memorizza in cache per hash del nome, imposta un TTL, e otterrai immagini banner personalizzate con una piccola bolletta CDN.

Il vincolo è la latenza. 25–45 secondi per render sono troppo lenti per un flusso di richieste sincrono, ma vanno benissimo per l'invio di email o notifiche push — genera mentre accodi, incorpora quando il messaggio parte.

Dove qwen-image-2.0 non eccelle

Per equilibrio, questi quattro tipi di lavoro li affidiamo ancora ad altri modelli sullo stesso endpoint /v1/tasks.

• Scatti a mano con motion blur. I packshot sono il punto di forza. Se ti serve qualcosa che sembri non messo in posa — stile UGC, leggero movimento, composizione imperfetta — prova nano-banana-pro, che comprende meglio le composizioni “casuali”.
• Varianti di prodotto identiche a livello di pixel. qwen-image-2.0 renderizza varianti simili tra chiamate diverse, ma se ti serve esattamente la stessa boccetta contagocce in cinque diverse impostazioni di luce, ti serve un modello con condizionamento da immagine di riferimento. Nessun modello puramente text-to-image su hiapi garantisce coerenza pixel per pixel tra chiamate.
• Volti fotorealistici a figura intera. I primi piani vanno bene; figure intere o gruppi tendono a sfumare i dettagli del viso. Per e-commerce centrato sulle persone — prove di abbigliamento, dimostrazioni di bellezza — abbina qwen-image-2.0 a un modello video con condizionamento da riferimento per le riprese in movimento.
• Turnaround sub-secondo. Se devi generare immagini nel ciclo interno di una richiesta sincrona (l'utente è davanti allo schermo in attesa), 25–45 secondi sono troppo lunghi. flux-schnell risponde in circa 5 secondi a $0.005 per immagine, ma non renderizza testo cinese. Scegli prima in base al budget di latenza.

Il costo reale di un lancio di 200 SKU

Facciamo i conti end-to-end del workflow su un caso rappresentativo.

Passo	Quantità	Prezzo unitario	Totale
Hero image/packshot per SKU	200 × 1	$0.025	$5.00
Immagine in scena per SKU	200 × 1	$0.025	$5.00
Griglia varianti per SKU (circa 3 varianti in un render)	200 × 1	$0.025	$5.00
Banner bilingue per categoria (10 categorie)	10 × 1	$0.025	$0.25
Scheda listing per SKU	200 × 1	$0.025	$5.00
Costo totale generazione immagini	810 render	—	$20.25

Al listino hiapi attuale, il budget immagini completo per un lancio transfrontaliero di 200 SKU è di circa $20. Lo stesso lavoro con modelli premium (a partire da $0.04 per immagine) si colloca tra $30 e $140, con tempi di esecuzione più lunghi per immagine. È proprio questo divario che qwen-image-2.0 è pensato per colmare: lavoro e-commerce consapevole del cinese, a una fascia di costo così bassa che smetti di contare i render.

Dove andare ora

• Leggi ricette di prompt per qwen-image-2.0 per le sei ricette orientate allo stile, non specifiche dell'e-commerce.
• Usa la pagina dei prezzi di hiapi come fonte di verità per qualsiasi cifra di costo — qwen-image-2.0 è attualmente a $0.025 per immagine, ma fa fede quella pagina.
• Per flussi sensibili alla latenza che non richiedono testo cinese, passa a flux-schnell mantenendo la stessa forma /v1/tasks — confronto in Generare immagini di prodotto e-commerce con FLUX.1 schnell.

Il senso dell'endpoint unificato /v1/tasks è tutto qui: cambiare modello significa cambiare una stringa. Una volta che hai impostato il ciclo per qwen-image-2.0, lo stesso script Python può renderizzare su qualsiasi modello immagine di hiapi semplicemente modificando il campo "model" e allineandosi allo schema size di quel modello.