Como Usar a API Seedance 2.0 em 2026

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

Experimente Hypereal AI

Experimente o Apidog hoje

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.

💡 Dica: A API segue um padrão de tarefa assíncrona: POST para criar a tarefa, receber o ID e então consultar um endpoint GET até que o trabalho termine. Este padrão deve ser testado de ponta a ponta antes de ir para produção. Os Cenários de Teste do Apidog permitem encadear o envio POST, extrair o ID, repetir consultas GET e afirmar que a resposta final contém uma URL de vídeo válida. Baixe o Apidog gratuitamente para seguir os passos de teste na seção sobre Apidog abaixo.

Este artigo cobre tipos de entrada suportados, cálculo de preços com base na resposta e os erros mais comuns na produção.

O que é Seedance 2.0?

Seedance 2.0 é um modelo de geração de vídeo da ByteDance, operando na Volcengine Ark sob os IDs de modelo doubao-seedance-2-0-260128 (padrão) e doubao-seedance-2-0-fast-260128 (rápido, menor qualidade).

Principais recursos:

• Texto-para-vídeo e imagem-para-vídeo
• Controle de quadro inicial e final (duas imagens)
• Entradas de referência multimodais: imagens, vídeos e áudio em uma requisição
• Geração de áudio nativa (diálogo, efeitos, música)
• Sincronização labial em 8+ idiomas
• Controle de movimento da câmera via prompt de linguagem natural
• Duração de até 15 segundos, resolução até 2K

O modelo gera vídeos a 24fps, com proporções de 1:1 a 21:9. A resolução é configurável na requisição.

O que mudou: guia vs. API oficial

Guias anteriores, incluindo este guia de fevereiro de 2026, cobriam apenas o console web. Agora, com a API oficial, é possível integrar Seedance a pipelines automatizados e produtos próprios. Este artigo foca no uso direto via API, para desenvolvedores.

Pré-requisitos

• Crie uma conta em volcengine.com.
• Gere sua chave de API no console do Ark:

https://console.volcengine.com/ark/region:ark+cn-beijing/apikey

• Exporte a chave como variável de ambiente:

export ARK_API_KEY="your-api-key-here"

• Use o token Bearer em cada requisição:

Authorization: Bearer YOUR_ARK_API_KEY

Contas novas recebem créditos de teste (cobrem ~8 gerações de 15s em 1080p).

Texto-para-vídeo: sua primeira requisição

A URL base da API Seedance:

https://ark.cn-beijing.volces.com/api/v3

Para criar uma tarefa texto-para-vídeo: POST em /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 resposta retorna o id da tarefa:

{"id": "cgt-2025xxxxxxxx-xxxx"}

Exemplo em Python (SDK oficial)

Instale o SDK:

pip install volcenginesdkarkruntime

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)

Guarde o id para a etapa de consulta.

Padrão de tarefa assíncrona: enviar, consultar, baixar

A geração não é instantânea. Um vídeo de 5s em 1080p leva 1-2 minutos. O ciclo:

queued -> running -> succeeded
                -> failed
                -> expired
                -> cancelled

Consulte o endpoint GET até o status sair de queued/running.

Loop 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 tarefa
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 status 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)

# Passo 3: Baixar vídeo
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")

Use backoff exponencial para evitar sobrecarregar a API.

Imagem-para-vídeo (I2V): animando uma imagem

Para animar uma imagem estática, adicione um objeto image_url ao array content junto ao prompt de texto. A imagem vira o quadro inicial.

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,
)

• Use ratio="adaptive" para manter a proporção da imagem.
• Imagens: até 30MB cada, máximo 9 por requisição.

Quadro inicial e final: controlando pontos de início e fim

Forneça duas imagens (primeiro e último quadro) mais o prompt de texto. O modelo faz a transição entre elas.

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,
)

Inclua as imagens em ordem (primeiro depois último quadro). Para encadear clipes, use return_last_frame: true para obter a imagem do último quadro e alimentar na próxima requisição.

Referência multimodal: combinando imagens, vídeo e áudio

Seedance 2.0 permite enviar imagens, vídeos e áudio como referência na mesma tarefa.

Array de conteúdo pode conter:

• {"type": "text", ...} para prompt
• {"type": "image_url", ...} para imagens
• {"type": "video_url", ...} para vídeos
• {"type": "audio_url", ...} para áudio

Limites:

• Até 9 imagens (<30MB cada)
• Até 3 vídeos (2-15s, <50MB cada)
• Até 3 áudios (MP3, <15MB cada)

Exemplo:

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,
)

Com referência de vídeo, o custo por token cai (~US$3,90/M tokens).

Geração de áudio nativa

Para gerar trilha de áudio junto ao vídeo, defina generate_audio: true.

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 cobre diálogos, efeitos, ambiente e música, com sincronização labial em vários idiomas. Isso aumenta um pouco o consumo de tokens.

Controlando resolução, proporção e duração

• resolução: "480p", "720p", "1080p", "2K". Padrão: "1080p".
• proporção: "16:9", "9:16", "4:3", "3:4", "21:9", "1:1", "adaptive".
• duração: inteiro de 4 a 15 (segundos). Padrão: 5.

O modelo rápido (doubao-seedance-2-0-fast-260128) é útil para prototipagem. Use o padrão para produção.

Prefira Seedance 2.0 para geração áudio-vídeo conjunta, controle de quadros e referências multimodais. Para T2V simples e barato, use o modelo rápido em 480p.

Lendo o custo da resposta

Após sucesso, a resposta inclui:

{
  "usage": {
    "completion_tokens": 246840,
    "total_tokens": 246840
  }
}

Referências:

• 15s 1080p ≈ 308.880 tokens
• 5s 1080p ≈ 102.960 tokens

Preço:

• T2V/I2V 1080p: 46 yuans/M tokens (~US$6,40/M tokens)
• V2V: 28 yuans/M tokens (~US$3,90/M tokens)

Exemplo:

• 5s 1080p: ≈ 102.960 tokens ≈ US$0,93
• 10s 1080p: ≈ 205.920 tokens ≈ US$1,97

Multiplique completion_tokens pela taxa do tipo de tarefa para rastreamento de custos.

Importante: baixe o vídeo em até 24 horas

A video_url expira 24h após o status "succeeded". Após isso, retorna erro 403 e o arquivo é perdido.

Baixe o arquivo imediatamente após sucesso. Consulte o campo execution_expires_after para o tempo de expiração da tarefa (em segundos), mas a URL segue a regra das 24h.

O histórico de tarefas só guarda os últimos 7 dias.

Como testar a API Seedance com Apidog

O padrão assíncrono envolve múltiplas chamadas dependentes. Use Cenários de Teste do Apidog para automatizar:

Passos práticos

1. Crie um Cenário de Teste

• No módulo Testes do Apidog, crie o cenário "Geração de vídeo Seedance 2.0".
• Defina a variável de ambiente ARK_API_KEY.

2. Adicione a requisição de envio

• POST para https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks
• Cabeçalho: Authorization: Bearer {{ARK_API_KEY}}
• Corpo JSON com modelo e conteúdo

Após enviar, extraia o id do corpo usando JSONPath $.id e salve como variável TASK_ID.

3. Adicione processador de Espera

• Processador "Wait" de 30s após extração do ID.

4. Adicione a consulta em loop

• Bloco For (máx 20 iterações):
  1. GET para /contents/generations/tasks/{{TASK_ID}}
  2. "Wait" de 10s após GET
  3. Quebre o loop se $.status == "succeeded" ou $.status == "failed"

5. Adicione asserções

• Após o loop, afirme que:
  • $.status é "succeeded"
  • $.content.video_url não está vazio

Execute o cenário. O Apidog mostra relatório detalhado de cada etapa, ID extraído, respostas e assertivas finais.

Você pode importar endpoints Seedance por comando cURL para agilizar a criação do cenário.

Detalhamento de preços: quanto custa um vídeo de 10 segundos

A cobrança é por uso (tokens):

Tipo de tarefa	Taxa (por 1M tokens)
T2V / I2V em 1080p	46 yuans (~US$6,40)
V2V (referência de vídeo)	28 yuans (~US$3,90)

Exemplos para 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

Contas novas recebem créditos de teste (~8 gerações de 15s). Use 720p no desenvolvimento para economizar tokens.

Erros comuns e correções

• 429 Muitas Requisições: Limite de concorrência. Use backoff exponencial (espere 10s, dobre, limite a 60s).
• status: "failed": Prompt violou filtros, imagem corrompida, parâmetros inválidos. Revise arquivos e tente novamente.
• status: "expired": Tarefa ficou muito tempo na fila. Reenvie.
• 403 na video_url: URL expirada. Geração antiga (>24h). Reenvie a tarefa.
• Reprodutibilidade com seed: Salve o seed da resposta e use para tentar gerar o mesmo vídeo novamente.

Conclusão

A API Seedance 2.0 permite automação completa de geração de vídeos avançados. O fluxo POST -> consulta -> download é simples de implementar. Suporte a multimodalidade, áudio nativo e controle de quadros habilita fluxos de trabalho impossíveis via console web.

Implemente sua cobertura de testes no Apidog antes de ir para produção. O uso de Cenários de Teste identifica problemas de consulta, extração ou expiração de URL antes que impactem os usuários.

Perguntas Frequentes

P: Qual a diferença entre doubao-seedance-2-0-260128 e doubao-seedance-2-0-fast-260128?

O modelo padrão gera vídeos com qualidade superior, indicado para produção. O modelo rápido é útil para prototipagem, com menor qualidade.

P: Posso usar o Seedance 2.0 fora da China?

Sim, mas o endpoint fica em Pequim. Fora da China, haverá maior latência. Confira os termos da Volcengine para restrições regionais.

P: Como encadear vários clipes em um vídeo mais longo?

Use return_last_frame: true para obter o último quadro. Passe como quadro inicial da próxima tarefa. Junte os clipes depois.

P: A geração de áudio nativa custa mais?

Sim, pois gera áudio e vídeo conjuntamente. Espere um aumento modesto em completion_tokens.

P: Posso definir um webhook em vez de polling?

Sim. Passe callback_url na requisição POST. A API fará POST para essa URL ao concluir a tarefa.

P: O que acontece se eu exceder 9 imagens?

A API retorna erro 400. Reduza para 9 ou menos.

P: O parâmetro seed garante reprodução idêntica?

Ajuda a reproduzir a saída, mas não garante identidade se parâmetros ou versão do modelo mudarem.

P: Como rastrear gastos em várias tarefas?

Leia o campo completion_tokens de cada resposta, multiplique pela taxa do seu tipo de tarefa e salve num banco de dados próprio. Não há painel integrado na API.