Come usare l'API text-to-video grok-imagine-1.5-lite (curl + Python)

Se vuoi generare un breve video con audio partendo da una sola frase, grok-imagine-1.5-lite/text-to-video è l'opzione più economica su hiapi in grado di arrivare a 1080P. Riceve un prompt e restituisce un MP4 da 1–15 secondi con l'audio già mixato, e gira sulla stessa API di task unificata di tutti gli altri modelli della piattaforma. Questa pagina fornisce richieste pronte da copiare e incollare, lo schema esatto (verificato contro l'endpoint live, non copiato dalla specifica), l'aspetto delle risposte reali e gli ostacoli che ho incontrato durante i test.

Quanto segue è stato verificato contro l'API live il 2026-10-21. I prezzi sono quelli che ho misurato; se cambiano, fa fede la pagina dei prezzi.

1. Cosa costruirai e cosa ti serve

Obiettivo: inviare un prompt testuale e ricevere una clip MP4 scaricabile con audio.

Ti serve solo una cosa: una API key di hiapi. Creane una nella console e conservala lato server — ha la forma sk-... e va inserita nell'header Authorization: Bearer. Non esiste un percorso senza key; ogni richiesta qui sotto deve essere autenticata.

Il modello è asincrono. Non ottieni il video direttamente nella risposta alla POST. Prima crei un task, ottieni un taskId, poi esegui il polling (o usi un callback) finché il task non è completato e restituisce l'URL di output.

2. Esempio minimo funzionante

Due passaggi: crea il task, poi esegui il polling del risultato.

Creare il task (curl)

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-1.5-lite/text-to-video",
    "input": {
      "prompt": "All'alba, una volpe rossa attraversa la neve fresca, il respiro si trasforma in vapore bianco, morbida luce del mattino, leggero vento ambientale. Cinematografico, colori naturali. Nessun testo.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Nota la struttura: model è al livello superiore, tutto il resto è annidato sotto input. Se invii i campi in modo piatto (senza il wrapper input), l'API rifiuta l'intero body con invalid input: must be a JSON object — è l'errore più comune.

Una creazione riuscita restituisce subito un id del task:

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

Polling del risultato (Python)

import time, requests

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

def generate(prompt, duration=5, resolution="720p", aspect_ratio="16:9"):
    r = requests.post(BASE, headers=HEAD, json={
        "model": "grok-imagine-1.5-lite/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # integer, 1–15
            "resolution": resolution,      # "480p" | "720p" | "1080p"
            "aspect_ratio": aspect_ratio,  # see schema below
        },
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    # Poll the SAVED task_id. A single transient network error is not a failure —
    # keep polling the same id rather than re-creating (re-creating bills again).
    deadline = time.time() + 300
    while time.time() < deadline:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEAD, timeout=30).json()
        except requests.RequestException:
            time.sleep(5); continue
        task = d.get("data") or {}
        status = task.get("status")
        if status == "success":
            return task["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

print(generate("All'alba, una volpe rossa attraversa la neve fresca, leggero vento ambientale. Cinematografico."))

Schema (verificato dal vivo)

I campi vanno dentro input. Lo schema è chiuso — qualsiasi key che non riconosce restituisce 400, quindi non inviare seed, negative_prompt o motion_mode (qui non esistono; tutte le inquadrature e le direzioni di movimento si esprimono tramite la formulazione del prompt).

Campo	Tipo	Obbligatorio	Valori accettati
prompt	string	Sì	testo libero
duration	integer	Sì	1–15 (secondi interi; 5.5 viene rifiutato)
resolution	string	—	480p, 720p, 1080p
aspect_ratio	string	—	16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16

Questo modello non ha l'aspect ratio auto (il suo omologo image-to-video ne ha uno; questo endpoint text-to-video no). Specifica esplicitamente il rapporto, altrimenti ottieni quello predefinito del modello.

Ecco una risposta reale di un task completato:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E3QKSB2TAJRDHR5Y8EQNEB",
    "model": "grok-imagine-1.5-lite/text-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      { "type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1793153637 }
    ]
  },
  "message": "success"
}

Ecco una clip generata da questo modello (output di riferimento fornito da hiapi per grok-imagine-1.5-lite/text-to-video, generata dal prompt di esempio della sua documentazione — "All'alba, una mongolfiera di vetro fluttua sopra i terrazzamenti"):

3. Passare in produzione

Usa i callback invece del polling. Il polling va bene per gli script; per un server aggiungi callback in modo da non dover tenere aperta la richiesta. Quando il task raggiunge lo stato finale, la piattaforma invia i dettagli del task via POST al tuo URL:

{
  "model": "grok-imagine-1.5-lite/text-to-video",
  "input": { "prompt": "...", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9" },
  "callback": { "url": "https://your.app/hooks/hiapi", "when": "final" }
}

Per questo tipo di task, when accetta solo "final". Deduplica per taskId nel tuo handler — i callback possono essere ritentati, quindi tratta l'handler come idempotente.

Gli URL di output scadono. Nota storage: "temp" e il timestamp unix expireAt — gli output temporanei risiedono su temp.hiapi.ai per circa 7 giorni, poi restituiscono 404. Non salvare hotlink. Scarica i byte nel momento in cui il task ha successo, oppure chiama l'endpoint di promozione dello storage per spostare l'artefatto in storage permanente prima della scadenza del TTL.

Il costo è per secondi di output. La fatturazione dipende solo da duration e dalla risoluzione richiesta. Nei test: 480P $0.029/s, 720P $0.043/s, 1080P $0.20/s. Quindi una clip da 5 secondi a 720P costa circa $0.215, una clip da 5 secondi a 1080P circa $1.00, una clip da 1 secondo a 480P circa $0.029. La tariffa 1080P è circa 5 volte quella 720P — usala solo se hai davvero bisogno di quella risoluzione. Per i numeri più aggiornati vedi la pagina dei prezzi.

Gestione degli errori. Le richieste rifiutate restituiscono HTTP 400 con un messaggio preciso che puoi registrare e usare per agire. La validazione avviene prima della creazione di qualsiasi task, quindi un 400 qui non comporta costi. Risposte reali che ho effettivamente provocato:

invalid input: duration: maximum: got 999, want 15
invalid input: duration: minimum: got 0, want 1
invalid input: duration: got number, want integer
invalid input: resolution: value must be one of '480p', '720p', '1080p'
invalid input: aspect_ratio: value must be one of '16:9', '4:3', '3:2', '1:1', '2:3', '3:4', '9:16'
invalid input: prompt: missing required field "prompt"
invalid input: <root>: additional properties 'bogus_field' not allowed

Un task accettato ma poi fallito si presenta come data.status: "fail" con un oggetto data.error nell'endpoint di dettaglio — non come errore HTTP — quindi controlla status, non affidarti al codice di stato HTTP del polling.

4. Cosa ho effettivamente osservato

Ho eseguito una generazione reale per confermare il flusso end-to-end (non solo lo schema): duration: 1, resolution: "480p", aspect_ratio: "16:9".

• Funziona davvero e viene fatturato — la POST ha restituito un taskId e il task si è completato con un URL di output reale. Il rendering lato server di una clip da 1 secondo ha impiegato circa 51 secondi; anche le clip piccole non sono istantanee, quindi imposta una scadenza di polling generosa (io ho usato 300 secondi).
• I task passano attraverso stati intermedi. Il campo status attraversa in sequenza handling → archiving → success. Solo success e fail sono stati finali; non considerare archiving come completato.
• 480P in 16:9 viene renderizzato a 848×480 H.264. Eseguendo ffprobe sul file scaricato: un flusso video H.264 (848×480) più un flusso thumbnail MJPEG incorporato. Il file da 495 KB è un MP4 valido.
• L'audio è sempre integrato. Anche se il mio prompt menzionava solo "leggero vento ambientale", l'output conteneva comunque una traccia AAC — il modello sintetizza un audio coerente e lo mixa nello stesso MP4. Non c'è un URL audio separato né un interruttore per disabilitarlo; se ti serve una clip muta, rimuovi la traccia tu stesso (ffmpeg -an).

Nota sull'ambito: ho verificato il contratto dell'API, i tre tipi di errore sopra e un rendering a 480P. Non ho fatto benchmark sulla qualità degli output 720P/1080P né sulle durate lunghe (15 secondi), quindi non esprimo giudizi di qualità su questi — dico solo che lo schema li accetta e che la fatturazione è al secondo.

5. Confronto tra Lite e l'API video Grok Imagine standard

Scegli l'endpoint giusto prima di costruire:

• grok-imagine-1.5-lite/text-to-video (questa pagina): 480P/720P/1080P, 1–15 secondi (quindi puoi generare clip da 1 o 2 secondi), prezzo $0.029–$0.20/s. È l'unico endpoint text-to-video di generazione 1.5 ospitato su hiapi, nonché l'unica fascia Grok t2v in grado di raggiungere 1080P.
• grok-imagine/text-to-video (la vecchia fascia standard, vedi questa guida): più economico al secondo ($0.0114–$0.0214/s) e offre Motion Modes, ma arriva solo fino a 720p e richiede durate di 6–30 secondi — non può generare clip inferiori a 6 secondi.

Quindi qui "lite" non è l'opzione più economica al secondo; è la fascia che sblocca 1080P e clip molto brevi. Se vuoi partire da una singola immagine statica invece che da testo, usa l'endpoint grok-imagine-1.5-lite/image-to-video della stessa fascia (stesso prezzo, input image_urls).

6. Link correlati

• Pagina del modello grok-imagine-1.5-lite text-to-video / playground
• Creare un task — riferimento API
• Ottenere i dettagli del task — riferimento API
• Prezzi

Domande frequenti

Devo fare polling o c'è un callback? Vanno bene entrambi. Gli script usano il polling con GET /v1/tasks/{taskId}; i server allegano callback.url e impostano when a "final". Deduplica per taskId.

Perché la mia richiesta restituisce 400 con "must be a JSON object"? I tuoi campi non sono racchiusi in input. Il body deve essere {"model": "...", "input": { ... }}.

Posso disattivare l'audio? Non al momento della richiesta — ogni output include una traccia AAC mixata. Se ti serve il muto, rimuovila a valle con ffmpeg -an.

Quanto dura l'URL di output? È un URL temporaneo con expireAt (circa 7 giorni). Scaricalo subito o promuovilo in storage permanente; non usarlo come hotlink.

Qual è la richiesta valida più economica? 1 secondo a 480P costa circa $0.029. Prima di elaborare in batch, usarla come richiesta canarino per verificare che la tua key abbia credito è una buona idea.