Hailuo API: guida a MiniMax H3 in Python e 3 modalità video provate

Hailuo API è l'API video di MiniMax, e il suo modello attuale è MiniMax H3 (MiniMax-H3), la generazione successiva a Hailuo 01 e 02. Ogni chiamata è asincrona: si crea un task, lo si controlla, si scarica l'MP4. Il 26 ottobre 2026 le nostre clip da 5 secondi in 768P hanno richiesto da 35 a 42 secondi in tutte e tre le modalità, e ognuna è arrivata con l'audio.

Risposta breve

• Modello: MiniMax-H3 sull'API di MiniMax, annunciato il 31 luglio 2026 (note di rilascio); minimax-h3 su OmniaKey, un solo id per i tre tipi di task (documentazione video).
• Impostazioni: resolution (obbligatorio) con "768P" o "2K", duration da 4 a 15 secondi interi, aspect_ratio (documentazione video).
• Costo: $0.08 al secondo in 768P, $0.40 per 5 secondi, $0.13 in 2K, il listino di MiniMax (prezzi, verificati il 26 ottobre 2026); la tariffa di OmniaKey è sulla pagina del modello.
• Tempo e audio: da 35 a 42 secondi per clip, tutte con audio stereo; il riferimento di creazione V2 non elenca nessun interruttore per togliere l'audio (riferimento di creazione).

Esiste una Hailuo API ufficiale?

Sì. MiniMax la gestisce su platform.minimax.io, e il modello attuale lì è MiniMax H3, con id MiniMax-H3 (pagina dei modelli, verificata il 26 ottobre 2026).

L'annuncio di MiniMax presenta H3 come la generazione successiva a Hailuo 01 e Hailuo 02 (annuncio). I modelli precedenti restano nell'API come MiniMax-Hailuo-2.3 e MiniMax-Hailuo-02 (riferimento V1).

Il nome cambia da pagina a pagina. La documentazione di MiniMax scrive "MiniMax H3", la descrizione del modello nell'API scrive "Hailuo-03" (riferimento di creazione), e l'app Hailuo AI, dove l'annuncio manda a provarlo, scrive "Hailuo 3.0" (app). "Hailuo 3" non è un nome ufficiale.

La chiave si crea in Account > API Keys e la fatturazione è a consumo (FAQ API). I pacchetti video di MiniMax coprono i modelli precedenti, non H3 (prezzi).

MiniMax elenca quattro varianti di H3 (riferimento di creazione):

Sull'API di MiniMax una chiamata richiede tre passaggi (guida video):

• POST https://api.minimax.io/v2/video_generation restituisce un task_id (riferimento di creazione).
• Si interroga GET /v2/query/video_generation/{task_id} finché non arriva succeeded, poi si scarica content.url (riferimento di interrogazione).
• Si possono interrogare solo i task degli ultimi 7 giorni, e MiniMax non pubblica quanto dura l'URL di download (riferimento di interrogazione).

V1 (Hailuo 2.3 e 02) passa l'id del task come parametro ?task_id= invece che come parte del percorso, quindi tenete separati i due flussi (riferimento V1).

OmniaKey vende l'accesso API a MiniMax H3, quindi questi esempi sono passati da lì. Il flusso è lo stesso: POST https://api.omniakey.com/v1/media/tasks con l'intestazione Idempotency-Key restituisce 202 e un id, poi si interroga GET /v1/media/tasks/{id} (panoramica media). Lo stesso flusso fa girare Grok Imagine Video nella nostra guida all'API di Grok Imagine Video. Tutti i prezzi qui sotto sono il listino di MiniMax.

Quali parametri si possono impostare?

• resolution è obbligatorio; 1080P e 4K falliscono con 400 model_price_error (documentazione video), e V2 non ha 1080P per H3 (riferimento di creazione). Le tre modalità hanno girato in 768P e 2K non l'abbiamo provato.
• duration va da 4 a 15 secondi interi (documentazione video); MiniMax-H3-Max parte da 5 e rifiuta 4 (riferimento di creazione).
• aspect_ratio accetta adaptive, 16:9, 9:16, 1:1, 4:3, 3:4 o 21:9 (documentazione video). Sull'API di MiniMax il testo a video richiede una proporzione fissa e l'immagine a video segue la forma dell'immagine (riferimento di creazione). Nella nostra prova immagine a video abbiamo omesso la proporzione e la clip ha mantenuto la forma dell'immagine fissa, 1376×768.
• input.media[] accetta first_frame e un last_frame opzionale per immagine a video, oppure reference_image, reference_video e reference_audio per riferimento a video. I due tipi non si mescolano, e un riferimento audio ha bisogno di un riferimento immagine o video accanto (documentazione video). Ogni voce è un type e una url, cioè un link HTTPS pubblico o un data URI. OmniaKey limita l'intera richiesta a 1 MiB, Base64 compreso (panoramica media), quindi lo script invia JPEG da 1024 pixel.
• Il prompt sta in input.prompt (documentazione video), fino a 7,000 caratteri (guida video). Anche l'audio che volete si descrive lì.

Come si chiama Hailuo API da Python?

Servono Python 3 e requests, con la chiave in una variabile d'ambiente.

pip install requests
export OMNIAKEY_API_KEY="your-key"
python hailuo_h3.py t2v   # or i2v (needs bicycle.jpg) or r2v (needs robot.jpg)

L'unico argomento è t2v, i2v o r2v; le esecuzioni che richiedono un'immagine leggono bicycle.jpg o robot.jpg dalla stessa cartella.

Questo è lo script che abbiamo eseguito, senza modifiche:

import base64
import os
import sys
import time
import uuid

import requests

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}"}

DRUMMER = (
    "A street drummer plays a fast rhythm on upturned plastic buckets on a rainy city sidewalk "
    "at night. Neon signs reflect in the puddles and a few people with umbrellas walk past "
    "behind him. The camera slowly pushes in from a medium shot to a close-up of his hands and "
    "drumsticks. Realistic, handheld documentary look, with the sound of rain and drumming."
)
BICYCLE = (
    "A gentle breeze moves the daisies in the basket and a few petals drift down to the "
    "cobblestones. The camera slowly pushes in toward the basket. The bicycle and the wall "
    "stay exactly as they are."
)
ROBOT = (
    "The small orange robot from the reference image waters potted plants on a sunny "
    "apartment balcony with a red watering can. Medium shot, slow sideways camera move, "
    "city rooftops in the background."
)


def data_uri(path):
    # A local JPEG sent inline. The whole request must stay under 1 MiB, so keep it small.
    with open(path, "rb") as f:
        return "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()


def make_video(operation, prompt, parameters, media, out):
    task_input = {"prompt": prompt}
    if media:
        task_input["media"] = media

    # 1. Create the task. Reuse the same Idempotency-Key only when retrying this exact request.
    resp = requests.post(
        API,
        headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
        json={
            "model": "minimax-h3",
            "type": "video",
            "operation": operation,
            "input": task_input,
            "parameters": parameters,
        },
        timeout=60,
    )
    resp.raise_for_status()
    task = resp.json()
    print(operation, "task:", task["id"])

    # 2. Poll the same task. Slow is not failed: never resubmit, keep polling this id.
    deadline = time.time() + 15 * 60
    while task["status"] in ("queued", "processing"):
        if time.time() > deadline:
            raise SystemExit(f"still {task['status']}: poll {task['id']} again later")
        time.sleep(5)
        task = requests.get(f"{API}/{task['id']}", headers=HEADERS, timeout=30).json()
    if task["status"] != "succeeded":
        raise SystemExit(f"{operation} ended {task['status']}: {task.get('error')}")

    # 3. Download the clip now: the signed URL lasts about an hour.
    asset = task["assets"][0]
    with open(out, "wb") as f:
        f.write(requests.get(asset["url"], timeout=120).content)
    print("saved", out, asset["byte_size"], "bytes")


mode = sys.argv[1] if len(sys.argv) > 1 else "t2v"
if mode == "t2v":
    make_video(
        "text_to_video", DRUMMER,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        None, "drummer.mp4",
    )
elif mode == "i2v":
    make_video(
        "image_to_video", BICYCLE,
        {"resolution": "768P", "duration": 5},
        [{"type": "first_frame", "url": data_uri("bicycle.jpg")}], "bicycle.mp4",
    )
elif mode == "r2v":
    make_video(
        "reference_to_video", ROBOT,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        [{"type": "reference_image", "url": data_uri("robot.jpg")}], "robot.mp4",
    )

L'output del 27 ottobre 2026:

$ python hailuo_h3.py t2v
text_to_video task: task_V5TXAJG7n3ny42imJNqgTXRL4L8PGStd
saved drummer.mp4 4612510 bytes
$ python hailuo_h3.py i2v
image_to_video task: task_c4m3wHmF79Cmq7ZhDrTnCyt8SmIaW1ls
saved bicycle.mp4 4705286 bytes
$ python hailuo_h3.py r2v
reference_to_video task: task_dqx1TYA7u0znN5PFTl9tbfdWgtbBUbKd
saved robot.mp4 5630121 bytes

Ogni esecuzione ha richiesto da 47 a 60 secondi dall'avvio al file salvato.

Conservate l'id del task. Un task lento non è fallito: interrogate lo stesso id invece di inviare di nuovo (panoramica media). L'URL di download firmato dura circa un'ora e il record del task 24 ore, quindi salvate il file subito oppure interrogate di nuovo per un URL fresco. Il download in sé non richiede la chiave API.

Cosa hanno restituito le tre modalità

Le tre clip vengono da tre task del 26 ottobre 2026, con esattamente i corpi di richiesta dello script.

Ogni clip era un MP4, H.264, 24 fps, 5.17 secondi, con audio AAC stereo a 32 kHz; usage riportava output_seconds: 5.

Testo a video: il batterista di strada

Il prompt è DRUMMER nello script.

Cosa abbiamo visto:

• Un marciapiede bagnato di notte, neon rossi e blu riflessi sull'asfalto, auto parcheggiate e un batterista con giacca nera incappucciata chino su secchi blu capovolti. Il cappuccio nasconde il viso per tutta la durata.
• La camera avanza da un'inquadratura larga a un primo piano delle mani, delle bacchette in movimento e della parte superiore dei secchi, mentre dietro passa una persona con l'ombrello.
• Le lettere delle insegne al neon non formano parole vere. I colpi di batteria diventano più forti verso la fine, ma la pioggia non si distingue nell'audio.

Cosa cambiare: se serve un viso, aggiungete "hood down, face visible"; se la pioggia deve sentirsi, datele una frase audio sua.

Immagine a video: il primo fotogramma resta

Il primo fotogramma è un'immagine fissa creata con Nano Banana 2.1; il prompt è BICYCLE e descrive solo il movimento.

Cosa abbiamo visto:

• Il primo fotogramma corrisponde all'immagine fissa: la stessa bicicletta rossa, la parete di intonaco gialla, le persiane, le piante in vaso e i ciottoli.
• La camera avanza finché il cesto di margherite bianche riempie l'inquadratura, e la bicicletta e la parete mantengono la forma fino in fondo.
• Nei fotogrammi controllati non abbiamo visto petali cadere. L'audio è una melodia lenta di pianoforte solo, anche se il prompt non nomina né audio né musica.

Cosa cambiare: descrivete solo il movimento e l'audio, perché l'aspetto lo decide già l'immagine fissa, e preparate l'immagine fissa nella forma che volete per la clip.

Riferimento a video: un'immagine tiene il personaggio

Il riferimento è una sola immagine di un piccolo robot arancione creata con Nano Banana 2.1; il prompt è ROBOT.

Cosa abbiamo visto:

• Lo stesso robot: corpo arrotondato arancione, occhi rotondi di vetro blu, una antenna corta con una sfera in cima e un disco rotondo sul lato della testa, ora su un balcone assolato con vasi di fiori ed erbe.
• Versa acqua da un annaffiatoio rosso, il getto si vede da circa 1 secondo e la camera scorre leggermente di lato.
• L'audio è acqua che scorre e schizza, inizia poco prima che appaia il getto, senza musica.

Cosa cambiare: il personaggio non ha avuto bisogno di correzioni. Per tenerlo uguale su più clip, riusate la stessa immagine di riferimento ogni volta.

Audio: descrivetelo, o lo sceglie H3

Quando il prompt non diceva nulla sull'audio, H3 lo ha scelto: acqua per il robot, che si adatta all'annaffiatura, e pianoforte per la bicicletta. Descrivete nel prompt l'audio che vi serve. Il riferimento di creazione V2 non elenca nessun interruttore per togliere l'audio (riferimento di creazione), quindi per una clip muta togliete la traccia dopo:

ffmpeg -i drummer.mp4 -an -c copy drummer-silent.mp4

Così ottenete una copia con il solo video H.264, sempre di 5.17 secondi e senza ricodifica.

Quali errori si incontrano?

Gli errori arrivano dall'API dei task di OmniaKey e, con una chiamata diretta, da MiniMax.

• 400 missing_idempotency_key: Manca l'intestazione Idempotency-Key. Aggiungetela.
• 409 idempotency_key_reused: Stessa chiave, corpo nuovo. Una chiave per task.
• 400 model_price_error: 1080P o 4K. Usate 768P o 2K.
• 400 invalid_request: Corpo o parametro sbagliato. Controllate i parametri.
• 403 model_not_allowed: La chiave non ha questo modello. Controllate l'accesso della chiave.
• 503 no_available_channel: Modello non disponibile adesso. Riprovate più tardi.
• provider_submit_uncertain: Rifiutato all'invio. Usate input.prompt, controllate il materiale.
• Task failed: Generazione fallita. Leggete error.

Un task fallito o annullato viene rimborsato (panoramica media). Sull'API di MiniMax (codici di errore, verificati il 26 ottobre 2026):

• MiniMax invia lo stato HTTP corrispondente a ogni codice, per esempio 401 con 1004 e 400 con 2013 (riferimento di creazione).
• H3 su V2 consente 300 richieste al minuto e 30 task in esecuzione insieme (limiti di frequenza).

Quanto costa Hailuo API?

MiniMax fattura H3 al secondo di video prodotto, secondo variante e risoluzione (pagina dei prezzi, verificata il 26 ottobre 2026):

Con questi prezzi: 5 secondi in 768P costano $0.40, 10 secondi in 2K $1.30 e 15 secondi in 2K $1.95.

• Le prime 5 immagini di input per task sono gratuite (2 su Max), ogni immagine in più costa $0.04 su H3 e l'input audio è gratuito. Il video di input si paga al secondo, e su Max un secondo di input ($0.143 in 768P) costa più di un secondo di output. A parità di variante e risoluzione, i tre tipi di task costano lo stesso.
• H3 è solo a consumo, e i pacchetti video di MiniMax non lo coprono. Le cifre al secondo dei piani dell'app Hailuo AI sono crediti dell'app, non prezzi API (app).
• La piattaforma cinese di MiniMax ha un listino suo in yuan, quindi non convertite l'uno nell'altro (prezzi Cina, verificati il 26 ottobre 2026).
• Su OmniaKey un task video viene addebitato al secondo di output alla creazione, e un task fallito o annullato viene rimborsato (panoramica media).

La tariffa attuale di OmniaKey è sulla pagina del modello MiniMax H3; la forma della richiesta è nella documentazione dell'API video.

Domande frequenti

Hailuo API è gratuita?

Sull'API di MiniMax no: le pagine di prezzi, avvio rapido e FAQ non mostrano prove gratuite né credito per H3 (verificate il 26 ottobre 2026). Le uniche parti gratuite sono le prime 5 immagini di input per task e l'input audio (prezzi), e i crediti dell'app Hailuo AI non valgono come crediti API.

Qual è la differenza tra Hailuo 2.3 e MiniMax H3?

Hailuo 2.3 gira su V1: 6 o 10 secondi, fino a 1080P, fatturato a video, con il listino di MiniMax a $0.28 per 6 secondi in 768P (prezzi, riferimento V1). H3 gira su V2: da 4 a 15 secondi, 768P o 2K, fatturato al secondo e con audio stereo (riferimento di creazione, pagina dei modelli). MiniMax li elenca ancora entrambi (FAQ modelli).

Che cos'è MiniMax H3 Max?

È un rilascio congiunto di MiniMax e fal.ai, con addestramento successivo di fal.ai su H3 per la velocità (guida video). Produce clip in 480P o 768P da 5 a 15 secondi, e extra.prompt_expansion_mode accetta disabled, balanced (il valore predefinito) o quality (riferimento di creazione). Sulle referenze le pagine di MiniMax non concordano: la guida video e le FAQ modelli elencano solo testo a video e immagine a video, mentre il riferimento di creazione e la pagina dei prezzi elencano anche riferimento a video.

Si può eseguire MiniMax H3 da soli?

Sì, fuori da alcune regioni. I pesi sono su Hugging Face (MiniMaxAI/MiniMax-H3) e GitHub (MiniMax-AI/MiniMax-H3) con la MiniMax H3 Community License Agreement, una licenza propria (Hugging Face, GitHub). Nella revisione della licenza consultata il 26 agosto 2026, Stati Uniti, UE, Regno Unito e Corea del Sud sono territori esclusi e richiedono una licenza separata (guida al deployment locale).

Registro degli aggiornamenti

27 ottobre 2026: prima versione, con clip realizzate il 26 ottobre 2026.