Con un'immagine nitida del prodotto, Claude Code e l'API di AIHubMix, puoi generare riferimenti di personaggi con Seedream, registrarli come asset di persone virtuali e usare Seedance per creare un annuncio pubblicitario di prodotto con IA.
Questo tutorial si basa su una vera campagna per uno spray idratante all'aloe e include la struttura del progetto, la configurazione, i comandi e il prompt video completo. L'obiettivo è ottenere un annuncio verticale di 20 secondi, 720p, 9:16, con una persona e un ambiente generati dall'IA.
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 unico punto d'accesso ai modelli, così la generazione di immagini e video può avvenire all'interno dello stesso progetto.
ID dei modelli, parametri e gestione degli errori provengono da una snapshot del progetto datata 16 settembre 2026. Verifica l'API attuale prima di riutilizzarli. I comandi usano il file flow.py incluso e devono essere eseguiti dalla radice del progetto.Scarica il kit di partenza completo
Scarica il codice, i prompt, la configurazione e le immagini di esempio:
https://drive.google.com/uc?export=download&id=1nXcj26Fq3daHeTd0SynS7_QEXgH8z4u_
Dopo aver estratto l'archivio, 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 usa solo la libreria standard.
- Inizia dalla fase video: usa i tre riferimenti inclusi, configura la tua chiave e parti dal 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 parti dal Passo 3.
Copia .env.example in .env e aggiungi la tua chiave API. Il tuo account deve avere accesso ai modelli necessari, all'eventuale permesso per le attività asincrone e quota sufficiente. La generazione tramite 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 insieme immagine, descrizione del prodotto e azione d'uso.
| File | Scopo |
|---|---|
assets/product.png | Immagine originale del prodotto |
prompts/prompt-a.txt | Prompt per il ritratto principale del personaggio |
prompts/prompt-b.txt | Prompt personaggio che tiene il prodotto |
prompts/prompt-c.txt | Prompt di utilizzo del prodotto |
prompts/prompt-video.txt | Timeline del video, requisiti di camera e audio |
prompts.json | Dimensioni, durata, dipendenze dai riferimenti e percorsi dei prompt |
flow.py | Richieste API, registrazione degli asset, polling e download |
seedream.schema.json, seedance.schema.json | Snapshot dello schema API in 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 annunci di prodotto con IA di solito richiede più di un modello. Un modello di immagini crea i riferimenti della persona e del prodotto; un modello video crea il movimento e il comportamento della camera. AIHubMix copre la maggior parte dei modelli più diffusi, quindi puoi scegliere i modelli in base al compito tramite un unico servizio API, senza dover gestire account, autenticazione e punti di accesso separati per ogni fornitore.
AIHubMix si collega inoltre a più fornitori e seleziona automaticamente un percorso disponibile a bassa latenza. Questo può ridurre l'effetto dell'instabilità di un singolo fornitore su un flusso che deve completare in sequenza generazione di immagini, elaborazione degli asset e generazione video. La disponibilità dei modelli, l'instradamento e i tempi di risposta dipendono comunque dalle condizioni attuali del servizio.
Crea .env nella radice del progetto, oppure 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 l'esempio, mai la chiave reale.
L'intero flusso di lavoro inizia con una sola immagine nitida del prodotto.
2. Imposta l'obiettivo di output e separa i parametri di immagine e video
La parte rilevante di prompts.json appare così. Mantieni l'array stills esistente e gli 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 invece di inviare l'intero oggetto di configurazione a entrambi gli endpoint.
Il progetto usa questi ID di 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. Mescolarli causa un rifiuto della richiesta. flow.py verifica le proprietà dello schema in cache prima di inviare una richiesta, ma non si tratta di una validazione completa dei parametri.
3. Genera in ordine i tre riferimenti del personaggio
Ogni immagine ha un ruolo diverso, e le immagini successive dipendono da quelle precedenti:
| Riferimento | Contenuto | Input |
|---|---|---|
| A: Ritratto del personaggio | Definisce volto, capelli, abbigliamento, stanza e illuminazione | Solo prompt di testo in questo esempio |
| B: Che tiene il prodotto | La stessa persona tiene il flacone con l'etichetta rivolta verso la camera | Immagine del prodotto + A |
| C: Che usa il prodotto | La stessa persona preme la pompetta dello spray | Immagine del prodotto + B |
I prompt ripetono i dettagli del personaggio e descrivono la forma del prodotto, i colori, la disposizione dell'etichetta e una manipolazione naturale.
Esegui:
python3 flow.py stills
I risultati vengono salvati come assets/frame-01.jpg, frame-02.jpg e frame-03.jpg. Verifica la coerenza del personaggio, la fedeltà della confezione e il realismo dell'azione d'uso.
Lo script salta i file già esistenti. Se modifichi un prompt, esegui il backup e sposta l'output corrispondente prima di rieseguire. Modificare A potrebbe richiedere anche la rigenerazione di B e C.
I riferimenti definiscono l'identità del personaggio, la presentazione del prodotto e il suo utilizzo.
4. Ospita le immagini e registra gli asset di ritratti virtuali
Il kit di partenza non contiene ID di asset dell'account dell'autore. Registra i riferimenti nel tuo account.
Questo progetto usa URL pubblici delle immagini per la registrazione. Il flusso di lavoro originale usava URL raw di GitHub fissati a uno SHA di commit, ma può funzionare qualsiasi hosting che restituisca l'immagine direttamente senza autenticazione.
Un URL GitHub con /blob/ restituisce una pagina HTML e non può essere usato come URL di 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 di immagine. assets crea o riutilizza un gruppo di asset virtual_portrait, registra ogni immagine, attende che diventi active e scrive gli ID degli asset in state.json.
Questo passaggio deriva da un errore reale del progetto: passare direttamente all'endpoint video URL di personaggi fotorealistici ha restituito doubao_real_person_required. La persona in questa campagna era generata dall'IA, quindi virtual_portrait era la classificazione corretta. Una fotografia di una persona reale deve seguire il relativo processo di verifica e non deve essere etichettata come virtuale.
Tutti gli asset usati in una stessa richiesta video devono appartenere allo stesso gruppo.
I riferimenti sono stati generati e tutti e tre gli asset erano attivi; il task video era ancora in esecuzione quando è stato acquisito questo screenshot.
5. Scrivi il prompt video come timeline con limiti di camera
Il prompt finale del progetto divide un'unica inquadratura continua di 20 secondi in quattro fasi:
| Tempo | Azione del personaggio | Posizione del prodotto |
|---|---|---|
| 0–5 secondi | Guarda in camera e presenta il flacone | Accanto al viso, etichetta verso la camera |
| 5–10 secondi | Solleva il flacone e preme la pompetta | Resta all'interno dell'inquadratura |
| 10–15 secondi | Chiude gli occhi e sente la nebbia depositarsi | Nel terzo inferiore dell'inquadratura |
| 15–20 secondi | Apre gli occhi e presenta di nuovo il prodotto | Di nuovo accanto al viso, etichetta verso la camera |
Un risultato precedente ha spinto la camera troppo vicino e ha fatto perdere il prodotto. Il prompt finale limita quindi il movimento a un primo piano medio, richiede che il prodotto resti visibile e chiede un'etichetta leggibile nei primi e negli ultimi tre secondi.
Ecco il file prompts/prompt-video.txt completo. Per un altro prodotto, aggiorna marchio, descrizione della confezione e azione d'uso. Queste istruzioni sono obiettivi di generazione e richiedono comunque una revisione dell'output.
One continuous 20-second vertical beauty commercial take, no cuts, in a sunlit minimalist vanity corner.
0-5s: the same 24-year-old East Asian woman in an oversized sage-green linen shirt over a white ribbed tank top stands at the vanity holding the translucent light-green Nature Republic Aloe Vera 92% Soothing Gel Mist beside her cheek, the label facing camera and fully legible. She looks to camera with a warm, easy smile and turns the bottle slightly so the label catches the morning light.
5-10s: she lifts the bottle just above eye level and presses the fine-mist pump. A soft cone of aloe mist sprays across her face and catches the light as a faint sparkle of micro-droplets.
10-15s: her eyes close and her chin lifts into a small contented smile as the mist settles, tiny droplets resting on her cheekbone and brow. The bottle stays visible in the lower third of the frame throughout this beat.
15-20s: she opens her eyes, brings the bottle back up beside her cheek with the label square to camera, and holds a final calm look at the lens.
Camera: one slow, smooth push-in from a chest-up framing to a mid-close framing ONLY. Do not push past a mid-close shot. The product must stay inside the frame for the entire take, and the label must be clearly legible in both the first three seconds and the last three seconds.
Look: soft diffused morning sunlight from camera left, photorealistic skin texture with real moisture on the skin, mist rendered as genuinely photographed spray rather than digital particles, premium K-beauty advertising. Keep the product packaging, colours, materials, label layout and label text exactly as in the reference images; do not redesign or re-letter the product. No text overlays, no captions, no watermarks.
Audio: a quiet bright room, one soft short pump-spray hiss, a gentle breath. No music, no voiceover.
La generazione audio è attivata, ma il prompt richiede solo il suono ambientale della stanza, un solo suono di spruzzo e un respiro delicato, senza musica né 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
Usare una lista di argomenti evita anche un problema di zsh presente nel progetto originale, dove più ID memorizzati in un'unica stringa semplice potevano arrivare allo script come un unico argomento non valido.
Lo script salva l'ID del task video, esegue il polling fino a completed e scarica l'output in out/video.mp4. Un altro download può sovrascrivere quel percorso, quindi esegui il backup delle versioni che vuoi confrontare.
Per riprendere un task esistente o riscaricarne il risultato, usa:
python3 flow.py status
Se la risposta di creazione è andata persa, elenca i task recenti e riprendi l'ID interessato:
python3 flow.py tasks
python3 flow.py status VIDEO_TASK_ID
Cercare un task esistente prima di crearne un altro previene generazioni duplicate accidentali.
7. Verifica l'output e itera
Il progetto originale conserva video-v1-10s.mp4 e il video.mp4 finale. La prima versione durava solo 10 secondi e non mostrava abbastanza l'uso del prodotto, quindi il flusso di lavoro ha passato una seconda iterazione del prompt.
Verifica ogni risultato con questa checklist:
- [ ] Durata, risoluzione e proporzioni corrispondono all'obiettivo.
- [ ] Il volto, l'abbigliamento e l'ambiente del personaggio restano coerenti.
- [ ] Il prodotto resta visibile e la sua etichetta è leggibile all'inizio e alla fine.
- [ ] Le azioni di manipolazione e spruzzo corrispondono al reale uso del prodotto.
- [ ] Forma del flacone, confezione e testo non cambiano in modo evidente.
- [ ] La camera non si avvicina troppo e l'audio corrisponde a quanto richiesto.
Se la durata è sbagliata, controlla sia la configurazione sia la richiesta effettiva. Se il prodotto esce dall'inquadratura, rafforza i limiti della camera. Se l'azione d'uso è troppo breve, assegna il tempo e il 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?
Nel progetto di esempio il nome abbreviato di Seedream ha restituito model_not_found. Usa l'ID completo del modello accettato dall'endpoint attuale, invece di presumere che il nome commerciale mostrato sia anche l'identificatore API.
Perché posso aprire un'immagine nel browser ma la registrazione continua a fallire?
Verifica che l'URL restituisca l'immagine stessa e non 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 modificato l'immagine di riferimento?
stills salta i file già esistenti. Esegui il backup e sposta qualsiasi immagine che deve essere rigenerata, poi verifica se anche i riferimenti a valle devono essere rigenerati.
HTTP 200 significa che il video è terminato?
No. Lo script controlla lo status dell'attività e scarica il file solo quando l'attività raggiunge completed.
Inizia la tua prima versione
Prepara un'immagine del prodotto, configura l'accesso ad AIHubMix e scegli i modelli per immagini e video. Poi lascia che Claude Code adatti la descrizione del prodotto e i prompt. Genera i tre riferimenti, verificali e registrali, crea il video e usa la checklist per decidere la prossima iterazione.
Quando un progetto futuro richiederà un altro modello, mantieni la stessa struttura di file e lo stesso flusso di lavoro, quindi aggiorna la selezione del modello su AIHubMix e i parametri specifici del modello. È questo il valore pratico di un servizio API unificato per un team di contenuti che utilizza più modelli di IA: i modelli possono cambiare in base al compito, mentre il flusso di lavoro resta riutilizzabile.
