curl.
Varianti
Tutte le varianti sono asincrone. Invia tramite
POST /api/v1/video/queue, quindi esegui il polling di POST /api/v1/video/retrieve finché il body della risposta non è video/mp4. Consulta Generazione video per il flusso generale della coda.
Passa resolution come uno tra: 480p, 720p, 1080p o 4k (minuscolo). Seedance 2.0 (non Fast) accetta tutti e quattro; 2.0 Fast e 2.5 accettano solo 480p / 720p. Scopri i model ID e le capacità in tempo reale con GET /models?type=video — non fare hardcoding sulla disponibilità.
Il modello “un modello, quattro workflow”
Le varianti reference-to-video (seedance-2-0-reference-to-video-basic, la sua controparte Fast e seedance-2-5-reference-to-video-basic) usano lo stesso pattern di routing basato sul prompt. Il modello deduce il task dal prefisso del prompt e dalla forma dei tuoi input. Non c’è alcun campo task o workflow — la sintassi del prompt è il routing.
La sintassi del prompt è canonica e case-sensitive: parentesi angolari, prima lettera maiuscola, singolo spazio prima del numero —
<Video 1>, <Image 1>, <Audio 1>.
Pattern dei workflow
Workflow Reference
Usa i file di riferimento caricati come donor — soggetto, scena, movimento, stile, timbro vocale — per generare un video completamente nuovo. Pattern canonici del prompt:Refer to <Subject 1> in <Image 1> to generate a 5-second clip of the same character riding a horse through snow.Refer to the camera scene in <Video 1> to generate a similar establishing shot of a futuristic city at dawn.Refer to <Subject 1> in <Image 1> and use the timbre in <Audio 1> for the narrator describing the scene.(gli audio donor devono essere abbinati ad almeno un’immagine o un video di riferimento — l’audio da solo viene rifiutato)
Workflow Edit
Modifica un singolo video di input. Tutto ciò che non è esplicitamente nominato nel prompt viene preservato. Usa questo quando vuoi una modifica localizzata (sostituzione del soggetto, cambio di meteo/colore, aggiunta/rimozione di elementi) piuttosto che un video completamente nuovo. Pattern canonico del prompt:Strictly edit <Video 1>, changing its weather from sunny to a heavy rainstorm.Add snacks such as fried chicken and pizza to the countertop in <Video 1>.Remove the red car from <Video 1>, keeping the rest of the video content unchanged.Replace the perfume featured in <Video 1> with the face cream from <Image 1>, with all original motions and camera work preserved.
<Image 1> come donor visivo per la sostituzione.
Rapporto d’aspetto e durata allineati alla sorgente
Per Seedance reference-to-video edit / extend, puoi chiedere che l’output segua la clip sorgente invece di scegliere un rapporto o una lunghezza fissi:
Requisiti:
- Queue: qualsiasi valore allineato alla sorgente richiede
reference_video_urls. - Quote: qualsiasi valore allineato alla sorgente richiede
reference_video_total_duration. La durata allineata alla sorgente viene fatturata comeceil(reference_video_total_duration)secondi. - Rapporto e durata sono indipendenti — puoi allineare uno senza l’altro.
- Per extend, preferisci una
durationfissa (quanto generare) e, opzionalmente,aspect_ratio: "adaptive". Ladurationallineata alla sorgente è pensata per job in stile edit “stessa lunghezza della sorgente”.
Workflow Extend
Continua una singola clip in avanti o all’indietro nel tempo. Per impostazione predefinita Seedance restituisce solo il nuovo contenuto — non il video di input originale concatenato all’estensione. Questo è di design, per la continuità di transizione; se vuoi che la clip di input sia preservata insieme all’estensione, dillo esplicitamente:Extend <Video 1>, generate a dramatic chase scene through narrow alleys at dusk.Extend <Video 1> backward, the same character walking toward the camera before the original shot begins.Extend <Video 1>, start with <Video 1>, then the camera pulls back to reveal a vast landscape.
Workflow Stitch (Track Completion)
Collega clip di input con transizioni generate dall’IA. Rispetta i limiti specifici della famiglia su durata combinata e numero di clip in Limiti di input multimodali (Seedance 2.0: ≤3 clip / ≤15 s combinati; Seedance 2.5: cap video più alti). Pattern canonico del prompt:<Video 1> + a smooth seamless cut + followed by <Video 2><Video 1>. The moment a leaf falls to the ground, it sets off a special effect of golden particles. A gust of wind blows by, leading into <Video 2>.<Video 1> + a wisp of smoke transforms into a flock of birds + followed by <Video 2> + a slow dolly-in + followed by <Video 3>
Formula universale del prompt
In tutti e quattro i workflow, la formula di scrittura raccomandata è:- Subject + Motion: la base logica — definire “Chi” esegue “Quale azione”
- Environment + Aesthetics: sfondo spaziale, illuminazione, stile visivo
- Camera: tipo di inquadratura o movimento esplicito
- Audio: effetti sonori ambientali o direzione vocale per un output immersivo
Strictly edit <Video 1>, changing its <subject + motion + environment + ...>) si ottengono output della massima qualità.
Limiti di input multimodali
I valori sottostanti sono ciò che l’API Venice accetta. Le richieste al di fuori di questi range vengono rifiutate al livello schema con un 400 prima di raggiungere l’inferenza. Seedance 2.0 e Seedance 2.5 usano cap diversi. Controlla sempre la colonna della famiglia di modelli che stai chiamando.Limiti minimi condivisi sui media
Confronto tra famiglie
L’audio di riferimento è supportato solo sulle varianti R2V. Ogni voce viene inoltrata al modello come content item
role: "reference_audio" che il prompt indirizza come <Audio 1>, <Audio 2>, … — il modello usa ciascuna clip per il timbro vocale, gli effetti sonori o la musica di sottofondo, a seconda di come il prompt lo inquadra. Il campo singolare legacy audio_url mappa sulla stessa forma di contenuto ed è ora equivalente al passaggio di un reference_audio_urls con un solo elemento.
Dimensione della richiesta
L’endpoint di coda accetta body JSON fino a 35 MB. I Data URL inline per video di grandi dimensioni possono superare questo limite — per lo Stitch multi-clip in particolare, preferisci gli URL al base64 inline.Prezzi
ChiamaPOST /api/v1/video/quote per ottenere un preventivo per una determinata forma di richiesta prima di inviarla a /video/queue. L’endpoint quote è l’unica fonte autorevole; i dettagli sui prezzi possono cambiare e non dovrebbero essere memorizzati nella cache o duplicati lato client.
Quando uno o più video di riferimento fanno parte della richiesta, passa anche reference_video_total_duration (la somma della durata di tutte le clip di riferimento in secondi) in modo che il preventivo corrisponda a ciò che /video/queue addebiterà:
Esempi completi
Tutti gli esempi assumono cheVENICE_API_KEY sia impostata nell’ambiente.
Text-to-video
Seedance 2.0 text-to-video (4K)
Seedance 2.5 text-to-video (durata più lunga)
Image-to-video (primo frame)
I modelli I2V di Seedance (
seedance-2-0-image-to-video-basic, la sua variante Fast e seedance-2-5-image-to-video-basic) non accettano aspect_ratio — il rapporto d’aspetto di output è derivato automaticamente dalle dimensioni dell’immagine di input. Passare il campo restituisce un 400 con “This model does not support aspect_ratio”. Usa le varianti T2V o R2V se hai bisogno del controllo esplicito del rapporto d’aspetto.Workflow Reference — subject donor
Workflow Reference Seedance 2.5 — multi-immagine
Workflow Reference — subject + audio donor
Workflow Edit
Edit Seedance 2.5 — durata e rapporto d’aspetto allineati alla sorgente
duration: "auto" (o "-1") e aspect_ratio: "adaptive" (o "auto") fanno sì che l’output segua la clip sorgente. Consulta Rapporto d’aspetto e durata allineati alla sorgente.
Workflow Edit con grounding immagine
Extend in avanti
Stitch (3 clip)
Polling per il completamento
Dopo ogni invio in coda, salva ilqueue_id restituito ed esegui il polling di /video/retrieve finché il body della risposta non è video/mp4:
{ "status": "queued" | "running" | "failed", ... }) finché il job non completa, momento in cui il body della risposta passa a byte video/mp4. Consulta Generazione video per il pattern completo di polling.
Risoluzione dei problemi
At least one reference is required for this model
Gli invii reference-to-video devono includere almeno uno tra reference_image_urls, reference_video_urls, image_references o video_references. La generazione basata solo su testo non è un workflow R2V valido — usa invece un model ID text-to-video. reference_audio_urls da solo non è sufficiente (vedi la sezione Audio sopra).
Troppi video / immagini di riferimento
Seedance 2.0 limita R2V a 9 immagini e 3 video. Seedance 2.5 alza questi cap a 30 immagini e 10 video. Se superi il limite della famiglia, riduci gli input o esegui prima uno stitch offline.Errori di durata / durata aggregata
- 2.0: video/audio di riferimento per clip
[2, 15]s; video/audio combinati ≤ 15 s; output 4–15 s. - 2.5: video/audio di riferimento per clip
[2, 30]s; video/audio combinati ≤ 30 s; output 4–30 s. - Durata allineata alla sorgente (
-1/autosu Seedance 2.5): la clip sorgente deve essere di 4–30 s, ed è richiestoreference_video_urls(queue) oreference_video_total_duration(quote).
Il prompt indirizza al workflow sbagliato
Il workflow è dedotto dalla sintassi del prompt. Errori comuni di routing:- Volere Extend ma scrivere
Refer to ...→ il modello tratta il tuo video come un donor, non come una tela da continuare - Volere Stitch ma scrivere
Refer to ...→ il modello sceglie uno come donor, ignora gli altri - Volere Edit ma scrivere
Generate a video based on <Video 1>→ ambiguo; il modello può ricadere di default su Reference
Strictly edit <Video 1>, ..., Extend <Video 1>, ..., <Video 1> + ... + followed by <Video 2>.
Contenuti multimediali con persone non supportati
I modelli pubblici dell’API Seedance non eseguono un flusso di attestazione del consenso. I contenuti multimediali con persone rilevabili possono fallire con un errore di content policy o del provider. Usa invece l’app o lo Studio di Venice.Il preventivo non corrisponde all’importo in coda
Se hai incluso un video di riferimento ma non hai passatoreference_video_total_duration a /video/quote, il preventivo e l’importo in coda possono differire. Passa sempre reference_video_total_duration (somma della durata di tutte le clip di riferimento, in secondi) quando sono presenti video di riferimento.
Riferimenti
- Endpoint della coda video di Venice:
POST /api/v1/video/queue - Endpoint quote di Venice:
POST /api/v1/video/quote - Guida correlata: Reference to Video (copre R2V di Kling O3 + Grok Imagine)
- Guida correlata: Generazione video (panoramica di coda / polling)