Materiais Seedance do TokenLab: Referências de vídeo reutilizáveis para fluxos de trabalho de produção

Se a sua equipe já colou a mesma URL de troca de rosto (face-swap) em três chamadas de API diferentes, você já sabe por que a biblioteca de materiais Seedance existe. Referências de vídeo reutilizáveis funcionam melhor como ativos com status de ciclo de vida do que como URLs únicas copiadas de uma planilha para cada solicitação de geração. O TokenLab delimita esses ativos à sua organização, para que você possa armazenar, verificar e reutilizar referências entre chamadas. Testamos o formato do fluxo de trabalho: grupos organizam material de pessoas reais, ativos contêm a referência real e as chamadas de geração consomem IDs apenas após o status atingir ACTIVE. Por exemplo, uma equipe que antes mantinha uma planilha de links de imagem e fazia o upload do mesmo vídeo de referência cinco vezes pode substituir esse hábito por um único ID de ativo de material.

Principais Pontos

• Um ativo de material é o objeto de referência pronto para geração; um grupo de material é o contêiner que organiza ativos relacionados, especialmente para fluxos de trabalho com pessoas reais.
• Use o id de um ativo de material como material_asset_id (ou dentro de material_asset_ids) apenas após o seu status atingir ACTIVE.
• Existem dois tipos de biblioteca: aigc_avatar para avatares virtuais e outras referências reutilizáveis que não são de pessoas reais, e liveness_face para grupos de material de pessoas reais que exigem verificação.
• O TokenLab pode preparar automaticamente entradas de imagem compatíveis (image, image_url, image_urls, reference_images, start_image, end_image) em ativos de material sem uma etapa de upload separada.
• Se a preparação levar mais de 60 segundos, a API retorna 409 seedance_material_preparing juntamente com auto_material_asset_ids que você pode consultar e tentar novamente.
• Seedance é a família de modelos públicos atual que este sistema de material suporta. Verifique os detalhes exatos de capacidade por modelo na documentação antes de criar uma dependência em um nível específico.

Biblioteca de Materiais Seedance: Ativos e Grupos

Um material Seedance é uma referência reutilizável — imagem, vídeo ou áudio — que o TokenLab armazena como um ativo delimitado pela organização, em vez de uma URL delimitada pela solicitação. Em vez de passar um link de arquivo bruto em cada chamada create-video, você faz o upload ou importa a referência uma vez, aguarda até que ela esteja pronta para geração e, em seguida, referencia-a pelo ID em quantas chamadas subsequentes precisar.

Isso é importante por três razões práticas. Primeiro, uploads repetidos desperdiçam largura de banda e adicionam latência a cada solicitação, especialmente para vídeos de referência grandes. Segundo, URLs brutas expiram, são rotacionadas ou revogadas por qualquer sistema de armazenamento que as hospedou originalmente. Um ativo de material gerenciado pelo TokenLab não possui essa fragilidade. Terceiro, e mais relevante para equipes que constroem pipelines de vídeo com consistência de personagem ou marca, os materiais oferecem um identificador estável que você pode versionar, auditar e trocar sem alterar sua lógica de geração a cada vez.

Ativos de Material vs. Grupos de Material

Os dois objetos principais neste sistema são o ativo de material e o grupo de ativos de material. É fácil confundi-los se você não leu a referência da API com atenção.

Um ativo de material é um objeto de referência único — uma imagem de avatar, um rosto verificado por vivacidade (liveness), um clipe de vídeo de referência. Quando você o cria, a API retorna um id. Esse id é o que você eventualmente passa para as chamadas de geração de vídeo assim que o ativo atinge o status ACTIVE.

Um grupo de ativos de material é um contêiner identificado por group_id. Os grupos organizam ativos relacionados. Eles são estruturalmente necessários para fluxos de trabalho de pessoas reais (liveness_face), onde a verificação ocorre no nível do grupo antes que ativos individuais possam ser carregados nele.

Em resumo: group_id organiza; material_asset_id gera. Você verá ambos os campos em diferentes partes da API. Usar o campo errado no lugar errado é o erro de integração mais comum que as equipes cometem com este sistema.

Campo	O que identifica	Onde você usa
group_id	Um grupo de ativos de material (contêiner)	Criando ou referenciando um grupo, especialmente para fluxos de verificação de pessoas reais
id (em um ativo de material)	Uma referência reutilizável única	Torna-se material_asset_id uma vez ACTIVE
material_asset_id	Uma referência de ativo única, singular	Passado para create-video para um slot de referência
material_asset_ids	Uma matriz de referências de ativos	Passado para create-video quando múltiplas referências reutilizáveis são necessárias

As definições completas dos campos e os parâmetros necessários estão documentados nas referências da API create material asset e create material asset group. Leia-as antes de implementar isso no código de produção. A documentação cobre o formato do fluxo de trabalho, não todos os parâmetros de solicitação.

Fluxos de Trabalho de Avatar Virtual e Pessoa Real

Os materiais Seedance suportam dois tipos de biblioteca. A distinção não é cosmética — ela reflete duas posturas diferentes de segurança e consentimento.

aigc_avatar: Avatares Virtuais e Referências que não são de Pessoas Reais

O tipo aigc_avatar cobre referências reutilizáveis que não estão vinculadas a uma pessoa real verificada: personagens ilustrados, avatares sintéticos, figuras estilizadas, mascotes de marca e ativos similares. Você pode criá-los diretamente através do fluxo de criação de ativo de material sem uma etapa de verificação.

Se o seu produto gera vídeos em torno de personagens fictícios ou avatares de marca, este é quase certamente o tipo de biblioteca que você deseja. Ele possui um caminho de criação mais simples porque não há requisito de verificação de identidade associado a ele.

liveness_face: Grupos de Material de Pessoas Reais

O tipo liveness_face é para grupos de material construídos em torno da imagem de uma pessoa real. Este é o tipo de referência usado para geração de vídeo com consistência facial apresentando um indivíduo real. Como isso envolve identidade e consentimento, o TokenLab exige um fluxo de verificação antes que os ativos possam ser carregados no grupo.

A sequência de verificação tem várias etapas distintas:

1. Criação de sessão — seu backend solicita uma sessão de verificação para o grupo.
2. Fluxo H5 — a pessoa sendo verificada completa uma verificação de vivacidade através de um fluxo web hospedado. H5 refere-se a uma interface de verificação web móvel.
3. Callback — o TokenLab notifica seu sistema quando a sessão de verificação termina.
4. Vincular resultado — a identidade verificada é vinculada ao grupo de material.
5. Uploads delimitados ao grupo — somente após a vinculação ser bem-sucedida, os ativos de material podem ser carregados nesse grupo específico.

Isso significa que os materiais de pessoas reais são inerentemente focados no grupo. Você não pode pular diretamente para a criação de um ativo da maneira que pode com aigc_avatar. O grupo precisa existir e passar pela verificação antes que qualquer upload de ativo nele seja válido.

Checklist: Escolhendo o Tipo de Biblioteca Correto

• A referência é o rosto ou a imagem de uma pessoa real e identificável? → Use liveness_face e planeje o fluxo de verificação.
• A referência é sintética, ilustrada ou um avatar que não é de uma pessoa real? → Use aigc_avatar e pule a verificação.
• Seu produto precisa de identidade consistente em múltiplas gerações para a mesma pessoa real? → Construa o grupo uma vez, verifique uma vez, reutilize o grupo para futuros ativos.
• Você não tem certeza em qual tipo uma determinada referência fornecida pelo cliente se enquadra? → Trate-a como liveness_face até que se confirme o contrário; verifique na documentação, não presuma.

Não presuma que todo modelo de geração ou todo tipo de solicitação suporte ambos os tipos de biblioteca de forma idêntica. Confirme o suporte atual no guia de Modelos de Vídeo Seedance antes de se comprometer com uma arquitetura.

Como Funciona a Preparação Automática de Material

Nem toda referência precisa de uma etapa de upload manual. O TokenLab pode preparar automaticamente entradas de imagem compatíveis em ativos de material como parte de uma solicitação de geração. Isso remove uma viagem de ida e volta para casos simples.

Os campos que ele reconhece para preparação automática são:

• image
• image_url
• image_urls
• reference_images
• start_image
• end_image

Se você passar qualquer um desses diretamente em uma chamada de geração, o TokenLab lida com a importação e preparação nos bastidores. Você não precisa chamar o endpoint de ativo de material separadamente antes.

O que acontece quando a preparação leva mais de 60 segundos

A preparação geralmente é rápida. Imagens de referência maiores ou mais complexas podem levar mais tempo para serem processadas em um ativo pronto para geração. Se a preparação exceder 60 segundos, a API responde com:

409 seedance_material_preparing

juntamente com um campo auto_material_asset_ids contendo os IDs dos ativos que ainda estão sendo preparados.

Isso não é um erro no sentido convencional. É um sinal para tentar novamente. Sua integração deve tratar 409 seedance_material_preparing como uma resposta de "verifique novamente em breve", não como uma falha a ser exibida ao usuário final. Consulte os IDs de ativos retornados, aguarde o status ACTIVE e, em seguida, prossiga com a geração usando esses IDs.

Em nosso pipeline, tratamos esse status como um backoff de limite de taxa: esperado, transitório e tratado no código em vez de reportado como um erro voltado ao usuário. Recomendamos um pequeno loop de repetição, não apenas um único try/catch.

Usando a Biblioteca de Materiais Seedance na Geração

Uma vez que um ativo de material — seja carregado manualmente ou preparado automaticamente — atinge o status ACTIVE, seu id torna-se utilizável como material_asset_id ou como uma entrada em material_asset_ids em uma chamada create video.

O fluxo de trabalho principal é assim:

1. Decida se a referência é de uma pessoa real ou não. Escolha liveness_face (com verificação) ou aigc_avatar de acordo.
2. Se for pessoa real: crie o grupo de material, execute a sessão de verificação e o fluxo H5, receba o callback e vincule o resultado.
3. Crie ou importe o ativo de material — seja através de uma chamada de upload direto ou permitindo que a preparação automática lide com um campo de imagem compatível dentro de uma solicitação de geração.
4. Verifique o status. Não passe o ID do ativo para a geração até que ele reporte ACTIVE.
5. Se você receber 409 seedance_material_preparing, consulte os auto_material_asset_ids retornados e tente novamente assim que eles resolverem para ACTIVE.
6. Use o id como material_asset_id ou dentro de material_asset_ids em sua chamada create-video, visando um modelo Seedance atual dependendo de suas necessidades de latência e qualidade.
7. Reutilize o mesmo ID de ativo em futuras chamadas de geração em vez de fazer o upload da referência novamente.

É aqui também que o gerenciamento de tarefas é importante. Uma chamada de geração construída sobre um ativo de material reutilizado pode precisar parar no meio da execução. Isso pode acontecer por controle de custos, um briefing criativo alterado ou um prompt ruim. Veja nossa peça complementar sobre cancelamento de tarefas Seedance para saber como o cancelamento interage com trabalhos de vídeo em andamento.

Para uma comparação mais ampla do que está disponível atualmente nos modelos de geração de vídeo no TokenLab, a página da categoria de modelos de vídeo lista as opções atuais lado a lado.

Próximos Passos Práticos

• Se você está prototipando, comece com materiais aigc_avatar. O caminho de criação é mais simples e não há dependência de verificação para construir em torno primeiro.
• Se o seu produto requer consistência de pessoa real, construa o fluxo de verificação (sessão → H5 → callback → vincular) como uma parte de primeira classe do seu onboarding, não como um complemento.
• Adicione um loop de repetição para 409 seedance_material_preparing antes de enviar qualquer coisa para produção. Trate-o como comportamento esperado, não como um caso extremo.
• Armazene os IDs de ativos de material junto com seus próprios registros de referência internos. Dessa forma, você não precisa derivar novamente qual ativo mapeia para qual personagem ou produto.
• Revise as referências da API material asset e material asset group diretamente. A documentação descreve o formato do fluxo de trabalho, e os campos exatos de solicitação/resposta devem ser confirmados em relação à documentação atual antes de você escrever o código de integração.

O painel de ativos Seedance mostra o status, o tipo de biblioteca e os relacionamentos de grupo para ativos que você já criou.

As taxas atuais em nossa visão geral de preços da API de vídeo AI 2026 ajudam você a entender como os custos escalam com o uso. Você também pode rastrear e exportar seus próprios dados de uso usando as orientações em exportações de uso do painel do TokenLab.

FAQ

Como os ativos de material e os grupos de material diferem?

Um ativo de material é um objeto de referência reutilizável único — uma imagem de avatar, um rosto verificado por vivacidade, um clipe de vídeo de referência. Seu id torna-se material_asset_id uma vez ACTIVE. Um grupo de material é um contêiner identificado por group_id. Os grupos organizam ativos relacionados e são necessários para fluxos de trabalho liveness_face. Em resumo: group_id organiza; material_asset_id gera.

Por que uma chamada de geração retorna 409 seedance_material_preparing?

A preparação automática de material, acionada por campos de imagem compatíveis como image_url ou start_image, pode levar mais de 60 segundos. Quando isso acontece, a API retorna 409 seedance_material_preparing com auto_material_asset_ids. Consulte esses IDs, aguarde ACTIVE e tente a geração novamente. Isso sinaliza um estado transitório em andamento, não uma falha.

Referências de pessoas reais sempre precisam de verificação?

Sim. Use o tipo liveness_face e seu fluxo de verificação sempre que a referência envolver o rosto ou a imagem de uma pessoa real identificável. O fluxo requer a criação de sessão, uma verificação de vivacidade H5, um callback e uma etapa de vinculação antes que quaisquer ativos possam ser carregados nesse grupo. Referências que não são de pessoas reais, como avatares ilustrados ou sintéticos, usam aigc_avatar e não exigem esse caminho.

Posso reutilizar um ativo de material em vários trabalhos de vídeo Seedance?

Sim, uma vez que o ativo atinja ACTIVE. Use seu id como material_asset_id ou dentro de material_asset_ids em uma chamada create-video. Reutilize o mesmo ID de ativo em futuras chamadas de geração em vez de fazer o upload da referência novamente. Se você precisar parar um trabalho em andamento, veja cancelamento de tarefas Seedance.

Fontes e Atualidade

• Guia de Modelos de Vídeo Seedance — https://docs.tokenlab.sh/guides/seedance-2-video — observado em 09/07/2026
• Criar ativo de material Seedance (referência da API) — https://docs.tokenlab.sh/api-reference/video/create-material-asset — observado em 09/07/2026
• Criar grupo de ativos de material Seedance (referência da API) — https://docs.tokenlab.sh/api-reference/video/create-material-asset-group — observado em 09/07/2026
• Criar vídeo (referência da API) — https://docs.tokenlab.sh/api-reference/video/create-video — observado em 09/07/2026
• Painel de ativos Seedance do TokenLab — /dashboard/seedance-assets — observado em 09/07/2026

O comportamento da API, os nomes dos campos e a semântica de status descritos aqui refletem a documentação pública e a cópia do painel na data observada. O sistema de material Seedance do TokenLab está em desenvolvimento ativo — confirme os nomes dos parâmetros atuais, valores de status e suporte específico do modelo na documentação vinculada antes de finalizar o código de integração de produção.

Se você está construindo um pipeline de vídeo que depende de referências estáveis e reutilizáveis, comece pelo guia de Modelos de Vídeo Seedance. É a maneira mais rápida de ver os nomes dos parâmetros atuais e confirmar o que seu nível de modelo alvo realmente suporta.