Aggiungere testo ai video tramite API: flusso di lavoro per sottotitoli e sovrapposizioni

Perché il testo sui video è un problema di progettazione API, non solo di prompt

Aggiungere testo a un video generato sembra questione di modificare una riga di prompt: descrivi il sottotitolo, invii la richiesta, ottieni una clip con il testo. Ma in pratica, non appena hai bisogno che i sottotitoli siano leggibili, sincronizzati nel tempo, localizzabili o riutilizzabili tra scene, il prompt smette di essere la parte interessante. L'architettura lo è.

Ci sono due percorsi praticabili, che portano a codebase diverse:

• Testo nativo in fase di generazione. Chiedi al modello video di renderizzare il testo come parte della scena. Una richiesta, un asset, nessuna post-elaborazione.
• Materiale pulito più sovrapposizioni. Generi prima il materiale senza testo (o richiedi una composizione priva di testo), poi componi sottotitoli e sovrapposizioni in un secondo passaggio di rendering.

Perché non è solo una questione estetica? Perché tutto ciò che sta a valle dipende da questa scelta. Se il testo vive nei pixel generati, non puoi facilmente ridisegnarne lo stile, tradurlo, allinearlo nel tempo alla voce o correggere un refuso senza rigenerare la clip. Se il testo vive in una sovrapposizione separata, controlli layout, font e tempi, ma ora devi possedere un renderer e avere una richiesta in più nella pipeline.

Il resto di questa guida tratta il testo sui video per ciò che diventa tipicamente in produzione: un problema di dati (quale testo, dove, quando) più un problema di rendering (chi lo disegna). Una volta separati questi due aspetti, le chiamate API diventano dirette e puoi cambiare backend di generazione senza riscrivere la logica dei sottotitoli.

Un modello mentale utile è distinguere sempre tre cose: il contenuto (il testo stesso), la temporizzazione (quando appare) e la presentazione (font, posizione, stile). La generazione nativa comprime tutti e tre in un passaggio opaco. Le sovrapposizioni li mantengono tutti e tre espliciti e modificabili. Nessuna delle due è universalmente migliore; l'obiettivo è sapere a quale ti stai impegnando prima di scrivere l'integrazione.

Percorso uno: testo su schermo nativo tramite prompt in fase di generazione

Testo nativo significa che il modello di generazione disegna i caratteri nei frame del video. Ottieni un unico asset di output con il testo già incorporato e la pipeline resta breve: costruisci il prompt, invii, fai polling, consegni.

Cosa mettere nel prompt

La tipografia renderizzata dal modello è più imprevedibile del testo composto, quindi tratta il prompt come un'istruzione ristretta, non come il luogo in cui descrivere l'intero design system. Consigli pratici:

• Mantieni il testo breve. Poche parole per inquadratura. Le frasi lunghe favoriscono slittamenti ortografici e layout affollati.
• Racchiudi tra virgolette le stringhe letterali. Se il testo deve apparire esattamente, mettilo tra virgolette e richiedi quel testo esatto. Le descrizioni vaghe producono risultati vaghi.
• Specifica posizione e stile. "Testo bianco grande centrato nel terzo inferiore" è eseguibile. "Bel titolo" non lo è.
• Un elemento testuale per inquadratura. Chiedere titolo, sottotitolo e watermark nella stessa clip moltiplica i modi di fallire.
• Specifica la lingua. Se il testo non è in inglese, dichiaralo, perché la copertura dei glifi varia.

Cosa aspettarsi in risposta

Tratta l'output come una bozza, non come una specifica. Anche i buoni risultati possono presentare glifi deformati, spaziatura incoerente o occlusione parziale da parte del movimento. Ispeziona sempre i frame renderizzati prima di consegnare; un controllo programmatico economico più uno sguardo umano ai frame iniziali e finali contenenti testo cattura la maggior parte dei problemi.

Quando questo percorso vince

Il testo nativo è la scelta predefinita corretta quando il testo è incidentale e atmosferico: insegne su una strada di sfondo, un logo stilizzato su un prodotto, una breve card di titolo che sei disposto a rigenerare se sbaglia. Vince anche quando non puoi davvero permetterti un secondo passaggio di rendering, ad esempio in un flusso con scadenze strette in cui una richiesta per clip è il budget.

Il prezzo è il controllo. Qualsiasi modifica a formulazione, stile o tempi significa una nuova richiesta di generazione, e i risultati non sono deterministici tra i tentativi. Progetta prompt e archiviazione in modo che le clip rigenerate possano sostituire pulitamente le vecchie.

Percorso due: generare materiale pulito e comporre il testo da soli

Il percorso a sovrapposizioni divide il lavoro in due. Prima generi materiale deliberatamente privo di testo. Poi componi sottotitoli e sovrapposizioni sopra di esso, usando un servizio di rendering o la tua pipeline media.

Genera prima il materiale pulito

Richiedi una composizione senza testo: descrivi scena, soggetto, movimento di camera e luce, ed evita esplicitamente di chiedere testo su schermo. Se il modello tende a inventare insegne o testo UI, menziona che l'inquadratura dovrebbe contenere testo non leggibile. L'output qui è un asset di base — un input stabile che puoi riutilizzare attraverso molte varianti di testo.

Composizione successiva

Il passaggio di sovrapposizione consuma due input: l'asset di base e un payload strutturato di sottotitoli/sovrapposizioni. Poiché controlli il renderer, ottieni proprietà che il prompt non può garantire:

• Font e dimensioni determinati. Lo stesso payload renderizza in modo identico ogni volta, il che conta per la coerenza del brand.
• Temporizzazione precisa. I sottotitoli possono allinearsi al frame con voce, battiti musicali o cambi di scena.
• Zone sicure e regole di layout. Puoi imporre margini, evitare volti e soggetti chiave, e mantenere il testo dentro le zone sicure specifiche della piattaforma.
• Iterazione economica. Correggere un refuso o tradurre un sottotitolo significa ri-renderizzare la sovrapposizione, non rigenerare il video.
• Componibilità. Watermark, lower third e sottotitoli possono essere stratificati in modo indipendente e attivati o disattivati per output.

Compromessi

Il percorso a sovrapposizioni scambia dipendenza dal modello con complessità della pipeline. Aggiungi una seconda richiesta, hai bisogno di un posto dove archiviare gli asset intermedi e possiedi la configurazione di rendering. In cambio, il testo diventa dati che puoi versionare, testare e sostituire. Per qualsiasi cosa con esigenze reali di sottotitoli — accessibilità, varianti multilingua, formati social templateizzati — questo scambio vale quasi sempre la pena.

Un pattern pratico è renderizzare le sovrapposizioni in modo non distruttivo: l'asset di base e il payload dei sottotitoli sono l'unica fonte di verità, e il video composto è un artefatto derivato che puoi sempre rigenerare.

Progettare un payload di sottotitoli che sopravviva a entrambi i percorsi

Se progetti bene i dati dei sottotitoli, la scelta tra generazione nativa e sovrapposizioni diventa un dettaglio di rendering, non una riscrittura. L'obiettivo è un singolo payload che possa sia serializzarsi in un prompt per il testo nativo sia alimentare un renderer per le sovrapposizioni.

Campi principali

Modella ogni elemento testuale come un oggetto, mantenendo separati contenuto, temporizzazione e presentazione:

{
  "track": "captions",
  "items": [
    {
      "text": "Everything you need to know",
      "start": 0.0,
      "end": 2.4,
      "style": { "role": "title", "align": "center", "position": "lower_third" },
      "lang": "en"
    }
  ]
}

Decisioni di progettazione chiave:

• Tempi in secondi, come float. Usa una singola base temporale in tutto il progetto e converti in frame solo al momento del rendering.
• Stile per ruolo, non per valori assoluti. Dai nomi a ruoli come title, caption e lower_third, e risolvili in font e dimensioni nel renderer. Questo rende il payload portabile tra formati.
• Nomi delle tracce. Separa le tracce captions, titles e watermark così puoi abilitare o disabilitare tracce per output.
• Tag di lingua per ogni elemento. Sia la selezione dei font sia le eventuali pipeline di traduzione ne hanno bisogno.
• Nessuna informazione di presentazione incorporata nel campo testo. Non mettere mai suggerimenti di stile nel testo; a questo serve l'oggetto stile.

Alimentare entrambi i percorsi da un unico schema

Per la generazione nativa, scrivi un piccolo adattatore che selezioni gli elementi più importanti e li converta in istruzioni di prompt: il testo letterale, la sua posizione e un descrittore di stile. Fai in modo che questo adattatore sia volutamente lossy — il rendering nativo non può comunque seguire una traccia completa di sottotitoli.

Per le sovrapposizioni, passa il payload al renderer, che risolve ruoli e posizioni e lo disegna all'interno della finestra temporale di ogni elemento.

Il ritorno è questo: il codice della tua applicazione costruisce un oggetto sottotitoli, e passare da nativo a sovrapposizione (o tornare indietro per una clip specifica) è una modifica di configurazione, non una migrazione di dati.

Una richiesta di sovrapposizione funzionante, passo dopo passo

Ecco la sequenza del percorso a sovrapposizioni, espressa come passaggi in forma di API. I nomi esatti degli endpoint e i parametri dipendono dal provider, ma la forma è stabile e un sottile strato di astrazione la mantiene stabile tra backend.

Passo 1: inviare la generazione del materiale pulito

POST /video/generations
{
  "prompt": "A slow dolly shot through a modern office, no on-screen text, natural light",
  "duration_seconds": 6,
  "aspect_ratio": "16:9"
}

Mantieni il prompt privo di testo e archivia l'identificatore del job restituito.

Passo 2: fare polling finché il materiale non è pronto

GET /video/generations/{job_id}

Fai polling con backoff invece che con un ciclo serrato. Tratta stati come queued, running, succeeded e failed come stati di prima classe nel codice, e persisti l'URL o l'ID dell'asset risultante così un crash non perde il risultato della generazione.

Passo 3: inviare il rendering della sovrapposizione

POST /video/overlays
{
  "source_asset": "asset_abc123",
  "captions": {
    "track": "captions",
    "items": [
      { "text": "Shipping today", "start": 0.4, "end": 2.0, "style": { "role": "title", "position": "lower_third", "align": "center" }, "lang": "en" },
      { "text": "No rebuild required", "start": 2.2, "end": 4.0, "style": { "role": "title", "position": "lower_third", "align": "center" }, "lang": "en" }
    ]
  }
}

Nota che la richiesta di sovrapposizione porta solo l'asset di origine e i dati testuali. Non rigenera il materiale, ed è proprio questo che rende economica l'iterazione.

Passo 4: recuperare il risultato composto

Fai polling del job di sovrapposizione allo stesso modo dei job di generazione, poi recupera l'asset finale. Archivia insieme l'asset di base, il payload dei sottotitoli e l'output, così la composizione è riproducibile.

Nel codice, incapsula i passaggi 1–4 in una funzione che accetta un prompt e un payload di sottotitoli e restituisce l'asset finale. Quella funzione è la tua vera interfaccia; i singoli endpoint sono dettagli implementativi sostituibili.

Controlli di affidabilità prima della pubblicazione

Le pipeline di testo su video falliscono in modo silenzioso: sottotitoli tagliati, righe tradotte male, rigenerazioni che non vengono mai ripulite. Aggiungi controlli prima che gli utenti le vedano.

Validare il testo renderizzato

• Percorso nativo: campiona i frame all'inizio e alla fine di ogni finestra di testo e controllali. Automatizza il più possibile i controlli di leggibilità di base, ma mantieni un passaggio di revisione umana per il testo rivolto ai clienti, perché la tipografia del modello può degradarsi in modo imprevedibile.
• Percorso a sovrapposizioni: valida il payload prima del rendering — tempi non sovrapposti per ogni elemento, entro la durata della clip, con lingua e ruolo supportati. Dopo il rendering, controlla a campione i frame ai confini degli elementi per confermare che nulla sia stato tagliato.

Rendere i retry sicuri

• Chiavi di idempotenza sulle richieste di invio, così un retry di rete non crea job di generazione duplicati.
• Macchina a stati per ogni job: queued → running → succeeded/failed, persistita, così un riavvio recupera invece di ricominciare.
• Polling limitato, con backoff e timeout, che mostri un fallimento chiaro invece di un ciclo infinito.
• Archivia gli asset intermedi. Se il passaggio di sovrapposizione fallisce, non dovresti pagare per rigenerare materiale che hai già.

Controllare i costi dell'intera catena

Il percorso a sovrapposizioni ha due passaggi a pagamento — generazione e rendering — quindi monitora entrambi. Tieni traccia della frequenza con cui rigeneri il materiale rispetto a quando ri-renderizzi solo le sovrapposizioni; se la rigenerazione del materiale domina, la tua divisione nativo/sovrapposizione potrebbe non essere giusta per quel carico di lavoro. Metti in cache l'asset finale per (asset di base, payload dei sottotitoli), così le richieste ripetute per lo stesso output sono gratuite.

Osservabilità

Registra insieme prompt, hash del payload dei sottotitoli, ID dei job e ID dell'asset finale. Quando un utente segnala un errore nei sottotitoli, vuoi poter determinare in pochi secondi se il problema è nella generazione, nei dati o nel rendering. Tratta il payload dei sottotitoli come fonte di verità versionata, così puoi sempre spiegare cosa è stato chiesto al renderer di disegnare.

Scegliere il flusso di lavoro predefinito

Prendi questo come regola di partenza e rivedila man mano che il prodotto cresce.

Scegli il testo nativo quando il testo è decorativo o incidentale, la formulazione è breve, accetti la rigenerazione come modo per correggere errori e aggiungere un secondo passaggio di rendering non vale il tempo di engineering per quella clip.

Scegli il percorso a sovrapposizioni quando il testo deve essere preciso, temporizzato, tradotto, ridisegnato nello stile o riutilizzato su più output. Sottotitoli, didascalie, lower third e formati marketing templateizzati finiscono quasi sempre qui. La richiesta extra è il prezzo del determinismo.

Un approccio ibrido è ragionevole. Molti team generano materiale pulito per impostazione predefinita, si affidano alle sovrapposizioni per tutto ciò che conta e riservano il testo nativo a inquadrature atmosferiche usa e getta. Poiché entrambi i percorsi consumano lo stesso payload di sottotitoli, puoi prendere questa decisione per ogni clip senza trattare i tuoi dati in modo speciale.

Qualunque cosa tu scelga, mantieni l'integrazione dietro un'astrazione sottile: una funzione che accetta un prompt e un payload di sottotitoli e restituisce l'asset finale. Quel confine è ciò che ti permette di cambiare backend di generazione, aggiungere opzioni di rendering o spostare una singola clip tra flussi di lavoro senza toccare la logica dei sottotitoli che hai faticato a mettere a punto.