API di Riferimento Seedance 2.0: Video Multi-Modale Programmatico

L'accesso programmatico a video AI multi-modali cambia ciò che è possibile. I clip singoli sono ottimi per il marketing e la creazione di contenuti, ma i flussi di lavoro automatizzati - generazione video di cataloghi, personalizzazione per utente, operazioni batch - richiedono accesso API.

L'API Reference di Seedance 2.0 espone l'intera capacità multi-modale: fino a 9 immagini, 3 video e 3 clip audio per richiesta, in modo programmatico, allo stesso prezzo al secondo dell'interfaccia web.

Quando usare l'API

L'interfaccia web è ottima per il lavoro creativo manuale, uno alla volta. L'API è per tutto il resto.

L'API è adatta quando hai bisogno di:

• Generazione batch su centinaia di asset
• Integrazione con pipeline di contenuti o prodotti esistenti
• Video personalizzati per utente in un'applicazione
• Test A/B automatico di varianti creative pubblicitarie
• Generazione di contenuti programmata per la pubblicazione giornaliera
• Flussi di lavoro di catalogazione collegati a record di database

Usa l'interfaccia web quando:

• Stai iterando creativamente e hai bisogno di vedere/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

Questo è l'unico endpoint di cui hai bisogno per le generazioni in modalità Reference multi-modale. 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 da testo a video o a singola immagine, usa invece gli endpoint API standard Seedance 2.0.

Struttura della Richiesta

Una tipica richiesta Reference-to-video include:

• prompt: Descrizione testuale di soggetto e azione (obbligatoria)
• reference_images: Array di fino a 9 URL di immagini o riferimenti di file
• reference_videos: Array di fino a 3 URL di video (opzionale)
• reference_audio: Array di fino a 3 URL audio (opzionale)
• duration: Durata dell'output in secondi, 4-15 (obbligatoria)
• aspect_ratio: Una di 16:9, 9:16, 1:1 (obbligatoria)

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

Prezzi Tramite l'API

I prezzi dell'API corrispondono esattamente ai prezzi dell'interfaccia web:

Non c'è nessuna tassa di accesso API e nessun addebito aggiuntivo per i caricamenti di riferimento. Paghi solo per i secondi di output generati.

I crediti funzionano allo stesso modo su API e interfaccia web. Ricarica tramite pagina dei prezzi e lo stesso pool di crediti viene utilizzato da entrambe le interfacce. Per l'uso API ad alto volume, il tier Max $100 (12.000 crediti) è il punto di partenza più economico.

Inizia a costruire con l'API. Accedi all'API con 50 crediti gratuiti alla registrazione. Inizia gratuitamente.

Esempi di Casi d'Uso

Automazione Video di Catalogo

Per piattaforme di ecommerce con centinaia o migliaia di SKU, l'API ti permette di generare un breve video di prodotto per ogni prodotto in base alle immagini di prodotto esistenti.

Flusso di lavoro:

1. Interroga il tuo database di prodotti
2. Per ogni prodotto, recupera 5-7 immagini di prodotto
3. Combina con un bundle di riferimento a livello di brand (2-3 immagini)
4. Chiama l'API con il modello di prompt per la rivelazione del prodotto
5. Archivia l'URL del video restituito nel record del prodotto
6. Servilo sulle pagine dei dettagli del prodotto

Economia: Catalogo da 500 SKU a video di 5 secondi = 500 × 303 crediti = 151.500 crediti = ~$1.515. Per un rollout video a livello di catalogo, è un valore straordinario.

Generazione di Video Personalizzati

Per app che forniscono video personalizzati per utente - biglietti di auguri, contenuti di celebrazione, intro di onboarding - l'API ti permette di generare video on-demand con riferimenti specifici dell'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 di stile
3. La chiamata API genera un clip video personalizzato
4. Forniscilo all'utente tramite la tua app

Questo si scala a decine di migliaia di utenti senza sovraccarico del team di contenuti.

Generazione di Varianti Creative Pubblicitarie

I team di marketing che gestiscono campagne su social a pagamento hanno bisogno di costanti varianti creative. L'API ti permette di generare varianti di test A/B in modo programmatico.

Flusso di lavoro:

1. Definisci un bundle di riferimento del brand (6-8 immagini)
2. Scrivi modelli di prompt per diversi angoli pubblicitari
3. Scorre le varianti, chiama l'API per ognuna
4. Fornisci i clip generati alla tua piattaforma pubblicitaria
5. Traccia le prestazioni e genera vincitori su scala

Puoi produrre 50 varianti pubblicitarie in un'esecuzione automatizzata per ~$150 di costi API, rispetto alla produzione tradizionale a migliaia per variante.

Gestione della Risposta

Le risposte API tipicamente includono:

• ID di generazione: Traccia lo stato della richiesta
• Stato: pending, processing, complete, failed
• URL di output: Disponibile una volta che lo stato è completo
• Metadati: Durata, risoluzione, dimensione del file

Le generazioni in modalità Reference richiedono 60-180 secondi, quindi la tua integrazione dovrebbe gestire risposte asincrone. Verifica lo stato dell'endpoint di stato o usa webhook (se disponibili nel tuo account) per ricevere notifiche al completamento.

Non bloccare i flussi rivolti all'utente sul completamento della generazione. Metti in coda la richiesta, notifica l'utente quando è pronta e forniscila in modo asincrono.

Rate Limits e Concorrenza

Per la maggior parte dei tier di account, si applicano limiti di generazione concorrente. Pianifica i tuoi flussi di lavoro batch per rispettare i limiti - metti in coda le richieste ed elaborale alla concorrenza consentita.

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

Autenticazione e Chiavi

L'accesso API utilizza l'autenticazione standard basata su chiave. Genera la tua chiave API nelle impostazioni del tuo account dopo la registrazione. Mantieni le chiavi solo lato server - non esporle mai nel codice client.

Idempotenza e Retry

Le generazioni API non sono nativamente idempotenti perché ogni chiamata costa crediti. Se una generazione fallisce a metà processo, la logica di retry dovrebbe controllare lo stato della generazione fallita prima di fare una nuova richiesta. Una generazione fallita tipicamente non consuma crediti, ma verifica sempre nel tuo dashboard dell'account.

Per flussi di lavoro di produzione, implementa:

• Logica di retry con backoff esponenziale su fallimenti transienti
• Polling dello stato o gestione webhook per il completamento asincrono
• Registrazione degli errori per catturare problemi sistematici
• Monitoraggio del saldo di crediti per avvisare prima di finire

Best Practice per Flussi di Lavoro Programmatici

1. Usa bundle di riferimento coerenti. Per il lavoro di catalogo o serie, cripta i tuoi bundle di riferimento in modo che bundle identici tra le richieste producano uno stile più coerente.

2. Mantieni i modelli di prompt semplici. I prompt programmatici dovrebbero essere generati da dati strutturati, non scritti a mano per ogni chiamata. Il pattern Modello + campi dati è quello giusto.

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

4. Gestisci la sicurezza dei contenuti appropriatamente. La piattaforma ha filtri di sicurezza dei contenuti. Costruisci la gestione elegante per le richieste rifiutate dal filtro nel tuo flusso di lavoro.

5. Registra i metadati di generazione. Traccia ogni generazione - prompt, set di riferimento, durata, crediti consumati, URL di output - nel tuo database dell'applicazione. Questo rende il debug e il reporting molto più facili.

Esempio di Flusso di Lavoro Batch

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

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 di follow-up gestisce il completamento e archivia l'URL di output nel record del prodotto.

Monitoraggio e Controllo dei Costi

Per l'uso API di produzione, configura il monitoraggio dei costi:

• Avvisi di budget giornalieri: Avvisa quando la spesa API giornaliera supera una soglia
• Limiti per flusso di lavoro: Limita i lavori batch a una spesa di crediti massima per prevenire automazione incontrollata
• Dashboard di utilizzo: Traccia quali flussi di lavoro consumano più crediti
• Avvisi di saldo di crediti: Ricarica prima di finire

Questi presidi impediscono sorprese quando scale l'automazione.

Parità di Prezzi API vs Interfaccia Web

Una domanda comune: c'è uno sconto per l'uso dell'API? No - API e interfaccia web addebitano entrambe gli stessi $0.3024 al secondo. L'API è prezzata per il lavoro che fa, non per l'interfaccia che usi.

Dove gli utenti ad alto volume risparmiano è nella loro selezione di tier. Gli utenti API ad alto volume dovrebbero eseguire sul Livello massimo $100 per il miglior valore per dollaro.

Inizia con l'API

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

La prima chiamata API può essere live entro un'ora dalla registrazione per la maggior parte delle integrazioni.

Letture Successive

Per l'intero set di funzionalità Reference, leggi Guida completa Seedance 2.0 Reference. Per il flusso di lavoro dell'interfaccia web, vedi tutorial coerente nello stile. Per i dettagli API standard di Seedance 2.0, controlla Guida API Seedance 2.0.

Il video multi-modale programmatico è qui. Costruisci qualcosa di nuovo con esso.