Come si usa l'API text-to-video di LTX 2.5 Fast? Il primo video in 5 minuti

TL;DR

• LTX 2.5 Fast Text to Video (ltx-2.5-fast/text-to-video) trasforma un testo in un video di 2–20 secondi, con 720p / 1080p, orientamento orizzontale o verticale e audio nativo generati insieme. Apri la pagina del modello per provarlo: i nuovi utenti ricevono 200 crediti alla registrazione.
• Il prezzo è al secondo: 720p $0.043 al secondo ($0.258 per 6 secondi), 1080p $0.086 al secondo; l'interruttore generate_audio non influisce sul prezzo.
• La chiamata passa dall'interfaccia /v1/tasks di HiAPI: invia il task e ottieni un taskId, poi interroga il risultato e, in caso di successo, preleva l'URL del video da output (indirizzo temporaneo, salvalo subito).

Cosa può fare

• Una frase per una scena con audio: scena, movimento, inquadratura e suono scritti nello stesso prompt; l'audio viene generato insieme alle immagini.
• 2–20 secondi, 12 durate disponibili: duration accetta 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 18, 20, predefinito 6 secondi.
• Orizzontale/verticale e due risoluzioni: 16:9 / 9:16, 720p / 1080p; frame rate fisso a 25fps in MP4.
• Nella stessa famiglia c'è anche image-to-video: ltx-2.5-fast/image-to-video carica un primo frame (con eventuale frame finale) per animare un'immagine statica, con le stesse regole di prezzo; vedi la pagina del modello image-to-video.

Come scegliere tra le due interfacce:

	ltx-2.5-fast/text-to-video (questa pagina)	ltx-2.5-fast/image-to-video
Input	Un testo	1–2 immagini + una frase che descrive il movimento
Adatto a	Esplorare inquadrature da zero, creatività pubblicitaria, storyboard	Avere già una foto/immagine di prodotto e volerla animare
Punti controllabili	Prompt, risoluzione, durata, formato	Primo frame (+ frame finale), prompt, risoluzione, durata

In breve: se il contenuto visivo non è ancora definito usa text-to-video, se l'immagine c'è già usa image-to-video; le due interfacce si possono concatenare — text-to-video genera il primo frame definitivo, poi lo si passa a image-to-video per aggiungere il movimento di camera.

Qui sotto un video reale (720p · 6 secondi, con audio nativo):

A barista pours steamed milk into a latte, creating a leaf pattern, close-up, soft morning light through a café window, gentle clinking cups and café ambience

(Significato: un barista versa il latte montato in un latte, creando una foglia, primo piano, luce morbida del mattino attraverso la finestra del caffè, tintinnio leggero di tazze e atmosfera del caffè. Parametri predefiniti: 720p, 6 secondi, 16:9, audio attivo.)

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

Genera con questo prompt →

Due percorsi per iniziare

Browser in 3 passi: apri la pagina del modello → incolla il prompt, scegli durata e risoluzione → clicca su genera; 720p 6 secondi costa $0.258 e il video è subito disponibile in anteprima online.

API in 3 passi: POST /v1/tasks per inviare → ottieni il taskId → GET /v1/tasks/<taskId> finché lo stato non è success, poi scarica.

curl: il primo video

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/text-to-video",
  "input": {
    "prompt": "A barista pours steamed milk into a latte, creating a leaf pattern, close-up, soft morning light through a café window, gentle clinking cups and café ambience",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

Questo video 720p × 6 secondi costa $0.258.

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/text-to-video",
    "input": {
        "prompt": "A barista pours steamed milk into a latte, creating a leaf pattern, close-up, soft morning light through a café window, gentle clinking cups and café ambience",
        "resolution": "720p",
        "duration": 6,
        "aspect_ratio": "16:9",
        "generate_audio": True,
    },
}

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")
    video_url = video["url"]   # indirizzo temporaneo, scarica e salva al più presto
    mp4 = requests.get(video_url, timeout=120)
    with open("output.mp4", "wb") as f:
        f.write(mp4.content)
    print("saved output.mp4")

Tabella dei parametri

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	1–5000 caratteri	Scrivi tutto in una frase: scena, movimento, inquadratura, suono
resolution	No	720p / 1080p, predefinito 720p	Il prezzo al secondo di 1080p è circa il doppio di 720p
duration	No	2/3/4/5/6/8/10/12/14/16/18/20, predefinito 6	Solo questi valori enumerati (non 7, 9)
aspect_ratio	No	16:9 / 9:16, predefinito 16:9	Per i video brevi verticali scegli 9:16
generate_audio	No	predefinito true	Audio nativo; disattivarlo non riduce il prezzo

La presenza nel corpo della richiesta di campi non previsti dalla tabella restituisce direttamente un 400.

Errori che incontrerai

Codice di stato	Significato	Come procedere
400 INVALID_REQUEST	Corpo della richiesta non valido (manca prompt, duration con valore non enumerato come 7, campi non previsti)	Correggi il corpo della richiesta confrontandolo con 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 una nuova Idempotency-Key

In caso di fallimento allo stato terminale ci sono anche CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT, ecc.; in caso di fallimento non viene addebitato nulla.

Da sapere prima della messa in produzione

• Callback: passa al livello superiore del corpo della richiesta "callback": {"url": "https://..."}; lo stato terminale viene notificato automaticamente. I task video richiedono tempo, quindi è consigliato.
• Salva subito: l'URL del video in output è temporaneo; scaricalo appena lo ricevi.
• Indica esplicitamente duration e resolution: questi due campi determinano la fatturazione, non affidarti ai valori predefiniti; prima della messa in produzione registrali nei log, così la riconciliazione è immediata.
• Ritmo per i batch: un video di 6 secondi richiede un po' di tempo dall'invio alla produzione; per i task in batch conviene accodare gli invii e ricevere i risultati tramite callback, senza attendere in modo sincrono.
• Per animare un'immagine statica: usa la pagina del modello image-to-video della stessa famiglia; caricare il primo frame offre maggiore controllo.

Domande frequenti

• Sì, l'audio viene generato insieme al video: generate_audio è attivo per impostazione predefinita; descrivendo il suono nel prompt (vento, tintinnio di tazze), l'audio sarà più aderente alle immagini.
• Sì, le durate sono solo 12: valori enumerati tra 2 e 20 secondi; 7 secondi, 9 secondi e simili restituiscono un 400.
• Sì, il prezzo = prezzo al secondo × numero di secondi: 720p 6 secondi $0.258, 1080p 6 secondi $0.516; disattivare l'audio non fa risparmiare.
• Sì, con $10 si producono circa 38 video: calcolando 720p 6 secondi ciascuno.
• Sì, per il verticale si sceglie 9:16: l'output è 720×1280 (720p) o 1080×1920 (1080p), pronto per le piattaforme di video brevi senza ritagli.
• Sì, si consiglia prima bassa e poi alta risoluzione: usa 720p per mettere a punto prompt e composizione, poi passa a 1080p e rigenera lo stesso prompt; il prezzo al secondo raddoppia ma il prodotto finito è uno solo.
• Sì, disattivare l'audio non fa risparmiare: se vuoi doppiaggio e musica in post-produzione passa generate_audio: false per ottenere immagini pulite.

Passo successivo: prendi il prompt del latte art e genera il primo video nella pagina del modello; per quattro modelli di scenario vedi la raccolta completa di prompt per text-to-video.