Tutoriale
Come usare minimax-h3 tramite l'API HiAPI: curl, Python e richieste eseguibili
In questa pagina
Che aspetto ha l'integrazione end-to-end di minimax-h3
La generazione video non è un'operazione istantanea. minimax-h3 deve accettare un prompt o un'immagine di origine, pianificare l'attività su un pool di GPU, codificare i fotogrammi e assemblare il file di output. L'intero processo, a seconda di durata e risoluzione, può richiedere da pochi secondi a diversi minuti. Se l'endpoint HiAPI bloccasse la risposta fino a quando il file è pronto, il tuo client HTTP manterrebbe una connessione aperta per tutta la durata: fragile in caso di retry, incompatibile con i limiti di tempo dei serverless e inutilizzabile in un handler Web di tipo richiesta/risposta.
Pertanto l'integrazione segue la forma invia prima, poi esegui il polling, il pattern standard delle API media asincrone:
- Invio. Effettui un
POSTdi un payload JSON che descrive l'attività (prompt, immagine opzionale, durata, proporzioni e qualsiasi parametro specifico del modello). Dopo la validazione, l'API restituisce immediatamente un identificatore dell'attività e uno stato iniziale. - Polling. A intervalli brevi chiami l'endpoint di stato dell'attività con quell'identificatore. Lo stato attraversa fasi come in coda, in elaborazione e infine successo o fallimento.
- Recupero. Una volta che lo stato raggiunge uno stato terminale, la risposta trasporta il risultato, di solito un URL scaricabile del video generato.
Questo modello ha tre conseguenze che determinano tutto il resto di questa guida:
- L'ID dell'attività è il tuo unico handle. Persistilo. Se lo perdi, non puoi recuperare l'attività; puoi solo inviarla di nuovo e pagare ancora per il lavoro.
- Il tuo codice ha due superfici di errore, non una. L'invio può fallire (autenticazione, payload malformato) e anche il polling può fallire (timeout, errori di rete transitori, attività che terminano in stato di fallimento). Gestiscili separatamente.
- Il ritmo del polling è una decisione di progettazione. Troppo aggressivo spreca richieste; troppo lento fa attendere all'utente uno stato che era già pronto da tempo.
In questo articolo tutte le chiamate sono dirette all'API unificata HiAPI. Devi ottenere una chiave API dal tuo account HiAPI e fare riferimento al modello come minimax-h3 nel payload. Tutto il resto — header di autenticazione, URL di base, endpoint di polling — è condiviso su tutta la piattaforma, quindi il pattern che impari qui è trasferibile ad altri modelli senza rifattorizzare il client.
Con questo modello mentale, il modo più rapido per confermare la configurazione è una singola chiamata curl.
La tua prima richiesta curl eseguibile
Prima di scrivere qualsiasi codice applicativo, verifica che la tua chiave sia valida e che l'API sia raggiungibile. Un comando curl una tantum è il modo più economico per distinguere un problema di autenticazione da un problema di payload.
Innanzitutto esporta la tua chiave, così non finisce in chiaro nella cronologia della shell:
export HIAPI_API_KEY="your-api-key-here"
Poi invia un'attività minima di generazione video da testo:
curl -sS -X POST "https://api.hiapi.ai/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3",
"prompt": "A slow aerial shot over a fog-covered pine forest at sunrise",
"duration": 5,
"aspect_ratio": "16:9"
}'
Una risposta di successo restituisce un oggetto JSON contenente l'identificatore dell'attività e lo stato. La struttura è approssimativamente questa:
{
"id": "task_abc123xyz",
"status": "queued",
"model": "minimax-h3",
"created_at": "2024-01-01T00:00:00Z"
}
Nota che al momento non c'è ancora un URL del video. È previsto: l'attività è stata solo accettata. I nomi dei campi nella tua risposta effettiva potrebbero differire leggermente da quelli mostrati sopra; leggi il corpo della risposta invece di darlo per scontato e registra l'intero contenuto durante lo sviluppo.
Cosa fa ogni parte della richiesta
- L'URL punta alla risorsa di generazione video sulla piattaforma HiAPI. Tutte le chiamate ai modelli condividono questa base, ed è per questo che cambiare modello significa solo modificare il payload invece di riscrivere il codice.
Authorization: Bearertrasporta la tua chiave API. È la fonte di errore più comune, quindi verificala per prima quando qualcosa non funziona.Content-Type: application/jsonè obbligatorio. Senza di esso, il server potrebbe rifiutare o interpretare male il corpo della richiesta.modelseleziona esplicitamente minimax-h3. Non ometterlo mai: la piattaforma instrada le richieste in base a questo valore.promptè l'istruzione creativa. Sii specifico su soggetto, movimento di camera e illuminazione; i prompt vaghi producono video vaghi.durationeaspect_ratiovincolano l'output. Mantienili entro gli intervalli supportati dal modello; i valori fuori intervallo sono errori di validazione del payload, non guasti del server.
Verifica che l'attività esista
Subito dopo l'invio, recupera l'attività una volta per dimostrare che l'ID è valido:
curl -sS "https://api.hiapi.ai/v1/tasks/task_abc123xyz" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Sostituisci task_abc123xyz con l'ID della risposta di invio. Se questo restituisce uno stato, allora la tua chiave, l'endpoint e l'handle dell'attività sono corretti: puoi passare a Python.
Vale la pena adottare subito due abitudini: eseguire curl con -sS, così gli errori emergono invece di essere silenziosamente inghiottiti, e mettere sempre tra virgolette l'URL. Un'espansione inattesa della shell in un payload JSON è una trappola di debug che costa molto più tempo delle virgolette stesse.
Costruire la stessa richiesta in Python
La chiamata curl ha dimostrato il contratto; Python è dove costruisci qualcosa di riutilizzabile. Invece di saltare direttamente al ciclo di polling, inizia con una piccola classe client che gestisce invio e recupero del risultato come due metodi distinti. Questa separazione mantiene la logica asincrona fuori dal tuo livello di trasporto.
Usa requests (o httpx se preferisci l'asincrono); la forma è la stessa in entrambi i casi.
import os
import time
import requests
BASE_URL = "https://api.hiapi.ai/v1"
class MiniMaxH3Client:
def __init__(self, api_key: str | None = None):
self.api_key = api_key or os.environ["HIAPI_API_KEY"]
self.session = requests.Session()
self.session.headers.update({
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json",
})
def submit(self, prompt: str, duration: int = 5,
aspect_ratio: str = "16:9", **extra) -> str:
payload = {
"model": "minimax-h3",
"prompt": prompt,
"duration": duration,
"aspect_ratio": aspect_ratio,
**extra,
}
resp = self.session.post(
f"{BASE_URL}/video/generations",
json=payload,
timeout=30,
)
resp.raise_for_status()
data = resp.json()
return data["id"]
Ci sono alcune scelte deliberate che vale la pena evidenziare.
Usa una session, non requests nudo. Riusare requests.Session mantiene attiva la connessione tra le chiamate di invio e di polling, cosa importante quando interroghi ripetutamente lo stesso host. Centralizza anche la gestione degli header, quindi l'header di autenticazione è definito una sola volta.
Imposta un timeout rigido sull'invio. Per una richiesta che dovrebbe tornare quasi immediatamente, trenta secondi sono ampi. Senza timeout, un'interruzione di rete farebbe bloccare il tuo processo all'infinito. Non omettere mai timeout su nessuna chiamata API remota.
Chiama raise_for_status() prima di analizzare. Il corpo di una risposta non-2xx ha spesso una forma diversa da quella di una risposta di successo. Controllare prima il codice di stato significa che la tua gestione degli errori legge un messaggio di errore ben formato invece di andare in crash per la mancanza della chiave id.
Passaggio trasparente di **extra. Le opzioni specifiche del modello evolvono. Il passaggio trasparente di argomenti keyword aggiuntivi ti consente di sperimentare nuovi parametri senza modificare ogni volta la firma del metodo.
Usarlo
client = MiniMaxH3Client()
task_id = client.submit(
"A slow aerial shot over a fog-covered pine forest at sunrise"
)
print(f"submitted: {task_id}")
Questo è l'intero percorso di invio. Il client restituisce una stringa — l'handle dell'attività — e nient'altro. Resisti alla tentazione di far attendere anche il risultato a submit. Fondere invio e attesa in un unico metodo rende i retry ambigui: in caso di errore, non puoi sapere se l'attività è stata creata, quindi rischi generazioni duplicate. Tienili separati e lascia che sia il chiamante a decidere la strategia.
Eseguire il polling dei risultati senza bombardare l'API
Il polling è la parte che si scrive con più leggerezza. Un ingenuo ciclo while True senza attesa invierebbe centinaia di richieste per un'attività che richiede due minuti, e continuerebbe a farlo anche dopo che l'attività è già fallita.
Un ciclo di polling corretto ha quattro responsabilità: controllare lo stato, attendere, fermarsi agli stati terminali e alla fine rinunciare.
TERMINAL = {"succeeded", "failed", "cancelled"}
def wait_for(self, task_id: str, interval: float = 3.0,
max_wait: float = 600.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
resp = self.session.get(f"{BASE_URL}/tasks/{task_id}", timeout=30)
resp.raise_for_status()
data = resp.json()
status = data.get("status", "unknown")
if status in TERMINAL:
return data
time.sleep(interval)
raise TimeoutError(f"task {task_id} did not finish in {max_wait}s")
Scegliere l'intervallo
Per la generazione video, un intervallo fisso di alcuni secondi è un valore predefinito ragionevole. Le attività non si completano nei primi secondi — il caricamento del modello e la codifica dei fotogrammi richiedono tempo reale — quindi eseguire il polling ogni 200 ms non produce nulla oltre al carico. Se vuoi essere allo stesso tempo gentile ed efficiente, usa un backoff esponenziale con limite massimo: inizia da uno o due secondi, moltiplica per circa 1,5 a ogni giro fino a raggiungere cinque o dieci secondi, poi mantieniti lì. Il polling iniziale cattura rapidamente i fallimenti precoci; quello successivo rimane economico durante i rendering lunghi.
Fermarsi correttamente
Tratta qualsiasi stato non riconosciuto come non terminale e continua ad attendere, ma solo fino a un certo limite. Due condizioni di arresto sono importanti:
- Stato terminale. Restituisci immediatamente in caso di successo. In caso di fallimento, esponi il messaggio di errore dalla risposta invece di restituire un risultato vuoto; la causa è importante per i tuoi log.
- Budget di tempo reale. Usa un orologio monotono, non l'orologio di sistema, così le regolazioni dell'orologio non faranno uscire il ciclo in anticipo né lo faranno girare per sempre. Scegli un limite comodamente superiore all'attività realistica più lunga per la durata e la risoluzione scelte, e considera il raggiungimento di quel limite come un errore operativo che richiede un avviso.
Restituire il risultato
Quando lo stato è successo terminale, la risposta trasporta l'URL del video generato. Scaricalo prontamente: l'URL del risultato di solito ha una scadenza, quindi se ti serve un accesso persistente archivialo nel tuo object storage. Non passare l'URL del fornitore direttamente all'utente finale dando per scontato che esisterà per sempre.
Un altro consiglio pratico: registra a livello di debug l'ID dell'attività, lo stato e il tempo trascorso per ogni polling, e a livello info il risultato terminale. Quando un'attività richiede più del previsto, quella cronologia è la differenza tra una diagnosi di cinque minuti e un'ora di supposizioni.
Forme delle richieste di generazione video da testo e da immagine
Le due modalità di generazione condividono gran parte del payload. La differenza sta nell'input creativo, e questa differenza ha effetti a valle sul tipo di errori che dovresti aspettarti.
Video da testo
Questa è la forma mostrata nelle sezioni precedenti: prompt più vincoli di output. Il modello inventa tutto — composizione, movimento, illuminazione e dettagli del soggetto. Il tuo payload trasporta:
model:minimax-h3prompt: la descrizione della scenaduration,aspect_ratioe qualsiasi altro controllo dell'output
Poiché non c'è alcun ancoraggio, la qualità del prompt domina il risultato. Descrivi il comportamento della camera («lento carrello in avanti», «inquadratura fissa su treppiede») e l'illuminazione («controluce all'ora d'oro») invece di accumulare aggettivi sulla qualità. Gli aggettivi super generici servono a poco; le descrizioni fisiche specifiche servono molto.
Video da immagine
La variante da immagine aggiunge alla stessa richiesta un riferimento all'immagine di origine. Di solito fornisci un URL dell'immagine o un identificatore di risorsa caricata in un campo immagine accanto al prompt, e il modello anima a partire da quel fotogramma iniziale.
client.submit(
"Gentle wind moves the hair, subtle camera push forward",
duration=5,
image_url="https://example.com/portraits/source.jpg",
)
Il prompt ora svolge un ruolo diverso: guida il movimento e la camera, non il contenuto, perché il contenuto visivo è già fissato dall'immagine. Scrivere una descrizione completa della scena di solito è controproducente: il modello non può aggiungere luoghi che non esistono nell'inquadratura. Mantieni i prompt di movimento brevi e specifici.
Consulta il riferimento della richiesta per i nomi esatti dei campi e i formati immagine accettati nella modalità immagine, oltre agli intervalli validi di durata e proporzioni in entrambe le modalità. Sono proprio quei vincoli a generare gli errori di validazione del payload, quindi leggerli una volta fa risparmiare un giro di debug successivo.
Una regola pratica
Scegli il video da testo quando ti servono scene nuove — B-roll, clip d'atmosfera, visualizzazioni di concetti. Scegli il video da immagine quando conta la coerenza: animare foto di prodotto, dare vita a ritratti di personaggi o trasformare fotogrammi di storyboard in inquadrature in movimento. La modalità è una differenza di payload, non di integrazione, quindi un'unica classe client può servire entrambe accettando semplicemente un parametro immagine opzionale.
Diagnosticare gli errori comuni
Quando una chiamata a minimax-h3 va storta, la causa è quasi sempre in uno di quattro punti. Indagali in questo ordine.
1. Autenticazione
Sintomo: risposta 401 o 403, oppure un corpo di errore che dichiara credenziali non valide.
- Verifica che l'header
Authorizationsia presente e nel formatoBearer <key>, con uno spazio in mezzo. - Controlla che la variabile d'ambiente contenga davvero un valore: un a capo finale incollato nella variabile d'ambiente rompe l'header in un modo invisibile nei log.
- Verifica che la chiave appartenga allo stesso progetto HiAPI che ti aspetti e che non sia stata ruotata.
Il test più rapido: riesegui il curl grezzo di prima. Se curl funziona e Python no, il bug è nel tuo client, non nel tuo account.
2. Payload malformato
Sintomo: risposta 400 o 422, oppure un messaggio di validazione che nomina un parametro.
- Verifica che
Content-Type: application/jsonsia presente e che il corpo sia JSON valido: una virgola finale di troppo è il colpevole classico. - Controlla che
modelsia esattamenteminimax-h3. - Verifica che
durationeaspect_ratiosiano entro gli intervalli supportati dal modello. - Nella modalità immagine, verifica che il riferimento all'immagine sia accessibile e in un formato accettato.
Leggi letteralmente il messaggio di errore. Gli errori di validazione di solito nominano il campo non conforme; gli sviluppatori spesso lo saltano e iniziano a riscrivere parti non correlate del payload.
3. Il polling non termina mai
Sintomo: lo stato rimane in coda o in elaborazione dopo una durata ragionevole, oppure il ciclo gira all'infinito.
- Registra la risposta completa dello stato: il valore dello stato potrebbe non essere quello che il tuo codice presume.
- Controlla il campo che leggi. Se il tuo insieme di stati terminali verifica
"completed"ma l'API restituisce"succeeded", il tuo ciclo girerà per sempre. Stampa una risposta grezza nelle fasi iniziali dello sviluppo. - Verifica che l'ID dell'attività sia copiato esattamente, senza troncamenti o spazi bianchi.
- Aggiungi una scadenza di tempo reale; un ciclo bloccato senza limite è un bug del tuo codice, non dell'API.
4. Timeout ed errori di rete transitori
Sintomo: errori di connessione, timeout di lettura o risposte 5xx durante l'invio o il polling.
- Assicurati che ogni chiamata passi un
timeoutesplicito: molti client hanno come valore predefinito None, il che significa che un socket sospeso può bloccare per sempre. - Distingui tra timeout di connessione e timeout di lettura; un invio con timeout di lettura potrebbe aver effettivamente creato l'attività. Se viene restituito un ID di richiesta, registralo dagli header della risposta e controlla se è comparsa un'attività prima di inviare di nuovo alla cieca.
- Per i 5xx durante il polling, riprova: l'attività potrebbe stare bene. Per i 5xx durante l'invio, verifica che non sia stata creata un'attività per evitare generazioni duplicate.
Un'abitudine di triage rapido: tieni un file curl di appunti accanto al progetto, con i comandi di invio e polling precompilati dalle variabili d'ambiente. Riprodurre un bug fuori dal codice applicativo richiede pochi secondi e ti dice subito se il problema è nel trasporto o nella logica.
Renderlo pronto per la produzione
Uno script eseguibile non è un servizio eseguibile. Le attività video sono abbastanza lente che il traffico di produzione si sovrapporrà, farà retry e occasionalmente fallirà in modi che una singola esecuzione manuale non rivelerà mai. Quattro pattern portano la maggior parte del peso.
Retry con backoff, ma solo dove è sicuro
La strategia di retry dipende da quale chiamata fallisce:
- Il polling è intrinsecamente sicuro da riprovare. Un controllo di stato fallito non ha effetti collaterali, quindi riprova con backoff esponenziale e jitter, limitato a un numero ridotto di tentativi.
- L'invio non può essere riprovato alla cieca. Un timeout non significa che l'attività non sia stata creata. Prima di reinviare, controlla se esiste già un'attività per quella richiesta (usando l'ID di richiesta dagli header della risposta, se disponibile, o una breve finestra di riconciliazione). In alternativa, rendi idempotenti i tuoi invii memorizzando nella cache gli ID delle attività in base all'hash del payload, così una richiesta riprovata restituisce l'attività esistente invece di avviare un nuovo rendering.
- I fallimenti a livello di modello — stato terminale
failed— di solito non dovrebbero essere ritentati automaticamente con lo stesso payload. Input identici tendono a fallire allo stesso modo. Registralo, avvisa e lascia che se ne occupi una persona o un prompt modificato.
Aggiungi jitter a ogni attesa di backoff. Senza di esso, un gruppo di worker che riprovano in sincrono produce picchi sincronizzati, peggiorando una situazione già brutta.
Registra gli ID delle attività ovunque
L'ID dell'attività è l'unico legame persistente tra il tuo sistema e il video generato. Nel momento in cui l'invio riesce, scrivilo nei log con campi strutturati — task_id, modello, durata, timestamp di invio. Quando un utente segnala un video perso, cercare per ID dell'attività trova la cronologia completa in pochi secondi. Registra anche lo stato terminale e il tempo trascorso, così puoi rispondere con i dati invece che con la memoria alla domanda «quanto ci vuole di solito?».
Imposta un budget di timeout esplicito
Ragiona in termini di budget totale per l'intera operazione, non solo di timeout per singola richiesta. Un'attività ha tre fasi — invio, attesa, download — e ognuna ha bisogno di limiti. Una struttura ragionevole:
- Timeout brevi per le richieste di invio e polling, per rilevare rapidamente le connessioni morte.
- Un limite totale di tempo reale per il polling, impostato sulla base della durata e risoluzione massime supportate con un certo margine.
- Un download limitato con scrittura in streaming, così i file grandi non esauriscono la memoria né bloccano il worker.
Quando il budget si esaurisce, fai fallire l'attività in modo pulito, libera lo slot di concorrenza e riporta un errore chiaro. Un fallimento prevedibile è meglio di una richiesta che resta appesa fino al riavvio del container da parte della piattaforma.
Separa invio e consumo
Il design invia-prima-poi-polling si mappa naturalmente su un'architettura a coda: il tuo handler Web invia e restituisce l'ID dell'attività, un worker in background esegue il polling e memorizza il risultato, il client esegue il polling del tuo endpoint di stato. Questo disaccoppia la latenza rivolta all'utente dal tempo di rendering, rende facili da applicare i limiti di concorrenza e significa che un picco di invii non esaurirà il pool di thread del tuo livello Web.
Se fai bene questi quattro punti, la forma asincrona di minimax-h3 lavorerà con te invece che contro di te: le attività vengono tracciate, i retry sono sicuri, i fallimenti sono visibili e nulla rimane appeso all'infinito.
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