Tutoriale
Tutorial API seedance-2.5-flash image-to-video: curl e Python Requests
Un'esercitazione pratica di integrazione per sviluppatori: struttura della richiesta, input del primo/ultimo fotogramma, polling asincrono e risoluzione degli errori
In questa pagina
Cosa fa realmente una chiamata image-to-video
Prima di scrivere la prima riga di codice, è utile capire cosa fa l'API dall'altra parte. Una chiamata a seedance-2.5-flash/image-to-video non è una richiesta sincrona che blocca fino alla restituzione del file video. È un flusso di lavoro asincrono in due fasi: prima invii un'attività, poi ne verifichi periodicamente il risultato.
Fase di invio
Invii una richiesta POST con l'immagine di input e le impostazioni di generazione. L'API convalida il corpo della richiesta, accoda l'attività e restituisce immediatamente una risposta contenente un identificatore dell'attività e lo stato iniziale. L'operazione è rapida, di solito istantanea, perché in questa fase non è ancora stato renderizzato alcun pixel. Il tuo compito è acquisire quell'identificatore e conservarlo con cura.
Fase di rendering
La generazione avviene in background. A seconda della durata del clip e delle impostazioni, può richiedere un tempo reale considerevole. Durante questa finestra, non aspettarti che l'URL del video finale sia già disponibile. Dovresti invece interrogare lo stato dell'attività.
Fase del risultato
Prima o poi l'attività raggiunge uno stato terminale: successo, con un artefatto video scaricabile, oppure fallimento, con un errore su cui indagare. Una volta raggiunto lo stato terminale, smetti di eseguire il polling.
Perché questo è importante per il tuo codice
Poiché il modello è asincrono, gli errori di integrazione più comuni sono architetturali, non sintattici: presumere che la prima risposta contenga già il video, attendere a intervalli fissi invece di interrogare il campo di stato e non riuscire a distinguere lo stato transitorio processing da un fallimento definitivo. Tutto in questo tutorial ruota attorno a un ciclo pulito "invio → polling → uscita", quindi tieni presenti queste tre fasi durante la lettura.
Prerequisiti e struttura della richiesta
Cosa serve prima della prima chiamata
- Credenziali API. La tua chiave API HiAPI, inviata con ogni richiesta. Conservala in una variabile d'ambiente (
HIAPI_API_KEY), non nel controllo del codice sorgente: gli esempi seguenti la leggono proprio così. - Identificatore del modello. In questo tutorial la stringa è fissa:
seedance-2.5-flash/image-to-video. Trattala come una costante opaca; non concatenarla a partire dalle sue parti. - Immagine di origine. Un URL pubblico o un riferimento a un'immagine inline supportato. Il modello richiede almeno un'immagine del primo fotogramma.
- Client HTTP.
curlper uno smoke test erequestsper tutto ciò che intendi mantenere.
I campi logici del corpo della richiesta
Indipendentemente dal linguaggio, il corpo di una richiesta image-to-video è composto da alcuni gruppi concettuali. Conoscerli separatamente rende il JSON più facile da comprendere:
Modello e input
- L'identificatore del modello.
- Un oggetto di input contenente l'immagine del primo fotogramma e, facoltativamente, l'immagine dell'ultimo fotogramma. Il capitolo 4 spiega come interagiscono.
Impostazioni di output
- Opzioni relative a risoluzione e durata.
- L'interruttore dell'audio nativo, che determina se il clip generato include una traccia audio. Il capitolo 5 spiega quando attivarlo.
Cosa viene restituito
Un invio riuscito restituisce un oggetto attività. I campi che ti servono davvero sono l'identificatore dell'attività e lo stato corrente. Tutto il resto sono metadati che puoi registrare o ignorare. Il primo giorno non convertire l'intera risposta in un modello tipizzato: registra, esamina, poi restringi.
Prima di procedere, fai un rapido controllo di realtà: se il corpo della tua richiesta contiene campi di cui non sai spiegare il nome in una frase, rimuovili e parti dal minimo. La pagina del modello seedance-2.5-flash/image-to-video è il riferimento per i nomi esatti dei campi accettati.
Inviare un'attività con curl
Parti dalla richiesta minima che può funzionare, poi aggiungi un campo alla volta. Di seguito è riportato l'invio minimo con curl:
curl -X POST "$HIAPI_BASE_URL/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/image-to-video",
"input": {
"first_frame_image": "https://your-bucket.example.com/frame-001.jpg"
}
}'
Annotazioni campo per campo
Authorization— la tua chiave API, come bearer token. Se qui c'è un errore, riceverai un errore di autenticazione prima che venga eseguita qualsiasi convalida, quindi controllalo per primo durante il debug.Content-Type: application/json— obbligatorio; ometterlo produce errori a valle poco chiari.model— l'identificatore fisso del modello. Un errore di battitura qui restituisce un 4xx, non un fallback silenzioso.input.first_frame_image— l'immagine di apertura del clip. Usa un URL effettivamente raggiungibile dalla tua rete; gli URL privati o scaduti falliscono al momento del recupero, non dell'invio.
Leggere la risposta
La risposta è un JSON contenente l'identificatore dell'attività e lo stato. Salva subito l'identificatore: è ciò che interrogherai nel capitolo 7. Un modo rapido per estrarlo nella shell:
# dopo il curl precedente, passa l'output a jq
# {"job_id": "...", "status": "queued"}
Aggiungere l'ultimo fotogramma
Per controllare anche il fotogramma finale, aggiungi una seconda immagine dentro lo stesso oggetto input. Il nome del campo e i formati accettati sono quelli della documentazione del modello: non indovinare grafie alternative; l'API rifiuta le chiavi sconosciute invece di ignorarle.
Una volta che la richiesta minima funziona, hai uno smoke test da rieseguire quando qualcosa va storto. Conservalo in un file; quando il servizio si guasta alle due di notte, vale più di qualsiasi lungo discorso.
Input del primo e dell'ultimo fotogramma
Le immagini di input sono il fattore che più determina il successo di un'attività. Plasmano il contenuto del clip e sono anche la fonte più comune di rifiuto delle richieste.
Cosa controlla il primo fotogramma
L'immagine del primo fotogramma stabilisce lo stato iniziale del clip generato: composizione, soggetto, illuminazione e colore. Il modello genera movimento e continuazione da quel punto di partenza, quindi l'immagine dovrebbe apparire come il fotogramma che vorresti davvero vedere al tempo zero. Un'immagine di origine sfocata, ritagliata o molto compressa non migliorerà magicamente nelle fasi successive.
Cosa controlla l'ultimo fotogramma
Fornire un'immagine dell'ultimo fotogramma fissa lo stato finale. È utile quando il clip deve terminare su un'inquadratura specifica: un fotogramma di prodotto curato, la rivelazione di un logo, un cambio di campo in montaggio. Se lo ometti, il modello sceglie da solo il finale, il che va bene per il lavoro esplorativo ma è imprevedibile in produzione.
Come interagiscono
Quando sono forniti entrambi, il modello interpola tra di essi. Questo ha conseguenze pratiche:
- La continuità conta più del contrasto. Due fotogrammi della stessa scena con un movimento moderato producono un clip più coerente rispetto a due immagini non correlate. Se i fotogrammi sono molto diversi, aspettati una deformazione visibile, non una transizione plausibile.
- Le proporzioni devono corrispondere. Proporzioni non corrispondenti tra primo e ultimo fotogramma costringono il modello a un ricomposizione scomoda. Ritaglia entrambi allo stesso rapporto prima di inviare.
- Le risoluzioni devono essere simili. Inviare un primo fotogramma nitido e un ultimo fotogramma a bassa risoluzione dà al modello segnali contraddittori.
Checklist prima dell'invio
Prima di inviare, verifica che: entrambi gli URL delle immagini siano accessibili pubblicamente e non scadano a metà attività; entrambe siano in un formato supportato; entrambe abbiano lo stesso rapporto d'aspetto; nessuna delle due sia uno screenshot con elementi di interfaccia che non vuoi renderizzare. Una rapida richiesta HEAD su ogni URL intercetta la maggior parte di questi problemi a un costo inferiore rispetto a un'attività di generazione fallita.
Se ricevi comunque un rifiuto, il messaggio di errore di solito punta all'oggetto di input. Convalida prima le immagini in locale (dimensioni, formato e accessibilità), poi sospetta l'API.
Impostazioni di risoluzione e audio nativo
Le impostazioni di output sono il punto in cui gli sviluppatori tendono a configurare troppo. La buona notizia è che i valori predefiniti sono ragionevoli; il rischio è copiare valori dalla documentazione di un altro modello.
Risoluzione
La risoluzione determina le dimensioni del video consegnato e quindi influisce sul tempo di generazione e sul volume dell'output. Due regole pratiche:
- Scegli in base alla destinazione, non al numero. Un clip per un feed mobile non ha bisogno di essere renderizzato in grande per poi essere ridotto. Scegli la risoluzione minima che soddisfa la piattaforma di destinazione.
- Preferisci uno dei preset documentati. Passare valori arbitrari o non supportati è una causa comune di rifiuto della richiesta. Se ti serve un fotogramma specifico, ritaglia o ridimensiona dopo la generazione invece di scontrarti con il validatore della richiesta.
Audio nativo
L'interruttore dell'audio nativo determina se il clip generato include una traccia audio prodotta insieme al video. Valuta se ti serve:
- Attivalo quando il clip è il prodotto finale da guardare con l'audio: contenuti social, brevi promozioni, scene di personaggi in cui l'audio ambientale esalta la sensazione di movimento.
- Disattivalo quando aggiungerai musica o voce fuori campo nel tuo editor, o quando il clip è un asset intermedio. Generare audio che poi scarterai è lavoro sprecato e rende l'elaborazione a valle più pesante.
Durata
La durata è legata a tutto il resto: i clip più lunghi richiedono più tempo per la generazione e tendono maggiormente alla deriva della coerenza del soggetto. Per la prima integrazione, inizia con clip brevi. Conferma che la pipeline funzioni end-to-end con un clip breve, poi allunga quando ti fidi della pipeline.
Mantieni piccolo l'oggetto delle impostazioni
Se ti ritrovi ad aggiungere impostazioni per correggere problemi di qualità, fermati e controlla se il problema è in realtà nelle immagini di input. La maggior parte degli output deludenti è riconducibile al capitolo 4, non alla mancanza di una manopola. Configura in modo intenzionale, registra l'oggetto esatto delle impostazioni insieme a ogni identificatore di attività e potrai attribuire le variazioni di qualità a modifiche specifiche.
La stessa richiesta in Python
La richiesta curl si trasferisce direttamente in Python. L'obiettivo qui non è un framework, ma un piccolo client leggibile che invia l'attività e restituisce l'identificatore, così che il livello di polling possa restare separato.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "seedance-2.5-flash/image-to-video"
def submit_job(first_frame_url: str, last_frame_url: str | None = None) -> dict:
payload = {
"model": MODEL,
"input": {"first_frame_image": first_frame_url},
}
if last_frame_url:
payload["input"]["last_frame_image"] = last_frame_url
response = requests.post(
f"{BASE_URL}/image-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()
Perché è strutturato così
- Configurazione tramite variabili d'ambiente. L'URL di base e la chiave restano fuori dal codice, così lo stesso client può essere eseguito in ambienti diversi.
timeout=30sull'invio. L'invio è rapido; un invio che si blocca indica un problema di rete o di autenticazione, e vuoi scoprirlo presto invece di bloccare indefinitamente un worker.raise_for_status()prima dell'analisi. Il corpo di una risposta 4xx è di solito un oggetto di errore JSON, non un'attività. Sollevare un'eccezione per prima cosa mantiene pulito il percorso normale e consente al chiamante di gestire esplicitamente il fallimento.- Invio e polling separati.
submit_jobfa una sola cosa. Il ciclo di polling del capitolo successivo riceve il dizionario restituito e si occupa dell'attesa.
Portarlo in un servizio
In un servizio reale, avvolgi la chiamata in modo che i fallimenti si presentino come eccezioni tipizzate che trasportano codice di stato e corpo della risposta: durante il debug in produzione vorrai il corpo originale della risposta. Registra il corpo della richiesta insieme all'identificatore dell'attività restituito; quando un collega chiederà perché un clip sembra sbagliato, quella riga di log sarà l'intera indagine.
I nomi dei campi sono esattamente quelli dell'esempio curl. Se sai leggere uno, sai leggere l'altro: è proprio questo il motivo per cui vale la pena dedicare cinque minuti a partire da curl.
Eseguire il polling dei risultati senza martellare l'API
Ora l'attività esiste e ha un identificatore. L'approccio ingenuo (dormire sessanta secondi e sperare) fallisce in due modi: spreca tempo quando l'attività è pronta prima, e fallisce del tutto quando l'attività richiede più tempo.
Interroga il campo di stato, non l'orologio
Scrivi un ciclo che interroga lo stato corrente dell'attività e dirama in base a esso:
import time
import requests
def wait_for_job(job_id: str, timeout_s: int = 600) -> dict:
deadline = time.monotonic() + timeout_s
delay = 2.0
while time.monotonic() < deadline:
r = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
r.raise_for_status()
job = r.json()
status = job.get("status")
if status == "succeeded":
return job
if status == "failed":
raise RuntimeError(f"job failed: {job.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15.0) # backoff esponenziale limitato
raise TimeoutError(f"job {job_id} not terminal after {timeout_s}s")
Le caratteristiche importanti
- Stati terminali espliciti. Solo
succeededefailedterminano il ciclo. Qualsiasi altro stato è transitorio. Non trattare gli stati sconosciuti come fallimenti: nel tempo emergono nuovi stati intermedi, e il tuo ciclo dovrebbe tollerarli. - Backoff limitato. Parti da un valore piccolo (pochi secondi), cresci con un fattore moderato e imponi un limite di circa dieci-quindici secondi. Questo mantiene reattive le attività brevi senza martellare l'endpoint durante lunghi rendering.
- Scadenza rigida. Limita sempre il tempo totale di attesa. Senza di essa, un'attività bloccata occupa un worker per sempre. Scegli il limite in base al tuo tempo di rendering realistico più lungo, con un margine.
- Separa i fallimenti dai timeout. Un'attività
failedè un errore di generazione da segnalare all'utente. Un timeout è una condizione dell'infrastruttura da ritentare o indagare separatamente. Confondere i due rende l'analisi post-incidente dolorosa.
In un servizio web
Non eseguire questo ciclo nel gestore della richiesta in cui l'utente è in attesa. Invia, memorizza l'identificatore dell'attività, restituisci immediatamente e lascia che un worker in background esegua il polling e consegni il risultato, tramite webhook, coda o aggiornamenti di riga osservati dal frontend. Il ciclo sopra è una preoccupazione del worker, non di HTTP.
Diagnosticare i fallimenti comuni
La maggior parte dei fallimenti rientra in tre categorie. Determina prima la categoria, poi la causa specifica.
Categoria 1: errori di convalida dell'input
Sintomo: un 4xx immediato al momento dell'invio, prima di qualsiasi rendering.
Diagnostica in questo ordine:
- L'URL dell'immagine è accessibile? Recuperalo tu stesso dalla stessa rete. Gli URL firmati scaduti e i bucket privati sono la causa principale.
- Il formato è supportato? Ricodifica in un formato standard invece di discuterne.
- Primo e ultimo fotogramma sono coerenti? Proporzioni non corrispondenti o scene molto diverse si manifestano spesso come problemi di convalida o di qualità.
- Hai aggiunto campi con il nome sbagliato? Le chiavi sconosciute di solito vengono rifiutate invece di essere ignorate. Confronta con il riferimento del modello.
Categoria 2: parametri non corrispondenti
Sintomo: la richiesta viene rifiutata a causa di un'impostazione, oppure l'output ignora la tua configurazione.
- Risoluzione o durata non supportate. Usa solo i valori della documentazione; i numeri arbitrari sono una causa comune di rifiuto.
- Identificatore del modello scritto male. È una stringa fissa: copiala, non ridigitarla.
- Annidamento errato. Impostazioni che appartengono al livello superiore messe dentro
input, o viceversa, producono errori poco chiari. Usa la struttura della richiesta del capitolo 3 come riferimento.
Categoria 3: timeout del polling e attività fallite
Sintomo: l'attività viene accettata ma non raggiunge mai uno stato terminale di successo.
- Verifica di interrogare l'identificatore corretto. Gli errori di copia-incolla tra le attività negli script batch sono sorprendentemente comuni.
- Controlla se lo stato avanza davvero. Registra lo stato a ogni polling per vedere se l'attività progredisce o è bloccata.
- Distingui un fallimento dell'API da un fallimento della generazione. Se la richiesta di polling stessa fallisce, è un problema di trasporto. Se l'attività riporta
failed, leggi il corpo dell'errore: di solito indica l'input che ha causato il problema. - Riesegui lo smoke test
curlminimo. Se fallisce anche lo smoke test, il problema è nelle credenziali o nel servizio; se riesce, il problema è nel tuo corpo della richiesta.
Approccio generale al debug
Registra tre cose per ogni attività: il corpo esatto della richiesta, l'identificatore dell'attività restituito e lo stato finale con il corpo dell'errore. Con questi tre elementi, quasi ogni incidente diventa una diagnosi di cinque minuti invece di un pomeriggio. In caso di dubbio, riduci la richiesta alla forma minima del capitolo 3 e aggiungi i campi uno alla volta finché non si rompe: l'ultimo campo aggiunto è il colpevole.
Articoli correlati
Vedi tutti gli articoli →-
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
-
Tutoriale
gemini-4-neon scenari applicativi reali: 5 casi d'uso ad alto valore e punti chiave di integrazione
-
Tutoriale
Come chiamare seedance-2.5-flash text-to-video tramite l'API HiAPI (curl e Python)
Una guida pratica per sviluppatori alle richieste funzionanti: endpoint, parametri, gestione dei task asincroni ed esempi eseguibili in curl e Python