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) 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 stessobitrate_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: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”.
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: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.Modalità bozza (Seedance 2.5)
I modelli Seedance 2.5 che supportano la modalità bozza, comeseedance-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
Impostadraft: 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:
PROCESSING, includono questi campi. draft_task_id è il queue_id della bozza.
Recupera la bozza mentre è in esecuzione:
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 nuovaPOST /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:
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
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 ilqueue_id restituito ed esegui il polling di /video/retrieve finché il body della risposta non è video/mp4:
{ "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/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 (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 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.
Modalità bozza
Queste richieste restituiscono 400 e non vengono addebitate. Vedi Modalità bozza (Seedance 2.5).draftsu un modello che non lo supporta: “This model does not support draft”draft_task_idsu un modello che non lo supporta: “This model does not support draft_task_id”draftedraft_task_idinsieme: “draft cannot be combined with draft_task_id”draft_task_idche 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.”
resolutiondella bozza diversa da480p: “Draft mode requires resolution 480p”resolutiondell’upgrade diversa da1080po4k: “Draft HD upgrade requires resolution 1080p or 4k”
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)