Genera immagini di prodotto e-commerce con grok-imagine/text-to-image tramite l'API hiapi

La maggior parte delle pipeline di immagini di prodotto si rompe nel momento in cui arriva questa richiesta: servono tre forme diverse dalla stessa foto — un quadrato per la griglia del catalogo, un ritaglio verticale per la pagina di dettaglio prodotto (PDP) mobile e un formato largo per il banner hero della homepage. Ritagliare una singola immagine hero raramente funziona bene in tutte le proporzioni — o il prodotto viene tagliato, oppure compaiono spazi vuoti imbarazzanti. grok-imagine/text-to-image aggira il problema: genera nativamente nelle proporzioni che ti servono, inclusi due formati larghi pensati apposta per questo tipo di banner (2:1 e 20:9), con un prezzo uniforme sull'API hiapi di $0.03 per immagine, indipendentemente dalla risoluzione.

Questa guida illustra la struttura effettiva della richiesta, le trappole dello schema che abbiamo incontrato nei test, uno script di generazione batch che esegue un intero elenco di scatti da un unico brief di prodotto, e un conteggio onesto dei costi per il catalogo su larga scala.

Posizionamento del prezzo

Verificato sulla pagina dei prezzi di hiapi al momento della stesura:

Modello	Prezzo per immagine	Risoluzione	Controllo delle proporzioni
grok-imagine/text-to-image	$0.03 uniforme	1K o 2K, stesso prezzo	13 proporzioni, incluse 2:1, 20:9
grok-imagine-quality/text-to-image	$0.07 (1K) / $0.10 (2K)	Prezzo a scaglioni per risoluzione	Stesso set di proporzioni

La fascia quality offre un miglioramento davvero significativo sui dettagli fini — riflessi, texture dei tessuti, testo piccolo — e vale il costo extra per un piccolo numero di immagini hero davvero centrali. Per la maggior parte delle immagini del catalogo (miniature della griglia, varianti lifestyle, altre angolazioni), il modello base è già abbastanza vicino, e il divario di prezzo di 2-3 volte non vale la spesa in scenari batch.

La richiesta che funziona davvero

Tutte le immagini di questa pagina provengono dallo stesso endpoint:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "input": {
      "prompt": "matte ceramic pour-over coffee dripper on a pale oak table, soft morning window light from the left, small negative space top-right, no text, no logo, product photography",
      "aspect_ratio": "1:1",
      "resolution": "2k"
    }
  }'

Questo restituisce un taskId; esegui il polling di GET /v1/tasks/{taskId} finché status non è success, poi recupera output[0].url e scarica — l'URL è firmato e scade, quindi salva subito i byte piuttosto che collegarti direttamente ad esso.

Durante i test, tre dettagli dello schema ci hanno fatto inciampare e vale la pena conoscerli prima di costruire il tuo:

• aspect_ratio è un enum rigoroso di 13 valori, non un formato libero. Inviare qualsiasi altro valore restituisce un 400 con l'elenco completo: 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2. Le due proporzioni necessarie per i banner sono 2:1 e 20:9 — la maggior parte dei modelli di immagine su hiapi arriva solo fino a 21:9, oppure non offre affatto opzioni ultra-large.
• resolution accetta solo minuscole — usa "2k", non "2K". L'invio della forma maiuscola viene rifiutato direttamente, senza conversione silenziosa.
• Lo schema di input è rigoroso. Campi extra o digitati male (un negative_prompt residuo, una chiave style copiata da esempi di altri modelli) fanno fallire l'intera richiesta invece di essere ignorati.

Scrivere prompt per immagini pulite a livello di catalogo

La leva più grande per un output di catalogo coerente è specificare esplicitamente ciò che non vuoi. Per l'immagine hero su fondo bianco sopra, il prompt efficace è:

"Caraffa da caffè pour-over in ceramica opaca su sfondo bianco uniforme senza cuciture, illuminazione da softbox da studio, centrata, nessun gradiente d'ombra oltre a una morbida ombra di contatto, nessun testo, nessuna filigrana, nessun oggetto di scena, fotografia di prodotto e-commerce, messa a fuoco nitida"

Per le varianti lifestyle destinate alle immagini secondarie della PDP o ai banner email, sostituisci lo sfondo e gli indizi di illuminazione ma mantieni la stessa disciplina "niente testo / niente filigrana / nessun oggetto di scena oltre a quelli specificati" — è proprio questo che impedisce a grok-imagine di aggiungere oggetti confusi o testo di etichetta illeggibile direttamente sul prodotto:

"La stessa caraffa pour-over in ceramica su un piano di lavoro in cucina in legno, accanto a una tazza fumante, luce mattutina calda, profondità di campo ridotta, sfondo cucina accogliente e vissuto sfumato dolcemente, nessun testo, nessun logo"

Workflow per banner ultra-larghi

Quando la richiesta è un banner per la homepage o per la categoria invece di una miniatura del catalogo, 2:1 e 20:9 sono esattamente le due proporzioni che rendono grok-imagine particolarmente adatto. Il trucco è chiedere direttamente lo spazio negativo, invece di sperare che il ritaglio vada bene — descrivi dove si trova il prodotto nell'inquadratura e quali aree devono rimanere vuote:

"Caraffa da caffè pour-over in ceramica opaca posizionata nel terzo destro dell'inquadratura, luce esterna dell'ora d'oro, ampio spazio negativo vuoto sul due terzi di sinistra dell'immagine per sovrapporre il testo del titolo, composizione cinematografica larga, nessun testo, nessun logo"

{
  "model": "grok-imagine/text-to-image",
  "input": {
    "prompt": "matte ceramic pour-over coffee dripper positioned in the right third of frame, golden-hour outdoor light, generous empty negative space across the left two-thirds of the image for headline text overlay, cinematic wide composition, no text, no logo",
    "aspect_ratio": "20:9",
    "resolution": "2k"
  }
}

Se il tuo CMS richiede dimensioni in pixel esatte anziché proporzioni, genera nella proporzione supportata più vicina e poi ritaglia senza perdita dall'immagine — per i calcoli specifici del padding consulta la nostra nota sulle dimensioni esatte tramite API.

Generare in batch l'intero elenco di scatti

Un singolo brief di prodotto di solito richiede più di un'immagine. Lo script seguente riproduce quello realmente usato per generare le quattro immagini di questa pagina — invia un task per immagine, esegue il polling fino al completamento, poi salva su disco:

import os
import time
import requests

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

SHOTS = [
    {
        "name": "hero",
        "prompt": "matte ceramic pour-over coffee dripper on a pure white seamless "
                  "background, studio softbox lighting, centered, e-commerce product "
                  "photography, no text, no watermark",
        "aspect_ratio": "1:1",
    },
    {
        "name": "lifestyle",
        "prompt": "same ceramic pour-over dripper on a wooden kitchen counter next to "
                  "a steaming mug, warm morning light, shallow depth of field, no text",
        "aspect_ratio": "4:3",
    },
    {
        "name": "banner",
        "prompt": "ceramic pour-over dripper in the right third of frame, soft studio "
                  "light, empty negative space across the left two-thirds for headline "
                  "text, no text, no logo",
        "aspect_ratio": "2:1",
    },
]


def create_task(shot):
    payload = {
        "model": "grok-imagine/text-to-image",
        "input": {"prompt": shot["prompt"], "aspect_ratio": shot["aspect_ratio"], "resolution": "2k"},
    }
    resp = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


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


for shot in SHOTS:
    task_id = create_task(shot)
    url = wait_for_result(task_id)
    image_bytes = requests.get(url, timeout=120).content
    with open(f"{shot['name']}.jpg", "wb") as f:
        f.write(image_bytes)
    print(f"{shot['name']}: saved {len(image_bytes)} bytes")

Se devi eseguire un batch completo su più SKU, invia tutti e tre i task in anticipo e poi esegui il polling in parallelo (un piccolo asyncio o un pool di thread è sufficiente) — ogni task di solito termina entro un minuto, ed eseguirli in serie aggiunge solo attese inattive senza motivo.

Costi per un'esecuzione reale sul catalogo

A $0.03 uniforme per immagine, la combinazione di tre immagini sopra (hero + lifestyle + banner) costa $0.09 per SKU. Su scala più ampia:

• 50 SKU × 3 immagini = 150 immagini → $4.50
• 500 SKU × 3 immagini = 1.500 immagini → $45
• Aggiungendo l'upgrade a grok-imagine-quality solo per le immagini hero 2K ($0.10 invece di $0.03), il totale per 500 SKU diventa $80 — comunque una frazione di un singolo servizio fotografico tradizionale di prodotto.

grok-imagine rispetto al resto della gamma

Se un'immagine deve muoversi — ad esempio un breve filmato di prodotto di 6 secondi per un annuncio social invece di un banner statico — la stessa famiglia è coperta da grok-imagine-image-to-video, che usa una di queste immagini statiche come frame iniziale; abbiamo trattato quel workflow separatamente nella guida ai video brevi. Per i team che confrontano con una pipeline di catalogo basata su Nano-Banana, la nostra guida e-commerce Nano-Banana è il riferimento affiancato più vicino — stessa struttura di task API, punti di forza del modello diversi.

Domande frequenti

grok-imagine/text-to-image supporta immagini di riferimento (i2i), non solo prompt testuali? Sì — ma quella è una variante separata del modello (grok-imagine/image-to-image), con il proprio schema di input. Questa guida copre il percorso puramente text-to-image.

Perché la mia richiesta restituisce un 400 con un errore "additional properties"? Lo schema di input è rigoroso. Controlla attentamente di inviare solo prompt, aspect_ratio e, facoltativamente, resolution — non portarti dietro campi extra copiati da esempi di altri modelli.

Posso ottenere una proporzione esatta come 1200×630 invece di scegliere dall'enum? Genera nella proporzione supportata più vicina (16:9 è vicino a molte forme di banner web), poi ritaglia senza perdita in post-produzione — per il metodo specifico di padding consulta la guida sulle dimensioni esatte linkata sopra.

Vale la pena aspettare la risoluzione 2K rispetto a 1K? Con questo modello entrambe le risoluzioni hanno lo stesso prezzo, quindi usa 2K come impostazione predefinita a meno che tu non abbia un budget di latenza rigoroso — ottieni più dettagli gratuitamente.

Prova tu stesso

Tutto l'accesso API qui è utilizzabile con una chiave hiapi standard — consulta la documentazione per l'autenticazione e il riferimento completo sul polling dei task, e controlla la pagina dei prezzi per le tariffe aggiornate dell'intera gamma di modelli prima di impegnarti in un'esecuzione batch.