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

Referências de vídeo reutilizáveis são mais fáceis de gerenciar quando são ativos com status de ciclo de vida, e não URLs descartáveis copiadas em cada solicitação de geração. Se você já manteve uma planilha de links de imagens, reenviou o mesmo vídeo de referência cinco vezes ou redigitou uma URL de troca de rosto (face-swap) em três chamadas de API diferentes, você já entende o problema que os materiais Seedance foram criados para resolver.

A biblioteca de materiais Seedance da TokenLab oferece às equipes de vídeo uma forma, com escopo de organização, de armazenar, verificar e reutilizar referências em chamadas de geração. Este artigo explica o que é um ativo de material, como os grupos de materiais se relacionam com ativos individuais, como funciona a preparação automática e onde a verificação de pessoa real se encaixa no fluxo de trabalho.

Principais pontos

• Um ativo de material é o objeto de referência pronto para geração; um grupo de materiais é o contêiner que organiza ativos relacionados, especialmente para fluxos de trabalho de pessoas reais.
• Use o id de um ativo de material como material_asset_id (ou dentro de material_asset_ids) apenas após 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 materiais de pessoas reais que exigem verificação.
• A 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 ultrapassar 60 segundos, a API retorna 409 seedance_material_preparing juntamente com auto_material_asset_ids que você pode consultar e tentar novamente.
• Seedance 2.0, Seedance 2.0 Fast e Seedance 2.0 Mini são os modelos públicos atuais que este sistema de materiais suporta. Verifique os detalhes exatos de capacidade por modelo na documentação antes de criar uma dependência em um nível específico.

O que é um material Seedance

Um material Seedance é uma referência reutilizável — imagem, vídeo ou áudio — que a TokenLab armazena como um ativo com escopo de organização, em vez de uma URL com escopo de 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 pela TokenLab não possui essa fragilidade.

Terceiro, e mais relevante para equipes que criam pipelines de vídeo consistentes em termos de personagens ou marca, os materiais fornecem 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 materiais

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

Um ativo de material é um único objeto de referência — uma imagem de avatar, um rosto com verificação de 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 e 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, e 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ê o usa
group_id	Um grupo de ativos de material (contêiner)	Criar ou referenciar um grupo, especialmente para fluxos de verificação de pessoa real
id (em um ativo de material)	Uma única referência reutilizável	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 — este artigo 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, e 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 abrange 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 semelhantes. Eles podem ser criados diretamente através do fluxo de criação de ativos 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 tem um caminho de criação mais simples porque não há requisito de verificação de identidade anexado a ele.

liveness_face: Grupos de materiais de pessoas reais

O tipo liveness_face é para grupos de materiais construídos em torno da imagem de uma pessoa real — o tipo de referência usada para geração de vídeo com rosto consistente apresentando um indivíduo real. Como isso envolve identidade e consentimento, a 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 conclui uma verificação de vivacidade através de um fluxo web hospedado (é a isso que "H5" se refere: uma interface de verificação web móvel).
3. Callback — a TokenLab notifica seu sistema quando a sessão de verificação termina.
4. Vincular resultado — a identidade verificada é vinculada ao grupo de materiais.
5. Uploads com escopo de 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 direto 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? → Crie 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 2.0 antes de se comprometer com uma arquitetura.

Como funciona a preparação automática de materiais

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

Os campos que ela 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, a TokenLab lida com a importação e preparação nos bastidores, em vez de exigir que você chame o endpoint de ativo de material separadamente primeiro.

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

A preparação geralmente é rápida, mas 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.

Na prática, isso significa que seu pipeline de geração precisa de um pequeno loop de repetição, não apenas um único try/catch. As equipes que constroem pipelines de vídeo automatizados devem tratar esse status da mesma forma que tratariam o backoff de limite de taxa (rate-limit) — esperado, transitório e tratado no código em vez de reportado como um erro voltado ao usuário.

Como usar materiais 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 materiais, 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 relate 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, como seedance-2.0, seedance-2.0-fast ou seedance-2.0-mini, 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 reenviar a referência.

É aqui também que o gerenciamento de tarefas é importante. Se uma chamada de geração construída sobre um ativo de material reutilizado precisar ser interrompida no meio da execução — por controle de custos, um briefing criativo alterado ou um prompt ruim — veja nosso artigo 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 na TokenLab, a página de categoria de modelos de vídeo lista as opções atuais lado a lado.

Próximos passos práticos

• Se você estiver fazendo prototipagem, comece com materiais aigc_avatar — o caminho de criação é mais simples e não há dependência de verificação para construir 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 um comportamento esperado, não como um caso extremo.
• Armazene os IDs dos ativos de material junto com seus próprios registros de referência internos para que você não precise redescobrir qual ativo mapeia para qual personagem ou produto.
• Revise as referências da API material asset e material asset group diretamente — este artigo 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.

Você pode navegar pela biblioteca de materiais diretamente no painel de ativos Seedance para ver o status, o tipo de biblioteca e os relacionamentos de grupo dos ativos que você já criou.

Antes de se comprometer com um fluxo de trabalho de produção, vale a pena revisar as taxas atuais em nossa visão geral de preços da API de vídeo AI 2026 para 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 TokenLab.

FAQ

O que é um ativo de material Seedance? Um ativo de material é uma referência de geração de vídeo reutilizável — imagem, vídeo ou áudio — armazenada como um objeto com escopo de organização com seu próprio status de ciclo de vida. Uma vez que ele atinge ACTIVE, você pode referenciá-lo por ID em múltiplas chamadas de geração em vez de fornecer novamente uma URL bruta a cada vez.

Qual é a diferença entre group_id e material_asset_id? group_id identifica um grupo de ativos de material, que é um contêiner usado principalmente para organizar ativos de pessoas reais (liveness_face) e gerenciar a verificação no nível do grupo. material_asset_id identifica uma única referência reutilizável — o id retornado quando um ativo de material é criado — e é o que você passa para as chamadas de geração de vídeo.

Quando devo usar a verificação de pessoa real? Use o tipo liveness_face e seu fluxo de verificação sempre que o material de referência envolver o rosto ou a imagem de uma pessoa real identificável. O fluxo requer a criação de uma 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 de verificação.

O que significa seedance_material_preparing? É uma resposta 409 retornada quando a preparação automática de material — acionada por campos de imagem compatíveis como image_url ou start_image em uma solicitação de geração — leva mais de 60 segundos para ser concluída. A resposta inclui auto_material_asset_ids para que você possa consultar esses IDs e tentar a geração novamente assim que eles se tornarem ACTIVE. Isso sinaliza um estado transitório em andamento, não uma falha.

Fontes e Atualidade

• Guia de modelos de vídeo Seedance 2.0 — 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 da TokenLab — https://tokenlab.sh/en/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 materiais Seedance da 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 2.0 — é a maneira mais rápida de ver os nomes dos parâmetros atuais e confirmar o que seu nível de modelo de destino realmente suporta.