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 reutilizar | O que fazer |
|---|---|
| Uma imagem usada uma vez | Envie 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 estilo | Crie um grupo aigc_avatar, crie um ativo, aguarde o status ACTIVE, então use o ID do ativo |
| Reutilizar uma pessoa real | Conclua 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 existente | Mantenha o formato da requisição Action e use a referência de material compatível com Volc |
Grupos e materiais
| Item | Campo REST | Campo Action | O que significa |
|---|---|---|---|
| Grupo de material | group_id | GroupId | Mantém materiais relacionados juntos |
| Material | id | Id | Um arquivo de imagem, vídeo ou áudio importado; use este ID após ele se tornar ativo |
| Grupo de avatar virtual | library_type: "aigc_avatar" | GroupType: "AIGC" | Não requer verificação de pessoa real |
| Grupo de pessoa real | library_type: "liveness_face" | GroupType: "LivenessFace" | Criado apenas por um fluxo de validação visual bem-sucedido |
| Nome do projeto | project_name | ProjectName | Manté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:
- Listar Grupos de Ativos de Material
- Obter Grupo de Ativos de Material
- Atualizar Grupo de Ativos de Material
- Excluir Grupo de Ativos de Material
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.
- Chame Criar Sessão de Validação Visual com
CallbackURL; salve oResult.BytedTokene abra oResult.H5Linkpara a pessoa que está sendo verificada. - Após o fluxo H5 redirecionar para o callback, consulte Obter Resultado de Validação Visual com o mesmo
BytedTokeneProjectName. - Armazene o
Result.GroupIdretornado. O TokenLab cria e vincula o grupoLivenessFacedurante esta etapa. - 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.
| Tipo | Entrada suportada |
|---|---|
| Imagem | jpeg, png, webp, bmp, tiff, gif, heic, heif; ≤ 30 MiB; largura e altura [300, 6000] px; proporção [0.4, 2.5] |
| Vídeo | mp4, mov; ≤ 200 MiB |
| Áudio | aac, 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_idpara uma referência de material genéricamaterial_asset_idspara múltiplas referências genéricasasset://<asset-id>emimage_url,start_image,end_imageoureference_imagesquando 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).