Tutoriale
Come chiamare minimax-h3-max-turbo text-to-video tramite l'API HiAPI
- Modello
- minimax-h3-max-turbo
In questa pagina
Funzionalità e casi d'uso dell'endpoint
minimax-h3-max-turbo/text-to-video è un endpoint di generazione video da testo esposto tramite l'API HiAPI. Invii un prompt testuale che descrive la scena desiderata, insieme ad alcuni parametri che controllano la forma dell'output, e HiAPI restituisce il video generato. Questo modello è ideale quando hai una descrizione testuale ma nessun materiale di partenza: spot marketing, transizioni per i social media, anteprime di storyboard, video in loop per sfondi di app o generazione di varianti in batch di uno stesso concept creativo.
Prima di scrivere codice, ci sono alcune caratteristiche da tenere presente:
- È un endpoint di generazione, non un template. L'output è prevedibile solo nella struttura (otterrai un video), non nel contenuto. Considera ogni task come un rendering completamente nuovo e progetta i prompt pensando alla riusabilità.
- È asincrono. La chiamata di invio non restituisce direttamente i byte del video finito. Ottieni prima un handle del task, poi ne interroghi il risultato. Qualsiasi integrazione che presupponga una risposta sincrona fallirà al primo timeout.
- L'output è determinato dai parametri della richiesta. Durata e risoluzione modificano il costo di rendering e il tempo effettivo, quindi i parametri che scegli sono anche decisioni su latenza e budget.
- Nessun media di origine richiesto. Non devi caricare video o immagini; prompt e parametri sono l'intera superficie di input.
Quando conviene usare un'altra soluzione? Se hai già materiale e vuoi ristilizzarlo o estenderlo, questo non è l'endpoint adatto. Se ti serve un controllo a livello di frame sul movimento della camera o sulla composizione precisa, un prompt testuale è troppo vago. E se ti serve solo un'immagine statica, l'endpoint text-to-image è più economico e più veloce. Usa minimax-h3-max-turbo/text-to-video quando il prompt è sufficiente come specifica della scena.
Il resto di questa guida illustra in ordine autenticazione, chiamata curl eseguibile, chiamata Python equivalente, ciclo di vita del task, parametri chiave, gli errori che incontrerai e i passi di irrobustimento prima della messa in produzione.
Prerequisiti e autenticazione
Prima della prima richiesta ti servono tre cose:
- La chiave API del tuo account HiAPI. Trattala come un segreto: caricala da una variabile d'ambiente, non salvarla mai nel repository e ruotala immediatamente in caso di esposizione.
- L'URL di base di HiAPI. Tutte le chiamate in questa guida puntano allo stesso host di base; il modello è selezionato dal segmento di percorso, non da un dominio diverso per ogni modello.
- Un client HTTP. curl per i test rapidi, qualsiasi libreria standard o client HTTP per il codice di servizio.
Come viene trasmessa la chiave
HiAPI autentica le richieste tramite un bearer token nell'header Authorization. Il formato è sempre coerente:
export HIAPI_API_KEY="your_api_key_here"
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Due abitudini fanno risparmiare molto tempo di debug:
- L'ortografia dell'header deve essere esatta.
Authorizationcon la A maiuscola,Bearerseguito da uno spazio, poi la chiave. Uno spazio mancante è la causa più comune di 401 misteriosi. - Invia sempre
Content-Type: application/json. I server che si aspettano JSON rifiutano o interpretano male i corpi delle richieste privi di questo header, e spesso l'errore che ricevi dice che manca un campo invece della vera causa.
Verifica prima di sviluppare
Non iniziare subito con l'endpoint video. Fai prima una chiamata economica e veloce per confermare che la chiave e l'URL di base si risolvano correttamente, poi procedi. Se questo controllo di sanità fallisce, nulla a valle funzionerà e ti ritroverai a fare debug al livello sbagliato. Tieni la chiave in un unico punto del codebase — un piccolo modulo client — così la rotazione futura richiederà una sola modifica.
Richiesta curl eseguibile
La chiamata di invio invia prompt e parametri come corpo JSON al percorso del modello. Ecco la chiamata minima eseguibile:
curl -sS -X POST "$HIAPI_BASE_URL/minimax-h3-max-turbo/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "All'alba, lento carrello aereo in avanti sopra una pineta nebbiosa, luce volumetrica soffusa, atmosfera cinematografica",
"duration": 5,
"resolution": "720p"
}'
Cosa fa ciascuna parte:
-X POST— i task di generazione vengono creati tramite POST.- URL — l'host di base più il percorso
minimax-h3-max-turbo/text-to-video. Metti l'host di base in una variabile, così test e produzione puntano allo stesso percorso di codice. Authorization— il bearer token descritto nella sezione precedente.Content-Type— dichiara il corpo JSON.prompt— l'unico input creativo obbligatorio. Scrivilo come descrizione di una scena: soggetto, comportamento della camera, illuminazione e atmosfera. Frasi nominali brevi producono risultati ambigui; una o due frasi con una direzione visiva concreta funzionano molto meglio.durationeresolution— parametri che controllano la forma dell'output, descritti in una sezione dedicata più avanti.
Usa -sS per rendere curl silenzioso ma comunque in grado di stampare gli errori, e durante l'esplorazione usa uno strumento di pretty-print per l'output della risposta. La risposta è un JSON contenente l'identificatore del task; salvalo, perché ti servirà per interrogare il video completato. Non aspettarti che questa risposta contenga i byte del video.
Se durante il debug vuoi vedere esattamente cosa viene inviato, aggiungi -v per l'output dettagliato, ma rimuovilo prima di condividere i log, poiché l'output dettagliato può contenere header.
Richiesta Python equivalente
La versione Python è la stessa richiesta, ma carica la chiave dall'ambiente e interpreta la risposta. Ecco un piccolo client riutilizzabile:
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
MODEL_PATH = "/minimax-h3-max-turbo/text-to-video"
def submit_video(prompt: str, duration: int = 5, resolution: str = "720p") -> dict:
payload = {"prompt": prompt, "duration": duration, "resolution": resolution}
resp = requests.post(
f"{BASE_URL}{MODEL_PATH}",
headers=HEADERS,
json=payload,
timeout=30,
)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
job = submit_video(
"All'alba, lento carrello aereo in avanti sopra una pineta nebbiosa, luce volumetrica soffusa, atmosfera cinematografica"
)
print(job)
Note per l'adattamento:
json=payloadimposta sia il corpo sia il content type; non serializzare manualmente.timeout=30limita il tempo della chiamata di invio. L'invio è veloce, il rendering no: ecco perché qui il timeout è breve e il polling si occupa dell'attesa.raise_for_status()trasforma le risposte non-2xx in eccezioni, così errori di autenticazione e validazione emergono subito, invece di restituire silenziosamente un corpo di risposta errato che poi interpreteresti erroneamente come task.- Restituisci il JSON analizzato come dizionario ed estrai l'identificatore del task nel punto di chiamata. In questo modo la funzione ausiliaria resta generica e il codice di orchestrazione decide come gestirlo.
Se usi uno stack asincrono, la stessa forma vale per il client HTTP che scegli: costruisci gli header una volta, invia il corpo con POST, controlla lo stato e restituisci il corpo della risposta analizzato.
Gestione del ciclo di vita dei task asincroni
La generazione richiede tempo, quindi l'endpoint si divide in invio e polling. Il ciclo di vita è sempre: invia, ricevi l'identificatore del task, interroga il task finché non riporta uno stato terminale, poi recupera l'output.
Invio
Invia il POST descritto in precedenza e leggi l'identificatore del task dalla risposta. Registralo immediatamente e associalo al tuo ID di richiesta, così se il polling fallisce in seguito puoi risalire al prompt originale.
Polling con backoff
Non interrogare con un ciclo serrato. Inizia con un intervallo breve, poi applica il backoff:
def wait_for_job(job_id: str, max_wait: int = 600) -> dict:
deadline = time.time() + max_wait
interval = 2.0
while time.time() < deadline:
resp = requests.get(
f"{BASE_URL}{MODEL_PATH}/{job_id}",
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
job = resp.json()
status = job.get("status")
if status in ("succeeded", "failed"):
return job
time.sleep(interval)
interval = min(interval * 1.5, 15.0)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
Tre dettagli rendono affidabile questo codice. Primo, la scadenza: devi sempre alla fine rinunciare e lanciare un timeout, invece di interrogare all'infinito. Secondo, il backoff con limite massimo: inizia da pochi secondi, raddoppia progressivamente e imponi un tetto all'intervallo, così ottieni progressi costanti senza martellare l'API. Terzo, la gestione degli stati terminali: considera terminali solo successo e fallimento, e restituisci l'oggetto job per consentire al chiamante di gestire i due casi.
Recupero del risultato
Una volta che il task riporta successo, la risposta contiene la posizione del video finito. Scarica o trasmetti il prima possibile nel tuo storage e registra l'URL insieme all'ID del task. Non presumere che il link sia permanente e non recuperare il video a ogni iterazione del polling. Interroga lo stato del task, poi recupera il video una sola volta al successo.
Parametri di durata e risoluzione
Due parametri della richiesta determinano l'output, e insieme anche il tempo di rendering e il costo della chiamata.
duration
La lunghezza della clip generata. Clip più lunghe aumentano proporzionalmente il tempo di rendering, il che significa finestre di polling più lunghe e maggiore probabilità di far scattare il timeout del client. Consigli pratici:
- Allinea la durata al caso d'uso. Le transizioni per i social sono brevi; un loop di sfondo deve essere lungo solo quanto basta per ciclare in modo accettabile. Generare più di quanto verrà effettivamente mostrato è puro spreco.
- Parti da valori bassi durante l'iterazione. Regola il prompt con durate brevi, poi ri-renderizza il prompt vincente con la durata finale.
- Ricorda che il costo cresce con la dimensione dell'output. La fatturazione si basa sulla lunghezza dell'output, quindi la durata è sia una leva creativa sia una leva di budget.
resolution
La qualità spaziale dell'output. Risoluzioni più alte offrono più dettaglio ma consumano più tempo di rendering e costano di più. Suggerimenti:
- Scegli in base al contesto di consegna, non alla scheda tecnica. Se il video apparirà in un feed o in un piccolo player, generare a risoluzione superiore non offre alcun beneficio.
- Itera a bassa risoluzione, produci ad alta risoluzione. Visualizza in anteprima a risoluzione inferiore mentre modifichi il prompt, poi reinvia il prompt approvato alla risoluzione di consegna.
- Impostazioni più alte significano attese più lunghe. Imposta la scadenza del polling sulla combinazione massima che consenti, non su quella minima.
Metti questi due valori nello stesso oggetto di configurazione, invece di spargerli nel codice, così il passaggio da anteprima a produzione è una modifica intenzionale e visibile, non un literal dimenticato.
Debug degli errori comuni
La maggior parte dei fallimenti rientra in quattro categorie. Prima di modificare il codice, associa il sintomo alla categoria.
Errori di autenticazione
Un 401 significa che HiAPI non accetta le tue credenziali. Controlla in ordine: l'header Authorization è presente e scritto correttamente; c'è esattamente uno spazio dopo Bearer; la chiave è valida e non proviene da un altro progetto; la variabile d'ambiente è effettivamente caricata (un newline finale incollato con la chiave è un problema classico). Verifica stampando la lunghezza della variabile, non la chiave stessa.
Errori di validazione
Un 4xx diverso da 401 di solito significa che il corpo della richiesta è errato. Content-Type mancante o diverso da application/json; prompt mancante o vuoto; duration o resolution fuori dall'insieme consentito. Leggi il messaggio di errore alla lettera; di solito indica il campo problematico. Riproduci con la versione curl, perché lì non c'è uno strato di libreria che nasconde il corpo della richiesta.
Timeout
Ci sono due tipi distinti di timeout. Un timeout di invio significa che il POST stesso non è tornato, di solito per problemi di rete o per un timeout del client troppo aggressivo. Un timeout di polling significa che il task non ha raggiunto lo stato terminale entro la tua scadenza; o il rendering richiede davvero più tempo, o la tua scadenza è impostata su valori di anteprima invece che di produzione. Per correggere il secondo caso, aumenta max_wait per durate e risoluzioni elevate, non ridurre l'intervallo di polling.
Errori di polling
Quelli più subdoli. Interrogare senza sleep spreca quota e provoca limitazioni di frequenza; interrogare a intervallo fisso breve ha lo stesso effetto. Interrogare un ID task errato, di solito perché hai riutilizzato la variabile tra invii multipli. Trattare stati intermedi come errori. E recuperare l'URL del video a ogni iterazione invece che una volta al successo. Registra l'ID del task e ogni stato osservato; la sequenza ti dirà subito quale di questi casi hai incontrato.
Checklist di produzione prima del rilascio
Passare da uno script funzionante a un servizio che gira senza supervisione significa aggiungere alcuni strati attorno alla stessa richiesta.
- Retry con jitter. Ritenta con backoff esponenziale e randomizzazione su errori di rete transitori e risposte 5xx. Non ritentare mai gli errori di validazione; falliranno allo stesso modo e consumeranno quota.
- Timeout limitati ovunque. Timeout brevi per l'invio, scadenze più lunghe per il polling (impostate sulla durata e risoluzione massime che consenti), e timeout anche per il download del video.
- Log strutturati. Registra il tuo ID di richiesta, l'ID del task, ogni transizione di stato osservata e il risultato finale, ma non le chiavi API o gli header completi. Quando qualcosa va storto alle tre di notte, questo log è la tua unica prova.
- Idempotenza nel tuo strato. Mantieni una mappa dal tuo ID di richiesta all'ID del task, così un retry del client non produce silenziosamente un secondo rendering.
- Controllo dei costi. La fatturazione si basa sulla lunghezza dell'output, quindi imposta limiti massimi di durata e risoluzione accettati dal servizio, e mantieni le anteprime dei prompt a impostazioni basse finché un'approvazione umana o basata su regole non autorizza il rendering finale.
- Igiene delle chiavi. Carica le chiavi da un secret store, ruotale periodicamente, usa chiavi diverse per test e produzione, così una chiave di test compromessa non può consumare il budget di produzione.
- Appropriazione dei risultati. Appena il task ha successo, copia il video finito in uno storage che controlli e tratta l'URL di consegna come un link temporaneo.
Con questi elementi in atto, l'endpoint diventa una dipendenza prevedibile, non una fonte di sorprese. Inizia confermando le credenziali con la richiesta curl qui sopra, poi integra il client Python nel tuo servizio e avvolgilo con i controlli di questa checklist.
Articoli correlati
Vedi tutti gli articoli →-
Tutoriale
Guida pratica a gpt-6.2-sol: 5 utilizzi ad alto valore dei modelli testuali nel business
-
Tutoriale
Guida pratica a gpt-6.2-astra: integrazione e punti chiave per 5 scenari testuali ad alto valore
Checklist dal punto di vista dello sviluppatore, dalla selezione degli scenari all'implementazione ingegneristica
-
Tutoriale
Scenari pratici di Tripo H3.1: 5 utilizzi ad alto valore e punti di implementazione
Da text-to-3D alla ricostruzione multi-view: scegliere modalità e parametri giusti per ogni scenario di business