Con un'immagine chiara del prodotto, Claude Code e l'API AIHubMix, puoi generare riferimenti ai personaggi in Seedream, registrarli come asset di persone virtuali e utilizzare Seedance per creare un annuncio per un prodotto AI.
Questo tutorial si basa su una campagna reale di aloe-mist e include la struttura del progetto, la configurazione, i comandi e il prompt video completo. L'output target è un annuncio verticale di 20 secondi, 720p, 9:16 con una persona e un'ambientazione generate dall'AI.
Claude Code e AIHubMix alimentano l'intero flusso di lavoro. Claude Code legge il brief del progetto, rivede i prompt e organizza l'esecuzione. AIHubMix fornisce un punto di ingresso per il modello in modo che la generazione di immagini e video possa operare all'interno dello stesso progetto.
Gli ID dei modelli, i parametri e la gestione degli errori provengono da uno snapshot del progetto datato 16 settembre 2026. Controlla l'API attuale prima di riutilizzarli. I comandi utilizzano il flow.py incluso e devono essere eseguiti dalla radice del progetto.Scarica il Pacchetto Completo
Scarica il codice, i prompt, la configurazione e le immagini di esempio
Dopo aver estratto il pacchetto, entra nella directory seedance-starter. Il pacchetto include flow.py, due snapshot dello schema, cinque file di prompt, l'immagine del prodotto e tre immagini di riferimento. Lo script Python utilizza solo la libreria standard.
- Inizia con la fase video: usa i tre riferimenti inclusi, configura la tua chiave e inizia con il Passo 4.
- Inizia con il tuo prodotto: sostituisci l'immagine del prodotto e i dettagli del prompt, sposta le immagini di riferimento incluse fuori da
assets/, e inizia con il Passo 3.
Copia .env.example in .env e aggiungi la tua chiave API. Il tuo account deve avere accesso ai modelli pertinenti, a qualsiasi autorizzazione per attività asincrone necessaria e a una quota sufficiente. La generazione API comporta costi di utilizzo.
1. Prepara l'Immagine del Prodotto e il Progetto
Il prodotto di esempio è Nature Republic Aloe Vera Mist. Quando adatti il flusso di lavoro, aggiorna l'immagine, la descrizione del prodotto e utilizza l'azione insieme.
| File | Scopo |
|---|---|
assets/product.png | Immagine originale del prodotto |
prompts/prompt-a.txt | Prompt per il ritratto del personaggio principale |
prompts/prompt-b.txt | Prompt per il personaggio che tiene il prodotto |
prompts/prompt-c.txt | Prompt per l'uso del prodotto |
prompts/prompt-video.txt | Timeline del video, requisiti della telecamera e audio |
prompts.json | Dimensioni, durata, dipendenze di riferimento e percorsi dei prompt |
flow.py | Richieste API, registrazione degli asset, polling e download |
seedream.schema.json, seedance.schema.json | Snapshot dello schema API memorizzati nella cache |
Claude Code aiuta a leggere il brief del progetto e a rivedere la configurazione e i prompt. flow.py invia le richieste effettive tramite AIHubMix.
Perché AIHubMix si Adatta a Questo Flusso di Lavoro
Un flusso di lavoro per un annuncio di prodotto AI di solito ha bisogno di più di un modello. Un modello di immagine crea i riferimenti per la persona e il prodotto; un modello video crea movimento e comportamento della telecamera. AIHubMix copre la maggior parte dei modelli mainstream, quindi puoi selezionare i modelli per compito attraverso un servizio API invece di mantenere account separati, autenticazione e punti di ingresso per ogni fornitore.
AIHubMix si collega anche a più fornitori e seleziona automaticamente un percorso a bassa latenza disponibile. Questo può ridurre l'effetto dell'instabilità di un singolo fornitore su un flusso di lavoro che deve completare la generazione di immagini, l'elaborazione degli asset e la generazione di video in sequenza. La disponibilità del modello, il routing e il tempo di risposta dipendono comunque dalle condizioni di servizio attuali.
Crea .env nella radice del progetto, o fornisci la stessa variabile nel tuo ambiente:
AIHUBMIX_API_KEY=replace_with_your_api_key
Il progetto esclude .env tramite .gitignore. Condividi solo il nome della variabile e un esempio, mai la chiave reale.
L'intero flusso di lavoro inizia con un'immagine chiara del prodotto.
2. Imposta l'Obiettivo di Output e Separa i Parametri di Immagine dai Parametri Video
La parte pertinente di prompts.json è simile a questa. Mantieni l'array stills esistente e altri campi quando modifichi il file reale.
{
"size": "1080x1920",
"aspect_ratio": "9:16",
"duration": 20,
"resolution": "720p",
"generate_audio": true,
"video_prompt_file": "prompts/prompt-video.txt"
}
size appartiene alla generazione di immagini. aspect_ratio, duration, resolution e generate_audio appartengono alla generazione video. Lo script costruisce richieste separate piuttosto che inviare l'intero oggetto di configurazione a entrambi gli endpoint.
Il progetto utilizza questi ID modello:
- Seedream:
doubao-seedream-5-0-pro-260628 - Seedance:
doubao-seedance-2-5-260628
Le snapshot dello schema incluse mostrano che l'endpoint delle immagini accetta size, mentre l'endpoint video accetta aspect_ratio. Mischiarli causa un rifiuto. flow.py controlla le proprietà dello schema memorizzate nella cache prima di inviare una richiesta, ma questa non è una validazione completa dei parametri.
3. Genera i Tre Riferimenti ai Personaggi in Ordine
Ogni immagine ha un ruolo diverso, e le immagini successive dipendono da quelle precedenti:
| Riferimento | Contenuto | Input |
|---|---|---|
| A: Ritratto del personaggio | Stabilire viso, capelli, guardaroba, stanza e illuminazione | Prompt di testo solo in questo esempio |
| B: Tenendo il prodotto | La stessa persona tiene la bottiglia con l'etichetta rivolta verso la telecamera | Immagine del prodotto + A |
| C: Uso del prodotto | La stessa persona preme il pomello dello spray | Immagine del prodotto + B |
I prompt ripetono i dettagli del personaggio e descrivono la forma, i colori, il layout dell'etichetta e la manipolazione naturale del prodotto.
Esegui:
python3 flow.py stills
I risultati vengono salvati come assets/frame-01.jpg, frame-02.jpg e frame-03.jpg. Controlla la coerenza del personaggio, la fedeltà dell'imballaggio e il realismo dell'azione d'uso.
Lo script salta i file esistenti. Se cambi un prompt, esegui il backup e sposta l'output corrispondente prima di rieseguire. Cambiare A potrebbe anche richiedere di rigenerare B e C.
I riferimenti stabiliscono l'identità del personaggio, la presentazione del prodotto e l'uso del prodotto.
4. Ospita le Immagini e Registra gli Asset di Ritratto Virtuale
Il pacchetto di avvio non contiene ID asset dall'account dell'autore. Registra i riferimenti nel tuo account.
Questo progetto utilizza URL di immagini pubbliche per la registrazione. Il flusso di lavoro sorgente utilizzava URL raw di GitHub fissati a un commit SHA, ma qualsiasi hosting che restituisce l'immagine direttamente senza autenticazione può funzionare.
Un URL GitHub /blob/ restituisce una pagina HTML e non può essere utilizzato come URL immagine.
Sostituisci questo host segnaposto con la posizione reale dei tuoi file caricati:
IMAGE_BASE='https://your-public-image-host.example/campaign'
python3 flow.py check "$IMAGE_BASE/frame-01.jpg" "$IMAGE_BASE/frame-02.jpg" "$IMAGE_BASE/frame-03.jpg"
python3 flow.py assets "$IMAGE_BASE/frame-01.jpg" "$IMAGE_BASE/frame-02.jpg" "$IMAGE_BASE/frame-03.jpg"
check verifica HTTP 200 e un Content-Type immagine. assets crea o riutilizza un gruppo di asset virtual_portrait, registra ogni immagine, attende fino a quando non diventa attivo e scrive gli ID degli asset in state.json.
Questo passaggio proviene da un reale fallimento nel progetto: passare URL di personaggi fotorealistici direttamente all'endpoint video restituiva doubao_real_person_required. La persona in questa campagna era generata dall'AI, quindi virtual_portrait era la classificazione corretta. Una fotografia di persona reale deve seguire il corrispondente processo di verifica e non deve essere etichettata come virtuale.
Tutti gli asset utilizzati in una richiesta video dovrebbero appartenere allo stesso gruppo.
I riferimenti sono stati generati e tutti e tre gli asset erano attivi; il compito video era ancora in esecuzione quando è stata catturata questa schermata.
5. Scrivi il Prompt Video come una Timeline con Limiti della Telecamera
Il prompt finale del progetto divide un'unica ripresa continua di 20 secondi in quattro fasi:
| Tempo | Azione del personaggio | Posizione del prodotto |
|---|---|---|
| 0–5 secondi | Guarda la telecamera e presenta la bottiglia | Accanto al suo viso, etichetta verso la telecamera |
| 5–10 secondi | Alza la bottiglia e preme il pomello | Rimane all'interno dell'inquadratura |
| 10–15 secondi | Chiude gli occhi e sente la nebbia posarsi | Terzo inferiore dell'inquadratura |
| 15–20 secondi | Apre gli occhi e presenta di nuovo il prodotto | Di nuovo accanto al suo viso, etichetta verso la telecamera |
Un risultato precedente ha spinto la telecamera troppo vicino e ha perso il prodotto. Pertanto, il prompt finale limita il movimento a una ripresa media ravvicinata, richiede che il prodotto rimanga visibile e chiede un'etichetta leggibile durante i primi e gli ultimi tre secondi.
Qui c'è il completo prompts/prompt-video.txt. Per un altro prodotto, aggiorna il marchio, la descrizione dell'imballaggio e l'azione d'uso. Queste istruzioni sono obiettivi di generazione e richiedono comunque una revisione dell'output.
Un'unica ripresa continua di 20 secondi di un annuncio di bellezza verticale, senza tagli, in un angolo di vanity minimalista illuminato dal sole.
0-5s: la stessa donna asiatica orientale di 24 anni in una camicia di lino verde salvia oversize sopra una canotta bianca a coste si trova davanti allo specchio tenendo il gel spray lenitivo Nature Republic Aloe Vera 92% traslucido verde chiaro accanto alla guancia, l'etichetta rivolta verso la telecamera e completamente leggibile. Guarda la telecamera con un sorriso caldo e facile e ruota leggermente la bottiglia in modo che l'etichetta catturi la luce del mattino.
5-10s: solleva la bottiglia appena sopra il livello degli occhi e preme il pomello a spruzzo fine. Un cono morbido di nebbia di aloe spruzza sul suo viso e cattura la luce come un lieve luccichio di micro-gocce.
10-15s: chiude gli occhi e solleva il mento in un piccolo sorriso soddisfatto mentre la nebbia si posa, piccole gocce riposano sulla sua guancia e sulla fronte. La bottiglia rimane visibile nel terzo inferiore dell'inquadratura per tutta questa fase.
15-20s: apre gli occhi, riporta la bottiglia accanto alla guancia con l'etichetta quadrata verso la telecamera e mantiene uno sguardo finale calmo verso l'obiettivo.
Telecamera: una lenta e fluida inquadratura dal petto in su a un'inquadratura media ravvicinata SOLO. Non spingere oltre un'inquadratura media ravvicinata. Il prodotto deve rimanere all'interno dell'inquadratura per tutta la ripresa e l'etichetta deve essere chiaramente leggibile nei primi tre secondi e negli ultimi tre secondi.
Aspetto: luce del mattino dolcemente diffusa da sinistra della telecamera, texture della pelle fotorealistica con vera umidità sulla pelle, nebbia resa come spray fotografato genuinamente piuttosto che particelle digitali, pubblicità K-beauty premium. Mantieni l'imballaggio del prodotto, i colori, i materiali, il layout dell'etichetta e il testo dell'etichetta esattamente come nelle immagini di riferimento; non ridisegnare o riscrivere il prodotto. Nessun sovrapposizione di testo, nessuna didascalia, nessun watermark.
Audio: una stanza tranquilla e luminosa, un breve sibilo di spruzzo morbido, un respiro gentile. Nessuna musica, nessuna voce narrante.
La generazione audio è abilitata, ma il prompt richiede solo il tono della stanza, un suono di spruzzo e un respiro gentile—nessuna musica o voce fuori campo.
6. Genera e Salva il Video
Dopo la registrazione degli asset, invia i riferimenti asset://. Questo comando legge gli ID salvati e passa ciascuno come argomento separato:
python3 - <<'PYCODE'
import json
import subprocess
import sys
from pathlib import Path
state = json.loads(Path("state.json").read_text())
refs = ["asset://" + asset_id for asset_id in state["asset_ids"]]
subprocess.run([sys.executable, "flow.py", "video", *refs], check=True)
PYCODE
Utilizzare un elenco di argomenti evita anche un problema zsh del progetto sorgente, dove diversi ID memorizzati in una stringa semplice potrebbero raggiungere lo script come un argomento non valido.
Lo script salva l'ID del compito video, effettua polling fino a quando non è completato e scarica l'output in out/video.mp4. Un altro download può sovrascrivere quel percorso, quindi esegui il backup delle versioni che desideri confrontare.
Riprendi un'attività esistente o riscarica il suo risultato con:
python3 flow.py status
Se la risposta di creazione è stata persa, elenca le attività recenti e riprendi l'ID pertinente:
python3 flow.py tasks
python3 flow.py status VIDEO_TASK_ID
Cercare un'attività esistente prima di crearne un'altra previene la generazione accidentale di duplicati.
7. Rivedi l'Output e Itera
Il progetto sorgente mantiene video-v1-10s.mp4 e il finale video.mp4. La prima versione durava solo 10 secondi e non mostrava abbastanza utilizzo del prodotto, quindi il flusso di lavoro è passato attraverso una seconda iterazione del prompt.
Controlla ogni risultato rispetto a questa lista di controllo:
- [ ] La durata, la risoluzione e il rapporto d'aspetto corrispondono all'obiettivo.
- [ ] Il viso, il guardaroba e l'ambientazione del personaggio rimangono coerenti.
- [ ] Il prodotto rimane visibile e la sua etichetta può essere letta all'inizio e alla fine.
- [ ] Le azioni di manipolazione e spruzzo corrispondono all'uso reale del prodotto.
- [ ] La forma della bottiglia, l'imballaggio e il testo non cambiano in modo evidente.
- [ ] La telecamera non si avvicina troppo e l'audio corrisponde alla richiesta.
Se la durata è errata, ispeziona sia la configurazione che la richiesta effettiva. Se il prodotto esce dall'inquadratura, rafforza i limiti della telecamera. Se l'azione d'uso è troppo breve, assegna tempo e comportamento in modo più esplicito. Modificare solo prompts/prompt-video.txt non richiede di rigenerare le immagini di riferimento; rigenerale e registrale solo quando i riferimenti visivi devono cambiare.
Domande Frequenti
Perché un nome di modello che sembra corretto restituisce 404?
Il nome abbreviato di Seedream ha restituito model_not_found nel progetto sorgente. Usa l'ID modello API completo accettato dall'endpoint attuale piuttosto che presumere che il nome visualizzato nel marketing sia anche l'identificatore API.
Perché posso aprire un'immagine nel mio browser ma non riesco comunque a registrarla?
Conferma che l'URL restituisca l'immagine stessa piuttosto che HTML, una pagina di condivisione o una pagina di accesso. Usa python3 flow.py check URL... prima della registrazione.
Perché cambiare un prompt non ha cambiato l'immagine di riferimento?
stills salta i file esistenti. Esegui il backup e sposta qualsiasi immagine che necessita di rigenerazione, quindi controlla se i riferimenti a valle devono essere rigenerati.
HTTP 200 significa che il video è finito?
No. Lo script si ramifica sul status del compito e scarica solo dopo che il compito raggiunge completato.
Inizia la Tua Prima Versione
Prepara un'immagine del prodotto, configura l'accesso a AIHubMix e scegli i modelli di immagine e video. Poi lascia che Claude Code adatti la descrizione del prodotto e i prompt. Genera i tre riferimenti, rivedili e registrali, crea il video e usa la lista di controllo per decidere la prossima iterazione.
Quando un progetto futuro avrà bisogno di un altro modello, mantieni la stessa struttura di file e flusso di lavoro, quindi aggiorna la selezione del modello AIHubMix e i parametri specifici del modello. Questo è il valore pratico di un servizio API unificato per un team di contenuti che utilizza diversi modelli AI: i modelli possono cambiare in base al compito mentre il flusso di lavoro rimane riutilizzabile.
