Vai al contenuto principale
Questo articolo presenterà un metodo di integrazione dell’API SeeDance Videos Generation, che consente di generare video ufficiali SeeDance inserendo parametri personalizzati.

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 prompt content.text, il tipo content.type=text e il modello model, è possibile ottenere il risultato elaborato; i dettagli specifici sono i seguenti:

Qui possiamo vedere che abbiamo impostato i Request Headers, inclusi:
  • accept: il formato del risultato di risposta che si desidera ricevere; qui è impostato su application/json, ovvero il formato JSON.
  • authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dal menu a discesa dopo averla richiesta.
Sono inoltre impostati i Request Body, inclusi:
  • 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.
  • content: array di contenuti in input; type può essere text (prompt), image_url (immagine di riferimento), audio_url (audio di riferimento), video_url (video di riferimento). Le immagini possono specificare l’uso tramite role: first_frame (primo fotogramma) / last_frame (ultimo fotogramma) / reference_image (riferimento del personaggio / soggetto).
  • resolution: risoluzione di output; opzionale 480p / 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; opzionale 16: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, predefinito mp4.
  • tools: solo 2.5; attualmente supporta lo strumento di ricerca online web_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 immediatamente task_id, e al completamento del task invia il risultato tramite POST a questo indirizzo.
  • async: opzionale; quando impostato su true, l’interfaccia restituisce immediatamente task_id, senza necessità di fornire callback_url; successivamente, il risultato viene ottenuto tramite polling attraverso la corrispondente interfaccia di query del task.
Dopo la selezione, è possibile vedere che anche sulla destra viene generato il codice corrispondente, come mostrato nella figura:

Fai clic sul pulsante «Try» per eseguire un test; come mostrato sopra, qui otteniamo il seguente risultato:
Il risultato restituito contiene diversi campi, descritti di seguito:
  • 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.
Possiamo vedere che abbiamo ottenuto informazioni video soddisfacenti; dobbiamo solo ottenere il video SeeDance generato in base all’indirizzo del link video in 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 prompt content[].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 (come resolution, 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 parametro generate_audio:
La serie 1.0 non supporta questo parametro.

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 un reference_image, reference_video o reference_audio; la versione 2.5 supporta il passaggio di solo audio di riferimento.
  • edit: è necessario utilizzare ratio: adaptive e duration: -1; la durata di output viene fatturata in base al risultato effettivo.
  • extend: è necessario utilizzare ratio: adaptive; duration può 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 parametro content 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: image_url non 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.
Il codice corrispondente:
Fare clic per eseguire, e si può osservare che viene immediatamente ottenuto un risultato, come segue:
Si può vedere che l’effetto generato è un video creato da immagine, e il risultato è simile a quello sopra.

Primo e ultimo fotogramma per video da immagine

Se si desidera il primo e l’ultimo fotogramma per un video da immagine, innanzitutto il parametro content 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, content deve anche inserire il tipo text come prompt
Il codice corrispondente:
Fare clic su Esegui e si può notare che si ottiene immediatamente un risultato, come segue:
Si può vedere che l’effetto generato è un video del personaggio, e il risultato è simile a quello sopra.

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 utilizzare first_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_frame non possono essere utilizzati insieme a reference_image / reference_video / reference_audio.
  • Se si desidera specificare il primo e l’ultimo fotogramma nel riferimento multimodale completo, contrassegnare le immagini come reference_image e 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 solo first_frame / last_frame.
  • Limite del numero di riferimenti multimodali: fino a 9 image_url; la versione 2.0 supporta anche audio_url (role è reference_audio, fino a 3 elementi) e video_url (role è reference_video, fino a 3 elementi).
  • Requisiti dei materiali audio di riferimento (audio_url): formato wav / 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): formato mp4 / 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:
Il risultato restituito è il seguente, e la persona nel video generato rimane coerente con la foto di riferimento:

Esempio due: inserire la stessa persona in una scena completamente nuova

Il punto di forza di reference_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:
Il risultato restituito è il seguente: l’aspetto della persona viene mantenuto, mentre la scena è già passata a un parco autunnale:
💡 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 campo callback_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.
Quando l’attività è completata, il contenuto inviato dalla piattaforma a callback_url è il seguente:
Il campo 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.

Esempio di risposta di errore

Conclusione

Attraverso questo documento, ha già appreso come utilizzare Seedance Videos Generation API per la generazione da testo a video, la generazione con primo e ultimo fotogramma e riferimenti multimodali, nonché come utilizzare Seedance 2.5 per modificare o estendere i video. Ci auguriamo che questo documento possa aiutarla a completare l’integrazione dell’API; in caso di domande, contatti il supporto tecnico.