Creare video brevi con flux-3-max/text-to-video su HiAPI API

Perché i video brevi sono un problema di orchestrazione dei prompt

La maggior parte dei team che fallisce con la generazione video da testo lo fa per lo stesso motivo: scrivono un unico enorme prompt che descrive l'intera scena e si aspettano che il modello restituisca un video completo di trenta secondi. La generazione non funziona così. Il modello genera un solo piano continuo per chiamata, e ogni chiamata è una piccola decisione autonoma su soggetto, azione, inquadratura e suono.

Il modello mentale che regge davvero è l'orchestrazione. Non stai prompettando un video, stai dirigendo una serie di inquadrature e poi le assembli. Un'opera video breve — un teaser di prodotto, un hook per i social, una spiegazione con voce fuori campo — è tipicamente composta da quattro a otto inquadrature. Ogni inquadratura ha un solo compito: stabilire, mostrare, transire, concludere. Una volta accettata questa scomposizione, l'API smette di essere una slot machine e diventa un passo di rendering in una pipeline che controlli.

Questo è importante perché le modalità di fallimento della generazione video da testo sono per lo più fallimenti di continuità, non di qualità. Una singola inquadratura può sembrare bellissima, ma se nell'inquadratura successiva il personaggio è diverso, la direzione della luce è diversa o la camera va alla deriva all'improvviso, quell'inquadratura resta inutilizzabile. Questi problemi si risolvono prima che la richiesta venga inviata, in base a come pianifichi e descrivi le inquadrature — non aggiungendo aggettivi a un prompt gigante.

Il resto di questa guida ti accompagna end-to-end in questo workflow, basato su HiAPI per chiamare flux-3-max/text-to-video: scomporre la sceneggiatura in inquadrature, scrivere prompt per singola inquadratura, trattare il movimento di camera come una dimensione controllata, usare l'audio nativo per saltare uno stadio audio separato e racchiudere tutto in un piccolo ciclo di richieste riproducibile.

Pianificare le inquadrature prima di chiamare l'API

Prima di scrivere qualsiasi codice, trasforma la sceneggiatura in una lista di inquadrature. Una lista di inquadrature è una struttura dati pura: un elemento per ogni chiamata di generazione, ognuno con uno scopo esplicito. Questa struttura funziona bene come rappresentazione intermedia:

[
  {
    "id": "s1",
    "role": "establish",
    "subject": "ceramic pour-over coffee dripper on a wooden counter",
    "framing": "medium close-up, three-quarter angle",
    "durationIntent": "short",
    "camera": "slow push in",
    "audio": "quiet room tone, soft steam"
  },
  {
    "id": "s2",
    "role": "demonstrate",
    "subject": "hot water spiraling over coffee grounds",
    "framing": "tight overhead macro",
    "durationIntent": "short",
    "camera": "locked off",
    "audio": "water pouring, gentle hiss"
  }
]

Alcune regole di pianificazione che risparmiano tentativi successivi:

• Un'idea per inquadratura. Se la descrizione dell'inquadratura contiene "poi", spezzala. Il modello gestisce molto meglio una singola azione continua rispetto a una sequenza di battute.
• Esprimi l'intenzione di durata, non i secondi esatti. Decidi se un'inquadratura è un taglio rapido o una sosta più lunga ed esprimila come intenzione. I tempi precisi appartengono alla fase di montaggio/assemblaggio, dove ottieni il controllo a livello di frame.
• Fissa presto il vocabolario dell'inquadratura. Scegli termini come wide, medium, close-up, overhead, low angle e riusali identici in tutte le inquadrature. Un vocabolario coerente produce risultati più coerenti.
• Pianifica gli ancoraggi di continuità. Decidi cosa resta invariato: descrizione del personaggio, abbigliamento, palette cromatica, ora del giorno, direzione della luce. Scrivilo una volta come prefisso condiviso e riusalo in ogni prompt.
• L'ordine conta in fase di revisione. Genera nell'ordine della sceneggiatura, così puoi rivedere nell'ordine di riproduzione finale invece di guardare le clip come frammenti isolati.

Una volta che la lista di inquadrature esiste, la chiamata API diventa meccanica — ed è esattamente ciò che vuoi, perché rende le chiamate ripetibili e riproducibili.

Scrivere prompt per singola inquadratura per flux-3-max/text-to-video

Un buon prompt per singola inquadratura è strutturato, non colloquiale. Invece di scrivere un'unica lunga stringa libera, componi ogni prompt con pochi paragrafi etichettati. Questo rende i prompt confrontabili, riutilizzabili e facili da modificare quando un singolo elemento non funziona.

Struttura in cinque parti

1. Soggetto — chi o cosa, con i dettagli di continuità che hai deciso (aspetto, abbigliamento, caratteristiche del prodotto).
2. Azione — un singolo movimento continuo o stato, descritto al presente.
3. Ambiente — luogo, ora del giorno, qualità della luce, palette cromatica.
4. Camera — inquadratura più movimento, usando il tuo vocabolario fisso. La sezione successiva lo approfondisce.
5. Audio — l'atmosfera sonora e l'intenzione di foley per questa inquadratura.

Componili in un ordine fisso, così anche il tuo debug resta coerente:

CONTINUITY = (
    "a minimalist ceramic pour-over coffee dripper, matte white, "
    "on a warm oak counter, soft morning window light from the left, "
    "muted natural palette"
)

def shot_prompt(subject, action, setting, camera, audio):
    return (
        f"{subject}. {action}. {setting}. "
        f"Camera: {camera}. Audio: {audio}."
    )

prompt = shot_prompt(
    subject=f"{CONTINUITY}",
    action="steam rising steadily as water slowly blooms the coffee grounds",
    setting="kitchen counter at dawn, shallow depth of field",
    camera="medium close-up, slow push in, no shake",
    audio="quiet room tone, soft water pour, faint steam hiss",
)

Mantenere coerente il look delle inquadrature

L'abitudine singola con il maggiore effetto leva è il blocco di continuità condiviso. Mettilo all'inizio di ogni segmento del soggetto e mantienilo identico in tutte le inquadrature della sequenza. Quando un'inquadratura presenta una deriva visiva, puoi isolare il problema per bisezione: è il blocco di continuità o l'azione specifica dell'inquadratura?

Altre due abitudini che riducono la deriva:

• Evita aggettivi contraddittori. "Cinematografico documentaristico a mano fermo" sono tre istruzioni in conflitto. Scegline una.
• Descrivi la luce una volta sola. Se il blocco di continuità dice luce mattutina da sinistra, non far introdurre alle inquadrature successive una luce fluorescente dall'alto — a meno che quel cambio non sia intenzionale.

Cosa omettere dai prompt

Tieni le proporzioni d'aspetto, la lunghezza dell'output e altri parametri tecnici fuori dalla descrizione testuale e passali come parametri della richiesta quando l'API li espone. La descrizione testuale dice cos'è l'inquadratura; i parametri dicono come viene consegnata. Mescolare i due rende entrambi più difficili da modificare.

Controllare il movimento di camera

Il movimento di camera è la dimensione più facile da lasciare al caso, e anche quella che più determina se una sequenza sembra diretta. Se non lo specifichi, il modello muoverà la camera in qualche modo; il movimento non specificato si manifesta come deriva, e la deriva è ciò che fa sembrare il materiale generato come ripreso per caso.

Trattare il movimento come un piccolo vocabolario chiuso

Non improvvisare il linguaggio di camera per ogni inquadratura. Definisci un piccolo insieme di movimenti e riusali:

• Camera fissa — nessun movimento. La scelta più sicura per dettagli di prodotto e primi piani.
• Push in / pull out — avvicinarsi o allontanarsi dal soggetto. Adatti a enfasi e rivelazione.
• Pan a sinistra / a destra — rotazione orizzontale. Per stabilire la spazialità.
• Tilt up / tilt down — rotazione verticale. Usali con cautela; risultano molto drammatici.
• Tracking — seguire il soggetto. Richiede un soggetto in movimento evidente come ancora.

Scrivili nel segmento camera, seguiti da un'istruzione negativa che sopprime il resto del movimento: Camera: slow push in, no shake, no handheld drift.

La clausola negativa è importante. Dire solo "push in" lascia al modello lo spazio per aggiungere ondeggiamento; dire "push in, no shake" restringe il campo.

Far servire il movimento al ruolo dell'inquadratura

Il movimento dovrebbe servire il montaggio. Una mappatura pratica:

• Inquadratura di stabilimento — un movimento chiaro (lento push in o pan delicato) che dia allo sguardo un punto di arrivo.
• Inquadratura di dettaglio — camera fissa. Il dettaglio è già denso di informazioni visive; il movimento gli farebbe concorrenza.
• Transizione — movimento coerente tra inquadrature adiacenti (entrambe push in, entrambe pan nella stessa direzione), così che il taglio sembri intenzionale anche senza effetti di transizione.
• Inquadratura hero — un movimento deliberato, mai due combinati.

Un solo movimento per inquadratura

I movimenti combinati ("pan a destra mentre fai push in e tilt up") producono risultati confusi. Se una battuta richiede un movimento di camera complesso, spezzala in due inquadrature. La fase di assemblaggio può unirle, e tu mantieni il controllo a livello di frame sul taglio.

Coerenza del movimento nella sequenza

Decidi in anticipo il movimento dominante dell'intera opera — ad esempio "tutte le inquadrature con lento push in" — e devia solo quando serve un effetto. Una sequenza con direzione di movimento coerente si legge come intenzionale; una con movimento casuale si legge come generata.

Usare l'audio nativo nella pipeline

La generazione audio nativa cambia l'architettura della pipeline per video brevi. Nel flusso tradizionale generi prima il video muto, poi esegui uno stadio audio separato — un modello testo-audio, oppure una libreria di foley e musica con licenza — e infine allinei i due nell'editor. Ogni fase è un altro servizio, un'altra credenziale, un'altra modalità di fallimento e un altro punto in cui può verificarsi uno scarto temporale.

Quando il modello video genera l'audio inline, suono e immagine vengono prodotti nello stesso passaggio di inferenza, quindi sono naturalmente allineati a ciò che accade sullo schermo. Nel momento in cui l'acqua versa, il suono del versare coincide con l'azione del versare. Questo elimina quasi del tutto il lavoro di allineamento.

Due pipeline, una differenza

Separate audio stage:            Native audio:
  shot -> video (silent)           shot -> video + audio
       -> audio generation              -> assemble
       -> alignment / mixing
       -> assemble

Il vantaggio pratico è avere meno parti in movimento. Il vincolo pratico è che devi pianificare il suono nei prompt, non aggiungerlo dopo.

Pianificare le inquadrature intorno al suono

Poiché l'audio fa parte della generazione, scrivilo come parte dell'inquadratura, non come aggiunta successiva:

• Nomina il suono dominante. Audio: water pouring, gentle hiss è meglio di Audio: pleasant kitchen sounds.
• Mantieni la sparsità. Uno o due elementi chiari per inquadratura. Le descrizioni audio stratificate tendono a confondersi.
• Decidi la musica consapevolmente. Se prevedi di aggiungere una base musicale all'intera opera nell'editor, lascia che l'audio delle inquadrature contenga solo atmosfera, così non compete con la traccia musicale.
• Considera la continuità del suono. Come per la continuità visiva, anche la continuità audio attraverso i tagli aiuta — lo stesso rumore di fondo della stanza in inquadrature adiacenti fa percepire una sequenza come ambientata nello stesso luogo.

Dove l'editor vince ancora

L'audio nativo non sostituisce l'editor. Sostituisce il passo di allineamento. Hai ancora bisogno della normalizzazione finale della loudness e, se usi la musica, di un passaggio di missaggio che abbassi dialoghi e foley sotto la base. Metti in budget queste attività nella tua pipeline, ma con un budget molto inferiore rispetto all'uso di uno stadio di generazione separato.

Una richiesta eseguibile e il flusso di assemblaggio

Con la lista di inquadrature e il costruttore di prompt, lo strato delle richieste è sottile. Le decisioni chiave sono: come chiamare il modello, come gestire ordine e tentativi, e come passare i risultati all'assemblaggio.

Ciclo di orchestrazione

import time

SHOTS = [
    # your planned shot list from the earlier step
]

def generate_shot(shot, attempt=0):
    payload = {
        "model": "flux-3-max/text-to-video",
        "prompt": build_prompt(shot),
        # pass delivery parameters here, not in the prose:
        # aspect ratio, length, etc. per the API reference
    }
    try:
        return client.generate(payload)
    except TransientError:
        if attempt >= 3:
            raise
        time.sleep(2 ** attempt)
        return generate_shot(shot, attempt + 1)

def run_sequence(shots):
    results = {}
    for shot in shots:
        results[shot["id"]] = generate_shot(shot)
    return [results[s["id"]] for s in shots]

Tre cose rendono questo ciclo sicuro per la produzione, non solo una demo:

• Iterazione ordinata. Generare nell'ordine della sceneggiatura significa che un fallimento parziale lascia un prefisso che puoi rivedere, ed è semplice rieseguire solo le inquadrature mancanti.
• Risultati memorizzati per chiave. Archivia gli output per id dell'inquadratura, non per posizione nella lista. Se la terza inquadratura fallisce e viene rigenerata, sovrascrivi per chiave, non riaccodi.
• Retry limitati con backoff. I fallimenti transitori sono normali in qualsiasi API di generazione. Limita i tentativi, così una singola inquadratura problematica non blocca l'intero lavoro.

Passaggio all'assemblaggio

Il tuo ciclo di generazione dovrebbe produrre un manifest — la lista di inquadrature con i riferimenti agli output — e fermarsi lì. L'assemblaggio è un passo separato che consuma quel manifest: taglia ogni clip alla durata prevista, applica le transizioni, aggiunge la base musicale e normalizza la loudness.

{
  "sequence": [
    {"id": "s1", "clip": "out/s1.mp4", "trim": "keep_first_portion"},
    {"id": "s2", "clip": "out/s2.mp4", "trim": "keep_first_portion"}
  ],
  "audioStrategy": "native_bed_plus_music"
}

Separare assemblaggio e generazione è ciò che rende riproducibile l'intera pipeline: puoi rigenerare un'inquadratura, inserirla nel manifest e rieseguire il rendering del montaggio finale senza toccare nient'altro.

Checklist di produzione e trappole comuni

Una pipeline per video brevi è affidabile quando le parti noiose diventano noiose. Esegui questi controlli prima di aumentare il volume di produzione.

Coerenza

• Il blocco di continuità è identico in ogni inquadratura di una sequenza.
• Il vocabolario delle inquadrature è chiuso e riusato, non improvvisato.
• La direzione della luce e la palette cromatica sono dichiarate una sola volta e non contraddette in seguito.
• Rivedi le inquadrature in ordine — i problemi di continuità non si vedono guardando le clip isolate.

Retry e idempotenza

• I risultati sono indicizzati per id dell'inquadratura, così la rigenerazione sovrascrive invece di duplicare.
• I retry sono limitati e con backoff; un'inquadratura permanentemente fallita deve fallire in modo rumoroso, non silenzioso.
• Il manifest delle inquadrature è l'unica fonte di verità su ciò che è stato generato — persiste insieme agli output.

Controllo dei costi

La generazione viene fatturata in base al lavoro prodotto dal modello, quindi la tua leva principale è quante inquadrature generi e quante volte le rigeneri. Controlli pratici: blocca la lista di inquadrature prima di generare, rivedi un'inquadratura rappresentativa di ogni sequenza prima di renderizzare le altre, ed evita rilanci speculativi di inquadrature già approvate. Quando pianifichi i volumi, consulta i prezzi correnti nel pannello prezzi del sito.

Revisione degli output

• Guarda ogni sequenza dall'inizio alla fine alla velocità di riproduzione reale, non clip per clip.
• Controlla l'audio rispetto all'immagine: il suono corrisponde a quel momento?
• Controlla in particolare i primi due secondi — è lì che un video breve conquista o perde l'attenzione.
• Mantieni un piccolo set di prompt di riferimento noti come validi e confronta i nuovi output quando la qualità sembra calare.

Trappole comuni

• Prompt giganti. Un prompt che descrive l'intera scena produce un'inquadratura lunga e fuori fuoco. Spezzalo.
• Scrivere la durata nella descrizione testuale. Esprimi i tempi in fase di montaggio, non nel testo del prompt.
• Movimento di camera casuale. Il movimento non specificato va alla deriva; specifica il movimento e sopprimi il resto.
• Trattare l'audio come una decisione di prodotto separata. Pianifica il suono nelle inquadrature, poi missalo nell'editor.

Il workflow di questa guida — pianificare le inquadrature, strutturare i prompt, controllare il movimento di camera, usare l'audio nativo, orchestrare con un manifest — trasforma flux-3-max/text-to-video da un generatore imprevedibile in un passo di rendering affidabile nella pipeline che possiedi.