Guida all'API Hailuo 2.3: testo-video, immagine-video e versione Fast

TL;DR

• Hailuo 2.3 è il modello video di MiniMax. Su HiAPI è disponibile con tre endpoint: hailuo-2.3/text-to-video, hailuo-2.3/image-to-video e il più economico hailuo-2.3-fast/image-to-video.
• La fatturazione è per video, non al secondo: $0.40 per un video da 6 secondi e $0.80 per uno da 10 secondi. Fast image-to-video costa $0.27 e $0.46.
• I parametri di input sono pochi: prompt, duration (stringa "6" o "10"), prompt_optimizer e, per l'image-to-video, anche un image_url. Non esistono parametri per risoluzione, aspect ratio o seed. Apri la pagina del modello text-to-video per provarlo; i nuovi account ricevono 200 crediti gratuiti.

Quale endpoint usare

	Testo-video	Immagine-video	Fast immagine-video
ID modello	hailuo-2.3/text-to-video	hailuo-2.3/image-to-video	hailuo-2.3-fast/image-to-video
Parametri obbligatori	prompt	prompt + image_url	prompt + image_url
Video da 6 secondi	$0.40	$0.40	$0.27
Video da 10 secondi	$0.80	$0.80	$0.46
Input immagine	Nessuno	Un primo fotogramma	Un primo fotogramma

Prezzi HiAPI in tempo reale, verificati il 20 ottobre 2026. Le attività fallite non vengono addebitate.

Quando esplori una scena, inizia dal testo; quando il primo fotogramma deve essere preciso (ad esempio un prodotto o un personaggio già esistente), inizia dall'immagine. Negli scenari image-to-video, Fast costa un terzo in meno e accetta gli stessi input, quindi puoi abbozzare prima con Fast e passare al modello standard quando una determinata inquadratura richiede maggiori dettagli di movimento.

Testo-video: output reale

Questo è l'esempio presente nella pagina del modello, della durata di 6 secondi:

un maestro di kung fu che pratica le forme sotto una pioggia battente, gocce d'acqua che si disperdono al rallentatore, movimento naturale e fluido, movimento di camera cinematografico stabile, illuminazione coerente tra i fotogrammi, composizione cinematografica, illuminazione direzionale drammatica, color grading ricco e coeso, ultra-dettagliato, finitura commerciale premium

Genera con questo prompt →

hailuo-2.3/text-to-video, 6 secondi, 1366×768, senza audio, $0.40.

In sei secondi, il maestro esegue in sequenza diverse posizioni e colpi di braccio, mentre la pioggia continua a cadere dietro di lui. La camera rimane stabile. Nonostante la richiesta non contenga alcun campo per l'aspect ratio, l'output è in orizzontale; text-to-video non consente di specificare il formato verticale.

Immagine-video: output reale

L'image-to-video conserva la tua immagine e la anima. Entrambi gli esempi seguenti usano un primo fotogramma in 16:9; il risultato restituito è 1364×768.

Primo fotogramma:

sbuffi di vapore erompono dalla locomotiva mentre questa inizia lentamente a muoversi, ruote che girano, movimento naturale e fluido, movimento di camera cinematografico stabile, illuminazione coerente tra i fotogrammi, composizione cinematografica, illuminazione direzionale drammatica, color grading ricco e coeso, ultra-dettagliato, finitura commerciale premium

Genera con questo prompt →

hailuo-2.3/image-to-video, 6 secondi, 1364×768, senza audio, $0.40.

La stazione, le carrozze e il tramonto rimangono identici all'immagine. La locomotiva avanza e il vapore si diffonde in basso lungo la banchina.

Lo stesso approccio applicato a Fast, con una scena più tranquilla:

barche che dondolano dolcemente, gabbiani che planano attraverso la nebbia mattutina, movimento naturale e fluido, movimento di camera cinematografico stabile, illuminazione coerente tra i fotogrammi, composizione cinematografica, illuminazione direzionale drammatica, color grading ricco e coeso, ultra-dettagliato, finitura commerciale premium

Genera con questo prompt →

hailuo-2.3-fast/image-to-video, 6 secondi, 1364×768, senza audio, $0.27.

L'ampiezza del movimento è ridotta: le barche oscillano leggermente, la nebbia si sposta lentamente e verso la fine compare un gabbiano. Per inquadrature tranquille e atmosferiche come questa, Fast è sufficiente.

I prompt per l'image-to-video devono descrivere cosa accade dopo. Il modello ha già visto l'immagine, quindi "una locomotiva nera ferma alla stazione" non aggiunge alcuna informazione; "il vapore erompe mentre inizia a muoversi" gli indica invece cosa fare.

curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3/text-to-video",
    "input": {
      "prompt": "Un bicchiere di tè freddo che si rovescia al rallentatore, il tè che si spande su un tavolo di legno, cubetti di ghiaccio che rotolano, ripresa macro",
      "duration": "6",
      "prompt_optimizer": true
    }
  }'

Ottieni un taskId. Esegui il polling su GET https://api.hiapi.ai/v1/tasks/{taskId} finché data.status non diventa success, poi scarica data.output[0].url. I video richiedono minuti, non secondi.

Per l'image-to-video, cambia il modello e aggiungi un'immagine:

{
  "model": "hailuo-2.3-fast/image-to-video",
  "input": {
    "prompt": "Il gatto si stira, salta giù dal davanzale e cammina verso la camera",
    "image_url": "https://your-cdn.example.com/first-frame.jpg",
    "duration": "6"
  }
}

Python: invio, polling, download

# pip install requests; export HIAPI_KEY=your-key first
import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(model, timeout_s=900, **inp):
    r = requests.post(API, json={"model": model, "input": inp}, headers=H, timeout=30).json()
    if r.get("code") != 200:
        raise RuntimeError(r)  # a 400 lists every invalid field at once
    task_id = r["data"]["taskId"]  # save this; if your script dies, poll it again instead of resubmitting
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(10)
    raise TimeoutError(task_id)

url = generate("hailuo-2.3/image-to-video",
               prompt="Il vapore erompe dalla locomotiva mentre inizia lentamente a muoversi, ruote che girano",
               image_url="https://your-cdn.example.com/train.jpg",
               duration="10")  # a string, not 10

with open("hailuo.mp4", "wb") as f:
    f.write(requests.get(url, timeout=120).content)

I link di output scadono circa 7 giorni dopo il completamento dell'attività, quindi salva il file, non solo il link.

Parametri

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	Testo	Descrive il movimento e il movimento di camera
image_url	Solo image-to-video	Un URL pubblico	Una singola stringa, non un array. jpeg, png o webp
duration	No	"6" (predefinito) o "10"	Deve essere una stringa
prompt_optimizer	No	true (predefinito) / false	Espande i prompt brevi prima della generazione

Il movimento e il movimento di camera si specificano nel prompt. Non esistono i campi motion_strength, camera_movement, resolution, aspect_ratio o seed.

Errori che incontrerai

Questi errori vengono restituiti al momento dell'invio con HTTP 400, quindi non creano alcuna attività e non comportano alcun addebito:

• duration: got number, want string: hai passato 6. Passa "6".
• duration: value must be one of '6', '10': sono disponibili solo due durate.
• image_url: missing required field "image_url": l'image-to-video richiede un primo fotogramma. Il nome del campo è al singolare, image_url.
• additional properties 'resolution' not allowed (o aspect_ratio, image_urls, seed): rimuovi quel campo.

Se un'attività termina con fail, leggi data.error. Nei casi di image-to-video, la causa frequente è che il server non riesce a recuperare l'URL dell'immagine, ad esempio un bucket privato o un link firmato scaduto.

Domande frequenti

Quanto costa Hailuo 2.3 al secondo?

Non si paga al secondo. Paghi per video: $0.40 per 6 secondi e $0.80 per 10 secondi con il modello standard; $0.27 e $0.46 con Fast. In proporzione, un video standard da 6 secondi costa circa $0.067 al secondo, mentre Fast circa $0.045 al secondo.

Posso generare video verticali?

Con il text-to-video no: non ha un campo per l'aspect ratio e restituisce video orizzontali. Anche l'image-to-video non ha un campo per l'aspect ratio; la documentazione non chiarisce se un primo fotogramma verticale produca un video verticale, quindi prima di sviluppare su questa base, prova un video Fast da 6 secondi a $0.27.

Dovrei disattivare prompt_optimizer?

Lascialo attivo per i prompt brevi. Disattivalo quando hai scritto con cura le parole e vuoi che il modello le esegua alla lettera.

C'è l'audio?

Nessuno dei tre video di esempio qui sopra ha una traccia audio, e non esiste alcun campo per abilitarlo.

Fast è peggiore?

Accetta gli stessi input e costa un terzo in meno. Nell'esempio delle barche qui sopra, il movimento è morbido e pulito. Per inquadrature con molto movimento rapido, genera prima una bozza da 6 secondi su entrambi i modelli e confrontale, poi renderizza la versione da 10 secondi.

Per un confronto più ampio tra i modelli video: le API per immagini e video più economiche su HiAPI. Per provare Hailuo senza codice, apri la pagina del modello image-to-video.