Guias de mídia

Materiais Seedance e Verificação de Pessoa Real

Reutilize imagens, vídeos, áudios ou uma pessoa verificada no Seedance

Os materiais Seedance permitem que você reutilize um arquivo de imagem, vídeo ou áudio sem precisar importá-lo a cada geração. Referências a uma pessoa real exigem consentimento e verificação visual; pessoas virtuais, produtos e estilos não exigem.

Escolha um tipo de material

O que você deseja reutilizarO que fazer
Uma imagem usada uma vezEnvie sua URL em um campo de imagem compatível; isso não cria um ID de material reutilizável
Reutilizar uma pessoa virtual, produto ou estiloCrie um grupo aigc_avatar, crie um ativo, aguarde o status ACTIVE, então use o ID do ativo
Reutilizar uma pessoa realConclua a validação visual, receba seu GroupId, crie um ativo nesse grupo, aguarde o status ACTIVE, então use o ID do ativo
Migrar um cliente de material Volcengine existenteMantenha o formato da requisição Action e use a referência de material compatível com Volc

Grupos e materiais

ItemCampo RESTCampo ActionO que significa
Grupo de materialgroup_idGroupIdMantém materiais relacionados juntos
MaterialidIdUm arquivo de imagem, vídeo ou áudio importado; use este ID após ele se tornar ativo
Grupo de avatar virtuallibrary_type: "aigc_avatar"GroupType: "AIGC"Não requer verificação de pessoa real
Grupo de pessoa reallibrary_type: "liveness_face"GroupType: "LivenessFace"Criado apenas por um fluxo de validação visual bem-sucedido
Nome do projetoproject_nameProjectNameMantém materiais de diferentes projetos separados; o padrão é default

Mantenha os IDs de grupo e IDs de ativo separados. Um grupo organiza uploads; um ID de ativo é a referência usada pela geração de vídeo. IDs públicos têm o formato group-20260720123456-vrt01 e asset-20260720123457-def45.

Retenção de Material

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

  • Se um ativo precisar ser preparado novamente ao ser usado, a primeira geração pode levar um pouco mais de tempo. Se ele ainda não estiver pronto, a requisição retornará 409 seedance_material_preparing; tente novamente em breve.
  • A exclusão de um ativo ou grupo é permanente e não pode ser desfeita.

URLs de imagem e materiais reutilizáveis

Envie URLs HTTP(S) públicas ou URLs de dados suportadas nos campos de imagem aceitos pelo modelo selecionado. Essas entradas seguem o caminho de mídia normal e não criam automaticamente IDs de material reutilizáveis.

Para materiais reutilizáveis, crie um ativo através da API de material, aguarde o status ACTIVE, então use material_asset_id, material_asset_ids ou asset://<id> em um campo de mídia compatível. Mantenha a função pretendida de primeiro quadro, último quadro ou imagem de referência.

Quando um material explícito ainda está sendo preparado, o POST /v1/videos/generations retorna 409 seedance_material_preparing com inactive_asset_ids. Consulte esses ativos até que fiquem ACTIVE, então tente novamente com os mesmos IDs de material. Se um ativo estiver FAILED, inspecione a error_message e corrija ou reimporte-o antes de tentar novamente. Uma requisição de geração que usa um ativo com falha retorna 422 seedance_material_failed com failed_asset_ids.

Materiais de Avatar Virtual

Use Criar Grupo de Ativos de Material para criar um grupo aigc_avatar. Para a criação de ativos via REST, o group_id é opcional apenas quando o project_name é default; o TokenLab então usa ou cria o grupo de avatar virtual padrão da organização. Um project_name diferente do padrão, e todo ativo de pessoa real, requer um group_id.

Após a existência de um grupo, gerencie-o com:

Excluir um grupo também exclui os materiais do TokenLab contidos nele e não pode ser desfeito.

Verificação de Pessoa Real

Use este fluxo quando seu produto precisar coletar consentimento e verificar um rosto antes de reutilizar uma pessoa real como referência Seedance.

  1. Chame Criar Sessão de Validação Visual com CallbackURL; salve o Result.BytedToken e abra o Result.H5Link para a pessoa que está sendo verificada.
  2. Após o fluxo H5 redirecionar para o callback, consulte Obter Resultado de Validação Visual com o mesmo BytedToken e ProjectName.
  3. Armazene o Result.GroupId retornado. O TokenLab cria e vincula o grupo LivenessFace durante esta etapa.
  4. Crie um ativo com esse ID de grupo, então consulte o ativo até que ele se torne ACTIVE.

O BytedToken é válido por 30 minutos. Um cliente não pode criar um grupo LivenessFace com CreateAssetGroup; isso evita que um grupo não verificado seja apresentado como verificado.

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

Para um grupo de pessoa real, os uploads são verificados em relação ao rosto validado. Um ativo pode falhar se contiver vários rostos ou se o rosto não corresponder. Para obter melhores resultados, faça o upload de uma referência de corpo inteiro de frente e um close-up frontal claro.

Criar e Preparar um Ativo

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

TipoEntrada suportada
Imagemjpeg, png, webp, bmp, tiff, gif, heic, heif; ≤ 30 MiB; largura e altura [300, 6000] px; proporção [0.4, 2.5]
Vídeomp4, mov; ≤ 200 MiB
Áudioaac, wav, mp3; ≤ 15 MiB

Estes são os limites de importação de arquivos. Uma requisição de importação bem-sucedida não garante que a validação de mídia ou de pessoa real será aprovada. Aguarde o status ACTIVE; se o ativo ficar FAILED, use a error_message para corrigir a fonte antes de importar novamente.

A ingestão de material é assíncrona. Consulte Obter Ativo de Material até que o status se torne ACTIVE. O sucesso HTTP significa que a importação foi aceita, não que o ativo está pronto. Se o ativo ficar FAILED, inspecione a error_message, corrija a fonte e crie um novo ativo.

A URL de origem é usada apenas para importação. O TokenLab retorna seu próprio ID de ativo e mantém o ativo na biblioteca de materiais da sua organização até que você exclua o ativo ou seu grupo.

Usar um Ativo na Geração de Vídeo

Após um ativo estar ACTIVE, escolha uma destas formas ao chamar Criar Vídeo:

  • material_asset_id para uma referência de material genérica
  • material_asset_ids para múltiplas referências genéricas
  • asset://<asset-id> em image_url, start_image, end_image ou reference_images quando a função da mídia precisar ser explícita

As referências de material contam para os limites de referência Seedance do modelo selecionado. Se a API retornar Seedance material asset not found or not accessible, confirme se o valor é um ID de ativo em vez de um ID de grupo, se pertence à mesma organização e projeto, se não foi excluído e se está ACTIVE.

REST ou Action do Volcengine

As integrações nativas do TokenLab podem continuar usando os endpoints REST snake_case /v1/videos/assets*. Clientes Volcengine existentes podem manter os corpos PascalCase com Ações de Material (Compatível com Volc). Ambas as interfaces operam nos mesmos dados de material com escopo de organização e projeto.

Exemplo REST: Ativo de Avatar Virtual

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","project_name":"default"}'

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

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

Exemplo de Action: Ativo de Pessoa Real Verificada

Primeiro, crie e conclua a validação visual:

curl 'https://api.tokenlab.sh/?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/?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"<BYTED_TOKEN>","ProjectName":"default"}'

Em seguida, passe o GroupId retornado para CreateAsset:

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 com GetAsset até que seu status seja Active, então passe o ID do ativo retornado para a geração de vídeo. Para todas as 10 operações de Action, filtros, paginação, formatos de resposta e erros, consulte Ações de Material (Compatível com Volc).

Nesta página