Seedance 2.0 Reference API: Vídeo Multi-Modal Programático

O acesso programático ao vídeo AI multimodal muda o que é possível. Clipes pontuais são ótimos para marketing e criação de conteúdo, mas fluxos de trabalho automatizados - geração de catálogo de vídeos, personalização por usuário, operações de conteúdo em lote - exigem acesso à API.

A Seedance 2.0 Reference API expõe a capacidade multimodal completa: até 9 imagens, 3 vídeos e 3 clipes de áudio por requisição, programaticamente, com o mesmo preço por segundo da interface web.

Quando Usar a API

A UI web é ótima para trabalho criativo manual, um de cada vez. A API é para tudo o mais.

A API é adequada quando você precisa:

• Geração em lote em centenas de ativos
• Integração com pipelines de conteúdo ou produto existentes
• Vídeo personalizado por usuário em uma aplicação
• Teste A/B automatizado de variantes criativas de anúncios
• Geração de conteúdo agendada para publicação diária
• Fluxos de catalogação vinculados a registros de banco de dados

Fique com a UI web quando:

• Você está iterando criativamente e precisa ver/ajustar cada saída
• O volume é baixo (menos de 10-20 clipes por sessão)
• Você está explorando a ferramenta pela primeira vez

O Endpoint

O endpoint Reference-to-video é:

bytedance/seedance-2.0/reference-to-video

Este é o único endpoint que você precisa para gerações do modo Reference multimodal. Uma única requisição trata texto, até 9 imagens, até 3 vídeos e até 3 clipes de áudio. O modelo funde todas as entradas e retorna um vídeo gerado.

Para fluxos de texto para vídeo ou imagem única, use os endpoints API Seedance 2.0 padrão em vez disso.

Estrutura da Requisição

Uma requisição típica de Reference-to-video inclui:

• prompt: Descrição em texto do assunto e ação (obrigatório)
• reference_images: Array de até 9 URLs de imagem ou referências de arquivo
• reference_videos: Array de até 3 URLs de vídeo (opcional)
• reference_audio: Array de até 3 URLs de áudio (opcional)
• duration: Duração de saída em segundos, 4-15 (obrigatório)
• aspect_ratio: Um de 16:9, 9:16, 1:1 (obrigatório)

Arquivos de entrada podem ser fornecidos como URLs (acessíveis publicamente) ou carregados diretamente dependendo do seu padrão de integração.

Preço Através da API

O preço da API corresponde exatamente ao preço da UI web:

Não há taxa de acesso à API e nenhuma cobrança adicional para uploads de referência. Você paga apenas pelos segundos de saída gerados.

Créditos funcionam da mesma forma na API e UI web. Top up via página de preços e o mesmo pool de créditos é usado por ambas as interfaces. Para uso de API de alto volume, o tier Max $100 (12.000 créditos) é o ponto de partida mais econômico.

Comece a construir com a API. Obtenha acesso à API com 50 créditos grátis no cadastro. Comece gratuitamente.

Exemplos de Casos de Uso

Automação de Vídeo de Catálogo

Para plataformas de ecommerce com centenas ou milhares de SKUs, a API permite gerar um vídeo curto de produto para cada produto com base em imagens de produto existentes.

Fluxo de trabalho:

1. Consulte seu banco de dados de produtos
2. Para cada produto, busque 5-7 imagens de produto
3. Combine com um pacote de referência de marca (2-3 imagens)
4. Chame a API com modelo de prompt para revelação de produto
5. Armazene a URL do vídeo retornado no registro do produto
6. Sirva nas páginas de detalhe do produto

Economia: Catálogo de 500 SKUs com vídeos de 5 segundos = 500 × 303 créditos = 151.500 créditos = ~$1.515. Para um lançamento de vídeo em todo o catálogo, esse é um valor notável.

Geração de Vídeo Personalizado

Para aplicativos que entregam vídeo personalizado por usuário - cartões de saudação, conteúdo de celebração, intros de integração - a API permite gerar vídeos sob demanda com referências específicas do usuário.

Fluxo de trabalho:

1. Usuário envia 3-5 fotos pessoais (com consentimento)
2. Seu aplicativo as combina com um pacote de referência de estilo
3. Chamada da API gera um clipe de vídeo personalizado
4. Entregue ao usuário através do seu aplicativo

Isso escala para dezenas de milhares de usuários sem sobrecarga da equipe de conteúdo.

Geração de Variante de Criativo de Anúncio

Equipes de marketing executando mídias sociais pagas precisam de constantes variantes criativas. A API permite gerar variantes de teste A/B programaticamente.

Fluxo de trabalho:

1. Defina um pacote de referência de marca (6-8 imagens)
2. Escreva modelos de prompt para diferentes ângulos de anúncio
3. Loop através de variantes, chamando a API para cada uma
4. Entregue clipes gerados à sua plataforma de anúncios
5. Rastreie o desempenho e gere vencedores em escala

Você pode produzir 50 variantes de anúncio em uma execução automatizada por ~$150 em custos de API, versus produção tradicional em milhares por variante.

Tratamento de Respostas

As respostas da API normalmente incluem:

• ID de Geração: Rastreie o status da requisição
• Status: pending, processing, complete, failed
• URL de Saída: Disponível quando o status está concluído
• Metadados: Duração, resolução, tamanho do arquivo

Gerações do modo Reference levam 60-180 segundos, então sua integração deve lidar com respostas assíncronas. Faça polling do endpoint de status ou use webhooks (se disponível em sua conta) para ser notificado na conclusão.

Não bloqueie fluxos voltados para o usuário na conclusão da geração. Enfileire a requisição, notifique o usuário quando pronto e entregue de forma assíncrona.

Limites de Taxa e Concorrência

Para a maioria dos níveis de conta, os limites de geração simultânea se aplicam. Planeje seus fluxos de trabalho em lote para respeitar os limites - enfileire requisições e processe-as na concorrência permitida.

Para fluxos de trabalho de produção de alto volume, entre em contato com o suporte da plataforma sobre limites de concorrência empresarial. A maioria das contas padrão pode lidar com trabalho em lote moderado (10-30 gerações simultâneas) sem problemas.

Autenticação e Chaves

O acesso à API usa autenticação padrão baseada em chaves. Gere sua chave de API nas configurações da conta após se inscrever. Mantenha as chaves apenas do lado do servidor - nunca as exponha no código do cliente.

Idempotência e Repetições

As gerações da API não são nativamente idempotentes porque cada chamada custa créditos. Se uma geração falhar no meio do processo, a lógica de repetição deve verificar o status da geração falhada antes de fazer uma nova requisição. Uma geração falhada normalmente não consome créditos, mas sempre verifique no painel da conta.

Para fluxos de trabalho de produção, implemente:

• Lógica de repetição com backoff exponencial em falhas transitórias
• Polling de status ou tratamento de webhook para conclusão assíncrona
• Logging de erro para capturar problemas sistemáticos
• Monitoramento de saldo de créditos para alertar antes de ficar sem

Melhores Práticas para Fluxos de Trabalho Programáticos

1. Use pacotes de referência consistentes. Para trabalho de catálogo ou série, hash seus pacotes de referência para que pacotes idênticos em requisições produzam estilo mais consistente.

2. Mantenha modelos de prompt simples. Prompts programáticos devem ser gerados a partir de dados estruturados, não escritos à mão por chamada. Modelo + campos de dados é o padrão correto.

3. Cache URLs de arquivos de referência. Se você estiver usando referências baseadas em URL, certifique-se de que as URLs são estáveis e acessíveis. URLs S3 expiradas ou arquivos movidos causarão falhas nas gerações.

4. Trate a segurança de conteúdo apropriadamente. A plataforma possui filtros de segurança de conteúdo. Construa tratamento gracioso para requisições rejeitadas por filtro em seu fluxo de trabalho.

5. Registre metadados de geração. Rastreie cada geração - prompt, conjunto de referência, duração, créditos consumidos, URL de saída - no banco de dados da sua aplicação. Isso facilita muito a depuração e relatórios.

Exemplo de Fluxo de Trabalho em Lote

Pseudocódigo para um fluxo de trabalho de geração de vídeo de produto em lote:

for product in product_catalog:
    references = build_reference_bundle(
        brand_images,
        product.photo_urls[:4]
    )
    prompt = f"{product.name} product rotates slowly on a clean surface, soft studio lighting, 5 seconds"

    response = seedance_api.generate(
        endpoint="bytedance/seedance-2.0/reference-to-video",
        prompt=prompt,
        reference_images=references,
        duration=5,
        aspect_ratio="16:9"
    )

    generation_id = response.id
    queue_poll_task(generation_id, product.id)

Um poller de acompanhamento trata a conclusão e armazena a URL de saída contra o registro do produto.

Monitoramento e Controle de Custo

Para uso de API de produção, configure monitoramento de custo:

• Alertas de orçamento diário: Alerte quando o gasto de API diário exceder um limite
• Limites por fluxo de trabalho: Limite trabalhos em lote para gastar máximo de créditos e impedir automação desenfreada
• Painéis de uso: Rastreie quais fluxos de trabalho consomem mais créditos
• Alertas de saldo de créditos: Top up antes de ficar sem

Essas medidas de proteção previnem surpresas quando você dimensiona a automação.

Paridade de Preço da API vs UI Web

Uma pergunta comum: existe desconto para uso de API? Não - API e UI web cobram o mesmo $0.3024 por segundo. A API é precificada pelo trabalho que ela faz, não pela interface que você usa.

Onde usuários de alto volume economizam é na seleção do tier. Usuários pesados de API devem rodar no Nível máximo de $100 para o melhor valor por dólar.

Começando com a API

1. Inscreva-se em arteza.ai (50 créditos grátis)
2. Gere sua chave de API nas configurações da conta
3. Top up um pacote de crédito correspondendo ao seu volume esperado
4. Integre o endpoint em sua aplicação
5. Comece com pequenos lotes de teste para validar seu fluxo de trabalho
6. Dimensione para produção uma vez testado

A primeira chamada de API pode estar ativa em uma hora do cadastro para a maioria das integrações.

Leituras Próximas

Para o conjunto de recursos Reference completo, leia o Guia completo Seedance 2.0 Reference. Para o fluxo de trabalho da UI web, veja o tutorial com estilo consistente. Para detalhes padrão da API Seedance 2.0, verifique o Guia da API Seedance 2.0.

Vídeo multimodal programático está aqui. Construa algo novo com isso.