Come si usa l'API MiniMax H3 Max? Genera video da testo o immagini

MiniMax H3 Max su HiAPI è disponibile con due nomi di modello: text-to-video minimax-h3-max/text-to-video e image-to-video minimax-h3-max/image-to-video, genera video da 0,92–15 secondi, 480P a $0,072 al secondo, 768P a $0,115 al secondo, 1080P a $0,229 al secondo, con fatturazione basata sui secondi richiesti. Inizia generando un cortometraggio orizzontale di 5 secondi con il prompt della barchetta di carta qui sotto: il budget per 768P è $0,575; per integrare l'API, invia un'attività e usa il taskId restituito per ottenere il video.

MiniMax H3 Max è già disponibile su HiAPI, genera con questo prompt →. Il prompt viene inserito automaticamente, poi seleziona manualmente 5 secondi, 768P, 16:9.

Il primo video: la barchetta di carta dopo la pioggia

After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.

genera con questo prompt →

Questo prompt separa azione e movimento di camera: la barchetta di carta va alla deriva con l'acqua, una camera bassa la segue fluidamente, il suono è affidato al canto degli uccelli in lontananza. Quando sostituisci la barchetta con il tuo soggetto, mantieni prima un'azione e un tipo di movimento di camera: sarà più facile capire cosa regolare.

Prova online o integrazione API: quale scegliere?

Se vuoi prima vedere il risultato, apri la pagina del modello text-to-video, copia il prompt, scegli durata e risoluzione e invia la generazione; se hai già un fotogramma iniziale, passa alla pagina del modello image-to-video e carica l'immagine del primo fotogramma. Per integrare in un'applicazione, ottieni prima la chiave dalla pagina API Key, crea l'attività con una richiesta lato server, salva il taskId e, quando l'attività è completata, leggi l'URL del video.

È consigliabile specificare esplicitamente la risoluzione: 5 secondi a 480P costano $0,36, a 768P $0,575, a 1080P $1,145. Verifica prima l'azione a bassa risoluzione, poi scegli il livello in base alle esigenze di consegna; il budget completo è nella tabella prezzi di H3 e H3 Max.

cURL: crea l'attività, poi interroga il risultato

Dopo aver impostato la API Key nella variabile d'ambiente locale HIAPI_API_KEY, esegui questa richiesta:

curl --fail-with-body --connect-timeout 10 --max-time 60 -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}'

Se il POST va in timeout, la connessione si interrompe o la risposta non permette di confermare la creazione, lo stato di invio è sconosciuto: controlla prima la cronologia delle attività, non rieseguire subito il POST. Dopo aver verificato che la risposta abbia code=200, che data sia un oggetto e che data.taskId non sia vuoto, salva l'ID e sostituisci YOUR_TASK_ID nell'URL di interrogazione:

curl --fail-with-body --connect-timeout 10 --max-time 60 "https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Per le attività in attesa, continua a interrogare lo stesso ID. Quando data.status è success, leggi il url della voce video da data.output; quando è fail, controlla il messaggio di errore dell'attività; se ci sono errori di input o di autenticazione, correggi prima il problema corrispondente e, se hai già un ID attività, continua a interrogare quell'attività.

Python: invia una volta, attendi la stessa attività

Qui sotto si usa la libreria standard di Python. Esegui il POST una sola volta e convalida la risposta; se l'esito dell'invio è sconosciuto, interrompi e indica di controllare la cronologia delle attività. Se l'interrogazione fallisce temporaneamente, conserva l'ID attività e continua il GET; 600 secondi è il limite di attesa di questo esempio.

import json
import os
import time
import urllib.error
import urllib.request

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer " + os.environ["HIAPI_API_KEY"],
    "Content-Type": "application/json",
}


def request(method, url, body=None):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(url, data=data, headers=HEADERS, method=method)
    with urllib.request.urlopen(req, timeout=30) as response:
        result = json.load(response)
    if not isinstance(result, dict) or result.get("code") != 200:
        raise ValueError(f"Unexpected API response: {result!r}")
    if not isinstance(result.get("data"), dict):
        raise ValueError("Missing data object")
    return result["data"]


payload = {
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}
try:
    created = request("POST", BASE, payload)
    task_id = created.get("taskId")
    if not isinstance(task_id, str) or not task_id.strip():
        raise ValueError("Missing taskId")
except (OSError, ValueError) as exc:
    raise SystemExit(
        f"Submission outcome is unconfirmed: {exc}. "
        "Check task history before another POST; do not blindly resubmit."
    )

print("taskId:", task_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    try:
        task = request("GET", f"{BASE}/{task_id}")
    except urllib.error.HTTPError as exc:
        if exc.code in (400, 401, 403, 404):
            raise SystemExit(
                f"Query rejected ({exc.code}). Correct URL/auth, then GET existing task {task_id}."
            )
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    except (OSError, ValueError) as exc:
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    status = task.get("status")
    if status not in ("queued", "handling", "archiving", "success", "fail"):
        raise RuntimeError(f"Unexpected task status {status!r}; keep task ID {task_id}")
    if status == "success":
        output = task.get("output")
        if not isinstance(output, list):
            raise RuntimeError(f"Invalid output; keep task ID {task_id}")
        videos = [item["url"] for item in output
                  if isinstance(item, dict) and item.get("type") == "video"
                  and isinstance(item.get("url"), str) and item["url"]]
        if not videos:
            raise RuntimeError(f"No video URL; keep task ID {task_id}")
        print(videos[0])
        break
    if status == "fail":
        raise RuntimeError(f"Task {task_id} failed: {task!r}")
    time.sleep(5)
else:
    raise TimeoutError(f"Keep querying existing task {task_id}; do not POST again")

Controllare il primo o l'ultimo fotogramma con le immagini

Per far iniziare il video dalla tua immagine prodotto, cambia il nome del modello in minimax-h3-max/image-to-video e aggiungi first_frame_image in input; per specificare il finale, aggiungi last_frame_image. Puoi passare solo l'ultimo fotogramma oppure sia il primo sia l'ultimo; image-to-video non ha il campo aspect_ratio, il formato segue l'immagine.

Campo	Utilizzo
prompt	Obbligatorio, massimo 50000 caratteri, descrive azione, movimento di camera e suono
duration	0,92–15 secondi, può includere decimali, predefinito 5 secondi
resolution	480P, 768P o 1080P, predefinito 768P
aspect_ratio	Solo text-to-video: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, predefinito 16:9
first_frame_image	Image-to-video: URL pubblico dell'immagine del primo fotogramma
last_frame_image	Image-to-video: URL pubblico dell'immagine dell'ultimo fotogramma
target_audio_url	Opzionale, sostituisce la traccia audio con la propria, almeno 2 secondi
prompt_expansion_mode	Opzionale, disabled / balanced (predefinito) / quality

Qui sotto c'è il body completo della richiesta con primo e ultimo fotogramma; gli URL delle immagini sono segnaposto da sostituire con indirizzi tuoi accessibili pubblicamente; le immagini definiscono la composizione iniziale e finale:

{
  "model": "minimax-h3-max/image-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "first_frame_image": "https://your-domain.com/images/paperboat-first.jpg",
    "last_frame_image": "https://your-domain.com/images/paperboat-last.jpg"
  }
}

Se devi controllare solo l'ultimo fotogramma, puoi rimuovere first_frame_image e mantenere last_frame_image. Scrivi nel prompt solo il movimento di camera, mentre l'immagine definisce soggetto e composizione iniziale. Per più inquadrature, descrivi chiaramente ogni cambio nel prompt; i campi della richiesta restano quelli di questa tabella, non aggiungere camera_angle, mode o watermark.

Per un cortometraggio verticale, in text-to-video scrivi direttamente "aspect_ratio": "9:16"; in image-to-video usa un'immagine verticale come primo fotogramma, il formato segue l'immagine.

Quando integri nell'applicazione, metti il callback al livello superiore della richiesta

Aggiungi il callback opzionale al livello superiore della richiesta di creazione, accanto a model e input:

{
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

Unisci questo blocco alla richiesta completa. Il ricevente deduplica per taskId, gestisce separatamente successi e fallimenti e recupera le notifiche perse tramite l'interrogazione delle attività. Dopo aver ottenuto l'ID attività, non reinviare; in caso di errore HTTP, leggi prima il contenuto della risposta per distinguere problemi di autenticazione da problemi di parametri.

Dopo l'integrazione, controlla questi quattro punti

1. Salva il data.taskId non vuoto e continua a usarlo anche dopo errori di interrogazione.
2. Verifica che lo stato finale sia success o fail, senza considerare il limite di attesa come tempo di elaborazione del modello.
3. Nelle attività riuscite, cerca l'URL del video in data.output con type=video.
4. Scarica il prodotto e verifica che dimensioni effettive, durata e contenuto visivo rispettino i requisiti di consegna.

Domande frequenti

H3 Max può usare video o audio di riferimento? H3 Max sostituisce la traccia audio con target_audio_url e non accetta video di riferimento; se ti serve un riferimento multimodale con immagini, video e audio, scegli MiniMax H3.

Rispetto a H3, Max costa di più? H3 2K costa $0,1189 al secondo, Max 768P $0,115 al secondo e 1080P $0,229 al secondo. Scegli prima il modello in base alla risoluzione e ai materiali di riferimento necessari, poi calcola il budget in base alla durata.

Come iniziare un cortometraggio verticale? In text-to-video scrivi "aspect_ratio": "9:16"; in image-to-video prepara un'immagine verticale come primo fotogramma, il formato segue l'immagine.

Copia il prompt della barchetta di carta, genera con questo prompt → e crea prima un cortometraggio di 5 secondi. Per altri esempi di azioni e movimenti di camera, vedi 4 video reali con i prompt completi; per tutti i campi, consulta la documentazione dei parametri text-to-video e la documentazione dei parametri image-to-video.