Vai al contenuto principale
Seedance è una famiglia multimodale di punta per la generazione video su Venice, per workflow guidati da testo, immagini e riferimenti. Seedance 2.0 (più Fast) e Seedance 2.5 condividono lo stesso modello R2V con routing basato sul prompt: un singolo endpoint reference-to-video gestisce quattro workflow distinti (Reference, Edit, Extend, Stitch) — il workflow viene dedotto dalla forma del tuo prompt. Questa guida copre le varianti, i quattro workflow, la policy sui contenuti multimediali dell’API pubblica, i limiti multimodali specifici della famiglia, il bitrate di output, la modalità bozza di Seedance 2.5, i prezzi ed esempi con curl.
I contenuti multimediali con persone non sono supportati sull’API pubblica di Seedance. I modelli pubblici *-basic non utilizzano un flusso di attestazione del consenso (consents.seedance / needs_consent). Tali input possono essere rifiutati a monte con un errore di content policy o del provider. Usa l’app o lo Studio di Venice per il set completo di funzionalità di Seedance.

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) e 2.5 accettano tutti e quattro; 2.0 Fast accetta solo 480p / 720p. Scopri i model ID e le capacità in tempo reale con GET /models?type=video — non fare hardcoding sulla disponibilità.

Bitrate di output

Puoi impostare il bitrate di encoding dell’output su ogni modello pubblico Seedance 2.0 (incluso Fast) e 2.5. Passa tu stesso bitrate_mode su /video/queue — Venice non lo sceglie automaticamente. È un’opzione di encoding disponibile solo in coda: non cambia il prezzo né il costo in token, e /video/quote non accetta bitrate_mode. Le altre famiglie video (Wan, Kling, LTX e così via) non supportano questo campo.

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:
Esempi:
  • 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:
Sotto-pattern per un controllo più fine:
Esempi:
  • 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.
L’ultimo esempio combina Edit con un riferimento immagine — perfettamente lecito: il modello usa <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 come ceil(reference_video_total_duration) secondi.
  • Rapporto e durata sono indipendenti — puoi allineare uno senza l’altro.
  • Per extend, preferisci una duration fissa (quanto generare) e, opzionalmente, aspect_ratio: "adaptive". La duration allineata alla sorgente è pensata per job in stile edit “stessa lunghezza della sorgente”.

omni_reference_task_type (Seedance 2.5 R2V)

BytePlus classifica i job all-modal reference di Seedance 2.5 come reference, edit o extend in base al prompt. Puoi opzionalmente pre-guidare quella classificazione su /video/queue con: Sono accettati gli alias editing→edit ed extension→extend. Quando omesso, Venice deduce il valore dal prompt se sono presenti reference_video_urls. Il prompt deve comunque corrispondere al tipo scelto — un conflitto può comunque fallire in modo asincrono.

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:
Gestione delle transizioni: il modello estrae automaticamente i frame di transizione per una fusione senza cuciture, e i segmenti originali del video di input non vengono ri-generati. Esempi:
  • 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:
Esempi:
  • <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>
Il modello ritaglia automaticamente i segmenti di collegamento nei punti di giunzione per la continuità.

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
Sovrapponendo questo a un prefisso di workflow (ad es., 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.
reference_audio_urls non può essere l’unico input di riferimento. Il modello richiede almeno un’immagine o un video di riferimento insieme a qualsiasi audio donor. Abbina reference_audio_urls a reference_image_urls o reference_video_urls — gli invii solo audio vengono rifiutati, così come quelli che abbinano l’audio soltanto a image_url o video_url.

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.

Modalità bozza (Seedance 2.5)

I modelli Seedance 2.5 che supportano la modalità bozza, come seedance-2-5-text-to-video-basic, possono generare una bozza a 480p e in seguito portarla a 1080p o 4k. La bozza e l’upgrade sono richieste separate e vengono addebitate separatamente. Chiama POST /api/v1/video/quote per ottenere ciascun prezzo prima di metterla in coda. Inviare draft a qualsiasi altro modello restituisce 400 “This model does not support draft”. Inviare draft_task_id a qualsiasi altro modello restituisce 400 “This model does not support draft_task_id”.

Creare una bozza

Imposta draft: true su POST /api/v1/video/queue o POST /api/v1/video/quote. resolution ha come valore predefinito 480p. Qualsiasi altro valore restituisce 400 “Draft mode requires resolution 480p”. Una bozza di 5 secondi in 16:9 è 854×480. Richiedi il preventivo della bozza:
Metti in coda la bozza:
La risposta della coda, e una risposta di retrieve mentre lo stato è PROCESSING, includono questi campi. draft_task_id è il queue_id della bozza. Recupera la bozza mentre è in esecuzione:
La risposta include anche average_execution_time ed execution_duration, come qualsiasi altro retrieve. draft_expires_at è 7 giorni dopo la creazione della bozza. Quando il corpo passa a video/mp4, gli stessi valori della bozza arrivano come header di risposta: x-venice-is-draft, x-venice-draft-task-id, x-venice-draft-expires-at e x-venice-can-upgrade-to-hd. In quella risposta completata, x-venice-can-upgrade-to-hd è true fino a draft_expires_at. I contenuti multimediali di una bozza vengono conservati fino alla fine della finestra di upgrade HD, anche quando delete_media_on_completion è true.

Fare l’upgrade della bozza a 1080p o 4k

Invia una nuova POST /api/v1/video/queue con draft_task_id impostato sul queue_id della bozza. La bozza deve essere tua, dello stesso modello e all’interno della finestra di 7 giorni. resolution ha come valore predefinito 1080p; invia "resolution": "4k" per un upgrade a 4k. Qualsiasi altro valore restituisce 400 “Draft HD upgrade requires resolution 1080p or 4k”. duration e aspect_ratio sono facoltativi nell’upgrade. Seed, durata, proporzioni e audio seguono la bozza. Una duration o un aspect_ratio che non corrispondono alla bozza vengono ignorati e si usano i valori della bozza. Gli input multimediali nella richiesta di upgrade vengono ignorati. prompt resta obbligatorio. La stessa bozza può essere portata in HD più di una volta all’interno della finestra. Non inviare draft e draft_task_id insieme. Richiedi il preventivo dell’upgrade. Questo preventivo richiede l’autenticazione. duration è obbligatorio nella richiesta di preventivo, ma il prezzo usa la durata della bozza. Aggiungi "resolution": "4k" per il preventivo di un upgrade a 4k:
Metti in coda l’upgrade:
Metti in coda la stessa bozza come upgrade a 4k:
Una richiesta di bozza o di upgrade rifiutata non viene addebitata.

Prezzi

Chiama POST /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à:
Quote di edit Seedance 2.5 allineato alla sorgente (fattura in base alla lunghezza sorgente):

Esempi completi

Tutti gli esempi assumono che VENICE_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

omni_reference_task_type: "edit" pre-guida la classificazione di BytePlus. 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 e omni_reference_task_type.

Workflow Edit con grounding immagine

Extend in avanti

Stitch (3 clip)

Polling per il completamento

Dopo ogni invio in coda, salva il queue_id restituito ed esegui il polling di /video/retrieve finché il body della risposta non è video/mp4:
La risposta è JSON ({ "status": "PROCESSING", ... }) mentre il job è in esecuzione, e il body passa a byte video/mp4 una volta completato. status è uno tra PROCESSING o COMPLETED — non esiste uno status failed. Un job fallito restituisce invece una risposta non-200 contenente l’errore registrato. 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 o image_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). Nota che video_references non è accettato su Seedance — è specifico dei modelli che supportano l’audio vocale per singolo riferimento, e passarlo restituisce “This model does not support per-reference video entities”.

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 / auto su Seedance 2.5): la clip sorgente deve essere di 4–30 s, ed è richiesto reference_video_urls (queue) o reference_video_total_duration (quote).
Ritaglia le clip lato client prima dell’invio.

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
Usa i prefissi canonici esattamente come scritto: 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 (consents.seedance / needs_consent). 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 passato reference_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.

Modalità bozza

Queste richieste restituiscono 400 e non vengono addebitate. Vedi Modalità bozza (Seedance 2.5).
  • draft su un modello che non lo supporta: “This model does not support draft”
  • draft_task_id su un modello che non lo supporta: “This model does not support draft_task_id”
  • draft e draft_task_id insieme: “draft cannot be combined with draft_task_id”
  • draft_task_id che non è un UUID: “draft_task_id must be a valid queue_id”
  • ID sconosciuto o non disponibile: “Draft queue id was not found or is no longer available.”
  • Un queue id che non è una bozza Seedance 2.5: “Only a Seedance 2.5 draft can be upgraded to HD.”
  • Un modello diverso da quello della bozza: “Draft HD upgrade must use the same model as the draft.”
  • Bozza ancora in generazione: “Draft has not finished generating. Wait until it completes, then upgrade to HD.”
  • Bozza non ancora accettata dal provider: “Draft is still submitting. Wait until the draft task is accepted before upgrading.”
  • Più vecchia di 7 giorni: “Draft expired. Draft task IDs are valid for 7 days from creation.”
  • resolution della bozza diversa da 480p: “Draft mode requires resolution 480p”
  • resolution dell’upgrade diversa da 1080p o 4k: “Draft HD upgrade requires resolution 1080p or 4k”

Riferimenti