Generare immagini di prodotti e-commerce con z-image tramite l'API hiapi

La maggior parte dei modelli di immagine sa disegnare un prodotto. Ma molti meno sanno disegnarlo bene e scrivere correttamente il prezzo. Per gli scenari e-commerce — cartellini prezzo, banner promozionali, card sconto, etichette di confezionamento — il testo nell'immagine è la cosa che conta: un solo carattere illeggibile significa asset scartato.

z-image è un modello text-to-image di livello Turbo su hiapi, nato proprio per questa nicchia: generazione rapida di immagini fotorealistiche, testo nell'immagine (inglese e cinese) accurato, al prezzo di $0.008 per immagine — meno di un terzo del prezzo della maggior parte delle alternative. Ogni immagine in questa guida è stata generata con esattamente lo stesso prompt mostrato accanto, tramite la stessa chiamata /v1/tasks che copierai qui sotto, con ogni rendering che richiede circa 30–60 secondi da end-to-end.

Perché scegliere z-image per le immagini di prodotto

Tre proprietà contano per una pipeline e-commerce, e z-image eccelle in tutte e tre:

• Rendering del testo. Seguendo le regole dei prompt qui sotto, card promozionali, banner logistici ed etichette di bottiglie tornano con ogni parola scritta correttamente.
• Velocità. È un modello ottimizzato Turbo; i nostri rendering di test si sono completati ogni volta in molto meno di un minuto, il che rende il batch di centinaia di immagini SKU un lavoro da pausa caffè.
• Prezzo. A $0.008/immagine (verificato sulla pagina dei prezzi), un refresh di catalogo di 1.000 immagini costa $8. Lo stesso lavoro con gpt-image-2 ($0.03/immagine) costerebbe $30.

Se vuoi una panoramica più completa del modello — configurazione delle chiavi, esempi generici, quando non usarlo — consulta Z-Image API: prezzi, chiave API, esempi e casi d'uso. Questa guida si concentra sui flussi di lavoro e-commerce.

L'interfaccia API verificata

z-image gira sull'endpoint di task asincroni di hiapi. Invii un task, fai polling finché non riesce, poi scarichi l'output. Abbiamo confermato due fatti sullo schema rispetto all'API live (entrambi diversi da alcuni altri modelli della piattaforma):

1. input accetta solo prompt e aspect_ratio. Inviare un campo resolution restituisce HTTP 400 (additional properties not allowed) — a differenza di gpt-image-2, che lo richiede.
2. aspect_ratio deve essere uno tra 1:1, 4:3, 3:4, 16:9, 9:16. Qualsiasi altro valore (abbiamo provato 3:2) viene rifiutato con 400 che elenca i valori validi.

La risoluzione di output è fissa per proporzione — i nostri rendering sono tornati come PNG: 1536×1536 (1:1), 1344×768 (16:9), 928×1232 (3:4) e 1728×1296 (4:3).

Inviare un task

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 risposta contiene un id di task:

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

Fare polling e scaricare

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

Fai polling ogni pochi secondi finché data.status è success e data.output esiste; considera fail come stato terminale. Un consiglio pratico: subito dopo la generazione il task può riportare brevemente uno stato intermedio (abbiamo osservato archiving) prima che compaia l'array di output, quindi il tuo loop dovrebbe basarsi sulla presenza dell'URL di output, non solo sulla stringa di stato.

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)

Scarica subito. output[0].url è un link temporaneo con un timestamp expireAt — persisti i byte nel tuo storage (S3/R2/CDN) immediatamente dopo il successo del task. Se un task sembra bloccato, qui è spiegato come diagnosticare i task hiapi bloccati o in timeout.

Cinque ricette e-commerce, con output reali

Tutte le immagini qui sotto sono rendering reali di z-image generati con esattamente i prompt mostrati. Nessun ritocco.

1. Immagine principale con cartellino prezzo

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.

Nota la formulazione: il testo da mostrare è tra virgolette e il prompt dice che la card contiene solo quelle parole. Il nostro primo tentativo descriveva il testo inline ("...reads exactly: SUMMER SALE on the first line and $19.99 on the second line") e il modello ha fedelmente impaginato la parola "ON" tra le due righe — le parole istruzione sono finite nel rendering. Cita le stringhe letterali; tieni le istruzioni fuori dalle virgolette.

2. Banner promozionale in formato largo

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 ti dà un banner da 1344×768, pronto per lo slot hero della homepage del negozio.

3. Card sconto verticale per social media

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) è la proporzione più vicina al formato post di un feed; se la tua piattaforma lo richiede, ritaglia a 4:5 a valle.

4. Etichetta di confezione leggibile

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.

Questo è il test più difficile del gruppo — testo piccolo su vetro curvo — e l'etichetta è tornata pulita, incluso "10%".

5. Gamma di colori (senza testo)

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 geometria coerente tra le varianti è proprio ciò che la rende utilizzabile come striscia di catalogo — z-image ha mantenuto identiche le forme delle tre tazze colorate in un'unica generazione.

Regole per i prompt che fanno sopravvivere il testo

Condensate da ciò che ha funzionato (e fallito) nei nostri test reali:

1. Metti le stringhe letterali tra virgolette. text reads exactly: "SUMMER SALE" — il modello tratta le parole circostanti non tra virgolette come possibili copy.
2. Aggiungi "and no other words" (e nessun'altra parola). Altrimenti il modello potrebbe inventare copy di badge extra per riempire lo spazio.
3. Mantieni il testo frontale alla fotocamera. Il nostro unico rendering illeggibile era testo appeso ad angolo su un cartellino; lo stesso copy su una card piatta è venuto perfetto. La deformazione prospettica è dove i glifi cedono per primi.
4. Uno o due blocchi di testo per immagine. Ogni blocco di testo aggiuntivo moltiplica le probabilità di fallimento; per layout complessi, componi a valle.
5. Verifica prima di pubblicare. A questo prezzo puoi permetterti un ciclo di retry: renderizza, OCR o ispezione visiva del testo, rigenera se non corrisponde. Anche con un retry per ogni immagine fallita, il costo resta una frazione di quello dei modelli alternativi.

Costo in batch

Uno scenario concreto: 200 SKU × 3 asset ciascuno (immagine di listing, banner promozionale, card social) = 600 immagini.

Modello	Prezzo/immagine	600 immagini	Note
z-image	$0.008	$4.80	Velocità Turbo, forte sul testo nell'immagine
flux-schnell	$0.005	$3.00	Il più economico, ma non incentrato sul rendering del testo
qwen-image-2.0	$0.025	$15.00	Forte sulla qualità generale
gpt-image-2	$0.03	$18.00	Richiede il campo resolution; guida e-commerce qui

(Prezzi presi dalla pagina dei prezzi hiapi al momento della pubblicazione.)

La modalità batch consiste semplicemente nel mettere la funzione generate() sopra in un loop — invia alcuni task in concorrenza, raccogli gli id dei task, poi fai polling in gruppo. Se spingi forte sul volume, leggi prima come hiapi gestisce i rate limit e i picchi di traffico.

Per iniziare

Prendi la chiave API dalla tua console, poi punta i frammenti sopra al tuo catalogo prodotti — la pagina del modello z-image ha la model card, e la documentazione hiapi illustra in modo completo l'API dei task. A $0.008 per rendering, il modo più economico per capire se fa per la tua pipeline è provarlo questo pomeriggio sui tuoi dieci SKU più difficili.