Generare video brevi in batch con hailuo-2.3-fast/image-to-video su hiapi

Il successo dei video brevi dipende dalla velocità di iterazione. Se il tuo flusso di lavoro è una pipeline orientata a TikTok o Reels, non hai bisogno di output cinematografici in 4K: ti serve un modello che trasformi un'immagine statica di prodotto in una clip utilizzabile in meno di un minuto, a un costo abbastanza basso da permetterti di generare decine di varianti prima di scegliere la migliore. È esattamente questo il posizionamento di hailuo-2.3-fast/image-to-video: il fratello di fascia Fast di hailuo-2.3, con prezzi e ottimizzazioni pensati specificamente per flussi di lavoro ad alto volume basati su tentativi multipli e sacrificabili.

Questa guida ti mostra come usarlo come motore per video brevi in batch: come scegliere l'immagine statica di partenza, come pilotarlo tramite l'API asincrona basata su task, come validare i dettagli dello schema che, se trascurati, ti fanno incassare errori 400, e come ragionare sull'economia di esercizio su scala TikTok/Reels.

Cosa ti offre il modello

hailuo-2.3-fast/image-to-video riceve un'immagine statica e un prompt e la anima in una breve clip video. Si trova nella pagina del modello hailuo-2.3-fast/image-to-video e, come tutti i modelli su hiapi, viene invocato tramite l'endpoint asincrono unificato /v1/tasks: invii un task con POST, esegui il polling (o registri un callback) fino al completamento, poi scarichi il video da un URL di output valido per un periodo limitato.

Verificato rispetto all'API live al momento della scrittura:

• Input: un'immagine (image_url) + un prompt testuale che descrive il movimento desiderato
• Output: MP4, durata fissa di 6s o 10s (nessuna durata arbitraria)
• Prezzo: tariffa fissa per video, non a secondi — $0.27 per una clip da 6 secondi, $0.46 per una da 10 secondi
• Tempo di turnaround: le nostre clip di test completate end-to-end (invio → successo) in circa 80 secondi

La tariffa fissa per video è proprio il dettaglio chiave per i lavori in batch: un tentativo da 6 secondi costa lo stesso sia che il tuo prompt centri il movimento al primo colpo sia che tu sia già al quarto tentativo. Con i prezzi della fascia Fast, generare 5-6 varianti dalla stessa immagine chiave per trovare quella con il movimento più fluido costa comunque meno di un singolo tentativo con la maggior parte dei modelli video di fascia alta. Prima di pianificare il budget per il batch, controlla i numeri attuali sulla pagina dei prezzi: i prezzi cambiano.

Se ti serve il riferimento completo dei parametri, opzioni di durata più lunghe o un confronto affiancato con il livello hailuo-2.3 non Fast, consulta il nostro tutorial di integrazione API di hailuo-2.3-fast/image-to-video: questa guida si concentra sull'ottica batch/flusso di lavoro, non sul riferimento API grezzo.

Flusso di lavoro: immagine statica → clip breve

Il gioco dei video brevi è semplice: parti da un'immagine statica che hai già (fotografia di prodotto, hero shot generato, materiale di brand) e lascia che il modello aggiunga movimento — lento push-in, leggera rotazione, atmosfera fluttuante — invece di generare il video da zero. Così blocchi la tua identità visiva (stesso prodotto, stessa illuminazione, stessa composizione) producendo al contempo contenuti che non sono semplici post statici.

Ecco un caso reale: un'immagine statica verticale (9:16) di una sneaker su un piedistallo illuminato, animata con un prompt di movimento che descrive un lento push-in e una rotazione delicata.

L'immagine statica di partenza e la richiesta completa:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3-fast/image-to-video",
    "input": {
      "prompt": "Lento e fluido push-in su una sneaker da basket retrò massiccia in camoscio grigio lupo con lacci giallo volt, sospesa sopra un piedistallo di cemento bagnato, rotazione sottile che rivela il pannello laterale, nebbia che si diffonde attraverso una luce di contorno dal verde acqua all'ambra, particelle di polvere che catturano la luce, movimento di camera cinematografico stabile, finitura da video commerciale di prodotto premium",
      "image_url": "https://static.hiapi.ai/gallery/2026/07/c2e71481d2eb81a7.jpg",
      "duration": "6",
      "prompt_optimizer": true
    }
  }'

Risposta:

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

Esegui polling finché la risoluzione non è completata:

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

{
  "status": "success",
  "output": [{"type": "video", "url": "https://temp.hiapi.ai/.../result.mp4", "expireAt": 1786421652}]
}

Quel output[0].url è temporaneo: scaricalo subito e trasferiscilo nel tuo storage. Non fare hotlink e non salvarlo in un campo del database aspettandoti che sia un URL stabile.

Schema di input (verificato rispetto all'API live)

Lo schema di questo modello è molto più ristretto di quanto potresti aspettarti dagli altri modelli video della piattaforma: nessun controllo dell'aspect ratio, nessun livello di risoluzione, nessun seed.

Campo	Tipo	Vincolo	Obbligatorio
prompt	string	Descrive movimento/scena	Sì
image_url	string	Singolare — un URL pubblico, non un array	Sì
duration	string	Enum "6" o "10" — come stringa, non come numero	Sì
prompt_optimizer	boolean	Consente alla piattaforma di riscrivere/migliorare il tuo prompt	No

Se porti con te le assunzioni di altri modelli, ci sono due trappole che ti fanno incassare un 400:

1. image_url è singolare, non image_urls. Diversi altri modelli i2v su hiapi ricevono un array di immagini di riferimento; questo modello ne riceve una sola. Se invii un array ottieni un errore di campo mancante, non una conversione di tipo utile.
2. duration deve essere la stringa "6" o "10", non il numero 6. Inviare il numero 6 restituisce duration: got number, want string. E qualsiasi valore al di fuori di questo enum a due valori non viene accettato: questo livello non ha controllo di durata arbitraria.

Inviare aspect_ratio, resolution, seed o watermark — campi comuni nei modelli fratelli — viene rifiutato direttamente con additional properties ... not allowed. Il modello eredita l'aspect ratio dall'immagine di input, quindi se ti serve un output 9:16 per Reels/TikTok, ritaglia o genera l'immagine statica di partenza in 9:16 prima dell'invio (è esattamente quello che abbiamo fatto con l'immagine della sneaker qui sopra).

Python end-to-end

import requests
import time

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "your-api-key"

def make_short_clip(prompt: str, image_url: str, out_path: str, duration: str = "6"):
    resp = requests.post(
        API_BASE,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "model": "hailuo-2.3-fast/image-to-video",
            "input": {
                "prompt": prompt,
                "image_url": image_url,
                "duration": duration,  # must be a string: "6" or "10"
                "prompt_optimizer": True,
            },
        },
        timeout=60,
    )
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    while True:
        task = requests.get(f"{API_BASE}/{task_id}",
                             headers={"Authorization": f"Bearer {API_KEY}"},
                             timeout=30).json()["data"]
        if task["status"] == "success":
            break
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(8)

    video_url = task["output"][0]["url"]  # temporary link — download immediately
    video_bytes = requests.get(video_url, timeout=120).content
    with open(out_path, "wb") as f:
        f.write(video_bytes)
    return out_path

Per un vero esecuzione in batch — ad esempio testare 6 varianti di prompt sulla stessa immagine statica di partenza per scegliere il movimento più fluido — avvolgi questa funzione in un ciclo sulla lista di prompt e controlla ogni task_id in modo indipendente, invece di bloccarti in sequenza; calcolando circa 80 secondi per clip, è l'esecuzione in parallelo di più clip che fa percepire davvero veloce la fascia Fast.

Domande frequenti

Posso controllare l'aspect ratio dell'output? No — questo modello non ha il campo aspect_ratio, inviarlo restituisce un 400. L'output segue l'aspect ratio dell'immagine di input, quindi prepara l'immagine statica di partenza nel formato desiderato prima dell'invio (9:16 per Reels/TikTok, 1:1 per i post nel feed).

Perché la mia richiesta fallisce con "got number, want string"? Hai inviato duration come numero JSON. Deve essere la stringa "6" o "10": sono gli unici due valori validi.

È lo stesso modello di hailuo-2.3/image-to-video (non Fast)? No — la fascia Fast è un modello separato su hiapi, con prezzo separato e schema proprio, ottimizzato per velocità e costo anziché per il livello standard. Se ti serve una guida di riferimento non orientata al batch, consulta il tutorial di integrazione completo.

Posso dargli in input un'immagine generata invece di una foto reale? Sì — l'immagine statica di partenza può provenire da qualsiasi modello di immagine su hiapi (o altrove), purché sia un URL accessibile pubblicamente. Usare immagini statiche che hai già prodotto per altri formati (visual di prodotto, poster) è di solito il modo più rapido per ottenere video brevi, senza un flusso creativo separato.

Il prezzo varia con la risoluzione? Questo modello non ha parametri di risoluzione, quindi il prezzo è fisso per durata indipendentemente dalla risoluzione dell'immagine di input: al momento della scrittura $0.27 per 6s e $0.46 per 10s. Verifica sulla pagina dei prezzi.

Punti principali

• hailuo-2.3-fast/image-to-video trasforma un'immagine statica in un MP4 da 6s o 10s, con tariffa fissa per video ($0.27 / $0.46) anziché a secondi: abbastanza economico da poter generare più varianti di prompt per ogni immagine di partenza.
• Lo schema è volutamente ristretto: prompt, image_url (singolare), duration (enum stringa "6"/"10") e l'opzionale prompt_optimizer — nessun controllo di aspect ratio, risoluzione o seed.
• L'output eredita l'aspect ratio dell'immagine di input, quindi prepara l'immagine statica di partenza in 9:16 (o nel formato richiesto dalla tua piattaforma) prima dell'invio.
• I due errori di integrazione più comuni sono inviare image_url come array e inviare duration come numero invece che come stringa.
• Per i flussi di lavoro di video brevi in batch, la tariffa fissa per video e un tempo di turnaround di circa 80 secondi rendono praticabile generare più tentativi e scegliere il movimento migliore, invece di inviare una sola generazione per ogni asset.

Pronto a provarlo sulle tue immagini di prodotto? Vai alla pagina del modello hailuo-2.3-fast/image-to-video per testare direttamente una richiesta, oppure, se vuoi prima confrontare la fascia Fast con altre opzioni di image-to-video, consulta il catalogo completo dei modelli.