Como usar um rosto real no Seedance 2.5 com os assets de pessoas reais do AIHubMix

O vídeo com IA se torna muito mais útil quando a pessoa na tela continua reconhecível de uma cena para outra. Os assets de pessoas reais do AIHubMix oferecem uma forma baseada em consentimento de usar um rosto aprovado na geração de vídeos com Seedance, mantendo a autorização, o processamento do asset e a geração como etapas separadas e verificáveis.

Este guia explica o que é um vídeo com pessoa real, como funciona o fluxo de trabalho do AIHubMix, por que ele é útil e como criar um vídeo no Seedance 2.5 a partir de um rosto real. Também explica a diferença entre a API nativa do Seedance 2.5 e as integrações compatíveis com o Seedance 2.0.

O que é um vídeo com pessoa real?

Um vídeo com pessoa real é um vídeo gerado por IA que usa uma pessoa autorizada como referência de identidade. O modelo pode alterar o cenário, a roupa, a ação, o movimento de câmera, a voz ou o idioma, preservando a aparência reconhecível da pessoa.

Isso é diferente da geração comum de texto para vídeo. Um prompt de texto descreve o que deve acontecer, mas não identifica de forma confiável uma pessoa real específica. Um asset de pessoa real fornece ao modelo uma referência visual aprovada que pode ser reutilizada em vários vídeos.

Aplicações típicas incluem avatares de criadores, apresentadores virtuais, explicações de produtos, campanhas localizadas, vídeos de treinamento, personagens de marca e conteúdo curto para redes sociais.

Como funciona o fluxo de trabalho do AIHubMix

O fluxo de trabalho tem cinco etapas principais:

Crie um grupo de assets para uma pessoa.
Peça que a pessoa da imagem conclua o fluxo de autorização.
Adicione um retrato e aguarde até que o asset esteja ativo.
Referencie o asset ativo com um URI asset://.
Envie uma tarefa de vídeo do Seedance e consulte seu status até a conclusão.

A separação é intencional. A autorização acontece antes da geração, a prontidão do asset pode ser verificada de forma independente e cada etapa importante expõe um status que sua aplicação pode monitorar.

Por que usar o AIHubMix?

Uma única API para todo o fluxo de trabalho

O AIHubMix oferece endpoints para grupos de assets, sessões de verificação, assets humanos e geração de vídeo assíncrona. A mesma conta e a mesma chave de API podem gerenciar todo o pipeline.

Autorização explícita

A pessoa no retrato conclui a página de autorização. Isso cria uma etapa de consentimento clara antes que a imagem seja usada como referência reutilizável de pessoa real.

Assets de identidade reutilizáveis

Depois que uma imagem se torna ativa, as aplicações podem reutilizar seu ID de asset em várias requisições de vídeo, em vez de enviar a imagem original toda vez.

Geração pronta para o Seedance

O endpoint nativo do Seedance 2.5 aceita referências de texto, imagem, vídeo e áudio, além de controles de duração, resolução, proporção de tela e geração de áudio.

Estados observáveis e adequados à produção

Sua aplicação pode aguardar verified, active e completed, em vez de presumir se uma operação foi concluída. Isso facilita a implementação de novas tentativas e do tratamento de erros.

Tutorial passo a passo

Passo 1: Prepare uma chave de API e um retrato

Crie uma chave de API no Console do AIHubMix. Mantenha-a privada. No Terminal, defina-a como variável de ambiente:

export AIHUBMIX_API_KEY="your_api_key"

Prepare uma URL HTTPS direta para a imagem. A URL deve retornar o arquivo de imagem sem login ou cabeçalhos personalizados e deve permanecer disponível enquanto o AIHubMix a processa.

Requisitos recomendados para a imagem:

JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC ou HEIF
Menos de 30 MB
Largura e altura maiores que 300 pixels e menores que 6000 pixels
Proporção maior que 0,4 e menor que 2,5
Um retrato nítido da mesma pessoa que concluirá a autorização

Passo 2: Crie um grupo de assets de pessoa real

Execute este comando no Terminal:

curl -sS -X POST "https://aihubmix.com/ai/v1/asset-groups" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My real-human asset"}'

Salve o id retornado, que tem o formato ag_...:

GROUP_ID="ag_your_group_id"

Um novo grupo normalmente começa com pending_auth.

Passo 3: Crie uma sessão de autorização

Use o ID do grupo para solicitar uma sessão de verificação:

curl -sS -X POST \
  "https://aihubmix.com/ai/v1/asset-groups/$GROUP_ID/verification-sessions" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

A resposta contém um verification_url temporário. Abra essa URL em um navegador e peça que a pessoa do retrato revise a finalidade e conclua o fluxo de autorização.

A URL é sensível e temporária. Não a publique, não a inclua em um repositório nem em capturas de tela.

Passo 4: Verifique a autorização e o status do grupo

Depois que a pessoa concluir o fluxo no navegador, consulte os dois recursos:

curl -sS "https://aihubmix.com/ai/v1/verification-sessions/$SESSION_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

curl -sS "https://aihubmix.com/ai/v1/asset-groups/$GROUP_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Continue somente quando a sessão de verificação estiver verified e o grupo de assets estiver active. Uma página de erro no navegador não determina o resultado final; use o status da API.

Passo 5: Adicione o retrato

Envie a URL direta da imagem:

curl -sS -X POST \
  "https://aihubmix.com/ai/v1/asset-groups/$GROUP_ID/assets" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: portrait-001" \
  -d '{
    "url":"https://cdn.example.com/portrait.jpg",
    "asset_type":"image",
    "client_reference_id":"portrait-001"
  }'

Salve o ID do asset retornado e consulte seu status:

ASSET_ID="ast_your_asset_id"
curl -sS "https://aihubmix.com/ai/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Use o asset somente quando seu status estiver active. creating e processing indicam que ele ainda não está pronto.

Passo 6: Gere um vídeo com Seedance 2.5

O asset de pessoa real deve ficar em input_references[].url. Ele não deve ser colado no texto do prompt:

curl -sS -X POST "https://aihubmix.com/ai/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\":\"doubao-seedance-2-5-260628\",
    \"prompt\":\"A realistic vertical vlog. The person smiles, waves, and says in Japanese: やっほー！今日も笑顔でね！ Keep the face consistent, synchronize lip movement, use natural hand motion, and add no subtitles.\",
    \"duration\":5,
    \"resolution\":\"720p\",
    \"aspect_ratio\":\"3:4\",
    \"generate_audio\":true,
    \"input_references\":[{\"type\":\"image_url\",\"url\":\"asset://$ASSET_ID\"}]
  }"

A resposta retorna um ID de tarefa de vídeo. Consulte GET /ai/v1/videos/{id} até que a tarefa esteja completed e, em seguida, baixe o resultado rapidamente, pois as URLs dos vídeos são temporárias.

Seedance 2.5 e Seedance 2.0

O Seedance 2.5 usa o endpoint nativo /ai/v1/videos descrito acima. Integrações mais antigas podem usar o Seedance 2.0 com o protocolo compatível /v1/videos e uma estrutura de conteúdo diferente.

Não misture os dois formatos de requisição. Antes do uso em produção, verifique o schema atual do modelo para confirmar durações, resoluções, tipos de referência, comportamento de áudio e caminhos de endpoint suportados.

Boas práticas de prompt

Descreva o ambiente, a ação, o timing, o movimento de câmera, a voz e as restrições. Um prompt forte pode especificar um kimono, pétalas de cerejeira caindo, um aceno suave, diálogo em japonês, movimento labial sincronizado, movimento natural do cabelo e nenhuma legenda.

Cinco segundos funcionam bem para uma saudação curta. Se o vídeo incluir várias ações ou uma frase longa, use uma duração maior ou encurte o roteiro para que a performance não pareça apressada.

Use uma única referência de identidade para um teste simples. Adicione referências extras somente quando o schema do modelo oferecer suporte e cada asset pertencer ao mesmo grupo de assets.

Problemas comuns

O grupo não está ativo: aguarde até que a sessão de verificação fique verified e o grupo fique active.
O asset está em processamento: consulte o ID original do asset; não crie duplicatas com um novo ID.
A URL da imagem falha: use uma URL HTTPS pública de arquivo, não um caminho local, uma página de login ou uma página de compartilhamento.
O vídeo rejeita o asset: confirme que o asset está active, pertence à mesma conta e usa o tipo de mídia correto.
O Playground não mostra asset://: o upload de imagem no Playground e o registro de assets de pessoa real são fluxos de trabalho separados. Use o campo de referência da API para os assets registrados.

Checklist final

Chave de API configurada com segurança.
Grupo de assets criado.
Autorização da pessoa concluída.
Status do grupo: active.
Status do asset do retrato: active.
A requisição de vídeo usa asset://<asset_id>.
A tarefa de vídeo é consultada até ficar completed.

Os assets de pessoas reais do AIHubMix oferecem aos desenvolvedores uma forma prática de criar experiências de vídeo baseadas em consentimento e com identidade consistente, usando o Seedance. Comece com um retrato aprovado e um vídeo de teste curto e, em seguida, expanda o mesmo fluxo de trabalho para ferramentas de criadores, conteúdo de marca e aplicações de produção.