Tutoriale
Come chiamare wan2.7-video text-to-video tramite l'API HiAPI: curl e Python
In questa pagina
Cosa costruirai in questo tutorial
Al termine di questa guida avrai una piccola pipeline funzionante: invierai un'attività text-to-video a wan2.7-video/text-to-video tramite l'API HiAPI — prima con curl, poi con Python — e attenderai il completamento della generazione del video.
Le due chiamate sono volutamente equivalenti. La versione curl è l'implementazione di riferimento, da incollare nel terminale per verificare che credenziali e corpo della richiesta siano corretti. La versione Python racchiude la stessa richiesta in una funzione, pronta per essere inserita in uno script o in un servizio, e include polling, gestione degli errori e valori predefiniti ragionevoli.
Poiché la generazione video è molto più lenta di un completamento chat, l'intero flusso è asincrono: invii l'attività, ottieni un identificatore, poi esegui il polling finché l'attività non raggiunge uno stato terminale. Il testo seguente è organizzato attorno a questo ciclo di vita, così la struttura resterà valida anche se in futuro passerai a image-to-video o ad altri modelli video della stessa famiglia di endpoint.
Prima di inviare la prima richiesta
Perché la prima chiamata riesca servono tre condizioni.
Credenziali
Ti serve una chiave API HiAPI, da inviare come bearer token nell'header Authorization. Mettila in una variabile d'ambiente, non nel codice sorgente:
export HIAPI_API_KEY="your-key-here"
Un identificatore di modello noto
L'identificatore del modello è una stringa esatta. In questo tutorial il valore è wan2.7-video/text-to-video — incluso il suffisso del task. Varianti approssimative come wan2.7-video o wan2.7/text-to-video verranno rifiutate, quindi copia l'identificatore dall'elenco dei modelli invece di scriverlo a memoria.
Un prompt su cui valutare
Iterare alla cieca sulla generazione video costa caro. Scrivi in anticipo un prompt specifico (soggetto, azione, comportamento della camera, illuminazione, stile), così quando arriva il risultato potrai capire se è necessario regolare queste impostazioni anziché la formulazione.
Ti servono inoltre un client HTTP e un modo per leggere il JSON. Lato shell, curl più jq; lato script, Python più requests.
Anatomia del corpo della richiesta
Una richiesta text-to-video è un oggetto JSON i cui campi si dividono in tre gruppi.
Identità
model— l'identificatore esatto del modello, cioèwan2.7-video/text-to-video.
Contenuto
prompt— il testo che descrive il video desiderato. È il campo che conta di più; specifica movimento, composizione e stile invece di accumulare aggettivi.negative_prompt— facoltativo. Descrive ciò che non deve apparire. Utile per sopprimere difetti comuni, ma non sostituisce un prompt ben scritto.
Impostazioni di generazione
duration— la durata della clip di output.resolution— il livello di dimensione/risoluzione dell'output.seed— facoltativo. Fissalo quando vuoi confrontare due prompt o due modifiche di impostazioni partendo da un punto stabile.
Il corpo minimo della richiesta richiede solo model e prompt; la piattaforma applica i valori predefiniti agli altri campi. Ma i valori predefiniti non sono le tue scelte — per capire perché in produzione convenga impostarli esplicitamente, vedi la sezione su durata e risoluzione più avanti.
Mantieni il corpo della richiesta piatto e poco profondo. Annidare solo i campi che appartengono davvero a sotto-oggetti rende la richiesta più leggibile e gli errori di schema più facili da individuare.
Inviare l'attività con curl
Ecco un esempio completo di invio. L'endpoint riceve JSON e restituisce un handle dell'attività, non il video stesso.
curl -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-video/text-to-video",
"prompt": "carrellata lenta in avanti in un vicolo al neon bagnato dalla pioggia di notte, pozzanghere riflettenti sul terreno, profondità di campo ridotta, color grading cinematografico",
"duration": 5,
"resolution": "720p"
}'
In caso di invio riuscito viene restituito un oggetto contenente l'identificatore dell'attività o del job e lo stato. La struttura è più o meno questa:
{
"id": "job_abc123",
"status": "queued",
"model": "wan2.7-video/text-to-video"
}
Due cose da notare. Primo, status non è succeeded — a questo punto non è ancora stato renderizzato nulla. Secondo, nella risposta non c'è alcun URL del video. Quell'URL compare solo quando l'attività raggiunge uno stato terminale.
Se vuoi conservare l'identificatore nella sessione shell per il passaggio di polling:
JOB_ID=$(curl -s -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json | jq -r '.id')
echo "$JOB_ID"
Spostare il corpo della richiesta in payload.json mantiene il comando breve e rende più facile modificare il prompt tra un'esecuzione e l'altra.
Inviare l'attività con Python
La versione Python è la stessa richiesta, solo più comoda da usare. Ciò che in curl sono header o chiavi JSON, qui diventa argomento con nome.
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",
}
payload = {
"model": "wan2.7-video/text-to-video",
"prompt": (
"carrellata lenta in avanti in un vicolo al neon bagnato dalla pioggia di notte, "
"pozzanghere riflettenti sul terreno, profondità di campo ridotta, color grading cinematografico"
),
"duration": 5,
"resolution": "720p",
}
resp = requests.post(
f"{BASE_URL}/v1/video/generations",
headers=HEADERS,
json=payload,
timeout=30,
)
resp.raise_for_status()
job = resp.json()
print(job["id"], job["status"])
La corrispondenza con la versione shell è uno a uno:
-H "Authorization: ..."→ dizionarioHEADERS.-d '<json>'→json=payload. Passare un dizionario anziché una stringa significa che la serializzazione spetta arequests, quindi non si rischia di inviare JSON malformato..idestratto conjq→job["id"].
Ci sono due abitudini specifiche di Python che vale la pena adottare subito. Imposta sempre un timeout per la chiamata di invio — la richiesta è piccola e dovrebbe tornare rapidamente, quindi un blocco prolungato indica un problema di connessione, non di rendering. E chiama raise_for_status() prima di leggere il corpo della risposta, così un errore a livello HTTP produce un traceback chiaro invece di un confuso KeyError su job["id"].
Gestire attività asincrone e polling
Il polling è il punto in cui la maggior parte delle integrazioni diventa solida o instabile. Le attività hanno un ciclo di vita — tipicamente in coda, in elaborazione, poi successo o fallimento come stato terminale — e il tuo ciclo deve gestire tutti e tre i casi.
def wait_for_job(job_id, interval=5, max_attempts=120):
url = f"{BASE_URL}/v1/video/generations/{job_id}"
for attempt in range(max_attempts):
r = requests.get(url, headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status == "succeeded":
return data
if status in ("failed", "cancelled"):
raise RuntimeError(f"Job {job_id} ended as {status}: {data.get('error')}")
time.sleep(interval)
raise TimeoutError(f"Job {job_id} still not finished after {max_attempts} polls")
Ci sono alcuni dettagli di progettazione in questo ciclo la cui importanza è maggiore di quanto sembri:
Controlla esplicitamente gli stati terminali. Trattare ogni stato diverso da succeeded come “continua ad attendere” significa che le attività fallite esauriranno silenziosamente tutto il tuo budget di polling. Fai corrispondere gli stati di fallimento e solleva un'eccezione.
Scegli l'intervallo di polling con consapevolezza. Il rendering video richiede da decine di secondi a minuti. Eseguire il polling ogni 200 ms aggiunge solo carico e non ti dice nulla di nuovo. Parti da circa 5 secondi; se le attività durano spesso a lungo, aumenta l'intervallo invece del numero di tentativi.
Metti sempre un limite al ciclo. Un tetto su max_attempts trasforma un blocco infinito in un TimeoutError diagnosticabile. Registra anche l'ID dell'attività — è il valore che ti servirà per la diagnosi.
Rispetta i limiti di frequenza. Se invii in batch, non lanciare tutte le richieste di polling contemporaneamente. Usare un poller condiviso che gira a intervalli fissi, o un semplice throttling lato client, ti mantiene entro i limiti.
In caso di successo, la risposta contiene la posizione dell'asset completato. Scaricalo subito, non trattare il record dell'attività come archiviazione permanente.
Scegliere durata e risoluzione
Queste due impostazioni influenzano l'output più di qualsiasi altro parametro, e incidono entrambe sulla durata dell'attività e sui costi. Il consumo fatturato è calcolato in secondi di output, e la risoluzione determina il lavoro per secondo — quindi considerale entrambe scelte deliberate per il tuo caso d'uso, non campi da lasciare ai valori predefiniti.
Durata
Clip più lunghe danno spazio all'azione, ma ogni secondo aggiuntivo significa più rendering e costi più alti, e le generazioni lunghe tendono a mostrare più facilmente problemi di coerenza. Consigli pratici:
- Breve (pochi secondi) — loop per i social, hero visual di prodotto, B-roll. È il costo di iterazione più basso ed è il più facile da giudicare.
- Media — battute narrative, inquadrature di ambientazione.
- Lunga — usala solo quando la storia lo richiede davvero. Se ti serve un video lungo, valuta di generare più clip brevi e montarle insieme; di solito costa meno di un singolo rendering lungo e ti dà più controllo.
Mentre iteri sul prompt, genera la clip più breve consentita dal modello. Giudica composizione e movimento a questa durata, poi allunga quando sei soddisfatto.
Risoluzione
Risoluzione più alta significa più pixel per frame, tempi di rendering più lunghi e costi più alti. Ma su uno schermo piccolo conta meno di quanto pensi. Un master 1080p va bene per la consegna al cliente; una bozza a 720p (o inferiore) va bene per capire se il prompt funziona.
Il modello efficiente è un flusso di lavoro in due fasi: blocca prompt e durata a bassa risoluzione, poi riesegui l'attività finale alla risoluzione di consegna. Non iterare con le impostazioni più alte — spenderai la maggior parte del budget in materiale scartato.
Diagnosticare gli errori comuni
La maggior parte dei fallimenti deriva da come è strutturata la richiesta, non dal modello stesso. Prima di trarre conclusioni sulle capacità del modello, controlla in ordine le seguenti categorie di problemi.
401 / 403 — problemi di credenziali
Controlla che la chiave sia impostata nell'ambiente effettivamente visibile al processo (una chiave esportata in una shell non è visibile a un servizio systemd), che l'header sia Authorization: Bearer <key> e che la variabile non contenga spazi finali. Durante il debug stampa solo i primi caratteri della chiave, mai la chiave completa.
404 — percorso o modello errato
Il percorso dell'endpoint e l'identificatore del modello sono due cose diverse, ed entrambe devono essere esatte. Verifica l'URL a cui fai POST e verifica che wan2.7-video/text-to-video sia stato copiato carattere per carattere dall'elenco dei modelli. Una chiave valida con una stringa di modello errata restituisce comunque un errore assimilabile a not-found.
400 — corpo della richiesta malformato
È la categoria più comune. Le cause frequenti includono: campi numerici come duration inviati come stringa "5", prompt inviati come lista anziché stringa, o corpo della richiesta codificato accidentalmente due volte. Il modo più rapido per fare triage è reinviare esattamente lo stesso comando curl — se la chiamata shell riesce e quella Python fallisce, il problema è nel modo in cui lo script costruisce il dizionario, non nella richiesta stessa.
422 / errori di validazione
Sintassi valida ma semantica problematica: durata fuori dall'intervallo supportato, livello di risoluzione sconosciuto o campo obbligatorio mancante. Leggi il messaggio di errore — di solito indica il campo problematico.
Attività fallita dopo l'invio
La chiamata di invio riesce, ma il rendering no. Può essere un rifiuto per policy sui contenuti o un fallimento temporaneo del rendering. Registra l'ID dell'attività e il payload dell'errore; se si tratta di un problema temporaneo, reinviare lo stesso payload è un primo passo ragionevole. Se lo stesso prompt fallisce ripetutamente, cambia la formulazione del prompt o le impostazioni di generazione invece di ritentare la stessa richiesta più volte.
Il polling non termina mai
Se un'attività resta in elaborazione molto più a lungo di attività simili, interrompi il polling, registra l'ID dell'attività e trattala come fallita. I casi della coda lunga sono abbastanza rari che un timeout limitato con un messaggio di errore esplicito sia meglio di un ciclo aperto.
Per ogni nuovo problema, parti dall'implementazione di riferimento in curl: esclude il tuo codice dall'equazione, isolando se il problema è nella richiesta o nel client.
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