Tutoriale
Come chiamare seedance-2.5-flash reference-to-video tramite l'API HiAPI (curl + Python)
Richieste funzionanti, uno script Python eseguibile e come gestire il polling dei task asincroni
In questa pagina
Cosa significa concretamente reference-to-video
Reference-to-video è una modalità di generazione in cui fornisci al modello due cose contemporaneamente: un prompt testuale che descrive movimento e scena, e uno o più materiali di riferimento che ancorano il contenuto visivo. Il prompt trasporta l'intento ("lento avvicinamento, il personaggio si gira e sorride"), i materiali di riferimento trasportano identità e aspetto (un personaggio, un prodotto, uno stile visivo).
L'endpoint del modello per questo flusso di lavoro è seedance-2.5-flash/reference-to-video, erogato tramite l'API unificata di HiAPI. Inserisci model, prompt e materiali di riferimento insieme in un unico corpo della richiesta. Non c'è un passaggio di upload separato da orchestrare, né un registro per singolo materiale da mantenere.
La conseguenza pratica è che si tratta di un'operazione di lunga durata. Il rendering di un video breve richiede comunque molto più tempo di un completamento testuale, quindi l'API tratta la chiamata come un task asincrono. La tua richiesta crea il task; una seconda chiamata ne recupera il risultato. Questa forma "prima invia, poi esegui il polling" è l'aspetto più importante da considerare in fase di progettazione, ed è la direzione su cui è costruito il resto di questo tutorial.
Tutto quanto segue resta all'interno dell'interfaccia HiAPI: un URL di base, un header di autenticazione, una famiglia di endpoint.
Prima di inviare la prima richiesta
Tre cose devono essere pronte prima della prima chiamata.
1. La chiave API
Crea la chiave nella console HiAPI e tienila lontana dal controllo di versione. Gli esempi seguenti la leggono da una variabile d'ambiente:
export HIAPI_API_KEY="your_key_here"
Se non sei sicuro del formato attuale della chiave o della convenzione degli header, consulta la documentazione API della piattaforma nella console: non tirare a indovinare e non codificare la chiave direttamente in uno script che potresti condividere.
2. URL di base e header di autenticazione
Tutte le chiamate vanno all'URL di base di HiAPI e trasportano la tua chiave nell'header Authorization. Impostalo una volta come variabile, così ogni richiesta resta coerente:
export HIAPI_BASE_URL="https://api.hiapi.ai"
Usa l'URL di base esattamente come indicato nella documentazione del tuo account: una barra finale non corrispondente è una causa comune di 404 confusi.
3. L'endpoint del modello
Il tuo obiettivo è seedance-2.5-flash/reference-to-video. Fai riferimento a esso con questo identificatore nel corpo della richiesta, invece di incorporarlo nel percorso, così in futuro cambiare modello richiederà una sola riga.
Devi anche rendere i materiali di riferimento accessibili via URL (o nella forma di materiale specificata dalla documentazione dell'endpoint). Ospitali e rendili pubblicamente accessibili prima di iniziare: un URL di riferimento non valido è la causa più comune di un task inviato con successo ma fallito durante la generazione.
Con queste tre cose impostate, puoi costruire il corpo della richiesta.
Costruire il corpo della richiesta con i materiali di riferimento
Il corpo della richiesta ha tre parti concettuali: quale modello usare, cosa vuoi, a cosa fare riferimento.
Il modello
Imposta model su seedance-2.5-flash/reference-to-video. Trattalo come un campo stringa normale: nessuna codifica URL, nessun segmento di percorso.
Il prompt
Scrivi il prompt come descrizione di un'inquadratura, non come una lista di desideri. Specifica soggetto, azione, comportamento della camera e ritmo. "Una persona con una giacca rossa cammina verso la camera, piano medio, lento avvicinamento, luce diurna soffusa" fornisce al modello molte più informazioni di "un bel video di una persona". Mantieni il prompt coerente con i materiali di riferimento che fornisci: se due materiali di riferimento mostrano personaggi diversi, indica quale è dominante.
I materiali di riferimento
I materiali di riferimento sono ciò che distingue questo endpoint da una normale chiamata text-to-video. Passi uno o più materiali che definiscono cosa deve rimanere coerente tra i fotogrammi. Regole pratiche che fanno risparmiare iterazioni:
- Usa il numero minimo di materiali di riferimento che determina l'identità. Un riferimento forte di solito vale più di quattro riferimenti mediocri.
- Mantieni i materiali di riferimento coerenti tra loro. Angolazioni o stili in conflitto causano derive nell'output.
- Preferisci materiali di origine puliti e ben illuminati. Materiali di riferimento ritagliati, sfocati o con filtri pesanti propagano questi difetti.
- Verifica che ogni URL sia risolvibile prima dell'invio: recuperalo tu stesso una volta.
Come vengono effettivamente strutturati i materiali di riferimento nel corpo della richiesta (nome del campo array, struttura dell'oggetto, tipi di materiale supportati) deve derivare dallo schema di richiesta dell'endpoint nella documentazione HiAPI. Costruisci il corpo della richiesta in base a quello schema, non a memoria; lo schema è la fonte autorevole dei nomi dei campi, e una chiave non corrispondente causa un fallimento silenzioso.
Valida il JSON in locale prima che la richiesta raggiunga la rete (python -m json.tool body.json). Un corpo della richiesta malformato è l'errore più facile da intercettare e anche il più fastidioso da diagnosticare da uno stack trace.
Una richiesta curl funzionante
Il comando seguente segue il pattern prima invia, poi esegui il polling: crea il task e stampa la risposta JSON che contiene l'identificatore del task che userai per il polling.
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/reference-to-video",
"prompt": "Una persona con una giacca rossa cammina verso la camera, piano medio, lento avvicinamento, luce diurna soffusa",
"references": [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png"
]
}'
Sostituisci gli URL di riferimento con materiali ospitati da te e, prima di dipendere da questo codice in produzione, verifica il percorso dell'endpoint e i nomi dei campi nella pagina del modello nella documentazione HiAPI: i dettagli dello schema sono autorevoli, questo frammento è solo illustrativo.
Cosa osservare nella risposta:
- Un id (o identificatore task/job): catturalo; ti servirà per ogni polling.
- Un campo status che indica che il task è stato accettato.
- Eventuali avvisi su materiali ignorati o rifiutati.
Per una lettura più agevole, formattalo in modo leggibile:
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @body.json | python -m json.tool
Salvare il corpo della richiesta in body.json vale questo piccolo passaggio in più: è facilmente versionabile, confrontabile in modo leggibile e rimuove dal perimetro di debug gli errori di quoting della shell.
La stessa chiamata in Python
Di seguito la chiamata equivalente in Python, scritta per essere eseguibile direttamente dopo aver impostato le variabili d'ambiente. Usa solo la libreria standard, quindi non serve installare nulla.
import json
import os
import urllib.request
BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
def submit_reference_video(prompt, references):
body = {
"model": "seedance-2.5-flash/reference-to-video",
"prompt": prompt,
"references": references,
}
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations",
data=json.dumps(body).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req, timeout=60) as resp:
payload = json.loads(resp.read().decode("utf-8"))
return payload
if __name__ == "__main__":
result = submit_reference_video(
prompt="Una persona con una giacca rossa cammina verso la camera, piano medio, lento avvicinamento, luce diurna soffusa",
references=[
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png",
],
)
print(json.dumps(result, indent=2))
job_id = result.get("id")
print("job id:", job_id)
Due dettagli contano più di quanto sembri. Primo, timeout=60: la chiamata di invio dovrebbe restituire rapidamente, ma una connessione bloccata è peggio di un fallimento rapido. Secondo, result.get("id") gestisce i casi in cui la struttura della risposta è inattesa, invece di sollevare un KeyError nel tuo percorso normale.
Se preferisci requests o httpx, la conversione è diretta: stesso URL, stessi header, stesso corpo JSON. La costruzione del corpo della richiesta è la parte che vale la pena copiare; il client HTTP è sostituibile.
Eseguire il polling del task asincrono fino al completamento
La generazione video non è una richiesta che puoi attendere. Invii, ricevi l'identificatore, poi controlli periodicamente lo stato finché il task raggiunge uno stato terminale. Due caratteristiche rendono tutto questo sicuro: il polling ha un costo basso, e la chiamata di invio ha già svolto il lavoro oneroso.
Il ciclo
import time
def wait_for_video(job_id, timeout_s=600, interval_s=5):
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(req, timeout=30) as resp:
job = json.loads(resp.read().decode("utf-8"))
status = job.get("status")
if status in ("succeeded", "completed"):
return job
if status in ("failed", "error", "cancelled"):
raise RuntimeError(f"job {job_id} ended with status {status}: {job.get('error')}")
time.sleep(interval_s)
raise TimeoutError(f"job {job_id} did not finish within {timeout_s}s")
Un ciclo più stretto non è più veloce; consuma solo i rate limit. Per i task video, un intervallo di cinque secondi è un valore predefinito ragionevole.
Note di progettazione
- Imposta sempre una scadenza. Un task che non termina mai non deve mai bloccare indefinitamente un thread di richiesta.
- Tratta gli stati sconosciuti come "continua ad attendere", non come successo. Solo un successo esplicito è un successo.
- Non eseguire il polling all'interno di un handler di richieste web. Invia nell'handler, restituisci l'id del task al client, e lascia che un worker in background esegua il polling e persista i risultati.
- Persisti l'id del task e le transizioni di stato, così un processo interrotto può riprendere invece di reinviare e pagare due volte il rendering.
Questa separazione tra invio e polling è ciò che permette a una pipeline video lenta di stare dietro un'API veloce.
Errori comuni e come risolverli
Quasi ogni errore nella prima ora rientra in una di quattro categorie. Controllale in questo ordine.
1. Autenticazione
Sintomo: risposta di non autorizzato o vietato prima che venga creato qualsiasi task.
Controlla: HIAPI_API_KEY è effettivamente popolata nella shell o nel processo che esegue lo script? L'header è esattamente Authorization: Bearer <key>? Stai caricando la chiave all'import quando lo script si aspetta di usarla più tardi? Stampa i primi caratteri della chiave risolta (mai l'intera chiave) e verifica che non sia una stringa vuota.
2. Percorso dell'endpoint
Sintomo: non trovato, di solito immediato.
Controlla: esattamente una barra tra URL di base e percorso: è per questo che l'esempio Python chiama .rstrip("/"). Verifica il percorso di generazione e quello di polling nella pagina del modello nella documentazione; un URL di polling privo del segmento dell'id del task restituisce 404 ogni volta. Una barra finale che il server non si aspetta produce lo stesso sintomo.
3. Corpo della richiesta malformato
Sintomo: errore di validazione, oppure task accettato ma fallito immediatamente.
Controlla: esegui json.dumps(body) e ispezionalo. model corrisponde esattamente a seedance-2.5-flash/reference-to-video? Il campo dei riferimenti è un array e ogni voce è un URL stringa risolvibile nel browser? Hai inviato Content-Type: application/json? Fai passare il corpo della richiesta da python -m json.tool per escludere errori di sintassi prima che raggiunga la rete.
4. Stato del task
Sintomo: la chiamata di invio ha successo, ma il task fallisce o non si completa mai.
Controlla: leggi il campo di errore nella risposta di stato, che di solito indica la causa, il più delle volte un materiale di riferimento irraggiungibile o non supportato. Se il task è semplicemente bloccato, verifica di eseguire il polling dell'id corretto e che il confronto degli stati nel ciclo copra gli stati terminali effettivamente restituiti dall'API. Registra ogni transizione di stato; l'ultimo stato prima del fallimento è la tua base diagnostica.
Una regola che accorcia tutte e quattro le categorie di risoluzione: registra l'id della richiesta e l'id del task per ogni chiamata. Quando qualcosa va storto, un id trasforma una segnalazione di errore vaga in una ricerca concreta.
Prossimi passi
Ora hai la forma completa: costruire il corpo della richiesta con prompt e materiali di riferimento, inviarlo, eseguire il polling fino alla terminazione e gestire le quattro categorie di errore comuni. Da qui, i prossimi passi naturali sono di livello ingegneristico, non di livello API.
- Avvolgi l'invio in un retry con backoff per gestire errori di rete transitori, ma non ritentare mai un task che ha già un id: sarebbe un rendering duplicato.
- Sposta il polling in un worker o in una coda, così il livello HTTP resta responsivo e i task sopravvivono ai riavvii del processo.
- Memorizza l'id del task insieme ai metadati della tua richiesta (prompt, materiali di riferimento, utente richiedente), così i risultati restano tracciabili anche dopo mesi.
- Lascia passare i materiali di riferimento solo dopo la validazione: recupera ogni URL fornito dagli utenti e poi spendi il task.
Per lo schema di richiesta autorevole, le forme di materiale supportate e i dettagli aggiornati dell'endpoint, consulta la pagina del modello reference-to-video seedance-2.5-flash su HiAPI. Costruisci in base a quello schema, mantieni la separazione tra invio e polling, e l'integrazione resterà noiosa: esattamente ciò che vuoi da una pipeline video.
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