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
- 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:
480po720p, predefinito480p. - 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, predefinitoadaptive(il modello sceglie il rapporto in base al prompt). - output_format:
mp4(predefinito) omov. - 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
- 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.
- 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.
- 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.
- 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.
Articoli correlati
Vedi tutti gli articoli →-
Guida all'uso
Guida all'integrazione di Seedance 2.5 Flash per la generazione video da materiali di riferimento: immagini di riferimento, audio di riferimento e regole di fatturazione
-
Guida all'uso
Guida all'integrazione di Seedance 2.5 Flash per la generazione di video da immagini: primo frame, ultimo frame e fatturazione al secondo
Far muovere un'immagine: parametri, prezzi e cause comuni di errore
-
Guida all'uso
Guida introduttiva a kling-image-4.0: punti chiave per l'integrazione dell'API di generazione immagini e controllo dei costi
Decisioni di integrazione e checklist operativa per gli sviluppatori