curl.
Variantes
Todas as variantes são assíncronas. Envie via
POST /api/v1/video/queue e depois faça polling em POST /api/v1/video/retrieve até o corpo da resposta ser video/mp4. Veja Geração de Vídeo para o fluxo geral da fila.
Passe resolution como um dos seguintes: 480p, 720p, 1080p ou 4k (em minúsculas). Seedance 2.0 (não-Fast) aceita todos os quatro; 2.0 Fast e 2.5 aceitam apenas 480p / 720p. Descubra os IDs de modelo e capacidades ao vivo com GET /models?type=video — não hardcode a disponibilidade.
O modelo “um modelo, quatro workflows”
As variantes reference-to-video (seedance-2-0-reference-to-video-basic, sua irmã Fast e seedance-2-5-reference-to-video-basic) usam o mesmo padrão de roteamento por prompt. O modelo infere a tarefa a partir do prefixo do prompt e do formato das suas entradas. Não existe campo task ou workflow — a sintaxe do prompt é o roteamento.
A sintaxe do prompt é canônica e sensível a maiúsculas: colchetes angulares, primeira letra maiúscula, um único espaço antes do número —
<Video 1>, <Image 1>, <Audio 1>.
Padrões de workflow
Workflow Reference
Use os arquivos de referência enviados como doadores — sujeito, cena, movimento, estilo, timbre vocal — para gerar um vídeo totalmente novo. Padrões canônicos de 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.(doadores de áudio devem ser pareados com pelo menos uma referência de imagem ou vídeo — áudio sozinho é rejeitado)
Workflow Edit
Modifica um único vídeo de entrada. Qualquer coisa não citada explicitamente no prompt é preservada. Use isto quando você quer uma alteração localizada (troca de sujeito, mudança de clima/cor, adição/remoção de elemento) em vez de um vídeo totalmente novo. Padrão canônico de 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> como doador visual para a substituição.
Proporção e duração correspondentes à origem
Para o Seedance reference-to-video edit / extend, você pode pedir que a saída siga o clipe de origem em vez de escolher uma proporção ou duração fixa:
Requisitos:
- Queue: qualquer valor correspondente à origem exige
reference_video_urls. - Quote: qualquer valor correspondente à origem exige
reference_video_total_duration. A duração correspondente à origem cobraceil(reference_video_total_duration)segundos. - Proporção e duração são independentes — você pode fazer uma corresponder sem a outra.
- Para extend, prefira uma
durationfixa (quanto tempo gerar) e opcionalmenteaspect_ratio: "adaptive". Adurationcorrespondente à origem é para jobs no estilo edit “mesma duração da origem”.
Workflow Extend
Continua um único clipe para frente ou para trás no tempo. Por padrão, o Seedance retorna apenas o novo conteúdo — não o input original concatenado com a extensão. Isso é intencional, para continuidade da transição; se você quer o clipe de entrada preservado junto da extensão, diga isso explicitamente: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)
Conecta clipes de entrada com transições geradas por IA. Respeite os limites específicos por família de duração combinada e contagem de clipes em Limites de entrada multimodal (Seedance 2.0: ≤3 clipes / ≤15 s combinados; Seedance 2.5: limites de vídeo maiores). Padrão canônico de 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>
Fórmula universal de prompt
Em todos os quatro workflows, a fórmula recomendada de autoria é:- Subject + Motion: a base lógica — define “Quem” está realizando “Qual ação”
- Environment + Aesthetics: fundo espacial, iluminação, estilo visual
- Camera: tipo de plano ou movimento explícito
- Audio: efeitos de som ambiente ou direção vocal para saída imersiva
Strictly edit <Video 1>, changing its <subject + motion + environment + ...>) produz as saídas de mais alta qualidade.
Limites de entrada multimodal
Os valores abaixo são os que a API Venice aceita. Requisições fora dessas faixas são rejeitadas na camada de schema com um 400 antes de chegar à inferência. Seedance 2.0 e Seedance 2.5 usam limites diferentes. Sempre confira a coluna da família do modelo que você está chamando.Pisos de mídia compartilhados
Comparação entre famílias
Áudio de referência é suportado apenas nas variantes R2V. Cada entrada é encaminhada ao modelo como um item de conteúdo
role: "reference_audio" que o prompt endereça como <Audio 1>, <Audio 2>, … — o modelo usa cada clipe para timbre vocal, efeitos sonoros ou música de fundo, dependendo de como o prompt o enquadra. O antigo campo singular audio_url mapeia para a mesma forma de conteúdo e agora é equivalente a passar um reference_audio_urls com um único elemento.
Tamanho do request
O endpoint de fila aceita corpos JSON de até 35 MB. Data URLs inline para vídeos grandes podem ultrapassar esse limite — para Stitch multi-clipe em particular, prefira URLs a base64 inline.Preços
ChamePOST /api/v1/video/quote para obter uma cotação de um dado formato de request antes de enviá-lo para /video/queue. O endpoint de cotação é a única fonte autoritativa; detalhes de preço podem mudar e não devem ser armazenados em cache ou duplicados no cliente.
Quando vídeo(s) de referência fazem parte da requisição, também passe reference_video_total_duration (a soma das durações de todos os clipes de referência em segundos) para que a cotação corresponda ao que /video/queue cobrará:
Exemplos completos
Todos os exemplos assumem queVENICE_API_KEY está definido no ambiente.
Text-to-video
Seedance 2.0 text-to-video (4K)
Seedance 2.5 text-to-video (duração maior)
Image-to-video (primeiro frame)
Os modelos I2V do Seedance (
seedance-2-0-image-to-video-basic, sua variante Fast e seedance-2-5-image-to-video-basic) não aceitam aspect_ratio — a proporção de saída é derivada automaticamente das dimensões da imagem de entrada. Passar o campo retorna um 400 com “This model does not support aspect_ratio”. Use as variantes T2V ou R2V se precisar de controle explícito de proporção.Workflow Reference — doador de sujeito
Workflow Reference do Seedance 2.5 — multi-imagem
Workflow Reference — sujeito + doador de áudio
Workflow Edit
Seedance 2.5 edit — duração e proporção correspondentes à origem
duration: "auto" (ou "-1") e aspect_ratio: "adaptive" (ou "auto") fazem a saída seguir o clipe de origem. Veja Proporção e duração correspondentes à origem.
Workflow Edit com grounding por imagem
Extend para frente
Stitch (3 clipes)
Polling até a conclusão
Após cada submissão à fila, salve oqueue_id retornado e faça polling em /video/retrieve até o corpo da resposta ser video/mp4:
{ "status": "queued" | "running" | "failed", ... }) até o job concluir, ponto em que o corpo da resposta muda para bytes video/mp4. Veja Geração de Vídeo para o padrão completo de polling.
Solução de problemas
At least one reference is required for this model
Submissões reference-to-video devem incluir pelo menos um de reference_image_urls, reference_video_urls, image_references ou video_references. Geração puramente text-only não é um workflow R2V válido — use um ID de modelo text-to-video em vez disso. reference_audio_urls sozinho não é suficiente (veja a seção sobre áudio acima).
Vídeos / imagens de referência em excesso
Seedance 2.0 limita R2V a 9 imagens e 3 vídeos. Seedance 2.5 eleva esses limites para 30 imagens e 10 vídeos. Se exceder o limite da família, corte as entradas ou faça o stitch offline primeiro.Erros de duração / duração agregada
- 2.0: vídeo/áudio de referência por clipe
[2, 15]s; combinado de vídeo/áudio ≤ 15 s; saída 4–15 s. - 2.5: vídeo/áudio de referência por clipe
[2, 30]s; combinado de vídeo/áudio ≤ 30 s; saída 4–30 s. - Duração correspondente à origem (
-1/autono Seedance 2.5): o clipe de origem deve ter 4–30 s, ereference_video_urls(queue) oureference_video_total_duration(quote) é obrigatório.
O prompt roteia para o workflow errado
O workflow é inferido pela sintaxe do prompt. Erros comuns de roteamento:- Querendo Extend mas escrevendo
Refer to ...→ o modelo trata o seu vídeo como um doador, não como uma tela para continuar - Querendo Stitch mas escrevendo
Refer to ...→ o modelo escolhe um como doador e ignora os outros - Querendo Edit mas escrevendo
Generate a video based on <Video 1>→ ambíguo; o modelo pode cair no default de Reference
Strictly edit <Video 1>, ..., Extend <Video 1>, ..., <Video 1> + ... + followed by <Video 2>.
Mídia com pessoas não suportada
Os modelos públicos da API do Seedance não executam um fluxo de atestação de consentimento (consents.seedance / needs_consent). Mídia com pessoas detectáveis pode falhar com um erro de política de conteúdo ou do provedor. Use o app Venice ou o Studio em vez disso.
A cotação não bate com o valor da fila
Se você incluiu um vídeo de referência mas não passoureference_video_total_duration para /video/quote, a cotação e o valor cobrado na fila podem divergir. Sempre passe reference_video_total_duration (soma das durações de todos os clipes de referência, em segundos) quando houver vídeos de referência.
Referências
- Endpoint de fila de vídeo Venice:
POST /api/v1/video/queue - Endpoint de cotação Venice:
POST /api/v1/video/quote - Guia complementar: Reference to Video (cobre Kling O3 + Grok Imagine R2V)
- Guia complementar: Geração de Vídeo (visão geral de fila / polling)