Skip to main content
Questo documento presenterà un’istruzione per l’integrazione dell’API di generazione video SeeDance, che consente di generare video ufficiali di SeeDance inserendo parametri personalizzati.

​
Processo di Richiesta

Per utilizzare l’API di generazione video SeeDance, prima di tutto vai al Pannello di Controllo di Ace Data Cloud per ottenere il tuo API Token, da conservare per uso futuro. Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente. Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza dover richiedere separatamente per ogni servizio. La prima richiesta offre un credito gratuito, per un’esperienza senza costi; se il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.
📘 Documentazione Completa: SeeDance Videos Generation API →

​
Uso di Base

Iniziamo a comprendere il modo di utilizzo di base, che consiste nell’inserire la parola chiave content.text, il tipo content.type=text e il modello model, per ottenere il risultato elaborato, i dettagli sono i seguenti:

Possiamo vedere che qui abbiamo impostato le intestazioni della richiesta, tra cui:
  • accept: il formato della risposta desiderata, qui indicato come application/json, ovvero formato JSON.
  • authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.
Inoltre, abbiamo impostato il corpo della richiesta, che include:
  • model: il modello per generare il video.
    • Serie Seedance 1.x: doubao-seedance-1-0-pro-250528, doubao-seedance-1-0-pro-fast-251015, doubao-seedance-1-5-pro-251215, doubao-seedance-1-0-lite-t2v-250428, doubao-seedance-1-0-lite-i2v-250428.
    • Serie Seedance 2.0 (supporta riferimenti multimodali audio e video): doubao-seedance-2-0-260128 (standard), doubao-seedance-2-0-fast-260128 (veloce), doubao-seedance-2-0-mini-260615 (leggero).
    • Seedance 2.5: doubao-seedance-2-5-260628, supporta fino a 30 secondi, riferimenti audio puri, più materiali, editing video e prolungamento.
  • content: array di contenuti in input, type può essere text (parola chiave), image_url (immagine di riferimento), audio_url (audio di riferimento), video_url (video di riferimento). Le immagini possono essere specificate tramite role: first_frame (primo fotogramma) / last_frame (ultimo fotogramma) / reference_image (riferimento per personaggio / soggetto).
  • resolution: risoluzione di output, opzioni 480p / 720p / 1080p / 4k. 2.5 supporta 480p, 720p, 1080p; 2.0 Fast/Mini supporta 480p, 720p; 2.0 Standard supporta fino a 4k.
  • ratio: rapporto d’aspetto, opzioni 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
  • duration: durata del video (secondi, intero). Serie 1.0 2–12; 1.5 Pro 4–12; serie 2.0 4–15; 2.5 da 4 a 30. 1.5/2.x supporta -1 (durata automatica).
  • seed: seme casuale, intero, da -1 a 4294967295.
  • camerafixed: se la telecamera è fissa, true / false.
  • watermark: se aggiungere un watermark, true / false.
  • generate_audio: se generare un video con audio, true / false, supportato da Seedance 1.5 Pro e serie 2.x.
  • return_last_frame: se restituire l’URL dell’ultima immagine del video nei risultati.
  • omni_reference_task_type: solo 2.5; auto / reference / edit / extend.
  • output_format: solo 2.5; mp4 / mov, predefinito mp4.
  • tools: solo 2.5; attualmente supporta web_search come strumento di ricerca online, può limitare il numero di risultati, il numero di parole chiave e le fonti di ricerca.
  • priority: 2.5 opzioni di priorità del compito, intero 0–9, predefinito 0.
  • safety_identifier: identificatore utente finale anonimo stabile lungo massimo 64 caratteri; utilizzare hash o ID anonimi interni, non inserire nome, email o numero di telefono.
  • execution_expires_after: tempo di scadenza del compito (secondi), intervallo 3600–259200.
  • callback_url: indirizzo di callback asincrono, una volta impostato l’API restituisce immediatamente task_id, e quando il compito è completato, invierà i risultati a questo indirizzo.
  • async: opzionale, impostato su true l’interfaccia restituisce immediatamente task_id, senza necessità di fornire callback_url, successivamente è possibile ottenere i risultati tramite l’interfaccia di query del compito corrispondente.
Dopo aver selezionato, puoi notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Prova” puoi effettuare un test, come mostrato nell’immagine sopra, qui abbiamo ottenuto il seguente risultato:
Il risultato restituito ha diversi campi, descritti come segue:
  • success, stato attuale del compito di generazione video.
  • task_id, ID del compito di generazione video attuale.
  • trace_id, ID di tracciamento della generazione video attuale.
  • data, elenco dei risultati del compito di generazione video attuale.
    • task_id, ID del compito di generazione video sul server.
    • video_url, link al video generato dal compito di generazione video attuale.
    • status, stato attuale del compito di generazione video.
      • model, modello utilizzato per generare il video.
Possiamo vedere che abbiamo ottenuto informazioni soddisfacenti sul video, dobbiamo solo ottenere il video SeeDance generato dall’indirizzo del link video in data del risultato. Inoltre, se desideri generare il codice di integrazione corrispondente, puoi semplicemente copiarlo, ad esempio il codice CURL è il seguente:

​
Descrizione dei parametri inline

Alla fine del prompt content[].text, è possibile passare i parametri di generazione aggiungendo --parameter value (metodo obsoleto, verifica debole, in caso di errore verranno utilizzati valori predefiniti). L’elenco completo dei parametri è il seguente:
Pratica consigliata: utilizzare direttamente i campi di livello superiore corrispondenti (come resolution, ratio, ecc.) nel corpo della richiesta, per una modalità di verifica forte; in caso di errore nei parametri, verrà restituito un messaggio di errore chiaro, facilitando la risoluzione dei problemi.

​
Generazione di video con audio

Seedance 1.5 Pro e la serie 2.x supportano la generazione di video con audio tramite il parametro generate_audio:
La serie 1.0 non supporta questo parametro.

​
Generazione, modifica e prolungamento multimodale di Seedance 2.5

doubao-seedance-2-5-260628 supporta 480p / 720p / 1080p, durata da 4 a 30 secondi o automatica, e aumenta il limite di materiali a 30 immagini di riferimento, 10 video di riferimento, 10 audio di riferimento (massimo 50 in totale). La 2.5 supporta anche l’invio solo di audio di riferimento, senza richiedere immagini o video contemporaneamente. La generazione multimodale normale può omettere omni_reference_task_type, impostandolo su auto, o esplicitamente su reference. La modifica e il prolungamento video devono includere reference_video:
  • reference: deve essere fornita almeno un’immagine di riferimento, un video di riferimento o un audio di riferimento; la 2.5 supporta solo audio di riferimento.
  • edit: deve utilizzare ratio: adaptive e duration: -1; la durata di output viene addebitata in base al risultato effettivo.
  • extend: deve utilizzare ratio: adaptive; duration può essere 4–30 o -1.
  • auto: il modello seleziona automaticamente generazione, modifica o prolungamento in base al prompt e ai materiali.
  • Se il tipo di attività non corrisponde ai materiali o al prompt, l’attività fallirà e restituirà un errore di parametro localizzabile; si prega di regolare secondo le restrizioni sopra e ripresentare.

​
Generazione di video da immagini per il primo fotogramma

Se si desidera generare un video da immagini, prima il parametro content deve contenere un elemento di tipo image_url, il campo image_url deve essere in formato oggetto: {"url": "https://..."} o in formato Base64 {"url": "data:image/png;base64,..."}.
Nota: image_url non supporta l’inserimento diretto in formato stringa (come "image_url": "https://cdn.acedata.cloud/e724d7f13d.png"), deve essere utilizzato in formato oggetto "image_url": {"url": "https://..."}, altrimenti verrà restituito un errore 400.
Codice corrispondente:
Cliccando su esegui, si può notare che si ottiene immediatamente un risultato, come segue:
Si può vedere che l’effetto generato è quello di un video creato da immagini, il risultato è simile a quanto descritto sopra.

​
Generazione di video da immagini per il primo e l’ultimo fotogramma

Se si desidera generare video da immagini per il primo e l’ultimo fotogramma, prima il parametro content deve includere il tipo image_url, e impostare rispettivamente role su first_frame e last_frame, in modo da specificare il contenuto seguente:
  • role: specifica il primo fotogramma o l’ultimo fotogramma.
  • image_url
    • url link all’immagine Inoltre, content deve anche includere un tipo text come prompt.
Cliccando su Esegui, si può notare che si ottiene immediatamente un risultato, come segue:
Si può vedere che l’effetto generato è un video generato dal personaggio, il risultato è simile a quanto sopra.

​
Riferimenti multimodali per personaggi e audio-video (Seedance 2.0)

La serie Seedance 2.0 (doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128, doubao-seedance-2-0-mini-260615) supporta reference_image, reference_audio e reference_video. È possibile utilizzare materiali propri o autorizzati per mantenere la coerenza tra personaggi, soggetti, azioni, movimenti della camera, suoni e ritmi.
Si prega di caricare solo materiali di persone reali e personaggi di proprietà o autorizzati. I diversi modelli supportano i materiali reali in modi diversi; il formato della richiesta rimane invariato, se i materiali non soddisfano i requisiti verrà restituito un errore chiaro.
Punti chiave da utilizzare:
  • Solo i modelli della serie Seedance 2.0 supportano reference_image; i modelli 1.x devono utilizzare first_frame / last_frame (frame iniziali e finali del video generato).
  • I frame iniziali del video generato, i frame iniziali e finali del video generato e i riferimenti multimodali sono tre scenari mutuamente esclusivi: first_frame / last_frame non possono essere mescolati con reference_image / reference_video / reference_audio.
  • Se si desidera specificare i frame iniziali e finali nel riferimento multimodale, si prega di contrassegnare l’immagine come reference_image e di indicare nei suggerimenti “immagine 1 come frame iniziale” o “immagine 2 come frame finale”; se è necessario bloccare rigorosamente i frame iniziali e finali, utilizzare solo first_frame / last_frame.
  • Limite massimo per il numero di riferimenti multimodali: image_url massimo 9 immagini; la 2.0 supporta anche audio_url (role è reference_audio, massimo 3) e video_url (role è reference_video, massimo 3).
  • Requisiti per i materiali audio di riferimento (audio_url): formato wav / mp3; durata singola 2~15 secondi, massimo 3 e durata totale non superiore a 15 secondi; singolo non superiore a 15 MB. Superare il limite di durata comporterà un errore nella fase di elaborazione dei materiali.
  • Requisiti per i materiali video di riferimento (video_url): formato mp4 / mov; durata singola 2~15 secondi, massimo 3 e durata totale non superiore a 15 secondi.
  • Si consiglia di utilizzare immagini di riferimento di una sola persona, di fronte, chiare e senza ostacoli, più il volto è chiaro, maggiore è la somiglianza.

​
Esempio 1: primo piano mantenendo l’aspetto del personaggio

Invia una foto del volto di una persona, facendo in modo che quella persona sorrida e saluti verso la telecamera. Il codice corrispondente:
Il risultato restituito è il seguente, il video generato mantiene la coerenza con la foto di riferimento:

​
Esempio 2: mettere la stessa persona in una nuova scena

La potenza di reference_image sta nel fatto che: mantiene solo l’identità del personaggio, mentre la scena, i vestiti e le azioni sono completamente determinati dai suggerimenti. Qui utilizziamo la stessa foto del volto, facendo indossare a quella persona un cappotto beige mentre cammina in un parco autunnale:
Il risultato restituito è il seguente, l’aspetto del personaggio è mantenuto, mentre la scena è cambiata in un parco autunnale:
💡 Se desideri che i personaggi riproducano con precisione la composizione della foto (anziché “la stessa persona in un’altra scena”), puoi utilizzare first_frame (il primo fotogramma del video), per far partire il video da questa foto.

​
Callback asincrona

Poiché il tempo di generazione dell’API SeeDance Videos Generation è piuttosto lungo (circa 1-2 minuti), puoi utilizzare il campo callback_url per attivare la modalità asincrona, evitando che la connessione HTTP rimanga occupata a lungo. Flusso generale: quando il client invia la richiesta specificando callback_url, l’API restituisce immediatamente una risposta contenente task_id; una volta completato il compito, la piattaforma invierà i risultati generati in formato JSON POST a callback_url, i risultati conterranno anche task_id per facilitare l’associazione.
Quando il compito è completato, il contenuto inviato dalla piattaforma a callback_url è il seguente:
Il campo task_id nei risultati è lo stesso di quello restituito nella richiesta, tramite questo campo è possibile realizzare l’associazione del compito.

​
Gestione degli errori

Quando si chiama l’API, se si verifica un errore, l’API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:
  • 400 token_mismatched: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 400 api_not_implemented: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 401 invalid_token: Non autorizzato, token di autorizzazione non valido o mancante.
  • 429 too_many_requests: Troppe richieste, hai superato il limite di frequenza.
  • 500 api_error: Errore interno del server, qualcosa è andato storto sul server.

​
Esempio di risposta di errore

​
Conclusione

Attraverso questo documento, hai appreso come utilizzare l’API Seedance Videos Generation per generare video da testo, fotogrammi iniziali e finali e riferimenti multimodali, oltre a utilizzare Seedance 2.5 per modificare o prolungare video. Speriamo che questo documento ti aiuti a completare l’integrazione dell’API; per qualsiasi domanda, contatta il supporto tecnico.