API de referência Seedance 2.0: vídeo multimodal programático

O acesso programático a vídeos de IA multimodal muda o que é possível. Clipes avulsos são ótimos para marketing e criação de conteúdo, mas fluxos de trabalho automatizados, como geração de vídeos para catálogos, personalização por usuário e operações de conteúdo em lote, exigem acesso via API.

A API de Referência do Seedance 2.0 expõe toda a capacidade multimodal: até 9 imagens, 3 vídeos e 3 clipes de áudio por requisição, de forma programática, com o mesmo preço por segundo da interface web.

Resumo rápido

• Endpoint: bytedance/seedance-2.0/reference-to-video
• Entradas: prompt de texto + até 9 imagens + 3 vídeos + 3 clipes de áudio
• Preço: $0,3024/seg de saída, igual à interface web
• Saída: vídeo 720p, 4-15 segundos, sincronização de áudio nativa
• Tempo de geração: 60-180 segundos por requisição
• Ideal para automação de catálogos, fluxos em lote e conteúdo programático
• Experimente a API gratuitamente com 10 créditos

Quando usar a API

A interface web é ótima para trabalho criativo manual, um item de cada vez. A API serve para todo o resto.

A API é a escolha certa quando você precisa:

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

Fique com a interface web quando:

• Você está iterando criativamente e precisa ver e 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 necessário para gerações no modo Referência multimodal. Uma única requisição processa texto, até 9 imagens, até 3 vídeos e até 3 clipes de áudio. O modelo combina todas as entradas e retorna um vídeo gerado.

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

Estrutura da requisição

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

• prompt: Descrição textual do sujeito e da ação (obrigatório)
• reference_images: Array de até 9 URLs de imagens ou referências de arquivos
• reference_videos: Array de até 3 URLs de vídeos (opcional)
• reference_audio: Array de até 3 URLs de áudio (opcional)
• duration: Duração da saída em segundos, de 4 a 15 (obrigatório)
• aspect_ratio: Um dos valores 16:9, 9:16, 1:1 (obrigatório)

Os arquivos de entrada podem ser fornecidos como URLs (acessíveis publicamente) ou enviados diretamente, dependendo do padrão de integração utilizado.

Preços via API

Os preços da API são idênticos aos da interface web:

Não há taxa de acesso à API nem cobrança adicional pelo envio de referências. Você paga apenas pelos segundos de saída gerados.

Os créditos funcionam da mesma forma na API e na interface web. Recarregue pela página de preços e o mesmo pool de créditos é compartilhado pelas duas interfaces. Para uso intensivo da API, o plano Studio de $120 (1.800 créditos por mês) oferece a melhor taxa por crédito, e qualquer recarga adicional não expira.

Comece a desenvolver com a API. Obtenha acesso à API com 10 créditos grátis ao criar sua conta. Comece gratuitamente.

Exemplos de casos de uso

Automação de vídeos para catálogos

Para plataformas de e-commerce com centenas ou milhares de SKUs, a API permite gerar um vídeo curto de produto para cada item com base nas imagens existentes.

Fluxo de trabalho:

1. Consulte seu banco de dados de produtos
2. Para cada produto, busque de 5 a 7 imagens do produto
3. Combine com um conjunto de referências da marca (2-3 imagens)
4. Chame a API com um template de prompt para a revelação do produto
5. Armazene a URL do vídeo retornado no registro do produto
6. Exiba nas páginas de detalhes 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ídeos em todo o catálogo, isso representa um valor extraordinário.

Geração de vídeos personalizados

Para apps que entregam vídeos personalizados por usuário, como cartões de saudação, conteúdo de celebração e intros de onboarding, a API permite gerar vídeos sob demanda com referências específicas de cada usuário.

Fluxo de trabalho:

1. O usuário envia de 3 a 5 fotos pessoais (com consentimento)
2. Seu app as combina com um conjunto de referências de estilo
3. A chamada à API gera um clipe de vídeo personalizado
4. Entregue ao usuário por meio do seu app

Isso escala para dezenas de milhares de usuários sem necessidade de uma equipe de conteúdo.

Geração de variantes de criativos para anúncios

Equipes de marketing que veiculam anúncios em redes sociais precisam constantemente de variantes criativas. A API permite gerar variantes para testes A/B de forma programática.

Fluxo de trabalho:

1. Defina um conjunto de referências da marca (6-8 imagens)
2. Escreva templates de prompt para diferentes abordagens de anúncio
3. Percorra as variantes, chamando a API para cada uma
4. Envie os clipes gerados para sua plataforma de anúncios
5. Acompanhe o desempenho e escale as versões vencedoras

Você pode produzir 50 variantes de anúncios em uma execução automatizada por ~$150 em custos de API, em comparação com a produção tradicional, que custa milhares de dollars por variante.

Tratamento de respostas

As respostas da API geralmente incluem:

• ID de geração: Acompanhe o status da requisição
• Status: pending, processing, complete, failed
• URL de saída: Disponível quando o status for complete
• Metadados: Duração, resolução, tamanho do arquivo

As gerações no modo Referência levam 60-180 segundos, portanto sua integração deve tratar respostas assíncronas. Faça polling no endpoint de status ou use webhooks (se disponíveis na sua conta) para ser notificado quando a geração for concluída.

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

Limites de taxa e concorrência

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

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

Autenticação e chaves

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

Idempotência e novas tentativas

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

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

• Lógica de nova tentativa com backoff exponencial em falhas transitórias
• Polling de status ou tratamento de webhooks para conclusão assíncrona
• Registro de erros para identificar problemas sistemáticos
• Monitoramento do saldo de créditos para alertar antes de esgotá-los

Boas práticas para fluxos de trabalho programáticos

1. Use conjuntos de referências consistentes. Para trabalhos em catálogo ou em série, aplique hash aos seus conjuntos de referências para que bundles idênticos entre requisições produzam estilos mais consistentes.

2. Mantenha os templates de prompt simples. Prompts programáticos devem ser gerados a partir de dados estruturados, não escritos manualmente por chamada. O padrão correto é template mais campos de dados.

3. Armazene em cache as URLs dos arquivos de referência. Se você usar referências baseadas em URL, certifique-se de que as URLs sejam estáveis e acessíveis. URLs do S3 expiradas ou arquivos movidos causarão falhas nas gerações.

4. Trate a segurança de conteúdo adequadamente. A plataforma possui filtros de segurança de conteúdo. Implemente no seu fluxo de trabalho um tratamento adequado para requisições rejeitadas pelos filtros.

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

Exemplo de fluxo de trabalho em lote

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

for product in product_catalog:
    references = build_reference_bundle(
        brand_images,
        product.photo_urls[:4]
    )
    prompt = f"{product.name} produto gira lentamente sobre uma superfície limpa, iluminação suave de estúdio, 5 segundos"

    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 complementar trata a conclusão e armazena a URL de saída vinculada ao registro do produto.

Monitoramento e controle de custos

Para uso da API em produção, configure o monitoramento de custos:

• Alertas de orçamento diário: Alerte quando o gasto diário com a API ultrapassar um limite definido
• Limites por fluxo de trabalho: Restrinja jobs em lote a um gasto máximo de créditos para evitar automações descontroladas
• Painéis de uso: Acompanhe quais fluxos de trabalho consomem mais créditos
• Alertas de saldo de créditos: Recarregue antes de esgotar os créditos

Essas proteções evitam surpresas ao escalar a automação.

Paridade de preços entre API e interface web

Uma dúvida comum: há desconto para uso da API? Não. Tanto a API quanto a interface web cobram os mesmos $0,3024 por segundo. O preço da API reflete o trabalho realizado, não a interface utilizada.

Onde os usuários de alto volume economizam é na escolha do plano. Usuários com uso intensivo da API devem optar pelo $120 plano Studio para obter o melhor custo-benefício.

Primeiros passos com a API

1. Cadastre-se em arteza.ai (10 créditos grátis)
2. Gere sua chave de API nas configurações da conta
3. Recarregue um pacote de créditos compatível com o volume esperado
4. Integre o endpoint na sua aplicação
5. Comece com pequenos lotes de teste para validar seu fluxo de trabalho
6. Escale para produção após os testes

A primeira chamada à API pode estar em funcionamento em menos de uma hora após o cadastro para a maioria das integrações.

Próximas leituras

Para o conjunto completo de funcionalidades de Referência, leia o Guia completo do Seedance 2.0 Reference. Para o fluxo de trabalho na interface web, consulte o tutorial de estilo consistente. Para detalhes sobre a API padrão do Seedance 2.0, veja o Guia da API do Seedance 2.0.

O vídeo multimodal programático chegou. Construa algo novo com ele.