Tutoriale
Come chiamare hailuo-2.3/image-to-video tramite l'API HiAPI: curl e Python
In questa pagina
Cosa può fare hailuo-2.3/image-to-video e quando usarlo
hailuo-2.3/image-to-video è un modello image-to-video fornito tramite l'API unificata HiAPI. Gli si passa un'immagine statica come primo frame, più un prompt che descrive come il contenuto dovrebbe muoversi, e il modello genera un breve video che inizia da quell'immagine e ne sviluppa l'animazione.
La parola chiave è primo frame. Nel text-to-video il modello immagina l'intera scena dal prompt; nell'image-to-video il modello ancora composizione, soggetto, illuminazione e stile all'immagine fornita. È quindi la scelta giusta quando hai già un materiale visivo specifico da preservare — foto di prodotto, reference di personaggi, frame di storyboard, rendering concettuali — e vuoi sovrapporre il movimento invece di reinventarlo.
Scenari adatti a questo endpoint:
- Devi mantenere la coerenza con materiali esistenti. Una foto di prodotto non deve essere rigenerata in un prodotto leggermente diverso, ma deve animarsi.
- Stai costruendo uno storyboard o animatic a partire da frame statici e vuoi un'anteprima rapida del movimento.
- Ti serve una composizione controllata: inquadratura e posizione del soggetto derivano dall'immagine, e il prompt descrive solo il movimento.
Se non hai un'immagine di riferimento e vuoi che sia il modello a progettare l'inquadratura, oppure se i dettagli visivi si esprimono meglio a parole che fissandoli in un frame, è più adatto il text-to-video.
Prerequisiti e ottenimento della chiave API
Prima della prima richiesta servono tre cose: un account HiAPI, una chiave API e un URL di immagine per il primo frame accessibile pubblicamente.
Account e chiave API
Accedi a HiAPI e crea una chiave API nella console. Tratta la chiave come un segreto: conservala in una variabile d'ambiente, non incollarla nei file sorgente. Gli esempi di questa guida leggono da HIAPI_API_KEY.
export HIAPI_API_KEY="your-api-key-here"
URL immagine accessibile
L'immagine passata come primo frame deve essere recuperabile dal server — va bene un URL firmato di storage cloud, un link CDN o qualsiasi URL HTTPS pubblico; un percorso di file locale no. Se il materiale si trova in una posizione che richiede autenticazione, genera per la richiesta un URL firmato con scadenza.
Prima di automatizzare qualsiasi flusso, verifica nella documentazione di riferimento più recente dell'API HiAPI il percorso dell'endpoint, i nomi dei parametri e i valori consentiti attuali. Le interfacce dei modelli evolvono, e codificare nomi di parametri visti in tutorial obsoleti è una fonte comune e facilmente evitabile di errori. I prezzi correnti e le eventuali regole di quota sono indicati nel pannello prezzi del sito — controllali lì, non darli per scontati.
Struttura della richiesta: input immagine e parametri
Concettualmente una richiesta image-to-video comprende tre parti: l'identificatore del modello, l'immagine e i parametri di generazione.
Identificatore del modello
Ogni chiamata punta a hailuo-2.3/image-to-video. Tienilo in un unico punto del codice, così che in futuro cambiare modello richieda una sola riga.
Immagine del primo frame
È l'URL dell'immagine statica da cui parte il video. Il suo aspect ratio e la sua risoluzione determinano la geometria di base dell'output, quindi scegli un'immagine che abbia già la composizione desiderata, invece di ritagliarla in seguito. Un'immagine pulita, ben illuminata e con un soggetto chiaro produce un movimento molto più prevedibile rispetto a un collage disordinato.
Prompt
Il campo testuale che descrive il movimento — lo trattiamo nella sezione successiva.
Durata e risoluzione
Le attività image-to-video offrono solitamente opzioni per la lunghezza del clip e la risoluzione dell'output. Questi parametri sono i più soggetti a cambiare con la versione del modello, quindi non codificarli a memoria. Apri la documentazione di riferimento più recente dell'API, leggi i nomi dei campi accettati e i valori consentiti, e inserisci questi valori in un oggetto di configurazione invece di spargere letterali nel codice. Se un valore viene rifiutato, la risposta dell'API di solito indica quale campo è problematico.
Il corpo della richiesta è JSON; la risposta restituisce l'identificatore dell'attività, non il video finito, come discusso nella sezione sul polling più avanti.
Scrivere prompt che producano un movimento credibile
L'immagine descrive già cosa c'è nella scena. Il compito del prompt è descrivere come si muove. Un prompt che ridescrive il soggetto spreca capacità del modello; un prompt che specifica movimento, comportamento della camera e leggi fisiche produce clip molto migliori.
Descrivi il movimento, non il contenuto
Esempio scarso: "Una donna con un cappotto rosso in piedi su un ponte."
Esempio migliore: "La donna gira lentamente la testa verso la camera, il cappotto ondeggia nel vento; la camera avanza dolcemente."
Separa il movimento del soggetto dal movimento della camera
Sii esplicito su entrambi. "Avanzamento lento in avanti", "deriva a mano libera", "camera fissa" e "orbita verso destra" indicano come cambia l'inquadratura stessa; "i capelli ondeggiano", "il vapore sale" e "le pagine si sfogliano" descrivono ciò che accade dentro l'inquadratura. Combinare i due aspetti è ciò che produce una ripresa coerente invece di un'immagine che va alla deriva.
Rispetta le leggi della fisica
Richiedi movimenti ragionevoli a velocità ragionevoli: "il tessuto si muove leggermente", "l'acqua scorre a valle", "il fumo si arriccia verso l'alto". Evita istruzioni in contraddizione con la scena — far camminare un soggetto seduto, o chiedere una panoramica rapida per un'inquadratura di prodotto a camera fissa, di solito produce artefatti.
Rimani breve e specifico
Due o tre frasi concrete e fisiche valgono più di un intero paragrafo di aggettivi. Indica prima il movimento principale, poi la camera, infine i dettagli secondari come i cambiamenti di illuminazione.
Inviare l'attività e fare polling del risultato
La generazione video richiede tempo, quindi l'API è asincrona. Il ciclo di vita si articola in tre fasi:
1. Creare l'attività
Invia via POST l'URL dell'immagine, il prompt e i parametri all'endpoint. Una risposta positiva restituisce l'identificatore dell'attività e lo stato iniziale, di solito simile a queued o processing. In quella risposta non c'è ancora il video.
2. Fare polling dell'attività
Invia periodicamente richieste GET per quell'identificatore di attività. Ogni risposta riporta lo stato e, al completamento, include il payload del risultato. Fai polling a intervalli ragionevoli — di solito a distanza di alcuni secondi — non in un ciclo serrato, e limita il numero di tentativi per evitare che un'attività bloccata faccia restare appeso il processo per sempre.
3. Ottenere il video
Quando lo stato riporta successo, la risposta contiene la posizione del video (di solito un URL), spesso insieme a metadati come la durata. Scaricalo o archivialo secondo le tue regole di conservazione.
Punti di progettazione per la produzione
- Persisti l'ID dell'attività. Se il tuo worker va in crash a metà polling, vuoi poter riprendere invece di reinviare e pagare per un'attività duplicata.
- Gestisci i fallimenti terminali. Le attività possono fallire; tratta il fallimento come un ramo separato, non come "continua a fare polling".
- Disaccoppia invio e polling. In un backend web, invia dal gestore della richiesta e fai polling da un worker in background, così un timeout HTTP non interrompe mai una generazione in corso.
Esempio curl eseguibile
L'esempio seguente invia un'attività. Sostituisci l'URL dell'immagine e il prompt con i tuoi; la chiave proviene dalla variabile d'ambiente impostata in precedenza.
curl -sS -X POST \
"https://api.hiapi.ai/v1/hailuo-2.3/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://your-cdn.example.com/first-frame.jpg",
"prompt": "Il soggetto si gira leggermente verso la camera e sorride; la camera avanza lentamente, una luce soffusa si muove sul viso."
}'
La risposta contiene l'identificatore dell'attività. Fai polling con una richiesta GET:
curl -sS \
"https://api.hiapi.ai/v1/hailuo-2.3/image-to-video/TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Ripeti finché lo stato non è di successo terminale, poi leggi l'URL del video dal payload. Il percorso esatto dell'endpoint e i nomi dei campi mostrati qui servono solo a illustrare il pattern — prima di incollare qualsiasi cosa nel codice di produzione, verificali con la documentazione di riferimento più recente dell'API, perché le interfacce dei modelli cambiano davvero.
Esempio Python eseguibile
Questo script invia l'attività, poi fa polling fino al completamento, includendo timeout e una gestione di base degli errori.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def create_task(image_url: str, prompt: str) -> str:
resp = requests.post(
BASE,
headers={**HEADERS, "Content-Type": "application/json"},
json={"image_url": image_url, "prompt": prompt},
timeout=60,
)
resp.raise_for_status()
data = resp.json()
task_id = data.get("task_id") or data.get("id")
if not task_id:
raise RuntimeError(f"No task id in response: {data}")
return task_id
def poll_task(task_id: str, timeout_s: int = 600, interval_s: int = 5) -> dict:
deadline = time.time() + timeout_s
while time.time() < deadline:
resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
data = resp.json()
status = str(data.get("status", "")).lower()
if status in {"succeeded", "success", "completed"}:
return data
if status in {"failed", "error", "cancelled"}:
raise RuntimeError(f"Task {task_id} failed: {data}")
time.sleep(interval_s)
raise TimeoutError(f"Task {task_id} did not finish in {timeout_s}s")
if __name__ == "__main__":
task = create_task(
image_url="https://your-cdn.example.com/first-frame.jpg",
prompt="Il vapore sale dalla tazza; la camera deriva lentamente verso destra.",
)
result = poll_task(task)
print(result)
Poiché le stringhe di stato possono variare tra versioni diverse dell'API, il codice controlla un piccolo insieme di valori comuni di successo e fallimento invece di un singolo letterale — verifica il vocabolario esatto nella documentazione di riferimento dell'API e ritaglia l'insieme di conseguenza. Se costruisci più pipeline multimediali, estrarre questa funzione di supporto ne facilita il riuso.
Modalità di errore comuni e metodi di debug
La maggior parte dei problemi con questo endpoint rientra nelle categorie seguenti.
Immagine rifiutata o non recuperabile
Il servizio deve poter scaricare la tua immagine. Se incontri errori di recupero o validazione, controlla che l'URL sia HTTPS pubblico, che non sia scaduto (gli URL firmati scadono) e che formato e dimensione rientrino nei limiti documentati. Un controllo rapido consiste nell'aprire l'URL in una finestra in incognito del browser — se chiede di effettuare l'accesso, il server non può leggerlo neanche lui.
Parametri non validi
Durata o risoluzione rifiutate, o campi sconosciuti, di solito restituiscono un errore di validazione che indica il campo. Confronta il tuo payload con la documentazione di riferimento più recente dell'API, non con i tutorial, e registra l'intero corpo dell'errore — il messaggio d'errore è più specifico del solo codice di stato HTTP.
Errori di autenticazione
401 o 403 significano quasi sempre che la chiave manca, è malformata o non ha i permessi di accesso. Verifica che l'header Authorization sia presente e che la variabile d'ambiente sia effettivamente esportata nella shell o nel processo che esegue la richiesta.
Timeout del polling
Se un'attività è ancora processing dopo il tuo timeout, controlla prima di aver interrogato l'ID di attività corretto, poi prolunga il timeout. In produzione, distingui "ancora in esecuzione" da "bloccato": persisti lo stato e lascia che il worker riprenda il polling, invece di reinviare, perché un reinvio spreca un'attività.
Attività fallita dopo l'invio
Un'attività fallita di solito rimanda alla combinazione di prompt e immagine — istruzioni di movimento contraddittorie, o un primo frame in conflitto con il movimento richiesto. Semplifica il prompt, prova un primo frame più pulito, poi esegui di nuovo.
L'output sembra sbagliato
Se il movimento è debole o strano, la soluzione è quasi sempre nel prompt: indica chiaramente il movimento principale, separa il comportamento della camera da quello del soggetto e mantieni il movimento fisicamente ragionevole. Registra nei log l'ID della richiesta e l'ID dell'attività, così da collegare le clip scadenti agli input esatti che le hanno prodotte. Prima di pubblicare, verifica i nomi dei parametri e i prezzi correnti nella documentazione di riferimento dell'API e nel pannello prezzi.
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