Come si usa l'API LTX 2.5 Fast da immagine a video? Fai muovere le immagini statiche

TL;DR

• LTX 2.5 Fast Image to Video (ltx-2.5-fast/image-to-video) fa muovere le immagini statiche: carica 1 immagine di primo frame (puoi aggiungerne 1 di ultimo frame), genera un video da 2–20 secondi in 720p / 1080p con audio nativo. Apri la pagina del modello, carica un'immagine e provalo: i nuovi utenti ricevono 200 crediti alla registrazione.
• Il prezzo segue le stesse regole del text-to-video: 720p a $0.043 al secondo, 1080p a $0.086 al secondo, con fatturazione in base ai secondi di duration; l'attivazione dell'audio non influisce sul prezzo.
• La chiamata passa dall'interfaccia HiAPI /v1/tasks: image_urls accetta 1–2 immagini (primo frame / primo frame + ultimo frame); in caso di successo, il video si preleva da output.

Cosa può fare

• Far muovere il primo frame: una foto statica + una descrizione del movimento, il soggetto resta invariato e si aggiungono movimento, inquadratura e suono.
• Primo frame + ultimo frame: carica due immagini, il modello ricostruisce la transizione dal primo all'ultimo frame (ad esempio da una casetta di giorno a una casetta sotto un cielo stellato).
• Formato verticale supportato: il formato di output è determinato da aspect_ratio (16:9 / 9:16); si consiglia di allinearlo al primo frame per evitare ritagli o bande.
• Text-to-video della stessa serie: per la generazione da zero consulta la guida all'integrazione del text-to-video; le regole di prezzo delle due interfacce sono identiche.

Ecco un risultato reale (foto statica di un faro → ripresa sonora di 6 secondi):

Waves crash against the rocks below the lighthouse, seagulls glide across the golden sky, the camera slowly pushes in, sound of surf and gulls

(Significato: le onde si infrangono sugli scogli sotto il faro, i gabbiani sorvolano il cielo dorato, la camera avanza lentamente, suono delle onde e dei gabbiani. Primo frame: la foto del faro del materiale; parametri: 720p, 6 secondi, 16:9.)

→

ltx-2.5-fast/image-to-video, 720p, 6 secondi, 16:9, 1280×720, con audio, $0.258.Guarda il risultato completo →

Genera con questo prompt →

Come passare primo frame / primo frame + ultimo frame

Input	image_urls	Effetto
1 immagine	["immagine del primo frame"]	Parte da questa immagine, il soggetto resta invariato
2 immagini	["immagine del primo frame", "immagine dell'ultimo frame"]	Transizione dal primo all'ultimo frame, il modello completa il passaggio intermedio

Le immagini supportano URL pubblici JPG / PNG / WebP; si consiglia che le due immagini abbiano lo stesso formato e di impostare aspect_ratio uguale a quello del primo frame.

Due percorsi per iniziare

Browser in 3 passi: apri la pagina del modello → carica l'immagine del primo frame, scrivi la descrizione del movimento → clicca su genera e, una volta prodotto, visualizza subito l'anteprima.

API in 3 passi: POST /v1/tasks per inviare → ottieni il taskId → con GET /v1/tasks/<taskId> verifica lo stato success e scarica.

curl: la prima chiamata (solo primo frame)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "ltx-2.5-fast/image-to-video",
  "input": {
    "prompt": "Waves crash against the rocks below the lighthouse, seagulls glide across the golden sky, the camera slowly pushes in, sound of surf and gulls",
    "image_urls": ["https://static.hiapi.ai/gallery/2026/10/0ca26560398eae72.jpg"],
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "16:9"
  }
}'

Primo frame + ultimo frame (casetta di giorno → casetta sotto un cielo stellato): cambia solo image_urls:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ltx-2.5-fast/image-to-video",
  "input": {
    "prompt": "Time passes from bright winter day to starry night, the sky darkens, the cabin windows light up warmly and smoke rises from the chimney, an aurora appears, fixed camera",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/7756ea1a228b0b88.jpg",
      "https://static.hiapi.ai/gallery/2026/10/16e267619aa1b003.jpg"
    ],
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }
}'

Python: invio, polling, download

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "ltx-2.5-fast/image-to-video",
    "input": {
        "prompt": "Waves crash against the rocks below the lighthouse, seagulls glide across the golden sky, the camera slowly pushes in, sound of surf and gulls",
        "image_urls": ["https://example.com/your-first-frame.jpg"],
        "resolution": "720p",
        "duration": 6,
        "aspect_ratio": "16:9",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(5)

if task["status"] == "success":
    video = next(o for o in task["output"] if o.get("type") == "video")
    mp4 = requests.get(video["url"], timeout=120)   # indirizzo temporaneo, salva al più presto
    with open("output.mp4", "wb") as f:
        f.write(mp4.content)
    print("saved output.mp4")

Tabella dei parametri

Campo	Obbligatorio	Valori	Descrizione
image_urls	Sì	1–2 URL pubblici	La 1ª è il primo frame; la 2ª è l'ultimo frame (JPG/PNG/WebP)
prompt	Sì	1–5000 caratteri	Descrive movimento, inquadratura e suono; non ripetere ciò che è già presente nell'immagine
resolution	No	720p / 1080p, predefinito 720p	Il prezzo al secondo in 1080p è circa il doppio del 720p
duration	No	2/3/4/5/6/8/10/12/14/16/18/20, predefinito 6	Valori enumerati
aspect_ratio	No	16:9 / 9:16, predefinito 16:9	Si consiglia di allinearlo al primo frame per evitare ritagli o bande
generate_audio	No	Predefinito true	Audio nativo; disattivalo se vuoi aggiungere la musica in post-produzione

La presenza di campi non elencati nella tabella nel corpo della richiesta restituisce direttamente 400.

Errori che incontrerai

Codice di stato	Significato	Come gestirlo
400 INVALID_REQUEST	Corpo della richiesta non valido (manca image_urls o prompt, sono state inviate 3 immagini, duration non è un valore enumerato)	Correggi il corpo della richiesta secondo la tabella dei parametri
402 INSUFFICIENT_QUOTA	Saldo insufficiente (nessun addebito)	Ricarica e riprova
429 RATE_LIMITED	Limite di frequenza raggiunto	Riduci la frequenza di invio
409 / 422 IDEMPOTENCY_KEY_*	Invio duplicato con la stessa chiave di idempotenza	Usa un nuovo Idempotency-Key

In caso di fallimento dello stato finale del task ci sono anche CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT, ecc.; i fallimenti non comportano addebiti.

Note prima del lancio

• Callback: i task video richiedono tempo; passa al livello superiore del corpo della richiesta "callback": {"url": "https://..."} per evitare il polling.
• Salva subito: l'indirizzo del video in output è temporaneo, scaricalo appena lo ottieni.
• Formato coerente tra primo e ultimo frame: se le proporzioni delle due immagini differiscono troppo, la transizione tende a deformarsi; imposta aspect_ratio uguale a quello del primo frame.
• Per aggiungere la musica in post-produzione: passa generate_audio a false per ottenere un'immagine pulita, il prezzo resta invariato.
• La qualità del primo frame determina la qualità del risultato: un primo frame sfocato o a bassa risoluzione non diventa più nitido quando si muove; parti da un'immagine grande e nitida, poi lascia che il modello aggiunga il movimento.

Domande frequenti

• Sì, massimo 2 immagini: 1 primo frame oppure primo frame + ultimo frame; una terza immagine restituisce 400.
• Sì, il formato non segue l'immagine: è determinato da aspect_ratio, quindi si consiglia di impostarlo manualmente uguale a quello del primo frame.
• Sì, il prezzo è lo stesso del text-to-video: 720p a $0.043 al secondo, 6 secondi costano $0.258.
• Sì, la transizione con ultimo frame è ideale per il «passare del tempo»: da giorno a notte, da una scena vuota a una scena piena di prodotti: due immagini e un prompt bastano.
• Sì, far muovere le immagini di prodotto è il suo punto di forza: usa l'immagine principale del prodotto come primo frame, scrivi nel prompt il movimento di camera (orbit, push in) e gli elementi decorativi, e ottieni subito un video dimostrativo.
• Sì, foto verticali con 9:16: output 720×1280, pronto per le piattaforme di video brevi; per le foto orizzontali mantieni 16:9.

Prossimo passo: prendi un'immagine del tuo prodotto e falla muovere dalla pagina del modello; per i quattro scenari di image-to-video consulta la raccolta completa di prompt.