Blog

Guida all'uso

Creare video brevi con veo-3.1-lite/text-to-video sull'API HiAPI

Un flusso di lavoro pratico per sviluppatori: storyboard text-to-video, audio nativo e scelta delle proporzioni

Nov 9, 2026
Incisioni a tratteggio in rame vintage disposte su uno sfondo blu notte a formare una fascia orizzontale, che costituisce la copertina astratta di uno storyboard per un cortometraggio.
In questa pagina
Un video breve realizzato end-to-end con veo-3.1-lite/text-to-video sull'API HiAPI: storyboard, audio nativo e consegna in 16:9, il tutto tramite un singolo prompt.

Perché i video brevi mandano in crisi i prompt text-to-video ingenui

Al primo incontro con un modello text-to-video, l'istinto è scrivere un lungo prompt cinematografico e aspettarsi indietro un video finito. Per un'opera breve di 30 secondi, questo approccio delude quasi sempre, e la ragione è strutturale, non legata al grado di rifinitura del prompt.

Un singolo prompt chiede al modello di mantenere la continuità lungo l'intero arco narrativo: coerenza dei personaggi, movimento di camera, ritmo e audio devono restare coerenti per tutta la durata. Eppure un video breve non è un unico piano sequenza: è una serie di battute. Hook, preparazione, svolta, chiusura. Ogni battuta richiede una composizione diversa, un'energia diversa e spesso una posizione diversa del soggetto. Compattarli in un unico prompt porta il modello a mediare, e la mediazione è esattamente ciò che distrugge la retention dei video brevi.

L'altra modalità di fallimento è il costo dell'iterazione. Quando un prompt genera un video lungo e la terza battuta viene male, puoi solo rigenerare tutto e sperare che la parte che ti piaceva sopravviva. È un ciclo lento e senza controlli affidabili.

Il flusso di lavoro adottato in questa guida è basato sugli shot: scomponi la sceneggiatura in shot discreti, invia una richiesta di generazione separata per ogni shot e gestisci la continuità nei tuoi metadati invece che nel prompt. Ogni sezione successiva si fonda su questa scomposizione: struttura delle richieste, proporzioni, audio e iterazione presumono tutti che tu lavori shot per shot.

È anche qui che veo-3.1-lite/text-to-video si inserisce naturalmente. Un modello text-to-video più leggero è ideale per generare molti clip brevi e rigenerabili singolarmente, che è esattamente la forma di una pipeline per video brevi.

Il cambio di modello mentale

Smetti di considerare il modello come un regista che restituisce un film finito. Trattalo come un renderer di shot: fornisci una descrizione di shot ben delimitata, ricevi un clip, e la tua pipeline si occupa di ordinamento, missaggio audio e ritmo. Una volta chiarita questa divisione dei compiti, la maggior parte delle decisioni successive diventa ingegneristica anziché di scrittura dei prompt.

Pianificare la lista degli shot prima di chiamare l'API

La lista degli shot è il contratto tra sceneggiatura e chiamate di generazione. Scrivila come dati, non come prosa, così che la tua pipeline possa scorrerla.

Parti dalla sceneggiatura e suddividila in battute. Per i video brevi, una regola pratica è: uno shot per ogni frase o per ogni idea visiva, prendendo il più breve dei due. Se una frase richiede due inquadrature per essere chiara, sono due shot. Se tre frasi condividono un'unica visuale continua, possono essere un solo shot, ma solo se la durata sta ancora comodamente in una singola generazione.

Per ogni shot, registra almeno:

  • ID shot: stabile, leggibile da un umano, usato per caching e retry.
  • Prompt: la descrizione visiva, sufficientemente autosufficiente da reggere lo shot in isolamento.
  • Durata: quanto deve durare quello shot nel montaggio finale.
  • Proporzioni: decise per canale, stabilite prima della generazione.
  • Intento audio: ambienza nativa, silenzio da sostituire, o segnaposto per la voce fuori campo.
  • Note di continuità: abbigliamento dei personaggi, illuminazione, luogo e direzione dello schermo.

Spostare la continuità fuori dai prompt quando possibile

Le note di continuità vanno nei metadati, non ripetute alla lettera in ogni prompt. I prompt che trasportano lunghe descrizioni riutilizzate tendono a spostare l'enfasi: uno shot enfatizza troppo l'abbigliamento, il successivo troppo poco. Uno schema più pulito consiste nel preparare un blocco descrittivo breve e stabile per ogni personaggio o luogo, che tu (autore della pipeline) assembli in ogni prompt, così che la formulazione sia identica tra gli shot anche quando i prompt stessi differiscono.

Far corrispondere ogni shot a una richiesta

Ogni shot dovrebbe poter essere generato in una singola chiamata. Se uno shot richiede più tempo di quanto una generazione possa coprire comodamente, spezzalo in un punto di taglio naturale (una reazione, un movimento di camera, un battito di silenzio) invece di allungare la richiesta. Gli shot più brevi costano anche meno da rigenerare quando uno va male, ed è proprio questo il senso della scomposizione.

Tieni la lista degli shot sotto controllo di versione insieme alla sceneggiatura. Quando la sceneggiatura cambia, il diff ti dice esattamente quali shot vanno ri-renderizzati.

Costruire le richieste di generazione nella pipeline

Con la lista degli shot come dati, il livello delle richieste diventa un sottile wrapper: legge uno shot, costruisce la richiesta per veo-3.1-lite/text-to-video, chiama l'API HiAPI, memorizza il risultato indicizzato per ID shot.

A livello alto, una chiamata di generazione trasporta le stesse informazioni di un record di shot: testo del prompt, durata prevista e proporzioni. I nomi esatti dei parametri e i valori accettabili sono definiti dal riferimento API del modello su HiAPI, quindi considera la documentazione dell'endpoint come fonte di verità e allinea ad essa i valori predefiniti del wrapper, invece di codificare assunzioni in molti punti.

Un wrapper riutilizzabile

La forma sottostante è deliberatamente pseudocodice neutro rispetto al linguaggio: il valore sta nella struttura, non nella sintassi:

function renderShot(shot, attempt):
    request = {
        model: "veo-3.1-lite/text-to-video",
        prompt: buildPrompt(shot),
        duration: shot.duration,
        aspect_ratio: shot.aspectRatio
    }
    response = hiapi.generate(request)
    save(shot.id, attempt, response)
    return response

Tre proprietà rendono questo wrapper utile:

  1. Ogni chiamata è indicizzata per ID shot e numero di tentativo. Quando lo shot 4 va male, sai esattamente quale artefatto sostituire e quali tentativi sono falliti.
  2. Il prompt è costruito, non incollato. buildPrompt fonde la descrizione dello shot con i blocchi stabili di descrizione di personaggi e luoghi nei metadati, così la formulazione della continuità resta coerente tra gli shot.
  3. Le fasi successive non dipendono dal successo della prima chiamata. Il wrapper restituisce un riferimento all'artefatto; il montatore legge il contenuto attualmente approvato per ogni shot.

In pratica la generazione è asincrona

Tratta la generazione come un'attività di lunga durata, non come una chiamata sincrona dentro il gestore delle richieste. Invia, persisti il riferimento al job e fai polling o attendi il completamento in un worker. Così retry, limiti di concorrenza e fallimenti parziali restano sotto il tuo controllo invece di intrecciarsi con il ciclo di vita delle richieste dell'applicazione.

Il montaggio è una fase separata

Non generare e montare in un solo passaggio. Renderizza tutti gli shot approvati, memorizzali, poi esegui un processo di assemblaggio separato: ordina per ID shot, concatena, applica transizioni (se previste) e mixa l'audio. Mantenere l'assemblaggio separato significa che ri-renderizzare uno shot richiede solo di rieseguire l'assemblaggio, senza rigenerare nulla.

Scegliere proporzioni e durata dei clip in base al canale

Proporzioni e durata vanno decise dall'esterno verso l'interno in base al canale di distribuzione, prima che avvenga qualsiasi generazione, non ritagliate dopo. Ritagliare clip finite in formati diversi è il modo più comune di sprecare rendering.

Proporzioni

Scegli un formato principale per ogni canale e mantienilo per tutta l'opera. Mescolare proporzioni in un singolo video breve rovina l'esperienza di visione su ogni piattaforma.

  • Verticale: la scelta predefinita per le interfacce a scorrimento dei feed dei video brevi. Componi per il formato alto: soggetto centrato o leggermente in alto, con margini di sicurezza in alto e in basso per gli overlay dell'interfaccia.
  • Orizzontale: per player incorporati, video hero dei siti web e contesti di presentazione in cui il pubblico è fermo.
  • Quadrato: occasionalmente per layout a griglia; trattalo come una scelta deliberata, non come ripiego.

L'impatto reale sulla tua lista degli shot: la composizione verticale cambia ciò che può stare nell'inquadratura. Un'ampia inquadratura di ambientazione che funziona in orizzontale può diventare illeggibile quando compressa nel formato alto. Decidi prima le proporzioni, poi scrivi gli shot componendo per quel formato.

Durata dei clip

La durata dei clip è guidata dal ritmo, non da quanto il modello può generare al massimo. Alcune linee guida:

  • L'hook deve essere breve. Il primo shot spesso decide se guadagni o perdi l'attenzione; mantienilo compatto e visivamente inequivocabile.
  • Un'idea per clip. Se uno shot contiene due eventi visivi distinti, sepàrali. I clip più brevi ti danno anche un controllo più fine sul ritmo finale in montaggio.
  • Lascia margine di taglio. Genera un po' più lungo del punto di taglio previsto e taglia in assemblaggio. Il taglio è gratuito; la rigenerazione no.
  • Verifica con il totale della piattaforma. La durata totale è la somma degli shot. Somma le durate pianificate prima di generare e controlla che la sequenza rientri nella finestra di consumo tipica del canale: ribilanciare la lista degli shot è molto più facile che ri-renderizzare.

Genera una volta per formato

Se ti serve davvero la stessa opera in due formati, trattale come due consegne separate, ciascuna con la sua lista degli shot. Condividere i prompt va bene; condividere i render no, perché la composizione è diversa. Codificare le proporzioni nei metadati dello shot rende esplicito questo punto e previene riutilizzi accidentali tra canali.

Combinare audio nativo e voce fuori campo

veo-3.1-lite/text-to-video può generare audio nativo insieme alle immagini, e questo audio è davvero utile: ambienza, texture ambientali e semplici suoni diegetici danno al clip una presenza che il silenzio non ha. L'errore è lasciare che audio nativo e voce fuori campo tentino di svolgere lo stesso ruolo.

La divisione efficace è: l'audio nativo fornisce il mondo, la voce fuori campo fornisce le informazioni. Se la traccia nativa contiene già qualcosa di simile al parlato o un letto musicale forte, entrerai in conflitto in fase di missaggio. Decidi shot per shot quale traccia domina.

Ordine del missaggio

  1. Prima la voce fuori campo. I tempi della narrazione sono fissati dalla sceneggiatura; tutto il resto si adatta.
  2. Sotto l'audio nativo. Quando la traccia nativa è ambienza o texture, mantienila udibile ma subordinata.
  3. Abbassa, non eliminare. Riduci la traccia nativa sotto la voce fuori campo invece di tagliarla completamente: un silenzio improvviso tra le battute suona innaturale. Ammorbidisci le transizioni di guadagno su ogni confine tra shot.
  4. Normalizza alla fine. Missare shot per shot e poi concatenare produce salti di livello. Esegui una lavorazione finale unica sull'opera assemblata.

Quando silenziare la traccia nativa

Silenziala, o rigenera lo shot con un intento audio più chiaro, quando:

  • L'audio nativo contiene parlato comprensibile che compete con la tua narrazione.
  • La texture non corrisponde alla scena (per esempio, ambienza interna in uno shot esterno).
  • Stai musicando l'intera opera con un unico letto musicale continuo, e il ritmo della traccia nativa confligge con esso.

Di solito questi casi si individuano shot per shot, un altro motivo per mantenere gli shot indipendenti: puoi rigenerare l'audio di uno shot senza toccare il resto.

Scrivere l'intento audio nella lista degli shot

Aggiungi per ogni shot un campo audio esplicito: native_ambience, silent o voiceover_covered. Ti costringe a decidere prima di generare e dice alla fase di assemblaggio quali shot richiedono abbassamento di volume e quali devono semplicemente scartare la traccia nativa.

Controllare qualità e costi tra più tentativi

La disciplina nell'iterazione è ciò che distingue una pipeline che converge da una che brucia rendering. La buona notizia è che la generazione basata sugli shot rende naturali le abitudini corrette.

Rigenera solo il singolo shot, mai la sequenza

Quando una battuta va male, sostituisci quello shot. Il tuo wrapper indicizza i risultati per ID shot e numero di tentativo, quindi la correzione consiste nell'avviare un nuovo tentativo per un ID e rieseguire l'assemblaggio. Se ti ritrovi a ri-renderizzare più shot per correggerne uno, la lista degli shot è probabilmente troppo grossolana: scomponila ulteriormente.

Memorizza attivamente in cache i clip approvati

Una volta approvato uno shot, trattalo come immutabile, memorizzato in modo persistente, indicizzato per ID shot più l'hash del suo prompt e dei suoi parametri. Rieseguire la pipeline salta tutto ciò che non è cambiato. Questo conta soprattutto durante il lavoro su audio e ritmo, quando iteri sul missaggio con le immagini fisse.

Cambia una sola variabile per tentativo

Quando uno shot non raggiunge il risultato, modifica una cosa (la specificità del prompt, la durata o la composizione) e rigenera. Cambiare tre variabili insieme non ti dice quale correzione ha funzionato, e riparerai la stessa lezione sullo shot successivo.

Fissa la ricetta prima di scalare i tentativi

Porta una sequenza completa a uno stato che ti soddisfa, poi usala come modello per le varianti: hook alternativi, CTA diverse. Poiché la lista degli shot è dati, una variante è solo un piccolo diff, non un nuovo progetto.

Fai il budget sul numero di shot, non sui minuti finali

L'unità di lavoro è lo shot, quindi anche l'unità di iterazione è lo shot. Prima di generare un lotto, calcola il numero di shot e i tentativi previsti per shot. Questo numero, combinato con la base di fatturazione del modello, è il tuo numero di pianificazione: consulta le tariffe correnti nel pannello prezzi di HiAPI invece di affidarti a supposizioni obsolete.

Rivedi alla dimensione finale

Controlla ogni shot nelle proporzioni reali e sullo schermo su cui il pubblico lo guarderà. I problemi invisibili alla dimensione orizzontale del desktop sono evidenti in un feed verticale. Scoprirli in fase di revisione costa molto meno che dopo la pubblicazione.

Risolvere i problemi di generazione comuni

Quando uno shot torna inutilizzabile, esegui questi controlli in ordine. Coprono la stragrande maggioranza dei fallimenti, e i primi due risolvono la maggior parte dei casi.

1. Specificità del prompt

Il prompt è autosufficiente? Descrive soggetto, azione, composizione e illuminazione, o dipende dal contesto degli shot adiacenti? Il prompt di uno shot deve reggere da solo: il modello vede solo ciò che gli invii. Descrizioni vaghe del soggetto causano deriva; prompt sovraccarichi causano confusione. L'obiettivo è un soggetto chiaro e un'azione chiara per ogni shot.

2. Lunghezza dello shot

Sta facendo troppe cose per la sua durata? Se un prompt implica più eventi visivi in un clip breve, il modello li comprime. Scomponi lo shot o allungalo. Al contrario, gli shot con troppo poco contenuto per la loro durata tendono a vagare: accorciali.

3. Proporzioni non corrispondenti

Hai scritto il prompt per il formato che stai effettivamente richiedendo? Descrizioni ampie e orizzontali in un formato verticale producono ritagli scomodi e spazi morti. Verifica che la descrizione visiva dello shot corrisponda alle sue proporzioni e che nessun'altra fase della pipeline stia ricandidando di nascosto.

4. Conflitto audio

Se le immagini vanno bene ma il risultato sembra sbagliato, ascolta la traccia nativa da sola. Voci in competizione, ambienza errata o un ritmo forte sotto la narrazione sono di solito problemi audio, non visivi. Risolvi silenziando la traccia nativa o regolando l'intento audio dello shot, poi rimixa: non serve rigenerare le immagini.

5. Errori di pipeline e parametri

Se la generazione fallisce direttamente o restituisce contenuti incoerenti con la richiesta, verifica i parametri con la documentazione dell'endpoint su HiAPI: identificatore del modello scritto correttamente, valori di durata e proporzioni nei limiti accettabili, prompt non vuoto. Sono errori banali ma comuni nei wrapper che codificano valori predefiniti in più punti: è il motivo per cui conviene tenere la costruzione delle richieste in un'unica funzione.

6. Deriva di continuità tra gli shot

Se ogni shot sembra a posto ma la sequenza non resta coerente, il problema è nei metadati, non nella generazione. Confronta il testo del prompt assemblato per ogni shot: se i descrittori di personaggi o luoghi sono formulati in modo diverso, allineali nel blocco condiviso dei descrittori e rigenera solo gli shot che deviano.

Procedi lungo la lista in ordine e annota quale controllo ha risolto ogni fallimento. Dopo alcune sequenze saprai quali controlli dominano per i tuoi contenuti, e la risoluzione dei problemi diventerà una rapida scansione invece di una ricostruzione. Puoi iniziare a renderizzare gli shot con veo-3.1-lite/text-to-video tramite l'API HiAPI, lasciando che il pannello prezzi si occupi dei numeri mentre tu ti concentri sulla sequenza.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API