Materiais Seedance e verificação de pessoas

Materiais Seedance são referências de imagem, vídeo ou áudio reutilizáveis dentro de uma organização. Escolha primeiro o fluxo: materiais comuns de avatar e materiais de pessoas verificadas têm caminhos de criação diferentes.

Escolha o fluxo de materiaisCopy Anchor Link

Conceitos de MateriaisCopy Anchor Link

Os materiais Seedance são referências reutilizáveis com escopo de organização que podem ser selecionadas posteriormente durante a geração de vídeo.

Mantenha group_id e o id do ativo de material separados. O group_id serve para organizar uploads; o id do ativo de material serve para a geração de vídeo. Se uma solicitação de vídeo retornar Seedance material asset not found or not accessible, confirme se você passou um id de ativo de material, não um group_id, e que o ativo pertence à mesma organização, não foi excluído e possui status: "ACTIVE".

Retenção de materiaisCopy Anchor Link

A TokenLab mantém cada ativo de material até que você exclua o ativo ou seu grupo. Ele não é removido por inatividade do lado da TokenLab.

O provedor upstream Seedance pode remover a própria cópia de trabalho de um ativo após 30 dias sem uso. Isso não exclui seu ativo nem altera seu ID: na próxima vez que você o usar em uma solicitação de geração, a TokenLab prepara automaticamente uma nova cópia upstream a partir do original armazenado.

• A primeira geração após uma limpeza pode demorar um pouco mais enquanto a nova cópia é preparada. Se ela ainda não estiver pronta, a solicitação retorna seedance_material_preparing; tente novamente em instantes.
• Excluir um ativo ou grupo é permanente e não pode ser desfeito.

URLs de imagens e materiais reutilizáveisCopy Anchor Link

Envie URLs HTTP(S) públicas ou data URLs compatíveis nos campos de imagem do modelo escolhido. Elas seguem o processamento normal de mídia e não criam automaticamente IDs de materiais reutilizáveis.

Para reutilizar um material, crie-o pela API de materiais, aguarde ACTIVE e use material_asset_id, material_asset_ids ou asset://<id> em um campo de mídia compatível. Preserve o papel de primeiro quadro, último quadro ou imagem de referência.

Se um material indicado explicitamente ainda estiver sendo preparado, POST /v1/videos/generations retorna 409 seedance_material_preparing com inactive_asset_ids. Consulte esses materiais até ACTIVE e tente novamente com os mesmos IDs. Em caso de FAILED, veja error_message e corrija ou importe novamente antes de repetir.

Verificação de Material de Pessoa RealCopy Anchor Link

Use a verificação de material de pessoa real quando seu produto precisar de consentimento e verificação facial antes que uma pessoa real possa ser usada como uma referência Seedance reutilizável.

1. Chame Criar sessão de validação visual com CallbackURL e salve o Result.BytedToken retornado.
2. Abra Result.H5Link para a pessoa que será verificada. Acrescente lng ao link H5 se precisar de um idioma específico.
3. Quando o fluxo H5 terminar, o navegador abrirá Result.CallbackURL com nomes de consulta oficiais, como bytedToken e resultCode.
4. Consulte Obter resultado da validação visual com BytedToken até Result.GroupId ser retornado.
5. Salve GroupId e use-o como group_id ao criar materiais liveness_face.

BytedToken é válido por 30 minutos. Use o mesmo ProjectName nas duas requisições Action. A autenticação usa Authorization: Bearer <TOKENLAB_API_KEY>; assinaturas AK/SK da Volc não são aceitas.

Abra o H5Link retornado imediatamente após a criação. A validade do token não garante que a página de verificação possa ser aberta pela primeira vez a qualquer momento desse período.

Opcional: use o console de teste para verificar seu fluxo de solicitação e callback, inspecionar grupos de materiais e revisar o histórico de verificação. Sua integração de produção deve chamar as APIs diretamente.

Criando Grupos de MateriaisCopy Anchor Link

Use Criar Grupo de Ativos de Material para grupos aigc_avatar. Novos grupos de pessoas reais são criados através do fluxo de verificação para que a pessoa verificada e o grupo de materiais permaneçam vinculados.

Use Listar Grupos de Ativos de Material, Obter Grupo de Ativos de Material, Atualizar Grupo de Ativos de Material e Excluir Grupo de Ativos de Material para gerenciar grupos após sua criação.

A exclusão de um grupo de materiais também exclui os materiais TokenLab dentro dele e não pode ser desfeita. Se a biblioteca de materiais TokenLab não puder concluir a exclusão porque o estado de autorização atual não permite, o TokenLab retornará um erro neutro de biblioteca de materiais.

Fazendo Upload de MateriaisCopy Anchor Link

Use Criar Ativo de Material para importar uma URL de origem publicamente acessível por vez.

Para aigc_avatar, group_id é opcional; o TokenLab usa ou cria o grupo de avatar virtual padrão da organização. Para liveness_face, group_id é obrigatório e deve ser o grupo retornado por Obter resultado da validação visual.

A tabela mostra limites de importação. Uma solicitação aceita não garante aprovação da mídia ou da pessoa. Aguarde ACTIVE; em FAILED, corrija a origem conforme error_message antes de importar novamente.

A ingestão de material é assíncrona. Faça polling em Obter Material Asset até que o status se torne ACTIVE. Uma resposta HTTP bem-sucedida significa apenas que a solicitação foi aceita; sempre leia o status de negócio. Se o status for FAILED, inspecione error_message, corrija o material de origem e crie um novo ativo.

Nas solicitações de criação de material, asset_url é apenas a origem da importação. A TokenLab retorna um id do ativo de material; use esse id para gerar vídeos em vez de reutilizar a URL original.

A TokenLab mantém os ativos de material na biblioteca da sua organização até que você exclua o ativo ou seu grupo de materiais. A cópia upstream é recriada automaticamente se for removida; veja a seção de retenção acima.

Para grupos de materiais de pessoas reais, um grupo mapeia para uma pessoa real. Os uploads são verificados em relação ao rosto verificado. Ativos com vários rostos ou um rosto que não corresponda à pessoa verificada podem falhar. Para obter melhores resultados, envie uma imagem de referência de corpo inteiro de frente e um close-up frontal onde o rosto esteja claro.

Usando Materiais na Geração de VídeoCopy Anchor Link

Após um ativo estar ACTIVE, passe o id do ativo TokenLab retornado como material_asset_id, ou inclua-o em material_asset_ids, ao chamar Criar vídeo. Os ativos de material contam para os limites de referência do Seedance.

REST ou Action do VolcengineCopy Anchor Link

Uma integração nativa do TokenLab pode continuar usando a API REST snake_case /v1/videos/assets*. Um cliente Volcengine existente mantém corpos PascalCase com as Actions de materiais compatíveis com Volcengine. As duas interfaces operam sobre os mesmos dados limitados à organização e ao projeto.

Exemplos de APICopy Anchor Link

Crie um grupo de avatar virtual, faça upload de uma imagem, faça polling até que esteja ativo e, em seguida, use o ID do ativo de material em uma solicitação de vídeo.

curl https://api.tokenlab.sh/v1/videos/assets/groups \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_name":"Product references"}'

curl https://api.tokenlab.sh/v1/videos/assets \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_type":"Image"}'

curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

Para um grupo de materiais de pessoa real, crie uma sessão de validação visual e obtenha o resultado antes de enviar materiais.

curl 'https://api.tokenlab.sh/api/v3?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"CallbackURL":"https://yourapp.example.com/seedance/callback","ProjectName":"default"}'

curl 'https://api.tokenlab.sh/api/v3?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"ZXhhbXBsZS10b2tlbg","ProjectName":"default"}'

Fluxo Action completo para pessoa realCopy Anchor Link

Passe ao CreateAsset o GroupId retornado pela verificação.

curl 'https://api.tokenlab.sh/?Action=CreateAsset&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId":"group-20260720123456-real1",
    "URL":"https://example.com/person-front.png",
    "Name":"Verified front view",
    "AssetType":"Image",
    "ProjectName":"default"
  }'

Consulte GetAsset até o estado Active e use o ID retornado na geração de vídeo.