Tutoriale
Come usare minimax-h3-max-turbo/image-to-video tramite l'API HiAPI: curl, Python ed esempi di richiesta funzionanti
In questa pagina
Cosa fa questo endpoint e quando usarlo
minimax-h3-max-turbo/image-to-video riceve un'immagine sorgente e un prompt testuale e restituisce un video breve che parte da quell'immagine. L'immagine funge da primo fotogramma (o ancoraggio visivo), quindi l'output ne eredita composizione, tonalità e identità del soggetto. Il prompt descrive poi ciò che deve accadere subito dopo: movimento di camera, azione del soggetto, atmosfera.
Quando preferirlo al text-to-video
Il text-to-video è lo strumento giusto quando non si ha un riferimento visivo e si vuole che il modello crei tutto da zero. L'image-to-video è la scelta corretta quando il primo fotogramma è il punto centrale: si ha già un'immagine di prodotto approvata, un keyframe di uno storyboard, un design di personaggio o una foto caricata dall'utente, e la si vuole animare mantenendola riconoscibile. In concreto, i team usano questo endpoint quando:
- Il primo fotogramma è un requisito contrattuale. Il team marketing ha bisogno di aprire con l'immagine principale esatta, non con una simile.
- La coerenza tra le clip è importante. Riusare la stessa immagine sorgente mantiene stabile un personaggio o un prodotto lungo una serie di clip.
- Si sta animando contenuto dell'utente. Le foto caricate dagli utenti finali devono essere animate, non reinventate.
- Si vuole un prompt più mirato. Descrivere il movimento è più semplice che descrivere l'intera scena da zero, quindi il prompt resta breve e prevedibile.
L'endpoint è asincrono: si invia un task e si recupera il video renderizzato in un secondo momento. Questa forma è ideale per backend guidati da code, come descritto in dettaglio più avanti. Per la superficie completa dei parametri, consultare la pagina del modello.
Prerequisiti e struttura della richiesta
Prima di chiamare l'endpoint, verificare di avere quattro elementi:
- Una chiave API. Creata nel proprio account HiAPI e inviata come bearer token. Trattarla come un segreto: non incorporarla mai nel codice client.
- L'URL di base. Tutte le richieste vanno all'host unificato dell'API HiAPI; il percorso dell'endpoint è l'identificatore del modello.
- Un'immagine sorgente raggiungibile o codificabile: un URL HTTPS pubblico oppure un payload base64, a seconda di ciò che accetta lo schema della richiesta.
- Un client HTTP:
curlper lo smoke test e qualsiasi libreria standard orequestsin Python per l'integrazione reale.
Le parti di una richiesta
Indipendentemente dal linguaggio, ogni invio di task contiene le stesse parti concettuali:
- Modello / endpoint:
minimax-h3-max-turbo/image-to-video, presente nel percorso della richiesta e ripetuto nel corpo per chiarezza. - Immagine sorgente: il primo fotogramma. È il campo che distingue l'image-to-video dal text-to-video ed è anche il più soggetto a errori di validazione.
- Prompt: descrizione di movimento e scena. Descrivere solo ciò che cambia, non ciò che è già presente nell'immagine.
- Suggerimenti di generazione opzionali: controlli di durata e stile di risoluzione, se l'endpoint li offre. Inviare solo i parametri documentati nello schema; le chiavi sconosciute sono una causa frequente di risposte 4xx.
L'invio restituisce un identificatore di task e uno stato. Il video stesso arriva successivamente tramite una seconda richiesta: ecco perché la sezione sul polling qui sotto è importante quanto la chiamata di invio.
Una richiesta curl funzionante
Il comando seguente invia un task image-to-video. Prima di eseguirlo, sostituire i segnaposto (i token in maiuscolo tra parentesi angolari) con i propri valori.
curl -X POST "https://api.hiapi.ai/v1/<ENDPOINT_PATH>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3-max-turbo/image-to-video",
"image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
"prompt": "Slow push-in on the product, soft studio light shifting across the surface, shallow depth of field."
}'
Alcune note pratiche su questo comando:
- Leggere la chiave da una variabile d'ambiente.
$HIAPI_API_KEYevita che la chiave finisca nella cronologia della shell, a condizione di esportarla invece di incollarla inline. - Per i primi test usare un URL immagine pubblico. In questo modo si esclude il fattore codifica base64 e si conferma che autenticazione e connessione funzionano.
- Mantenere compatto il corpo JSON. Il payload di
-dè l'intera richiesta; una virgola mancante qui produce un 400 confuso anziché un chiaro errore di schema. - Mettere tra virgolette il prompt. I prompt con punteggiatura rompono le stringhe di shell non quotate.
La risposta è un oggetto task, non un video. Catturare da esso l'ID del task: servirà per la richiesta di polling. Se la chiamata fallisce immediatamente, saltare alla sezione di risoluzione dei problemi; gli errori di autenticazione e di payload si manifestano in questa fase, non più tardi.
La stessa richiesta in Python
Di seguito è riportata la chiamata di invio equivalente in Python con requests. Presuppone che HIAPI_API_KEY sia impostata nelle variabili d'ambiente.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1/<ENDPOINT_PATH>"
payload = {
"model": "minimax-h3-max-turbo/image-to-video",
"image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
"prompt": (
"Slow push-in on the product, soft studio light shifting "
"across the surface, shallow depth of field."
),
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
response.raise_for_status()
job = response.json()
print(job["id"], job.get("status"))
Punti da mantenere quando si adatta questo frammento:
- Il timeout non è opzionale. L'invio è rapido, ma un socket bloccato in un handler di richieste web trascinerà giù anche il worker.
- Chiamare
raise_for_status()prima di analizzare la risposta. Trasforma un 401 silenzioso in un'eccezione che si può effettivamente registrare. - Restituire l'ID del task, non la risposta. In un servizio, la funzione di invio dovrebbe restituire l'identificatore, così che un poller separato (o un task in background) si occupi dell'attesa.
- Salvare il payload in una variabile. Dopo una chiamata riuscita, sostituire l'URL dell'immagine con un URL di upload firmato o una stringa base64 richiede una sola riga.
Qui si usa deliberatamente un client HTTP semplice anziché una libreria wrapper: la forma della richiesta è il contratto, e dovrebbe essere riproducibile in qualsiasi linguaggio usato dal proprio stack.
Preparare l'immagine e il primo fotogramma
La maggior parte dei task image-to-video falliti fallisce sull'immagine, non sul prompt. Alcune abitudini lo evitano.
Formato e consegna
Usare un formato raster standard e ampiamente supportato (JPEG o PNG) e assicurarsi che l'URL sia pubblicamente accessibile, senza cookie, senza reindirizzamenti a pagine di login e senza dipendere da firme che scadono dopo l'invio. Se le risorse si trovano in un bucket privato, generare un URL firmato con una durata chiaramente superiore al tempo di esecuzione previsto del task. Per i payload base64, se lo schema si aspetta i byte codificati grezzi, rimuovere il prefisso data-URI e assicurarsi che la dimensione dopo la codifica sia ben entro i limiti documentati.
Dimensioni e composizione
Il modello renderizza il video con dimensioni di output fisse, quindi l'immagine sorgente viene adattata. Due conseguenze:
- Allineare il rapporto d'aspetto desiderato. Inviare una foto verticale a un rendering orizzontale comporterà ritaglio o bande nere, e il soggetto potrebbe risultare fuori centro.
- Lasciare margine per il movimento. Se il prompt descrive un'inquadratura che avanza o un soggetto che si muove verso l'alto, lasciare spazio in quella direzione nell'immagine sorgente.
Mantenere integro il primo fotogramma
Il fotogramma iniziale dipende principalmente dall'immagine stessa. Scrivere il prompt come istruzione su ciò che accade dopo il primo fotogramma: descrivere il comportamento della camera, l'azione del soggetto e le variazioni di illuminazione. Evitare di ridescrivere la scena: quando l'immagine mostra già "una sedia rossa su un pavimento bianco", ripetere la descrizione tende ad aumentare la deriva anziché la fedeltà. Se il risultato si discosta dall'immagine sorgente, abbreviare prima il prompt e solo dopo considerare la sostituzione dell'immagine.
Non presumere l'esistenza di parametri non documentati. Se il controllo desiderato non è nello schema, ottenerlo tramite il prompt o la preparazione dell'immagine.
Gestire il ciclo di vita dei task asincroni
I task image-to-video non sono sincroni. Il pattern è invio → polling → recupero, e un'integrazione in produzione dovrebbe implementare esplicitamente tutti e tre i passaggi.
1. Inviare e persistere
Inviare la richiesta e memorizzare immediatamente l'ID del task restituito, preferibilmente insieme al proprio ID di correlazione, all'hash del payload della richiesta e a un timestamp. Se il processo muore tra l'invio e la memorizzazione, si è pagato per un task che non si può recuperare.
2. Polling con backoff
Usare l'ID memorizzato per interrogare l'endpoint di stato del task. Il rendering video richiede sensibilmente più tempo della generazione di immagini, quindi:
- Iniziare con un intervallo moderato (qualche secondo) e aumentarlo man mano che il task si allunga, anziché martellare l'endpoint a ritmo fisso.
- Limitare il tempo di attesa totale a una soglia adeguata al task, poi considerarlo scaduto e decidere se riprovare.
- Trattare gli stati terminali come tali: una volta che il task segnala successo o fallimento, smettere di interrogare.
import time
def wait_for_job(poll_fn, job_id, max_wait=600):
deadline = time.time() + max_wait
interval = 5
while time.time() < deadline:
job = poll_fn(job_id)
if job["status"] in ("succeeded", "failed"):
return job
time.sleep(interval)
interval = min(interval * 1.5, 30)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
3. Recuperare e archiviare l'output
In caso di successo, l'oggetto task contiene la posizione del risultato. Scaricare il video tempestivamente e copiarlo nel proprio storage: l'URL di output va considerato una risorsa temporanea, non la propria libreria di asset permanente. Registrare l'ID del task accanto al file archiviato, così che l'assistenza possa risalire da qualsiasi clip alla relativa richiesta.
Per i retry, interrogare di nuovo solo i task di cui si è memorizzato l'ID; non reinviare mai alla cieca, altrimenti si generano rendering e addebiti duplicati.
Risoluzione degli errori più comuni
Errori di autenticazione (401 / 403)
Controllare prima l'header Authorization: la parola Bearer, uno spazio, poi la chiave, senza newline finali dovuti alla copia della chiave. Verificare che la chiave sia attiva e appartenga all'account previsto. Se curl funziona e Python no, stampare la lunghezza dell'header: una variabile d'ambiente vuota produce un token apparentemente valido ma inutile.
Immagini malformate o non supportate (400 / 422)
Il fallimento più comune dopo quelli di autenticazione. Verificare in ordine:
- L'URL dell'immagine si risolve davvero e non reindirizza a una pagina HTML di login.
- Il formato è JPEG o PNG, non WebP, HEIC o una miniatura PDF.
- La dimensione dopo codifica o download rientra nei limiti documentati.
- Il payload base64 non ha il prefisso
data:né spazi dovuti a newline. - L'immagine non è corrotta: recuperarla e aprirla prima di dare la colpa all'API.
Parametri sconosciuti o non validi
Un nome di campo scritto male, o un parametro non esposto dall'endpoint, di solito restituisce un errore di validazione che indica il campo. Rimuovere i parametri speculativi e ricostruire partendo dai requisiti minimi indicati nella documentazione.
Limiti di frequenza (429)
Applicare backoff esponenziale e rispettare eventuali suggerimenti di retry nella risposta. Non riprovare in un ciclo serrato: peggiora il limite. Se il problema si presenta spesso, inviare i task in batch tramite una coda anziché attivarli inline dalle richieste utente.
Timeout dei task e polling bloccato
Se un task non raggiunge mai uno stato terminale entro il proprio budget, registrare l'ID del task e la cronologia degli stati e smettere di interrogare. I timeout ricorrenti spesso indicano un'immagine troppo grande o anomala al momento dell'invio, quindi ricontrollare la sezione sulla preparazione dell'immagine. Non reinviare automaticamente senza un limite ai tentativi.
Checklist di produzione prima del rilascio
Prima che l'endpoint riceva traffico reale, verificare ciascuno dei seguenti punti:
- Timeout ovunque. Invio con timeout breve, polling con limite di attesa totale, retry con tetto rigido. Nessun ciclo
while Truesenza limiti. - Retry con backoff. Riprovare su 429 e 5xx transitori; non riprovare mai gli errori di validazione: fallirebbero allo stesso modo.
- ID dei task nei log. Registrare per ogni richiesta l'ID del task, il proprio ID di correlazione e lo stato finale. È l'artefatto di debug più utile che si possa conservare.
- Output nel proprio storage. Copiare i video completati dall'URL restituito allo storage persistente e conservare il riferimento all'immagine sorgente per la riproducibilità.
- Validazione delle immagini ai margini. Rifiutare formati errati e upload troppo grandi prima che raggiungano l'API, così che gli utenti ricevano subito un errore chiaro anziché un fallimento asincrono dopo qualche minuto.
- Consapevolezza dei costi. La generazione viene fatturata per ogni output video renderizzato, quindi tracciare volume e durata dei task per utente o funzionalità. Consultare il pannello prezzi corrente anziché codificare ipotesi nel codice o nella documentazione.
- Prompt canarino. Mantenere nella suite di test un set di immagini e prompt noti come validi ed eseguirlo dopo ogni modifica all'integrazione per confermare che il contratto della richiesta regga ancora.
Una volta gestito correttamente il ciclo di vita asincrono (invio, persistenza, polling, archiviazione), l'endpoint è lineare. Recuperare lo schema esatto dalla pagina del modello, poi applicare i pattern di invio e polling descritti sopra.
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