Genera video brevi da immagini statiche di prodotto: grok-imagine/image-to-video su hiapi API

I contenuti video brevi per i prodotti hanno un problema di offerta. Un breve video pronto per la pubblicazione richiedeva in passato un servizio fotografico: tempo in studio, motion design, un montatore. Ma se stai già gestendo un catalogo e-commerce, hai già la materia prima a portata di mano: migliaia di immagini statiche di prodotto. grok-imagine/image-to-video (l'endpoint image-to-video di Grok Imagine di xAI) trasforma queste immagini statiche in brevi video cinematografici da 6–30 secondi con una singola chiamata API asincrona, e il condizionamento sulle immagini di riferimento fa sì che il tuo prodotto continui a sembrare il tuo prodotto.

Questa guida è un flusso di lavoro end-to-end su hiapi API: animare una singola immagine statica di catalogo, bloccare la coerenza del soggetto con più immagini di riferimento, scegliere la durata e il livello di risoluzione in base all'economicità del feed, e processare in batch l'intero catalogo in una coda di video verticali brevi. Ogni breve video incorporato qui sotto è un output reale, non montato, di prima generazione, prodotto dall'API in produzione — generato per questo articolo da immagini statiche del nostro archivio, con accanto il prompt e le impostazioni esatti.

Modello, limiti e prezzi

grok-imagine/image-to-video gira sull'interfaccia di task asincroni di hiapi (POST /v1/tasks). Lo schema di input che abbiamo verificato con test reali per questo articolo:

• image_urls (array, obbligatorio) — uno o più URL di immagini di riferimento pubblicamente accessibili. Gli URL privati o non recuperabili falliscono in fase di normalizzazione, non con un errore di schema, quindi ospita le immagini di riferimento in una posizione pubblica prima di procedere.
• prompt (stringa, opzionale) — indicazioni su movimento, inquadratura e atmosfera. Senza un prompt il modello improvvisa; per i contenuti di prodotto dovresti sempre fornirlo.
• duration (intero, 6–30 secondi)
• resolution (480p o 720p)
• aspect_ratio (1:1, 2:3, 3:2, 16:9, 9:16)

Non esistono campi motion_mode, seed o prompt negativo — i campi sconosciuti vengono rifiutati con un 400. Tutto il controllo del movimento passa dalla formulazione del prompt.

Un comportamento che abbiamo riscontrato durante la generazione dei video brevi per questo articolo: quando aspect_ratio non corrisponde alle proporzioni dell'immagine di riferimento stessa, spesso vince l'immagine di riferimento. In tutte e tre le esecuzioni qui sotto abbiamo richiesto 9:16; due immagini statiche di partenza quadrate hanno restituito video quadrati (960×960 e 544×544), mentre l'esecuzione con la prima immagine di riferimento in formato orizzontale ha prodotto un vero verticale 720×1280. Se il tuo feed richiede un 9:16 garantito, ritaglia l'immagine statica di riferimento in 9:16 prima dell'invio, invece di affidarti a quel parametro.

Il prezzo è calcolato sui secondi di output, secondo la pagina dei prezzi di hiapi al momento della stesura:

Livello	Prezzo al secondo	Video breve da 6 s	Video breve da 15 s	Video breve da 30 s
480p	$0.0114	$0.068	$0.171	$0.342
720p	$0.0214	$0.128	$0.321	$0.642

Questo prezzo plasma l'intero flusso di lavoro: un video breve hero da 6 secondi in 720p costa circa 13 centesimi, mentre una bozza in 480p costa circa la metà. Puoi permetterti tranquillamente di iterare più volte.

Invio → polling → download

Il ciclo di vita del task è invio, polling, download. Invio con curl:

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/image-to-video",
    "input": {
      "prompt": "Slow cinematic orbit around the bag, studio lighting glinting off the brass zippers, background stays clean, product unchanged.",
      "image_urls": ["https://your-cdn.example.com/products/weekender.jpg"],
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "9:16"
    }
  }'

Riceverai immediatamente un ID del task:

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

Poi esegui il polling di GET /v1/tasks/{taskId} finché status non è success, quindi scarica output[0].url. Di seguito uno script helper Python completo — esattamente il pattern usato per generare ogni video breve in questo articolo:

import json, subprocess, time, os

API = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]

def submit(input_fields: dict) -> str:
    payload = {"model": "grok-imagine/image-to-video", "input": input_fields}
    out = subprocess.run(
        ["curl", "-s", "-X", "POST", API,
         "-H", f"Authorization: Bearer {TOKEN}",
         "-H", "Content-Type: application/json",
         "-d", json.dumps(payload)],
        capture_output=True, text=True, timeout=70).stdout
    data = json.loads(out)
    if not (data.get("data") or {}).get("taskId"):
        raise RuntimeError(f"submit failed: {out[:300]}")
    return data["data"]["taskId"]

def wait(task_id: str, timeout_s: int = 1200) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        out = subprocess.run(
            ["curl", "-s", f"{API}/{task_id}",
             "-H", f"Authorization: Bearer {TOKEN}"],
            capture_output=True, text=True, timeout=40).stdout
        task = json.loads(out)["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(10)
    raise TimeoutError(task_id)

task_id = submit({
    "prompt": "...",
    "image_urls": ["https://your-cdn.example.com/products/weekender.jpg"],
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "9:16",
})
task = wait(task_id)
video_url = task["output"][0]["url"]
subprocess.run(["curl", "-s", "-o", "clip.mp4", video_url], timeout=180)

Due dettagli operativi da tenere presenti in produzione:

1. output[0].url è un link firmato con scadenza (con un tempo di scadenza). Scarica immediatamente i byte non appena il task va a buon fine e spostali nel tuo storage — non conservare mai l'URL originale del task in modo persistente.
2. La fatturazione avviene quando il task viene accettato, quindi valida prima di inviare in grande quantità. Un trucco utile: invia un valore fuori intervallo, come "duration": 99 — riceverai un errore completo di validazione dello schema, senza creare un task fatturabile.

Un'immagine statica → un video hero

L'operazione più comune: prendi un'immagine di prodotto del catalogo e dalle un movimento di camera continuo. La fotografia di prodotto è per natura statica, quindi il compito del prompt è aggiungere un solo movimento credibile e fissare esplicitamente tutto il resto:

Slow cinematic orbit around the burnt-orange canvas weekender bag, camera
circling smoothly from front to three-quarter view, studio lighting glinting
off the brass zippers, seamless white background stays clean and shadowless,
product perfectly sharp and unchanged, subtle premium e-commerce energy.

Output reale — grok-imagine/image-to-video, 6 s @ 720p, singola immagine di riferimento. Prima generazione, non montato. Consegna effettiva 960×960: l'immagine statica sorgente quadrata ha prevalso sulla nostra richiesta 9:16 (vedi la nota sulle proporzioni sopra). L'immagine statica sorgente è qui sotto.

Lo schema di prompt per mantenere reale il video di prodotto:

• Un solo verbo di camera ("orbit", "push in", "move"). Due movimenti in un prompt ti danno un'immagine da mal di mare.
• Scrivi esplicitamente "prodotto invariato / perfettamente nitido". I modelli image-to-video deriva; dire al modello che il soggetto non deve essere modificato riduce sensibilmente la deformazione di loghi, cuciture e ferramenta.
• Indica il momento materico ("glinting off the brass zippers") — la luce che si muove sul metallo e sulla pelle è ciò che fa sembrare l'immagine statica una ripresa invece di una distorsione.
• Fissa lo sfondo ("stays clean and shadowless"). Altrimenti il modello si inventa una scenografia.

Più immagini di riferimento: bloccare il soggetto

image_urls accetta più di un'immagine di riferimento, ed è proprio questo che distingue grok-imagine nel lavoro sui prodotti rispetto agli animatori a singolo fotogramma. Dagli l'immagine lifestyle che vuoi come scena, più l'immagine pulita del prodotto come assicurazione sull'identità, e il modello armonizza le due — la scena viene dalla prima immagine, mentre i dettagli esatti del prodotto, le cinghie e le zip sono ancorati dalla seconda:

The same burnt-orange weekender bag rests on a weathered wooden bench in a
sunlit loft; a gentle push-in as dust motes drift through warm window light,
soft shadows slide slowly across the bench, the bag and its dark leather trim
stay exactly consistent with the reference images, calm lifestyle-catalog mood.

Output reale — grok-imagine/image-to-video, 6 s @ 720p, 9:16, due immagini di riferimento (immagine lifestyle sulla panchina + immagine del prodotto su sfondo bianco). Prima generazione, non montato.

Nota la frase "stay exactly consistent with the reference images" nel prompt — quando usi più immagini di riferimento, dirglielo esplicitamente aiuta il modello a trattare le immagini extra come vincoli di identità, non come una seconda scena da fondere. È il pattern per i post giornalieri degli account di marca: scatta (o genera) un'immagine di prodotto per ogni SKU, poi riusala come ancora di coerenza in ogni video breve lifestyle che vuoi animare.

Economicità di durata e livello bozza

La durata va da 6 a 30 secondi, e la risoluzione è dove sta la leva di budget: il prezzo al secondo del 480p è circa la metà del 720p. Dato che i feed comprimono comunque in modo aggressivo, la pipeline sensata è abbozzare in 480p, rifinire i vincitori in 720p. Una durata maggiore dà anche al modello spazio per un lento sviluppo — qui sotto un video breve da 12 secondi del livello bozza 480p, con un movimento d'atmosfera continuo su un'immagine statica di una lattina di tè:

Moody slow dolly-in on the matte-black tea tin standing on slate, steam curls
up lazily behind it, a soft beam of morning light sweeps across the embossed
label, tiny tea leaves tumble gently onto the slate in the final seconds, dark
premium atmosphere, label text unchanged and legible.

Output reale — grok-imagine/image-to-video, 12 s @ 480p, singola immagine di riferimento. Prima generazione, non montato (consegnato quadrato, in linea con l'immagine statica sorgente quadrata). Costo: $0.137.

Il costo di rendering in 480p è $0.0114/secondo — un intero video breve da 12 secondi è costato solo 13,7 centesimi. Abbastanza economico da provare tre varianti di prompt su ogni prodotto e pagare la tariffa 720p solo per quella che pubblichi davvero. Nota "label text unchanged and legible" nel prompt: il testo delle confezioni è la prima cosa che si sfoca nell'image-to-video, e indicarlo è la tua misura di protezione più economica.

Processare il catalogo in batch

Tutto quanto sopra scala linearmente, perché i task sono asincroni: invia prima l'intero batch, poi esegui il polling. Un batch runner minimo per un elenco di prodotti:

products = [
    {"sku": "weekender-orange", "refs": ["https://cdn.example.com/weekender.jpg"],
     "prompt": "Slow cinematic orbit around the bag, studio light on the brass zippers, background clean, product unchanged."},
    {"sku": "tea-tin-black", "refs": ["https://cdn.example.com/tea-tin.jpg"],
     "prompt": "Moody slow dolly-in, steam drifting, light sweeping the embossed label, label text unchanged."},
    # ... resto del catalogo
]

jobs = []
for p in products:
    tid = submit({
        "prompt": p["prompt"],
        "image_urls": p["refs"],
        "duration": 6,
        "resolution": "480p",     # livello bozza
        "aspect_ratio": "9:16",
    })
    jobs.append((p["sku"], tid))

for sku, tid in jobs:
    task = wait(tid)
    url = task["output"][0]["url"]
    subprocess.run(["curl", "-s", "-o", f"{sku}.mp4", url], timeout=180)
    print(f"{sku}: done")

Consigli pratici per il batch quando esegui questa pipeline:

• Prima invia, poi esegui il polling. Ogni rendering richiede alcuni minuti e viene eseguito in parallelo lato server; serializzare "invio-attesa-invio" spreca questo parallelismo.
• Mantieni un template di prompt piatto per ogni tipo di contenuto (orbit per le immagini di prodotto, push-in per le immagini lifestyle), poi inserisci il nome del prodotto. La coerenza dell'intero feed conta più dell'ingegnosità del singolo video breve.
• Verifica del budget: un catalogo di 50 SKU abbozzato in 6 s/480p costa 50 × $0.068 ≈ $3.42. Promuovere i dieci migliori in 720p aggiunge dieci × $0.128 ≈ $1.28. Un intero mese di video brevi di prodotto giornalieri costa meno di un'ora di tempo in studio.

Note per la pubblicazione di video brevi

• Il verticale richiede un'immagine di riferimento verticale. Come detto sopra, le proporzioni dell'immagine di riferimento tendono a prevalere su aspect_ratio — se il video breve è destinato a un feed, ritaglia l'immagine statica in 9:16 prima di inviarla. Ritagliare in verticale un rendering quadrato finito fa perdere gran parte dei pixel.
• Il primo secondo è l'aggancio — i prompt che fanno partire subito il movimento ("camera orbiting", "push-in") hanno tassi di completamento migliori rispetto alle dissolvenze lente in apertura.
• I video brevi includono una traccia audio d'atmosfera generata dal modello. Ogni output che abbiamo generato porta uno stream AAC — alcuni video hanno una sottile atmosfera da studio, altri sono quasi silenziosi. Non c'è un campo di input per controllarla, quindi al momento della pubblicazione pianifica di sostituirla con la tua musica o voce fuori campo, invece di trattarla come una colonna sonora finita.
• Compatibilità con il loop: le orbite e le luci che scorrono funzionano molto meglio in loop rispetto ai video brevi che terminano con una rivelazione. Per i feed che vanno in loop automatico (Shorts, Reels), il pattern orbit qui sopra si riproduce senza soluzione di continuità.

Domande frequenti

Quanto tempo richiede il rendering? I video brevi da 6 secondi di questo articolo hanno richiesto alcuni minuti ciascuno; quello da 12 secondi un po' di più. Trattalo come una coda asincrona, non come una chiamata interattiva — invia in batch ed esegui il polling.

Posso usare immagini generate come immagini di riferimento? Sì. Gli URL di riferimento devono solo essere recuperabili pubblicamente. Le tre immagini statiche sorgente di questo articolo sono esse stesse immagini di prodotto generate dall'API (da esecuzioni di seedream-5.0-lite), prese dal nostro archivio — una pipeline completamente sintetica da immagine statica a video.

E il 1080p o oltre 30 secondi? Questo endpoint è limitato a 720p e 30 secondi. Per i feed di video brevi, questa è esattamente la fascia ottimale; se ti serve una risoluzione più alta, ingrandisci in post-produzione, oppure consulta il catalogo dei modelli per le opzioni attuali.

In cosa è diverso da grok-imagine-1.5/image-to-video? L'endpoint di anteprima 1.5 scambia l'intervallo con la qualità del movimento: durata 1–15 secondi, movimento migliorato, stesso prezzo al secondo. Questo endpoint 1.0 ti offre 6–30 secondi. Abbiamo illustrato le basi di 1.5 in una guida dettagliata separata.

Esiste una versione text-to-video? Sì — grok-imagine/text-to-video, stessa interfaccia di task, input solo prompt. Quando la coerenza di brand/prodotto è importante, image-to-video è la scelta giusta; quando devi generare materiale da zero, usa text-to-video.

---

Se hai immagini statiche di prodotto e una chiave API, ti separa solo un POST /v1/tasks dal primo video breve per il feed: ottieni la chiave dalla dashboard, inizia dalla pagina del modello grok-imagine/image-to-video, anima un'immagine di prodotto con il prompt orbit qui sopra — a 13 centesimi per bozza, il modo più veloce per imparare questo modello è eseguirlo.