Procedura di richiesta
Per utilizzare l’API SeeDance Videos Generation, innanzitutto vai alla console Ace Data Cloud per ottenere il tuo API Token e conservarlo come riserva.
Se non hai ancora effettuato l’accesso o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso per essere invitato a registrarti e ad accedere; una volta completato, tornerai automaticamente alla pagina corrente.
Un solo API Token può chiamare tutti i servizi della piattaforma, senza necessità di richiederne uno separato per ogni servizio. Alla prima richiesta verrà assegnato un credito gratuito, che consente di provare il servizio gratuitamente; quando il credito è insufficiente, puoi ricaricare il saldo universale nella console.
📘 Documentazione completa: SeeDance Videos Generation API →
Utilizzo di base
Innanzitutto, comprendiamo il metodo di utilizzo di base: inserendo il promptcontent.text, il tipo content.type=text e il modello model, è possibile ottenere il risultato elaborato; i dettagli specifici sono i seguenti:

accept: il formato del risultato di risposta che si desidera ricevere; qui è impostato suapplication/json, ovvero il formato JSON.authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dal menu a discesa dopo averla richiesta.
model: il modello per generare 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 di personaggi e audio-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, modifica ed estensione video.
- Serie Seedance 1.x:
content: array di contenuti in input;typepuò esseretext(prompt),image_url(immagine di riferimento),audio_url(audio di riferimento),video_url(video di riferimento). Le immagini possono specificare l’uso tramiterole:first_frame(primo fotogramma) /last_frame(ultimo fotogramma) /reference_image(riferimento del personaggio / soggetto).resolution: risoluzione di output; opzionale480p/720p/1080p/4k. La 2.5 supporta 480p, 720p, 1080p; la 2.0 Fast/Mini supporta 480p, 720p; la 2.0 Standard supporta fino a 4k.ratio: rapporto d’aspetto; opzionale16:9/4:3/1:1/3:4/9:16/21:9/adaptive.duration: durata del video (secondi, numero intero). Serie 1.0 2–12; 1.5 Pro 4–12; serie 2.0 4–15; 2.5 4–30. La 1.5/2.x supporta-1(durata automatica).seed: seme casuale, numero intero, da -1 a 4294967295.camerafixed: se fissare la videocamera,true/false.watermark: se aggiungere una filigrana,true/false.generate_audio: se generare un video con audio,true/false, supportato da Seedance 1.5 Pro e dalla serie 2.x.return_last_frame: se restituire nell’output l’URL dell’immagine dell’ultimo fotogramma del video.omni_reference_task_type: solo 2.5;auto/reference/edit/extend.output_format: solo 2.5;mp4/mov, predefinitomp4.tools: solo 2.5; attualmente supporta lo strumento di ricerca onlineweb_search, che può limitare il numero di risultati, il numero di parole chiave e le fonti di ricerca.priority: priorità del task opzionale per la 2.5, numero intero 0–9, predefinito 0.safety_identifier: identificatore stabile e anonimo dell’utente finale, lungo al massimo 64 caratteri; utilizza un hash o un ID anonimo interno, non inserire nome, e-mail o numero di telefono.execution_expires_after: tempo di timeout del task (secondi), intervallo 3600–259200.callback_url: indirizzo di callback asincrono; dopo l’impostazione, l’API restituisce immediatamentetask_id, e al completamento del task invia il risultato tramite POST a questo indirizzo.async: opzionale; quando impostato sutrue, l’interfaccia restituisce immediatamentetask_id, senza necessità di fornirecallback_url; successivamente, il risultato viene ottenuto tramite polling attraverso la corrispondente interfaccia di query del task.

success, lo stato attuale del task di generazione video.task_id, l’ID attuale del task di generazione video.trace_id, l’ID di tracciamento attuale della generazione video.data, l’elenco dei risultati del task di generazione video attuale.task_id, l’ID lato server del task di generazione video attuale.video_url, il link video del task di generazione video attuale.status, lo stato del task di generazione video attuale.model, il modello utilizzato per generare il video.
data nel risultato.
Inoltre, se desideri generare il codice di integrazione corrispondente, puoi copiarlo direttamente; ad esempio, il codice CURL è il seguente:
Descrizione dei parametri inline
Alla fine del promptcontent[].text, è possibile passare parametri di generazione aggiungendo nella forma --parameter value (modalità precedente, con convalida debole; se compilati in modo errato, vengono utilizzati automaticamente i valori predefiniti). L’elenco completo dei parametri è il seguente:
Pratica consigliata: utilizzare direttamente i campi di primo livello corrispondenti nel Request Body (comeresolution,ratio, ecc.). Questa è una modalità di convalida forte: se i parametri vengono compilati in modo errato, verrà restituito un messaggio di errore chiaro, rendendo più semplice l’individuazione 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 parametrogenerate_audio:
Generazione, modifica ed estensione omnmodale di Seedance 2.5
doubao-seedance-2-5-260628 supporta 480p / 720p / 1080p, 4–30 secondi o durata automatica, e aumenta il limite dei materiali a 30 immagini di riferimento, 10 video di riferimento e 10 audio di riferimento (per un totale massimo di 50). La versione 2.5 supporta inoltre il passaggio di solo audio di riferimento, senza più richiedere la fornitura simultanea di immagini o video.
Per la normale generazione omnmodale si può omettere omni_reference_task_type, impostarlo su auto oppure impostarlo esplicitamente su reference. Per la modifica e l’estensione video è necessario passare reference_video:
reference: passare almeno unreference_image,reference_videooreference_audio; la versione 2.5 supporta il passaggio di solo audio di riferimento.edit: è necessario utilizzareratio: adaptiveeduration: -1; la durata di output viene fatturata in base al risultato effettivo.extend: è necessario utilizzareratio: adaptive;durationpuò essere 4–30 oppure-1.auto: il modello seleziona automaticamente la generazione, la modifica o l’estensione in base al prompt e ai materiali.- Quando il tipo di attività non corrisponde ai materiali o al prompt, l’attività fallirà e restituirà un errore di parametro individuabile; modificare e inviare nuovamente secondo i vincoli sopra indicati.
Primo fotogramma per video da immagine
Se si desidera un’attività di video da immagine, innanzitutto il parametrocontent deve includere un elemento con type pari a image_url, e il campo image_url deve essere in formato oggetto: {"url": "https://..."} oppure in formato Base64 {"url": "data:image/png;base64,..."}.
Nota:Il codice corrispondente:image_urlnon supporta il passaggio diretto in formato stringa (come"image_url": "https://cdn.acedata.cloud/e724d7f13d.png"), è obbligatorio utilizzare il formato oggetto"image_url": {"url": "https://..."}, altrimenti verrà restituito un errore 400.
Primo e ultimo fotogramma per video da immagine
Se si desidera il primo e l’ultimo fotogramma per un video da immagine, innanzitutto il parametrocontent deve passare il tipo image_url, e impostare rispettivamente role su first_frame e last_frame, così è possibile specificare i seguenti contenuti:
- role: specifica il primo fotogramma o l’ultimo fotogramma.
- image_url
- url collegamento dell’immagine
Allo stesso tempo,
contentdeve anche inserire il tipotextcome prompt
- url collegamento dell’immagine
Allo stesso tempo,
Riferimento multimodale di personaggi, audio e 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 di personaggi, soggetti, movimenti, movimenti di camera, suoni e ritmo.
Caricare solo materiali di persone reali e personaggi propri o autorizzati. I diversi modelli supportano in modi diversi i materiali di persone reali; il formato della richiesta rimane invariato e, se il materiale non soddisfa i requisiti, verrà restituito un errore esplicito.Punti chiave di utilizzo:
- Solo i modelli della serie Seedance 2.0 supportano
reference_image; per i modelli 1.x utilizzarefirst_frame/last_frame(primo e ultimo fotogramma per immagini in video). - Il primo fotogramma per immagini in video, il primo e ultimo fotogramma per immagini in video e il riferimento multimodale completo sono tre scenari mutuamente esclusivi:
first_frame/last_framenon possono essere utilizzati insieme areference_image/reference_video/reference_audio. - Se si desidera specificare il primo e l’ultimo fotogramma nel riferimento multimodale completo, contrassegnare le immagini come
reference_imagee indicare nel prompt “immagine 1 come primo fotogramma” oppure “immagine 2 come ultimo fotogramma”; se è necessario bloccare rigorosamente il primo e l’ultimo fotogramma, utilizzare solofirst_frame/last_frame. - Limite del numero di riferimenti multimodali: fino a 9
image_url; la versione 2.0 supporta ancheaudio_url(roleèreference_audio, fino a 3 elementi) evideo_url(roleèreference_video, fino a 3 elementi). - Requisiti dei materiali audio di riferimento (
audio_url): formatowav/mp3; durata di ogni elemento 2~15 secondi, fino a 3 elementi e durata totale non superiore a 15 secondi; ogni elemento non deve superare 15 MB. Il superamento dell’intervallo di durata causerà un errore nella fase di elaborazione del materiale. - Requisiti dei materiali video di riferimento (
video_url): formatomp4/mov; durata di ogni elemento 2~15 secondi, fino a 3 elementi e durata totale non superiore a 15 secondi. - Per le immagini di riferimento, si consiglia di utilizzare foto di una sola persona, frontali, nitide e senza ostruzioni; più nitido è il volto, maggiore sarà la somiglianza.
Esempio uno: primo piano che mantiene l’aspetto del personaggio
Passare una foto di un volto e fare in modo che quella persona sorrida e saluti la telecamera. Il codice corrispondente:Esempio due: inserire la stessa persona in una scena completamente nuova
Il punto di forza direference_image è: mantenere solo l’identità della persona, mentre la scena, l’abbigliamento e l’azione sono completamente determinati dal prompt. Di seguito, utilizzando la stessa foto di un volto, si fa camminare quella persona in un parco autunnale indossando un cappotto beige:
💡 Se si desidera che il personaggio replichi con precisione la composizione nella foto (anziché «la stessa persona in una scena diversa»), è possibile usare first_frame (primo fotogramma immagine-a-video), in modo che il video inizi a muoversi da questa foto.
Callback asincrono
Poiché il tempo di generazione di SeeDance Videos Generation API è relativamente lungo (circa 1-2 minuti), è possibile utilizzare la modalità asincrona tramite il campocallback_url, evitando che la connessione HTTP rimanga occupata a lungo.
Flusso complessivo: il client specifica callback_url quando avvia la richiesta e l’API restituisce immediatamente una risposta contenente task_id; una volta completata l’attività, la piattaforma invia il risultato generato a callback_url sotto forma di POST JSON, e il risultato contiene anch’esso task_id per consentire l’associazione.
callback_url è il seguente:
task_id nel risultato corrisponde a quello restituito al momento della richiesta; tramite questo campo è possibile associare l’attività.
Gestione degli errori
Durante la chiamata all’API, se si verifica un errore, l’API restituirà il codice e il messaggio di errore 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, è stato superato il limite di velocità.500 api_error:Errore interno del server, qualcosa è andato storto sul server.

