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

Il successo di un catalogo e-commerce dipende tutto dalla coerenza. Un venditore con 40 SKU non ha bisogno di 40 servizi fotografici diversi: ha bisogno di uno sfondo accattivante e di un modo per inserirvi rapidamente ogni prodotto. Questo è esattamente il caso d'uso reale dell'editing di immagini guidato da reference, ed è ciò in cui eccelle grok-imagine/image-to-image su hiapi API: gli si fornisce una scena e una foto del prodotto, e combina i due elementi in un'immagine pulita e coerente con il brand, senza maschere manuali né passaggi separati di scontorno.

Questa guida illustra lo schema di richiesta reale e testato del modello (non copy marketing), il prezzo effettivamente applicato, uno script di elaborazione batch per applicare lo stesso sfondo a un intero catalogo e un trucco pratico: controllare le proporzioni dell'output tra le varie piattaforme e-commerce che richiedono ritagli diversi.

Cosa fa realmente il modello

grok-imagine/image-to-image riceve un prompt testuale e alcune immagini di riferimento, e le fonde in una nuova immagine. Per la fotografia di prodotto, questo significa:

• Uniformità dello sfondo — collocare ogni foto SKU davanti alla stessa scena stilizzata (un tavolo, uno scaffale, un fondale da studio), senza dover riscattare nulla.
• Composizione della scena — combinare lo scontorno del prodotto con un'immagine di riferimento ambientale, facendo corrispondere luci e composizione.
• Trasferimento di stile tra reference — trasferire la colorazione o gli oggetti di scena di un'immagine in un'altra, mantenendo il prodotto stesso inalterato.

Tutto questo avviene in un'unica chiamata, con fatturazione per immagine di output più un piccolo costo per ogni immagine di riferimento inviata.

Lo schema reale (verificato sull'API live, non sulla pagina dei prezzi)

Abbiamo interrogato direttamente POST /v1/tasks con grok-imagine/image-to-image: lo schema di input del modello accetta esattamente due campi:

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "string, required",
    "image_urls": ["array of public image URLs, required, max 3"]
  }
}

Tutto qui: niente resolution, niente aspect_ratio, niente strength. Qualsiasi altro contenuto nel payload viene rifiutato dallo schema rigoroso.

C'è un errore da segnalare che merita una correzione: la pagina dei prezzi di hiapi afferma attualmente che il modello supporta "fino a 6" immagini di riferimento. Abbiamo testato direttamente inviando 6 e 7 URL di immagini nella stessa richiesta, ed entrambe sono state rifiutate:

{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 6, want 3"}
{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 7, want 3"}

Alla data di stesura, il limite effettivamente applicato è di 3 immagini per chiamata, non 6. Se costruisci una pipeline attorno a questo modello, pianifica su 3 immagini e considera obsoleto qualsiasi copy marketing che affermi il contrario: prima di pubblicare automazioni che dipendono da questo limite, verifica sempre con una chiamata live a POST /v1/tasks, perché questi limiti cambiano con l'evoluzione della piattaforma.

Proporzioni automatiche: il rapporto di output segue la tua prima immagine di riferimento

Il modello non ha un campo di input aspect_ratio: da dove deriva quindi la forma dell'output? Abbiamo eseguito un test controllato per scoprirlo: stesso prompt, stesse due immagini di riferimento, invertendo solo l'ordine di image_urls.

In questo rendering, la foto del prodotto (lo zaino) era elencata per prima in image_urls, seguita dalla scena di sfondo. L'output restituito era 1248×832, un'immagine orizzontale 3:2 che corrisponde alle proporzioni della foto del prodotto.

Stesso prompt, stesse due immagini, ma questa volta la scena di sfondo era elencata per prima. L'output restituito era 1024×1024, un ritaglio quadrato che corrisponde alle proporzioni della scena di riferimento, non a quelle del prodotto.

La regola è: il rapporto d'aspetto dell'output di grok-imagine/image-to-image eredita da quello dell'URL che compare per primo in image_urls. Non legge gli indizi di composizione dal prompt ("foto prodotto" o "scena ampia"): è puramente posizionale. Una volta capito questo, diventa una leva davvero utile: per ottenere il ritaglio preferito da una specifica piattaforma e-commerce, basta riordinare l'array delle immagini di riferimento. Per un listino quadrato in stile Instagram, metti per prima l'immagine di riferimento quadrata; per un banner orizzontale, metti per prima quella orizzontale.

Prezzi (verificati sul listino live)

Modello	Tipo di chiamata	Prezzo
grok-imagine/text-to-image	Testo → Immagine	$0.03 / immagine
grok-imagine/image-to-image	Editing guidato da reference (questa guida)	$0.03 / immagine + $0.003 per immagine di riferimento
grok-imagine-quality/text-to-image	Testo → Immagine, livello avanzato	$0.07 / immagine (1K)
grok-imagine-quality/image-to-image	Editing guidato da reference, livello avanzato	$0.08 / immagine (1K), $0.10 / immagine (2K), + $0.015 per immagine di riferimento

Il livello base grok-imagine/image-to-image utilizzato in questa guida non varia con la risoluzione ed è a tariffa fissa: non paghi il supplemento 2K/4K come nel livello -quality. Per un aggiornamento di catalogo che compone decine di SKU sulla stessa scena, $0.036 per immagine (una foto prodotto più un'immagine di riferimento della scena) è il numero su cui basare il budget. Prima di eseguire grandi volumi, ricontrolla sempre /en/pricing, perché le tariffe possono cambiare.

Se ti servono dettagli più nitidi per immagine e puoi accettare un aumento di prezzo di circa 3 volte, il livello grok-imagine-quality è la versione ad alta fedeltà dello stesso flusso di lavoro. Per render di prodotto puramente testuali, senza alcuna foto di riferimento, consulta la guida pratica al text-to-image del livello base.

Script di elaborazione batch: una scena, un intero catalogo

Di seguito un ciclo Python minimale che prende una scena di sfondo riutilizzabile, la combina con ogni foto prodotto in una cartella, invia ciascuna come attività separata e attende il completamento. Usa lo schema confermato sopra e colloca la foto prodotto per prima, così ogni output eredita le proporzioni della foto del prodotto; se vuoi le proporzioni della scena, inverti l'ordine.

import os
import time
import requests

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

SCENE_URL = "https://static.hiapi.ai/blog/grok-imagine-image-to-image-ecommerce/scene-base.jpg"
PROMPT = (
    "Composite the product from the first reference photo naturally into the "
    "second reference's studio scene, matching its lighting and shadow direction. "
    "Keep the product's shape, color, and texture unchanged."
)


def submit(product_url: str) -> str:
    payload = {
        "model": "grok-imagine/image-to-image",
        "input": {
            "prompt": PROMPT,
            "image_urls": [product_url, SCENE_URL],  # product first -> output follows its ratio
        },
    }
    resp = requests.post(f"{API_BASE}/tasks", headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


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


if __name__ == "__main__":
    product_urls = [
        "https://your-storage.example.com/catalog/dripper-raw.jpg",
        "https://your-storage.example.com/catalog/sneaker-raw.jpg",
        "https://your-storage.example.com/catalog/backpack-raw.jpg",
    ]
    for url in product_urls:
        task_id = submit(url)
        output_url = wait_for_result(task_id)
        print(f"{url} -> {output_url}")

Per una pipeline di produzione, registra un callback.url sull'attività invece di eseguire polling in un ciclo: per la struttura completa del payload di callback, consulta il catalogo dei modelli hiapi. Memorizza il taskId insieme allo SKU del prodotto, così le attività fallite possono essere ritentate senza reinviare l'intero batch.

Esempi con foto reali di prodotto

Entrambe sono state generate usando la stessa immagine di riferimento della scena di sfondo, cambiando solo la foto del prodotto tra una chiamata e l'altra: luce, tavolo e piante sullo sfondo restano coerenti in tutto il "catalogo", ed è proprio questo il senso del flusso di lavoro con scena riutilizzabile.

Domande frequenti

Posso usare più di 3 immagini di riferimento in una singola chiamata? No. Lo schema live impone maxItems: 3 su image_urls: confermato tramite test diretti sull'API, indipendentemente da ciò che afferma il copy marketing altrove. Progetta i prompt per un massimo di 3 immagini di riferimento (di solito: prodotto + scena, oppure prodotto + scena + riferimento di stile).

Come posso controllare le proporzioni dell'output? Il modello non ha un parametro aspect_ratio. L'output eredita le proporzioni della prima immagine in image_urls: riordina le immagini di riferimento per ottenere il rapporto desiderato.

Supporta la generazione puramente testuale senza immagini di riferimento? No: image_urls è un campo obbligatorio. Per render di prodotto puramente testuali, usa grok-imagine/text-to-image, a $0.03/immagine.

Esiste una versione ad alta fedeltà del modello? Sì, grok-imagine-quality/image-to-image esegue lo stesso flusso di lavoro guidato da reference a $0.08/immagine (1K) o $0.10/immagine (2K), più $0.015 per immagine di riferimento, offrendo dettagli più nitidi.

Prova subito

Ottieni una chiave API dalla tua dashboard hiapi, prepara una scena di sfondo, esegui le prime attività su pochi SKU e poi decidi se sostituire l'intero catalogo: a $0.036 per immagine, testare questo flusso di lavoro su 10 prodotti costa meno di un dollaro.