HiAPI
Blog

Guida all'uso

Guida all'integrazione di Seedance 2.5 Flash text-to-video: parametri, tariffazione al secondo e pratica ingegneristica

Da una richiesta alla messa in produzione stabile: come impostare i parametri e come calcolare i costi

Nov 17, 2026
Su uno sfondo color carbone caldo, una larga fascia di luce ambrata attraversa in diagonale, con bordi netti e un insieme sobrio e ricco di spazio vuoto.
Modello
seedance-2.5-flash
In questa pagina

Cosa fa questo modello

seedance-2.5-flash/text-to-video è il modello text-to-video di ByteDance: riceve in input un prompt testuale e restituisce un video con audio sincronizzato. Ha un'unica modalità di input: non accetta immagini o video come input condizionale e non esegue comprensione video.

Gli scenari adatti sono quelli in cui serve «un piccolo video utilizzabile da una sola frase»: produzione in serie di materiali marketing, riprese di ambientazione e atmosfera per video prodotto, riempimento di segmenti per pool di contenuti, rapida anteprima di direzioni creative. Se il punto di partenza è un'immagine, è più diretto usare la pipeline image-to-video; se serve mantenere coerente il soggetto in base a materiale di riferimento, usare la pipeline guidata da materiale di riferimento.

Quali parametri contiene la richiesta

  • prompt (obbligatorio): scenario, soggetto, movimento della camera e azione. Lunghezza massima 5000 caratteri.
  • resolution: 480p o 720p, predefinito 480p.
  • duration: numero intero da 4 a 30, predefinito 5, in secondi.
  • aspect_ratio: 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive, predefinito adaptive (il modello sceglie il rapporto in base al prompt).
  • output_format: mp4 (predefinito) o mov.
  • generate_audio: predefinito true, genera dialoghi, effetti sonori e suoni di sottofondo sincronizzati con l'immagine.

Tranne prompt, tutti hanno un valore predefinito: la richiesta minima richiede solo prompt. Il corpo della richiesta viene validato in modo rigoroso: i campi non dichiarati inviati in più vengono rifiutati anziché scartati silenziosamente, così gli errori in fase di integrazione emergono al momento dell'invio e non dopo la tariffazione.

Come si calcola la tariffazione al secondo

Il criterio di tariffazione è «prezzo unitario al secondo × secondi di output», legato alla fascia di risoluzione:

  • 480p: $0,0679/secondo
  • 720p: $0,1525/secondo

I secondi di output corrispondono alla duration della richiesta, senza arrotondamenti imprevisti. Esempi: 480p per 5 secondi costa $0,3395, 720p per 5 secondi costa $0,7625; 480p per 30 secondi costa $2,037, 720p per 30 secondi costa $4,575. Raddoppiando la durata raddoppia il costo: non ci sono sconti «più è lungo, più conviene».

Ciò implica tre cose: primo, la stima del budget è una moltiplicazione, si fissa prima la durata di un singolo video e poi si moltiplica per il numero di video; secondo, un nuovo tentativo significa pagare di nuovo, quindi i retry in caso di fallimento devono avere un limite; terzo, i video lunghi non vanno generati in un'unica volta: conviene suddividerli in più segmenti brevi da generare separatamente e poi montare, il che fa risparmiare e limita il fallimento al solo segmento difettoso.

Modalità di integrazione: attività asincrona

La generazione video è un'attività dispendiosa in termini di tempo e l'interfaccia è asincrona: dopo l'invio si ottiene l'identificativo dell'attività, poi si esegue il polling o si attende la callback per ottenere il risultato, infine si scarica il prodotto e lo si salva nel database. Non incapsularla come RPC sincrona bloccante per la richiesta dell'utente.

  • Macchina a stati persistita: salvare nel database identificativo dell'attività, stato e parametri della richiesta; non tenerli solo in memoria del processo, perché perdere l'attività al riavvio significa aver speso soldi senza risultato.
  • Backoff del polling: intervallo iniziale breve, progressivamente più lungo con aggiunta di jitter, e timeout totale per ogni attività; allo scadere si passa al ramo di fallimento anziché fare polling infinito.
  • Classificazione degli errori: errori di parametri e violazioni di contenuto sono fallimenti deterministici, ritentare non ha senso; solo errori transitori come instabilità di rete e rate limiting meritano un retry con backoff.
  • Idempotenza: lato invio, usare una chiave univoca di business per evitare che clic ripetuti dell'utente generino più attività e una tariffazione duplicata.

Come scrivere i prompt in modo stabile

Scrivere secondo quattro sezioni — «soggetto → sequenza delle azioni → ambiente e luce → camera» — è molto più stabile che accumulare una serie di aggettivi.

soggetto: un gatto bianco seduto sul davanzale, in controluce
azioni: da fermo ad alzare la testa verso la finestra, coda che oscilla lentamente
ambiente e luce: luce calda del pomeriggio, profondità di campo ridotta, atmosfera silenziosa in interni
camera: piano medio, camera fissa, leggero effetto a mano libera

Tre regole: un prompt descrive un solo piano sequenza, non inserire cambi di scena multipli in un'unica generazione; versionare i prompt modificando una sola variabile alla volta, così si capisce quale modifica ha fatto la differenza; prima il campione, poi il batch, non usare il batch per validare un prompt ancora indefinito.

Il formato dell'immagine e il linguaggio della camera si descrivono in linguaggio naturale: il modello non ha un parametro separato per il «movimento di camera», scriverlo nel prompt è più affidabile che aspettarsi un campo inesistente.

Percorso di messa in produzione

  1. Far funzionare la pipeline: tre prompt che coprono gli scenari tipici, verificare che invio, polling e download funzionino tutti, senza guardare ancora la qualità del risultato.
  2. Definire prompt e durata: fissare un piccolo numero di prompt, confrontare i risultati con diverse formulazioni e diverse durate, registrare il costo di ciascuno, formare una libreria di template riutilizzabili.
  3. Rilascio graduale: aumentare il volume in proporzione, osservare tasso di successo, tempo medio, tasso di retry e curva dei costi; aumentare solo quando i tre indicatori sono a target.
  4. Operatività ordinaria: revisionare periodicamente la libreria di template, eliminare le formulazioni inefficienti, monitorare l'andamento dei costi e le soglie di retry.

Sulla pagina del modello sono disponibili le descrizioni più recenti dei parametri e i prezzi: basta verificarli una volta prima dell'integrazione.

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