Seedance 2.0 Reference API: video multi-modale programmatico

L'accesso programmatico all'AI video multimodale cambia ciò che è possibile. I clip singoli vanno benissimo per il marketing e la creazione di contenuti, ma i flussi di lavoro automatizzati come la generazione di video per catalogo, la personalizzazione per utente e le operazioni batch sui contenuti richiedono accesso API.

La Reference API di Seedance 2.0 espone l'intera capacità multimodale: fino a 9 immagini, 3 video e 3 clip audio per richiesta, in modo programmatico, con la stessa tariffazione al secondo dell'interfaccia web.

Quando ricorrere all'API

La web UI è perfetta per il lavoro creativo manuale, un clip alla volta. L'API è per tutto il resto.

L'API è la scelta giusta quando hai bisogno di:

• Generazione batch su centinaia di asset
• Integrazione con pipeline di contenuti o prodotti già esistenti
• Video personalizzati per utente all'interno di un'applicazione
• Test A/B automatizzati di varianti creative per gli annunci
• Generazione di contenuti programmata per la pubblicazione quotidiana
• Flussi di lavoro per la catalogazione collegati a record di database

Resta sulla web UI quando:

• Stai iterando creativamente e hai bisogno di vedere e modificare ogni output
• Il volume è basso (meno di 10-20 clip per sessione)
• Stai esplorando lo strumento per la prima volta

L'endpoint

L'endpoint Reference-to-video è:

bytedance/seedance-2.0/reference-to-video

È l'unico endpoint necessario per le generazioni in modalità Reference multimodale. Una singola richiesta gestisce testo, fino a 9 immagini, fino a 3 video e fino a 3 clip audio. Il modello fonde tutti gli input e restituisce un video generato.

Per flussi di lavoro text-to-video o con singola immagine, usa invece gli endpoint API standard di Seedance 2.0.

Struttura della richiesta

Una tipica richiesta Reference-to-video include:

• prompt: descrizione testuale del soggetto e dell'azione (obbligatorio)
• reference_images: array di fino a 9 URL di immagini o riferimenti a file
• reference_videos: array di fino a 3 URL di video (facoltativo)
• reference_audio: array di fino a 3 URL di file audio (facoltativo)
• duration: durata dell'output in secondi, da 4 a 15 (obbligatorio)
• aspect_ratio: uno tra 16:9, 9:16, 1:1 (obbligatorio)

I file di input possono essere forniti come URL (accessibili pubblicamente) o caricati direttamente, a seconda del tuo pattern di integrazione.

Prezzi tramite API

I prezzi dell'API corrispondono esattamente a quelli della web UI:

Non è prevista nessuna quota di accesso all'API né alcun costo aggiuntivo per i caricamenti di riferimento. Paghi solo per i secondi di output generati.

I crediti funzionano allo stesso modo sia tramite API che tramite web UI. Ricarica tramite pagina dei prezzi e lo stesso pool di crediti viene utilizzato da entrambe le interfacce. Per un utilizzo API ad alto volume, il piano Studio da $120 (1.800 crediti al mese) offre il miglior rapporto credito-prezzo, e le ricariche aggiuntive non scadono mai.

Inizia a sviluppare con l'API. Ottieni l'accesso all'API con 10 crediti gratuiti alla registrazione. Inizia gratis.

Esempi di utilizzo

Automazione dei video per catalogo

Per le piattaforme di e-commerce con centinaia o migliaia di SKU, l'API consente di generare un breve video di prodotto per ogni articolo a partire dalle immagini di prodotto esistenti.

Flusso di lavoro:

1. Interroga il tuo database di prodotti
2. Per ogni prodotto, recupera 5-7 immagini
3. Combinale con un bundle di riferimento del brand (2-3 immagini)
4. Chiama l'API con un template di prompt per il lancio del prodotto
5. Salva l'URL del video restituito nel record del prodotto
6. Mostralo nelle pagine di dettaglio prodotto

Economia: un catalogo di 500 SKU con video da 5 secondi equivale a 500 × 303 crediti = 151.500 crediti = ~$1.515. Per un rollout video sull'intero catalogo, si tratta di un valore straordinario.

Generazione di video personalizzati

Per le app che offrono video personalizzati per utente, come biglietti di auguri, contenuti celebrativi o introduzioni all'onboarding, l'API consente di generare video on-demand con riferimenti specifici per ogni utente.

Flusso di lavoro:

1. L'utente carica 3-5 foto personali (con consenso)
2. La tua app le combina con un bundle di riferimento stilistico
3. La chiamata API genera un clip video personalizzato
4. Il clip viene consegnato all'utente tramite la tua app

Questo approccio scala fino a decine di migliaia di utenti senza bisogno di un team di contenuti.

Generazione di varianti creative per gli annunci

I team di marketing che gestiscono campagne social a pagamento hanno costantemente bisogno di varianti creative. L'API consente di generare varianti per test A/B in modo programmatico.

Flusso di lavoro:

1. Definisci un bundle di riferimento del brand (6-8 immagini)
2. Scrivi template di prompt per diversi angoli pubblicitari
3. Itera tra le varianti, chiamando l'API per ciascuna
4. Consegna i clip generati alla tua piattaforma pubblicitaria
5. Monitora le performance e scala i vincitori

Con un'esecuzione automatizzata puoi produrre 50 varianti pubblicitarie a un costo API di circa $150, rispetto alla produzione tradizionale che costa migliaia di dollari per variante.

Gestione delle risposte

Le risposte dell'API includono tipicamente:

• ID generazione: per monitorare lo stato della richiesta
• Stato: pending, processing, complete, failed
• URL di output: disponibile una volta che lo stato è complete
• Metadati: durata, risoluzione, dimensione del file

Le generazioni in modalità Reference richiedono 60-180 secondi, quindi la tua integrazione deve gestire risposte asincrone. Esegui il polling dell'endpoint di stato o usa i webhook (se disponibili nel tuo account) per ricevere una notifica al completamento.

Non bloccare i flussi visibili all'utente in attesa del completamento della generazione. Metti la richiesta in coda, avvisa l'utente quando è pronta e consegna in modo asincrono.

Limiti di velocità e concorrenza

Per la maggior parte dei livelli di account si applicano limiti di generazione concorrente. Pianifica i tuoi flussi di lavoro batch in modo da rispettare i limiti: metti le richieste in coda ed elaborale alla concorrenza consentita.

Per flussi di lavoro in produzione ad alto volume, contatta il supporto della piattaforma riguardo ai limiti di concorrenza enterprise. La maggior parte degli account standard può gestire lavori batch moderati (10-30 generazioni concorrenti) senza problemi.

Autenticazione e chiavi

L'accesso all'API utilizza l'autenticazione standard basata su chiave. Genera la tua chiave API nelle impostazioni dell'account dopo la registrazione. Conserva le chiavi solo lato server: non esporle mai nel codice client.

Idempotenza e nuovi tentativi

Le generazioni API non sono nativamente idempotenti perché ogni chiamata consuma crediti. Se una generazione fallisce a metà processo, la logica di retry deve verificare lo stato della generazione fallita prima di effettuare una nuova richiesta. In genere una generazione fallita non consuma crediti, ma verifica sempre nel pannello del tuo account.

Per i flussi di lavoro in produzione, implementa:

• Logica di retry con backoff esponenziale per i guasti transitori
• Polling dello stato o gestione dei webhook per il completamento asincrono
• Logging degli errori per individuare problemi sistematici
• Monitoraggio del saldo crediti per ricevere un avviso prima di esaurirli

Best practice per i flussi di lavoro programmatici

1. Usa bundle di riferimento coerenti. Per lavori su cataloghi o serie, calcola l'hash dei tuoi bundle di riferimento in modo che bundle identici tra richieste diverse producano uno stile più consistente.

2. Mantieni i template di prompt semplici. I prompt programmatici devono essere generati a partire da dati strutturati, non scritti a mano per ogni chiamata. Il pattern corretto è: template + campi dati.

3. Memorizza nella cache gli URL dei file di riferimento. Se usi riferimenti basati su URL, assicurati che siano stabili e accessibili. URL S3 scaduti o file spostati faranno fallire le generazioni.

4. Gestisci in modo appropriato la sicurezza dei contenuti. La piattaforma dispone di filtri per la sicurezza dei contenuti. Integra nel tuo flusso di lavoro una gestione elegante per le richieste rifiutate dai filtri.

5. Registra i metadati delle generazioni. Traccia ogni generazione, inclusi prompt, set di riferimento, durata, crediti consumati e URL di output, nel database della tua applicazione. Questo semplifica notevolmente il debug e la reportistica.

Esempio di flusso di lavoro batch

Pseudocodice per un flusso di lavoro di generazione batch di video di prodotto:

for product in product_catalog:
    references = build_reference_bundle(
        brand_images,
        product.photo_urls[:4]
    )
    prompt = f"{product.name} product rotates slowly on a clean surface, soft studio lighting, 5 seconds"

    response = seedance_api.generate(
        endpoint="bytedance/seedance-2.0/reference-to-video",
        prompt=prompt,
        reference_images=references,
        duration=5,
        aspect_ratio="16:9"
    )

    generation_id = response.id
    queue_poll_task(generation_id, product.id)

Un poller successivo gestisce il completamento e salva l'URL di output nel record del prodotto.

Monitoraggio e controllo dei costi

Per l'utilizzo dell'API in produzione, configura il monitoraggio dei costi:

• Avvisi sul budget giornaliero: notifica quando la spesa API giornaliera supera una soglia
• Limiti per flusso di lavoro: limita i job batch a una spesa massima in crediti per evitare automazioni fuori controllo
• Dashboard di utilizzo: monitora quali flussi di lavoro consumano più crediti
• Avvisi sul saldo crediti: ricarica prima di esaurirli

Queste protezioni evitano sorprese quando si scala l'automazione.

Parità di prezzo tra API e web UI

Una domanda comune: esiste uno sconto per l'utilizzo dell'API? No: sia l'API che la web UI applicano la stessa tariffa di $0.3024 al secondo. L'API è prezzata in base al lavoro che svolge, non all'interfaccia che si utilizza.

Il risparmio per gli utenti ad alto volume deriva dalla scelta del piano. Chi fa un uso intenso dell'API dovrebbe operare sul $120 piano Studio per ottenere il miglior rapporto qualità-prezzo.

Come iniziare con l'API

1. Registrati su arteza.ai (10 crediti gratuiti)
2. Genera la tua chiave API nelle impostazioni dell'account
3. Ricarica un pacchetto di crediti adeguato al volume previsto
4. Integra l'endpoint nella tua applicazione
5. Inizia con piccoli batch di test per validare il flusso di lavoro
6. Scala in produzione una volta completati i test

Per la maggior parte delle integrazioni, la prima chiamata API può essere attiva entro un'ora dalla registrazione.

Letture consigliate

Per il set completo di funzionalità Reference, leggi Guida completa a Seedance 2.0 Reference. Per il flusso di lavoro tramite web UI, consulta tutorial sullo stile coerente. Per i dettagli standard dell'API di Seedance 2.0, vedi Guida all'API di Seedance 2.0.

Il video multimodale programmatico è qui. Costruisci qualcosa di nuovo con esso.