Resumo
A API Seedance 2.0 foi lançada em 2 de abril de 2026, através da Volcengine Ark. Você envia uma tarefa de geração de vídeo com uma requisição POST e então consulta um endpoint GET até que o status atinja "succeeded" (bem-sucedido). A API suporta texto-para-vídeo, imagem-para-vídeo, controle de quadro inicial e final, referências multimodais e geração de áudio nativa. Um vídeo de 5 segundos em 1080p custa aproximadamente US$0,93. Faça o download do vídeo em até 24 horas. A URL expira depois disso.
Hypereal AI
Introdução
Em 2 de abril de 2026, a plataforma Volcengine Ark da ByteDance lançou a API oficial do Seedance 2.0. Antes dessa data, a única forma de gerar vídeos Seedance 2.0 era através do console web. Se você viu tutoriais mostrando um passo a passo da interface do usuário, eles foram escritos para o console. Este guia cobre a API real que os desenvolvedores podem chamar programaticamente.
Este artigo abrange todos os tipos de entrada suportados, o cálculo de preços a partir da contagem de tokens de resposta e os erros que você encontrará em produção.
O que é Seedance 2.0?
Seedance 2.0 é um modelo de geração de vídeo da ByteDance. Ele roda na Volcengine Ark sob os IDs de modelo doubao-seedance-2-0-260128 (padrão) e doubao-seedance-2-0-fast-260128 (mais rápido, menor qualidade).
O modelo suporta mais tipos de entrada do que a versão 1.5. A versão 1.5 lidava com texto-para-vídeo e imagem-para-vídeo. A versão 2.0 adiciona:
- Controle de quadro inicial e final (você fornece as duas imagens de abertura e encerramento)
- Entradas de referência multimodais: imagens, clipes de vídeo e arquivos de áudio combinados em uma única requisição
- Geração de áudio nativa, incluindo diálogo, efeitos sonoros, som ambiente e música
- Sincronização labial em mais de 8 idiomas
- Controle de movimento da câmera através de prompts de linguagem natural (dolly, tracking, crane shots)
- Saída de até 15 segundos de duração com resolução de até 2K
O modelo gera vídeos a 24 fps em proporções de aspecto de 1:1 a 21:9. Você escolhe a resolução no momento da requisição.
O que mudou: guia vs. API oficial
Artigos anteriores sobre o Seedance 2.0, incluindo um guia de fevereiro de 2026 neste site, descreviam o console web do Seedance 2.0 na Volcengine. Nenhuma API existia naquele ponto. Esses guias detalhavam como preencher um campo de prompt em uma página da web e clicar em um botão de gerar.
O lançamento da API em 2 de abril de 2026 muda isso completamente. Agora você pode chamar a API de qualquer linguagem, automatizar pipelines de geração de vídeo e integrar o Seedance ao seu próprio produto. Este guia substitui o passo a passo da interface do usuário para qualquer caso de uso de desenvolvedor.
Pré-requisitos
Você precisa de uma conta Volcengine para começar. Crie uma em volcengine.com. Assim que sua conta estiver ativa, vá para o console do Ark em:
https://console.volcengine.com/ark/region:ark+cn-beijing/apikey
Gere uma chave de API lá. Em seguida, exporte-a como uma variável de ambiente:
export ARK_API_KEY="your-api-key-here"
Cada requisição à API usa esta chave em um cabeçalho de token Bearer:
Authorization: Bearer YOUR_ARK_API_KEY
Novas contas recebem créditos de teste gratuitos. Estes cobrem aproximadamente 8 gerações completas de 15 segundos em 1080p antes que você precise pagar.
Texto-para-vídeo: sua primeira requisição
A URL base para todas as chamadas da API Seedance é:
https://ark.cn-beijing.volces.com/api/v3
Para enviar uma tarefa de texto-para-vídeo, faça um POST para /v1/contents/generations/tasks.
Exemplo de cURL
curl -X POST "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ARK_API_KEY" \
-d '{
"model": "doubao-seedance-2-0-260128",
"content": [
{
"type": "text",
"text": "A golden retriever running through a sunlit wheat field, wide tracking shot, cinematic"
}
],
"resolution": "1080p",
"ratio": "16:9",
"duration": 5,
"watermark": false
}'
A API retorna um ID de tarefa imediatamente:
{"id": "cgt-2025xxxxxxxx-xxxx"}
Exemplo em Python (SDK oficial)
Instale o SDK primeiro:
pip install volcenginesdkarkruntime
Em seguida, envie uma tarefa:
import os
from volcenginesdkarkruntime import Ark
client = Ark(api_key=os.environ.get("ARK_API_KEY"))
resp = client.content_generation.tasks.create(
model="doubao-seedance-2-0-260128",
content=[
{
"type": "text",
"text": "A golden retriever running through a sunlit wheat field, wide tracking shot, cinematic"
}
],
resolution="1080p",
ratio="16:9",
duration=5,
watermark=False,
)
print(resp.id)
Armazene o ID da tarefa. Você precisará dele para a etapa de consulta.
O padrão de tarefa assíncrona: enviar, consultar, baixar
A geração do Seedance não é instantânea. Um vídeo de 5 segundos em 1080p geralmente leva de 60 a 120 segundos. A API lida com isso através de um ciclo de vida de tarefa assíncrona:
queued -> running -> succeeded
-> failed
-> expired
-> cancelled
Você consulta o endpoint GET até que o status mude de queued (na fila) ou running (em execução).
Loop completo de consulta em Python
import os
import time
import requests
from volcenginesdkarkruntime import Ark
client = Ark(api_key=os.environ.get("ARK_API_KEY"))
# Passo 1: enviar
resp = client.content_generation.tasks.create(
model="doubao-seedance-2-0-260128",
content=[
{"type": "text", "text": "Aerial shot of a mountain lake at sunrise, slow dolly forward"}
],
resolution="1080p",
ratio="16:9",
duration=5,
watermark=False,
)
task_id = resp.id
print(f"Tarefa enviada: {task_id}")
# Passo 2: consultar com backoff exponencial
wait = 10
while True:
result = client.content_generation.tasks.get(task_id=task_id)
status = result.status
print(f"Status: {status}")
if status == "succeeded":
video_url = result.content.video_url
print(f"URL do vídeo: {video_url}")
break
elif status in ("failed", "expired", "cancelled"):
print(f"Tarefa terminou com status: {status}")
break
time.sleep(wait)
wait = min(wait * 2, 60) # limite em 60 segundos
# Passo 3: baixar imediatamente
if status == "succeeded":
response = requests.get(video_url, stream=True)
with open("output.mp4", "wb") as f:
for chunk in response.iter_content(chunk_size=8192):
f.write(chunk)
print("Baixado: output.mp4")
O backoff exponencial evita sobrecarregar a API. O limite de 60 segundos mantém a consulta frequente o suficiente para uso prático.
Imagem-para-vídeo (I2V): animando uma imagem estática
Para animar uma imagem, adicione um objeto image_url ao array content junto com seu prompt de texto. A imagem se torna o primeiro quadro do vídeo.
resp = client.content_generation.tasks.create(
model="doubao-seedance-2-0-260128",
content=[
{
"type": "text",
"text": "The woman slowly turns her head and smiles at the camera"
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/portrait.jpg"}
}
],
ratio="adaptive",
duration=5,
watermark=False,
)
Definir ratio como `"adaptive"` instrui o modelo a usar a proporção nativa da imagem de entrada. Isso evita cortes indesejados ou letterboxing.
Cada imagem deve ter menos de 30MB. Você pode fornecer até 9 imagens em uma única requisição.
Quadro inicial e final: controlando pontos de início e fim
Seedance 2.0 suporta controle de quadros de início e fim. Você fornece a imagem do primeiro quadro, a imagem do último quadro e um prompt de texto. O modelo gera o movimento intermediário.
Isso é útil para transições de produtos, efeitos de morphing ou qualquer sequência onde você conhece seus estados inicial e final.
resp = client.content_generation.tasks.create(
model="doubao-seedance-2-0-260128",
content=[
{
"type": "text",
"text": "The flower blooms from bud to full open, macro lens, soft light"
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/flower-bud.jpg"}
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/flower-open.jpg"}
}
],
ratio="adaptive",
duration=8,
watermark=False,
)
O modelo infere que duas imagens significam o modo de primeiro e último quadro quando um prompt de texto também está presente. Inclua ambas as imagens em ordem: primeiro quadro, depois o último quadro.
Você também pode usar return_last_frame: true ao gerar um clipe. Isso retorna uma imagem do quadro final junto com a URL do vídeo. Alimente essa imagem como o primeiro quadro de sua próxima requisição para encadear vários clipes em uma sequência mais longa.
Referência multimodal: combinando imagens, vídeo e áudio
Uma das adições mais fortes no Seedance 2.0 é a aceitação de vídeo e áudio como entradas de referência na mesma requisição que imagens e texto.
O array de conteúdo pode conter:
{"type": "text", "text": "..."}para o prompt{"type": "image_url", "image_url": {"url": "..."}}para imagens{"type": "video_url", "video_url": {"url": "..."}}para referências de vídeo{"type": "audio_url", "audio_url": {"url": "..."}}para referências de áudio
Limites por requisição:
- Até 9 imagens (máximo de 30MB cada)
- Até 3 clipes de vídeo (de 2 a 15 segundos cada, máximo de 50MB cada)
- Até 3 arquivos de áudio (MP3, máximo de 15MB cada)
Um exemplo de referência combinada:
resp = client.content_generation.tasks.create(
model="doubao-seedance-2-0-260128",
content=[
{
"type": "text",
"text": "Match the visual style of the reference clip and add the provided background audio"
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/style-reference.jpg"}
},
{
"type": "video_url",
"video_url": {"url": "https://example.com/motion-reference.mp4"}
},
{
"type": "audio_url",
"audio_url": {"url": "https://example.com/background-music.mp3"}
}
],
duration=10,
ratio="16:9",
watermark=False,
)
Quando você inclui uma referência de vídeo, a taxa de cobrança cai para o nível V2V: aproximadamente US$3,90 por milhão de tokens em vez de US$6,40.
Geração de áudio nativa
Defina generate_audio: true para que o Seedance gere uma trilha de áudio junto com o vídeo. O modelo realiza a geração conjunta de áudio e vídeo, de modo que os sons correspondam à ação na tela em vez de serem sobrepostos posteriormente.
A geração de áudio cobre diálogos, efeitos sonoros, ruído ambiente e música de fundo. A sincronização labial funciona em mais de 8 idiomas.
resp = client.content_generation.tasks.create(
model="doubao-seedance-2-0-260128",
content=[
{
"type": "text",
"text": "A street musician plays guitar outside a cafe in Paris, crowds passing by, city sounds"
}
],
resolution="1080p",
ratio="16:9",
duration=10,
generate_audio=True,
watermark=False,
)
A geração de áudio nativa aumenta ligeiramente o consumo de tokens em comparação com vídeos sem áudio. Leve isso em consideração em suas estimativas de custo.
Controlando resolução, proporção e duração
Três parâmetros moldam a saída:
resolução aceita `"480p"`, `"720p"`, `"1080p"` ou `"2K"`. O padrão é `"1080p"`. Resoluções mais altas significam mais tokens consumidos e custo mais elevado.
proporção aceita `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"`, `"21:9"`, `"1:1"` ou `"adaptive"`. Use `"adaptive"` quando sua imagem de entrada tiver uma proporção incomum. O modelo lê as dimensões da imagem e define a proporção de acordo.
duração aceita inteiros de 4 a 15. A unidade é segundos. O padrão é 5. Vídeos mais longos custam proporcionalmente mais.
O modelo rápido (doubao-seedance-2-0-fast-260128) gera com menor qualidade, mas termina mais rapidamente. Use-o para prototipagem ou quando estiver iterando em prompts. Mude para o modelo padrão para a saída final de produção.
Quando escolher Seedance 2.0 em vez de outras APIs de vídeo: escolha Seedance quando precisar de geração conjunta nativa de áudio-vídeo, controle de quadro inicial e final, ou entradas de referência multimodais. Se você precisar apenas de texto-para-vídeo simples e o custo for a prioridade, o modelo rápido em 480p é a opção mais barata nesta classe.
Lendo o custo da resposta
Após uma tarefa ser bem-sucedida, a resposta inclui um campo usage:
{
"usage": {
"completion_tokens": 246840,
"total_tokens": 246840
}
}
O consumo de tokens se correlaciona com o comprimento e a resolução do vídeo. Um ponto de referência da documentação oficial: um vídeo de 15 segundos em 1080p consome aproximadamente 308.880 tokens. Um vídeo de 5 segundos em 1080p usa aproximadamente 102.960 tokens.
O preço para T2V e I2V em 1080p é de 46 yuans por milhão de tokens (cerca de US$6,40 por milhão de tokens nas taxas de câmbio atuais).
Estimativas rápidas:
- Vídeo de 5 segundos em 1080p: aproximadamente 102.960 tokens = cerca de 0,47 yuan = aproximadamente US$0,93
- Vídeo de 10 segundos em 1080p: aproximadamente 205.920 tokens = cerca de 9,47 yuan = aproximadamente US$1,97
Para tarefas V2V (requisições que incluem uma referência de vídeo), a taxa cai para 28 yuans por milhão de tokens (cerca de US$3,90 por milhão de tokens).
Você pode verificar a contagem exata de tokens em cada resposta e incorporar o rastreamento de custos em sua aplicação. Multiplique completion_tokens pela taxa do seu tipo de tarefa.
Importante: baixe o vídeo em até 24 horas
A video_url em uma resposta bem-sucedida aponta para o armazenamento de objetos da Volcengine. Essa URL expira 24 horas após a tarefa ser bem-sucedida. Depois disso, a URL retorna um erro 403 e o arquivo é perdido.
Sempre baixe o arquivo para seu próprio armazenamento imediatamente após o status mudar para succeeded. O loop de consulta na seção anterior inclui esta etapa de download como parte do fluxo padrão.
O campo `execution_expires_after` confirma a janela de expiração em segundos. 172800 significa 48 horas para o próprio registro da tarefa. A URL do vídeo ainda expira em 24 horas, independentemente. Confie na regra das 24 horas.
O histórico de tarefas também é limitado aos últimos 7 dias. Você não pode consultar tarefas mais antigas do que isso.
Como testar a API Seedance com Apidog
O padrão de tarefa assíncrona possui duas chamadas de API que dependem uma da outra. Você não pode escrever um teste de única requisição para isso. Os Cenários de Teste do Apidog lidam com isso com um fluxo encadeado.
Aqui está a configuração exata:
Passo 1: Crie um Cenário de Teste
No Apidog, vá para o módulo de Testes e crie um novo cenário chamado "Geração de vídeo Seedance 2.0". Defina sua variável de ambiente ARK_API_KEY nas configurações de ambiente do Apidog. Use {{ARK_API_KEY}} em qualquer lugar onde você referenciaria a chave.
Passo 2: Adicione a requisição de envio
Adicione uma etapa de requisição POST personalizada para https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks. Defina o cabeçalho de Autorização como Bearer {{ARK_API_KEY}}. Adicione seu corpo JSON com os campos de modelo e conteúdo.
Após esta etapa, adicione um processador "Extract Variable". Configure-o para extrair do corpo da resposta usando a expressão JSONPath $.id. Salve o valor em uma variável de ambiente chamada TASK_ID.
Passo 3: Adicione um processador de Espera
Insira um processador "Wait" após a etapa de extração. Defina o atraso para 30 segundos. Isso dá tempo ao modelo para começar a processar antes da sua primeira tentativa de consulta.
Passo 4: Adicione a requisição de consulta em um loop For
Adicione um bloco de controle de loop For com um máximo de 20 iterações. Dentro do loop:
- Adicione uma etapa de requisição GET para
https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/{{TASK_ID}}com o mesmo cabeçalho de Autorização. - Adicione um processador "Wait" com um atraso de 10 segundos após a requisição GET.
- Defina a condição "Break If" do loop:
$.status == "succeeded"ou$.status == "failed".
Passo 5: Adicione asserções
Após a saída do loop, adicione um processador "Assertion" que verifica:
$.statusé igual a `"succeeded"`$.content.video_urlnão está vazio
Execute o cenário e o Apidog gera um relatório de teste completo mostrando cada etapa, o ID da tarefa extraído, todas as respostas de consulta e se as asserções finais foram aprovadas.
Você também pode importar os endpoints do Seedance diretamente de um comando cURL para as etapas do cenário de teste. Essa abordagem funciona bem quando você quer adicionar rapidamente as requisições de envio e consulta sem inserir manualmente cada cabeçalho e parâmetro.
Detalhamento de preços: quanto custa um vídeo de 10 segundos
A API Seedance usa um modelo de precificação por token de pagamento conforme o uso. Não há assentos mensais ou créditos para gerenciar além do saldo de teste inicial.
| Tipo de tarefa | Taxa (por 1M de tokens) |
|---|---|
| T2V / I2V em 1080p | 46 yuans (~US$6,40) |
| V2V (entrada de referência de vídeo) | 28 yuans (~US$3,90) |
Custos aproximados para durações comuns em 1080p:
| Duração | Tokens aprox. | Custo (T2V/I2V) |
|---|---|---|
| 5 segundos | ~103.000 | ~$0,66 yuan / ~$0,93 |
| 10 segundos | ~206.000 | ~$9,48 yuan / ~$1,32 |
| 15 segundos | ~309.000 | ~$14,21 yuan / ~$1,97 |
Novas contas começam com créditos de teste gratuitos que cobrem cerca de 8 gerações completas de 15 segundos. Use essa franquia para experimentar prompts e configurações antes de se comprometer com uma carga de trabalho de produção.
Resoluções mais baixas reduzem significativamente o consumo de tokens. Um vídeo de 480p com a mesma duração custa consideravelmente menos do que um de 1080p. Comece o desenvolvimento em 720p e atualize a resolução apenas para sua saída final.
Erros comuns e correções
429 Muitas Requisições
Isso significa que você atingiu o limite de concorrência, não um limite de taxa de requisições por minuto. Muitas tarefas estão sendo executadas ao mesmo tempo. Use o backoff exponencial quando vir este código de status. Comece com uma espera de 10 segundos e duplique-a a cada tentativa, limitando a 60 segundos. O loop de consulta mostrado anteriormente inclui este padrão.
status: "failed" (falhou)
Uma tarefa falha significa que o modelo não conseguiu gerar o vídeo. Causas comuns: o prompt continha conteúdo que violava os filtros de segurança, a imagem de entrada estava corrompida ou era muito grande, ou a combinação de parâmetros era inválida. Verifique seus arquivos de entrada e prompt e, em seguida, reenvie.
status: "expired" (expirado)
Uma tarefa expira se permanecer na fila por muito tempo sem ser concluída. Isso pode acontecer durante períodos de pico de carga. Reenvie a tarefa. Não há como reiniciar uma tarefa expirada.
403 na video_url
A URL expirou. A janela de 24 horas passou antes de você baixar o arquivo. O registro da tarefa ainda pode existir na API por até 7 dias, mas o arquivo de vídeo foi perdido. Você precisará regenerá-lo usando os mesmos parâmetros e valor de seed, se o tiver salvo.
Reprodutibilidade do seed
Se você salvou o valor seed de uma resposta anterior, passe-o de volta na próxima requisição com os mesmos parâmetros. O modelo tentará reproduzir a mesma saída. Isso é útil para regenerar vídeos expirados com resultados idênticos.
Conclusão
A API Seedance 2.0 oferece acesso programático a um dos modelos de geração de vídeo mais capazes disponíveis atualmente. O padrão de tarefa assíncrona é direto: POST para criar uma tarefa, consultar até ser bem-sucedida, baixar imediatamente. As entradas multimodais, geração de áudio nativa e controle de quadro inicial e final tornam possível construir fluxos de trabalho de vídeo que eram impossíveis a partir de um console web.
Configure sua cobertura de teste no Apidog antes de ir para produção. A cadeia de Cenários de Teste detecta lógica de consulta quebrada, etapas de extração ausentes e problemas de expiração de URL antes que afetem usuários reais.
Botão
Perguntas Frequentes
P: Qual a diferença entre doubao-seedance-2-0-260128 e doubao-seedance-2-0-fast-260128?
O modelo padrão produz saída de maior qualidade e é o padrão para produção. O modelo rápido completa trabalhos mais rapidamente com menor qualidade visual. Use o modelo rápido ao iterar em prompts e mude para o padrão para renderizações finais.
P: Posso usar o Seedance 2.0 fora da China?
O endpoint da API é hospedado na região de Pequim. Desenvolvedores fora da China podem chamá-lo, mas a latência será maior. Verifique os termos de serviço da Volcengine para quaisquer restrições geográficas no seu tipo de conta.
P: Como encadeio vários clipes em um vídeo mais longo?
Defina return_last_frame: true em cada geração. A resposta incluirá uma imagem do último quadro junto com a URL do vídeo. Passe essa imagem como o primeiro quadro de sua próxima requisição. Repita até ter todos os clipes de que precisa e, em seguida, junte-os usando uma biblioteca de edição de vídeo.
P: A geração de áudio nativa custa mais?
A geração de áudio nativa aumenta ligeiramente o consumo de tokens porque o modelo executa a geração conjunta de áudio-vídeo em vez de apenas vídeo. Espere um aumento modesto em `completion_tokens` em comparação com a mesma requisição sem `generate_audio: true`.
P: Posso definir um webhook em vez de fazer polling?
Sim. Passe um parâmetro `callback_url` em sua requisição de envio. A API fará um POST com o resultado da tarefa concluída para essa URL quando o status mudar. Isso é mais eficiente do que o polling para pipelines de alto volume.
P: O que acontece se eu exceder o limite de 9 imagens?
A API retorna um erro de validação 400 antes que a tarefa seja criada. Reduza o número de imagens no seu array de conteúdo para 9 ou menos.
P: O parâmetro seed garante a reprodução exata do mesmo vídeo?
O parâmetro seed torna as saídas mais reproduzíveis. A reprodução exata não é garantida se os parâmetros diferirem ou as versões do modelo no servidor mudarem. É a aproximação mais próxima disponível.
P: Como rastreio os gastos em várias tarefas?
Leia o campo `completion_tokens` da resposta de cada tarefa e multiplique pela taxa de token do seu nível. Registre esses valores em um banco de dados para rastreamento de custos. Não há um painel de gastos integrado na API, então construa seu próprio rastreamento desde o início.