Come usare un volto reale in Seedance 2.5 con gli asset real-human di AIHubMix

I video generati con l'IA diventano molto più utili quando la persona sullo schermo resta riconoscibile da una scena all'altra. Gli asset real-human di AIHubMix offrono un modo basato sul consenso per usare un volto approvato nella generazione video con Seedance, mantenendo separate e verificabili le fasi di autorizzazione, elaborazione dell'asset e generazione.

Questa guida spiega che cos'è il video real-human, come funziona il flusso di lavoro di AIHubMix, perché è utile e come creare un video con Seedance 2.5 a partire da un volto reale. Spiega anche la differenza tra l'API nativa di Seedance 2.5 e le integrazioni compatibili con Seedance 2.0.

Che cos'è il video real-human?

Il video real-human è un video generato dall'IA che utilizza una persona autorizzata come riferimento di identità. Il modello può cambiare ambientazione, abbigliamento, azione, movimento della camera, voce o lingua, preservando l'aspetto riconoscibile della persona.

Questo è diverso dalla normale generazione da testo a video. Un prompt di testo descrive ciò che deve accadere, ma non identifica in modo affidabile una specifica persona reale. Un asset real-human fornisce al modello un riferimento visivo approvato che può essere riutilizzato in più video.

Le applicazioni tipiche includono avatar di creator, presentatori virtuali, video esplicativi di prodotti, campagne localizzate, video formativi, personaggi di brand e contenuti brevi per i social.

Come funziona il flusso di lavoro di AIHubMix

Il flusso di lavoro prevede cinque fasi principali:

Crea un gruppo di asset per una persona.
Chiedi alla persona nell'immagine di completare il flusso di autorizzazione.
Aggiungi un ritratto e attendi che l'asset diventi attivo.
Fai riferimento all'asset attivo con un URI asset://.
Invia un task di generazione video con Seedance e interrogalo fino al completamento.

La separazione è voluta. L'autorizzazione avviene prima della generazione, la disponibilità dell'asset può essere verificata in modo indipendente e ogni fase importante espone uno stato che la tua applicazione può monitorare.

Perché usare AIHubMix?

Un'unica API per l'intero flusso di lavoro

AIHubMix fornisce endpoint per gruppi di asset, sessioni di verifica, asset umani e generazione video asincrona. Lo stesso account e la stessa chiave API possono gestire l'intera pipeline.

Autorizzazione esplicita

La persona nel ritratto completa la pagina di autorizzazione. Questo crea una chiara fase di consenso prima che l'immagine venga usata come riferimento real-human riutilizzabile.

Asset di identità riutilizzabili

Una volta che un'immagine diventa attiva, le applicazioni possono riutilizzare il suo ID asset in più richieste video, invece di caricare ogni volta l'immagine originale.

Generazione pronta per Seedance

L'endpoint nativo di Seedance 2.5 supporta riferimenti di testo, immagini, video e audio, oltre a controlli per durata, risoluzione, rapporto d'aspetto e generazione audio.

Stati osservabili, adatti alla produzione

La tua applicazione può attendere gli stati verified, active e completed, invece di tirare a indovinare se un'operazione è terminata. Questo rende più semplici da implementare i tentativi di ripetizione e la gestione degli errori.

Tutorial passo passo

Passo 1: Prepara una chiave API e un ritratto

Crea una chiave API nella Console di AIHubMix. Tienila riservata. Nel Terminale, impostala come variabile d'ambiente:

export AIHUBMIX_API_KEY="your_api_key"

Prepara un URL HTTPS diretto dell'immagine. L'URL deve restituire il file immagine senza login o intestazioni personalizzate e deve restare disponibile mentre AIHubMix lo elabora.

Requisiti consigliati per l'immagine:

JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC o HEIF
Inferiore a 30 MB
Larghezza e altezza maggiori di 300 pixel e minori di 6000 pixel
Rapporto d'aspetto maggiore di 0,4 e minore di 2,5
Un ritratto chiaro della stessa persona che completa l'autorizzazione

Passo 2: Crea un gruppo di asset real-human

Esegui questo comando nel Terminale:

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"}'

Salva l'id restituito, che ha un aspetto simile a ag_...:

GROUP_ID="ag_your_group_id"

Un nuovo gruppo normalmente inizia con pending_auth.

Passo 3: Crea una sessione di autorizzazione

Usa l'ID del gruppo per richiedere una sessione di verifica:

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

La risposta contiene un verification_url temporaneo. Apri questo URL in un browser e chiedi alla persona nel ritratto di esaminare lo scopo e completare il flusso di autorizzazione.

L'URL è sensibile e temporaneo. Non pubblicarlo, non includerlo in un repository e non inserirlo negli screenshot.

Passo 4: Verifica l'autorizzazione e lo stato del gruppo

Dopo che la persona ha completato il flusso nel browser, interroga entrambe le risorse:

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"

Procedi solo quando la sessione di verifica è verified e il gruppo di asset è active. Una pagina di errore del browser non determina il risultato finale; usa lo stato dell'API.

Passo 5: Aggiungi il ritratto

Invia l'URL diretto dell'immagine:

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"
  }'

Salva l'ID asset restituito e interrogalo:

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

Usa l'asset solo quando il suo stato è active. creating e processing indicano che non è ancora pronto.

Passo 6: Genera un video con Seedance 2.5

L'asset real-human va inserito in input_references[].url. Non deve essere incollato nel testo del 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\"}]
  }"

La risposta restituisce un ID del task video. Interroga GET /ai/v1/videos/{id} finché il task non è completed, poi scarica tempestivamente l'output, perché gli URL dei video sono temporanei.

Seedance 2.5 e Seedance 2.0

Seedance 2.5 usa l'endpoint nativo /ai/v1/videos descritto sopra. Le integrazioni più vecchie possono usare Seedance 2.0 con il protocollo compatibile /v1/videos e una struttura dei contenuti diversa.

Non mescolare i due formati di richiesta. Prima dell'uso in produzione, verifica lo schema attuale del modello per durate supportate, risoluzioni, tipi di riferimento, comportamento dell'audio e percorsi degli endpoint.

Best practice per i prompt

Descrivi l'ambiente, l'azione, i tempi, il movimento della camera, la voce e i vincoli. Un prompt efficace potrebbe specificare un kimono, petali di ciliegio che cadono, un gesto gentile della mano, dialoghi in giapponese, movimento labiale sincronizzato, movimento naturale dei capelli e nessun sottotitolo.

Cinque secondi funzionano bene per un breve saluto. Se il video include più azioni o una frase lunga, usa una durata maggiore o accorcia il testo, così che la performance non sembri frettolosa.

Usa un solo riferimento di identità per un test semplice. Aggiungi riferimenti aggiuntivi solo quando lo schema del modello li supporta e ogni asset appartiene allo stesso gruppo di asset.

Problemi comuni

Il gruppo non è attivo: attendi che la sessione di verifica diventi verified e che il gruppo diventi active.
L'asset è in elaborazione: interroga l'ID asset originale; non creare duplicati con un nuovo ID.
L'URL dell'immagine non funziona: usa un URL pubblico HTTPS di un file, non un percorso locale, una pagina di login o una pagina di condivisione.
Il video rifiuta l'asset: verifica che l'asset sia active, appartenga allo stesso account e utilizzi il tipo di media corretto.
Il Playground non mostra asset://: il caricamento delle immagini nel Playground e la registrazione degli asset real-human sono flussi di lavoro separati. Usa il campo di riferimento dell'API per gli asset registrati.

Checklist finale

Chiave API configurata in modo sicuro.
Gruppo di asset creato.
Autorizzazione della persona completata.
Lo stato del gruppo è active.
Lo stato dell'asset del ritratto è active.
La richiesta video usa asset://<asset_id>.
Il task video viene interrogato fino a completed.

Gli asset real-human di AIHubMix offrono agli sviluppatori un modo pratico per creare esperienze video basate sul consenso e coerenti nell'identità con Seedance. Inizia con un ritratto approvato e un breve clip di prova, poi estendi lo stesso flusso di lavoro a strumenti per creator, contenuti di brand e applicazioni di produzione.