Tutoriale
Come usare pixverse-v6-max image-to-video tramite l'API HiAPI: curl, Python e una richiesta funzionante
In questa pagina
Cosa richiede l'endpoint pixverse-v6-max image-to-video
L'endpoint pixverse-v6-max/image-to-video su HiAPI è un'attività di generazione video asincrona condizionata da un'immagine. Questa singola frase determina quasi ogni decisione che prenderai durante l'integrazione.
L'endpoint riceve un'immagine di origine (il primo fotogramma) e un insieme di parametri di generazione, e restituisce un riferimento all'attività, non un video finito. Il rendering effettivo avviene lato server e, a seconda dei parametri scelti, può richiedere da pochi secondi a diversi minuti. Il tuo client è responsabile dell'invio dell'attività e poi dell'interrogazione ripetuta del suo stato finché non riporta uno stato terminale.
Confrontalo con la modifica sincrona delle immagini: nella modifica sincrona invii un corpo con POST e ricevi l'immagine trasformata nella stessa risposta HTTP. Qui invece il flusso è:
- Invia con
POSTla tua immagine e i parametri all'endpoint di generazione. - Ricevi un identificatore di attività (di solito insieme a uno stato iniziale).
- Esegui con cadenza
GETsullo stato dell'attività finché non viene completata o fallisce. - Leggi l'URL del video generato dal corpo della risposta dell'attività completata.
A causa di questa separazione esistono due classi distinte di errori: problemi in fase di invio (errori di autenticazione, corpo della richiesta malformato, immagine rifiutata) e problemi in fase di esecuzione (l'attività viene accettata ma poi fallisce o si blocca). Una buona integrazione gestisce esplicitamente entrambe: la checklist concreta è nella sezione di risoluzione dei problemi più avanti.
C'è un altro punto da tenere a mente: l'immagine di origine è l'ancora. Il modello anima a partire da questo primo fotogramma, quindi la qualità, le proporzioni e il contenuto dell'immagine influenzano l'output più di qualsiasi testo di prompt tu fornisca. Tratta la correttezza del caricamento come preoccupazione primaria, non come un ripensamento.
Prepara la tua chiave API e l'endpoint
Prima di effettuare la prima richiesta hai bisogno solo di due cose: una chiave API HiAPI e l'URL di base corretto per l'endpoint.
Ottieni la tua chiave
Crea una chiave API nella console del tuo account HiAPI. Trattala come una password: mettila in una variabile d'ambiente, non nel codice sorgente o nella cronologia della shell.
export HIAPI_API_KEY="your_key_here"
Se usi localmente un file .env, aggiungilo a .gitignore prima di fare qualsiasi commit. Qualsiasi chiave comparsa in log condivisi, screenshot o repository di codice deve essere ruotata immediatamente.
Conosci il tuo URL di base e il percorso
L'endpoint si trova sotto l'host dell'API HiAPI, con il percorso del modello pixverse-v6-max/image-to-video. Negli esempi seguenti l'URL di base è mostrato come https://api.hiapi.ai e il percorso completo viene concatenato da esso. Se il tuo account o la tua regione ti fornisce un host diverso, sostituiscilo in modo coerente: un host e una chiave non corrispondenti sono una delle cause più comuni di 401, che gli sviluppatori spesso interpretano erroneamente come "chiave non valida".
Scegli i tuoi strumenti
- curl per una prima verifica rapida: elimina tutte le variabili tranne la richiesta stessa.
- Python 3 con
requests(ohttpx) per l'integrazione reale.
python3 -c "import requests; print(requests.__version__)"
Se stampa un numero di versione, sei pronto. Gli esempi in questo articolo non richiedono l'installazione di un SDK; tutto è HTTP puro, il che significa anche che potrai portarlo in qualsiasi linguaggio in seguito. Una volta confermati chiave e host, puoi iniziare a costruire la richiesta.
Costruisci la richiesta con curl
Inizia con la richiesta minima che può davvero avere successo, poi aggiungi parametri. Il corpo della richiesta qui sotto mostra la struttura di un invio completo di image-to-video.
curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://your-cdn.example.com/first-frame.jpg",
"duration": 5,
"aspect_ratio": "16:9"
}'
Qui accadono tre cose:
- L'autenticazione è trasportata nell'header
Authorizationcome bearer token. - Il corpo è JSON, quindi l'immagine è fornita come stringa URL (come passare invece un file locale è descritto nella sezione successiva).
- Due parametri di generazione —
durationeaspect_ratio— sono campi di primo livello.
Un invio riuscito restituisce un oggetto JSON contenente un identificatore di attività. Catturalo:
JOB_ID=$(curl -s -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image":"https://your-cdn.example.com/first-frame.jpg","duration":5,"aspect_ratio":"16:9"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "$JOB_ID"
Poi interrogalo:
curl -s "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
In caso di errore controlla sempre il campo di stato e il corpo grezzo della risposta di errore. curl può stampare JSON di errore anche con codice di uscita 0, quindi negli script non affidarti solo al codice di uscita.
Fornisci correttamente l'immagine del primo fotogramma
L'immagine di origine è il punto di fallimento più comune; quasi ogni rifiuto si riduce a una delle quattro cause seguenti.
1. L'immagine non è raggiungibile
Quando passi un URL, i server di HiAPI devono poterla GET — dalla loro rete, non dalla tua. Un URL localhost, un bucket privato, un URL firmato che scade dopo sessanta secondi o un endpoint dietro una VPN falliranno. Usa un URL di object storage o un link CDN pubblicamente leggibile e verifica che si carichi in una nuova sessione del browser senza cookie.
2. Il formato dell'immagine non è supportato
Attieniti ai formati web standard: JPEG, PNG, WebP. File con estensioni insolite, HEIC acquisiti da un telefono o GIF animate sono rischiosi. Se la tua pipeline produce un formato esotico, transcodificalo prima.
3. Il primo fotogramma non corrisponde alle proporzioni dichiarate
Questo è più sottile. Se la tua immagine di origine è quadrata ma richiedi 16:9, il servizio deve ritagliare, riempire o rifiutare quell'input. Il comportamento può variare, e nessuna delle tre opzioni è ciò che la maggior parte degli sviluppatori vuole. Ritaglia o aggiungi bande nere tu stesso prima del caricamento in modo che la geometria dell'immagine corrisponda già all'aspect_ratio che richiederai. Questo rende l'output prevedibile ed evita di sprecare un'attività.
4. L'immagine è troppo grande o troppo piccola
Immagini fisse a risoluzione estremamente elevata (ad esempio output di fotocamere 8K) consumano banda e possono essere rifiutate o ridimensionate; miniature minuscole lasciano al modello quasi nulla da animare. Normalizza l'immagine a una dimensione ragionevole del lato lungo come parte della fase precedente al caricamento.
Passare un file locale
Se l'endpoint accetta caricamenti multipart per il campo immagine, il modello è:
curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-F "image=@./first-frame.jpg" \
-F "duration=5" \
-F "aspect_ratio=16:9"
Nota che con multipart i campi numerici diventano stringhe. Consulta la documentazione di riferimento dell'endpoint per sapere quali tipi di contenuto sono accettati e preferisci la forma con URL nelle pipeline di produzione: così i grandi file binari non transitano affatto sul tuo server applicativo.
Imposta durata e proporzioni
Questi due campi influenzano costo e output più di qualsiasi altro contenuto nel corpo della richiesta.
duration
duration è espressa in secondi e rappresenta la lunghezza della clip generata. È anche il campo più direttamente legato alla fatturazione: il prezzo in tempo reale si basa sulla durata dell'output richiesta, quindi scegli con attenzione invece di prendere il valore massimo per impostazione predefinita. Consigli pratici:
- Inizia con la durata più breve che racconta la tua storia. Una clip di 5 secondi è perfetta per loop, teaser di prodotto o agganci social.
- Usa durate più lunghe solo quando l'inquadratura ha davvero bisogno di più tempo; un primo fotogramma statico animato a lungo tende a derivare e perdere coerenza.
- Valida lato client: rifiuta valori non interi, zero, negativi e numeri assurdamente grandi prima che la richiesta lasci il tuo servizio.
if not isinstance(duration, int) or not 1 <= duration <= 8:
raise ValueError("duration out of supported range")
Verifica l'intervallo attualmente supportato nella documentazione di riferimento dell'endpoint e rispecchialo nella tua logica di validazione: non codificare in modo fisso le ipotesi di questo articolo.
aspect_ratio
aspect_ratio è una stringa, ad esempio "16:9", "9:16" o "1:1". Controlla la geometria del fotogramma di output.
16:9per l'orizzontale: YouTube, video hero per il web, riproduzione desktop.9:16per il verticale: Reels, Shorts, pubblicazioni in stile TikTok.1:1per feed e miniature.
Due regole ti evitano problemi. Primo, fai corrispondere l'immagine di origine al rapporto richiesto: un primo fotogramma verticale in una richiesta orizzontale produce un ritaglio che molto probabilmente non desideri. Secondo, tratta il rapporto come un'enumerazione, non come testo libero: valida rispetto a una whitelist, così un errore di battitura come "16x9" fallisce rapidamente nel tuo codice invece che dopo un round trip.
Tutto il resto
Se l'endpoint espone ulteriori controlli di generazione, lasciali fuori dalla tua prima richiesta. Un corpo minimo e verificato è la tua linea di base; aggiungi un parametro alla volta e confronta gli output. Questa disciplina rende ovvio quale campo ha causato una regressione.
Implementa la stessa richiesta in Python
Quella che segue è la traduzione in Python del flusso curl. Mantiene deliberatamente le dipendenze snelle: requests più la libreria standard.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def submit(image_url: str, duration: int = 5, aspect_ratio: str = "16:9") -> str:
resp = requests.post(
f"{BASE}/v1/pixverse-v6-max/image-to-video",
headers={**HEADERS, "Content-Type": "application/json"},
json={"image": image_url, "duration": duration, "aspect_ratio": aspect_ratio},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def fetch(job_id: str) -> dict:
resp = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
job_id = submit("https://your-cdn.example.com/first-frame.jpg")
print("submitted", job_id)
Alcune scelte deliberate da cui prendere spunto:
- Chiama
raise_for_status()all'invio. Un400o un401dovrebbero emergere subito come eccezione, invece di trasformarsi in unKeyErrorquando provi a leggere["id"]dal corpo della risposta di errore. - Timeout espliciti. Senza timeout, una connessione bloccata blocca il tuo worker all'infinito.
- Configurazione letta dall'ambiente. L'URL di base e la chiave non sono mai codificati nel codice.
- Funzioni di supporto piccole e tipizzate.
submitrestituisce la stringa dell'id dell'attività;fetchrestituisce un dizionario. Centralizzare l'analisi in un unico punto significa che un cambiamento di schema richiede una sola riga.
Se preferisci httpx, basta sostituire con httpx.post(...) e httpx.get(...); la chiamata è per il resto identica. Per qualsiasi cosa eseguita all'interno di un gestore di richieste web, invia qui e poi passa l'id dell'attività a un worker in background, invece di bloccare la richiesta HTTP dell'utente sulla generazione del video.
Interroga l'attività asincrona fino al completamento
L'interrogazione è la parte che la maggior parte dei tutorial sorvola e l'origine della maggior parte degli incidenti. Il ciclo in sé è breve; la disciplina che lo circonda è ciò che conta.
def wait_for_video(job_id: str, timeout: int = 600, interval: int = 5) -> str:
deadline = time.time() + timeout
while time.time() < deadline:
job = fetch(job_id)
status = job.get("status")
if status == "completed":
return job["output"]["video_url"]
if status in ("failed", "cancelled"):
raise RuntimeError(f"job {job_id} ended as {status}: {job.get('error')}")
time.sleep(interval)
raise TimeoutError(f"job {job_id} did not finish within {timeout}s")
Punti chiave codificati sopra:
- Imposta sempre una scadenza. La generazione video è lenta; un ciclo illimitato diventa fatturazione illimitata e worker bloccati. Per clip brevi, dieci minuti sono un limite ragionevole: adattalo alle impostazioni di durata.
- Distingui gli stati terminali. Solo
completedproduce un URL. Anchefailedecancelledsono stati terminali: interrompi l'interrogazione ed esponi il campo error. - Usa un intervallo ragionevole. Ogni pochi secondi è sufficiente. Tempestare di richieste l'endpoint di stato ti fa finire nella limitazione di frequenza e non ti dice nulla di nuovo.
- Backoff moderato per attività lunghe: dopo il primo minuto, aumenta l'intervallo da 3 a 10 secondi. Riduce il carico senza aggiungere costi di latenza.
- Persisti l'id dell'attività. Salvalo insieme ai tuoi record, così se il processo si riavvia puoi riprendere l'interrogazione senza reinviare — e ripagare — la stessa attività.
- Non interrogare mai direttamente dal browser con la tua chiave API. Fai passare i controlli di stato tramite il tuo backend.
Quando l'attività è completata, scarica prontamente il video nel tuo storage invece di collegarti per sempre all'URL restituito; gli URL delle risorse generate non sono garantiti permanenti.
Diagnostica attività fallite e bloccate
Segui questa checklist in ordine. Ogni passaggio isola un livello.
Errori di invio (l'attività non è mai stata creata)
401 Unauthorized— chiave mancante, malformata, revocata o abbinata all'host sbagliato. Verifica che l'header sia esattamenteAuthorization: Bearer <key>, con un solo spazio nel mezzo, e che la variabile d'ambiente non contenga newline extra.403 Forbidden— la chiave è valida ma non è autorizzata per questo modello o endpoint. Controlla carattere per carattere il percorso della risorsa:pixverse-v6-max/image-to-video.400 Bad Request— il tuo JSON è malformato o un campo non è valido. Decodifica il corpo della risposta di errore; di solito indica il campo problematico. Colpevoli comuni:durationcome stringa invece che numero,"16x9"invece di"16:9",imagemancante.- Errori di validazione tipo
422— il campo esiste ma è fuori intervallo. Confronta con la documentazione di riferimento dell'endpoint invece di tirare a indovinare. 429 Too Many Requests— hai inviato troppo velocemente. Metti in coda gli invii e riprova con backoff esponenziale e jitter; non riprovare mai in un ciclo stretto.
Errori di esecuzione (l'attività è stata creata ma non è riuscita)
- Stato
failedcon un errore relativo all'immagine — il recupero dell'URL di origine è fallito dopo l'invio. È la classica trappola del "funziona nel mio browser": quell'URL richiede cookie, referrer o un'allowlist di IP. Ripubblica l'immagine pubblicamente. - Stato
failedcon un errore di contenuto o validazione — l'immagine di origine è stata rifiutata per motivi tecnici (formato, geometria, dimensione). Transcodifica, ridimensiona e ritaglia di nuovo sul rapporto dichiarato. - L'attività resta in coda o in elaborazione oltre la tua scadenza — prima conferma di leggere l'id dell'attività corretto (gli errori di copia e incolla sono sorprendentemente comuni). Poi verifica se lo stato è davvero invariato o se l'interrogazione ha colpito l'URL di base sbagliato. Se è davvero bloccata, annulla e reinvia una volta, se l'API lo consente; reinviare ripetutamente in silenzio è esattamente il modo in cui il budget svanisce.
Un'abitudine che fa risparmiare tempo
Registra per ogni chiamata l'id completo della richiesta, l'id dell'attività, lo stato HTTP e il corpo della risposta — oscurando la chiave. Quando qualcosa va storto alle due di notte, un id di richiesta fa la differenza tra una correzione di cinque minuti e un'ora di supposizioni. Parti da un corpo minimo e verificato, aggiungi un parametro alla volta, e quasi non avrai bisogno 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