SeeDance Videos Generation API integrazione descrittiva

Questo documento presenterà una descrizione dell’integrazione dell’API SeeDance Videos Generation, che consente di generare video ufficiali di SeeDance inserendo parametri personalizzati.

Processo di richiesta

Per utilizzare l’API SeeDance Videos Generation, 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 necessità di richiederne uno per ogni servizio. La prima richiesta ti darà 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, che includono:

accept: il formato della risposta desiderata, qui impostato su 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 input multimodali come riferimento facciale / personaggio): doubao-seedance-2-0-260128 (standard), doubao-seedance-2-0-fast-260128 (veloce), doubao-seedance-2-0-mini-260615 (leggero). Vedi la sezione successiva “Riferimenti facciali e personaggi (Seedance 2.0)”.
content: array di contenuti di input, type può essere text (parola chiave), image_url (immagine di riferimento), audio_url (audio di riferimento, 2.0), video_url (video di riferimento, 2.0). Le immagini possono essere specificate tramite role: first_frame (primo fotogramma) / last_frame (ultimo fotogramma) / reference_image (riferimento facciale / personaggio / soggetto).
resolution: risoluzione di output, opzioni 480p / 720p / 1080p (il modello standard 2.0 supporta anche 4k; fast / mini di 2.0 supportano massimo 720p).
ratio: rapporto d’aspetto, opzioni 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
duration: durata del video (secondi), intervallo 1.x 2–12, 2.0 intervallo 2–15.
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, solo doubao-seedance-1-5-pro-251215 supporta.
return_last_frame: se restituire l’URL dell’immagine dell’ultimo fotogramma del video nei risultati.
execution_expires_after: tempo di scadenza del compito (secondi), intervallo 3600–259200.
callback_url: indirizzo di callback asincrono, 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 puoi ottenere i risultati tramite l’interfaccia di polling corrispondente.

Dopo aver effettuato le scelte, 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:

{
  "success": true,
  "task_id": "9777f36b-4f44-47ff-962d-45cd2f7aeaa8",
  "trace_id": "ce5da2ca-6695-4459-9d2c-2ef9f86db752",
  "data": {
    "task_id": "7e4e1773-510a-4a73-9ab4-98dd1a0b2a7f",
    "status": "succeeded",
    "model": "doubao-seedance-2-0-fast-260128",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152.mp4"
  }
}

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, e abbiamo solo bisogno di ottenere il video SeeDance generato dall’indirizzo del link video in data. Inoltre, se desideri generare il codice di integrazione corrispondente, puoi semplicemente copiarlo, ad esempio il codice CURL è il seguente:

curl -X POST 'https://api.acedata.cloud/seedance/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "content": [{"type":"text","text":"A white ceramic coffee mug on a glossy marble countertop with soft morning window light. The camera slowly orbits 360 degrees around the mug, steam gently rising."}],
  "model": "doubao-seedance-2-0-fast-260128",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}'

Descrizione dei parametri inline

Alla fine della parola chiave content[].text, puoi passare i parametri di generazione aggiungendo --parameter value (metodo obsoleto, verifica debole, se inserito erroneamente verrà utilizzato il valore predefinito). L’elenco completo dei parametri è il seguente:

Parametri in linea	Campo corrispondente	Descrizione	Intervallo di valori
`--rs`	`risoluzione`	Risoluzione di output	`480p` / `720p` / `1080p`
`--rt`	`rapporto`	Rapporto d’aspetto	`16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adattivo`
`--dur`	`durata`	Durata del video (secondi)	2–12
`--frames`	`frame`	Numero di frame del video	Interi che soddisfano 25+4n in [29, 289]
`--fps`	`framepersecondo`	Frame rate	Supporta solo `24`
`--seed`	`seme`	Seme casuale	-1 a 4294967295
`--cf`	`camerafissa`	Telecamera fissa	`true` / `false`
`--wm`	`filigrana`	Aggiungere filigrana	`true` / `false`

Pratica consigliata: Utilizzare direttamente i campi di livello superiore corrispondenti (come risoluzione, rapporto, ecc.) nel corpo della richiesta, per una modalità di verifica rigorosa; se i parametri sono errati, verrà restituito un messaggio di errore chiaro, facilitando la risoluzione dei problemi.

Generazione di video con audio

doubao-seedance-1-5-pro-251215 supporta la generazione di video con audio tramite il parametro generate_audio:

{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {
      "type": "text",
      "text": "Una ragazza tiene una volpe, il vento le scompiglia i capelli, puoi sentire il suono del vento"
    }
  ],
  "generate_audio": true,
  "ratio": "16:9",
  "duration": 5
}

Altri modelli non supportano questo parametro, e verrà ignorato se passato.

Video generato da immagine - primo frame

Se desideri generare un video da un’immagine, prima il parametro content deve contenere un elemento con type uguale a 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://..."), deve essere utilizzato in formato oggetto "image_url": {"url": "https://..."}, altrimenti verrà restituito un errore 400.

Codice corrispondente:

import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "content": [
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
            }
        },
        {
            "type": "text",
            "text": "Una ragazza tiene una volpe tra le braccia. Apre gli occhi e guarda teneramente verso la telecamera, mentre la volpe la abbraccia affettuosamente. Mentre la telecamera si allontana lentamente, i suoi capelli vengono delicatamente scompigliati dal vento. --ratio adattivo  --dur 5"
        }
    ],
    "model": "doubao-seedance-1-0-pro-250528"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Cliccando su esegui, puoi notare che riceverai immediatamente un risultato, come segue:

{
    "success": true,
    "task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39",
    "trace_id": "b3b09de3-b7fa-4bb0-88b5-aad4b4a96fd4",
    "data": {
        "task_id": "cgt-20251222072003-x2259",
        "status": "succeeded",
        "video_url": "https://platform.cdn.acedata.cloud/seedance/6afb78b8-5ba8-424f-adcd-69423a700b50.mp4",
        "model": "doubao-seedance-1-0-pro-250528"
    }
}

Puoi vedere che l’effetto generato è un video creato da un’immagine, il risultato è simile a quanto descritto sopra.

Video generato da immagine - primo e ultimo frame

Se desideri generare un video da un’immagine con primo e ultimo frame, prima il parametro content deve includere il tipo image_url, e impostare rispettivamente role su first_frame e last_frame, puoi specificare i seguenti contenuti:

role: specifica il primo o l’ultimo frame.
image_url
- url link all’immagine Inoltre, content deve includere un tipo text come parola chiave di prompt.

Codice corrispondente:

import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
   "model": "doubao-seedance-1-0-pro-250528",
    "content": [
         {
            "type": "text",
            "text": "Ripresa a 360 gradi"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg"
            },
            "role": "first_frame"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg"
            },
            "role": "last_frame"
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Cliccando su esegui, puoi notare che riceverai immediatamente un risultato, come segue:

{
    "success": true,
    "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
    "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
    "data": {
        "task_id": "cgt-20251222073134-54qcw",
        "status": "succeeded",
        "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
        "model": "doubao-seedance-1-0-pro-250528"
    }
}

Puoi vedere che l’effetto generato è un video generato da personaggi, il risultato è simile a quanto descritto sopra.

Riferimenti a volti e personaggi (Seedance 2.0)

Serie Seedance 2.0 (doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128, doubao-seedance-2-0-mini-260615) supporta l’inserimento di materiali di riferimento per “persone reali / personaggi”: aggiungendo nel content un elemento con type uguale a image_url e role uguale a reference_image, puoi utilizzare foto di persone come riferimento; il modello manterrà le caratteristiche fisiche di quella persona nel video generato, permettendo di “inserire” la stessa persona in nuove scene, azioni o inquadrature.

📌 Le foto di persone reali verranno automaticamente registrate dalla piattaforma come materiali di base e poi utilizzate per la generazione; l’intero processo è completamente trasparente per il chiamante: il formato di richiesta e risposta rimane invariato, non sono necessari parametri aggiuntivi, solo la prima generazione richiederà qualche secondo in più per l’elaborazione dei materiali.

Punti chiave per l’uso:

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 del video generato).
reference_image non può essere utilizzato insieme a first_frame / last_frame, è possibile scegliere solo uno dei due.
Limite massimo per il numero di riferimenti multimodali: image_url massimo 9 immagini; la 2.0 supporta anche audio_url (con role di reference_audio, massimo 3) e video_url (con role di reference_video, massimo 3).
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, facendo in modo che la persona sorrida e saluti verso la telecamera. Il codice corrispondente:

import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
        {
            "type": "text",
            "text": "La donna guarda la telecamera, sorride calorosamente in modo naturale e saluta con la mano, illuminazione morbida da studio, dolce avvicinamento della telecamera."
        },
        {
            "type": "image_url",
            "role": "reference_image",
            "image_url": {
                "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
            }
        }
    ],
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Il risultato restituito è il seguente, il video generato mantiene la somiglianza con la foto di riferimento:

{
  "success": true,
  "task_id": "895eb5ea-bbe1-41a3-a9e9-48608e03f93a",
  "trace_id": "83544791-7a84-44de-b8d2-afe171a1c0e4",
  "data": {
    "task_id": "458abf29-cc39-4fd0-bcea-24f89a70d8de",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/e71d3cc5-27e7-4719-be34-1f0e254eccaf.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
  }
}

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, l’abbigliamento e le azioni sono completamente determinati dalle parole chiave. Qui utilizziamo la stessa foto del volto, facendo in modo che la persona indossi un cappotto beige mentre cammina in un parco autunnale:

{
  "model": "doubao-seedance-2-0-fast-260128",
  "content": [
    {
      "type": "text",
      "text": "La stessa donna che indossa un cappotto beige cammina attraverso un soleggiato parco autunnale, foglie dorate che cadono intorno a lei, sorride dolcemente alla telecamera, ripresa cinematografica in movimento."
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

Il risultato restituito è il seguente, l’aspetto del personaggio è mantenuto, mentre la scena è cambiata in un parco autunnale:

{
  "success": true,
  "task_id": "00872de7-16b7-431f-b4f7-6bf38ae86157",
  "trace_id": "577a07c3-4f5f-4cc7-86fe-535bb8332614",
  "data": {
    "task_id": "32fe1537-ba3e-452a-8749-3ef8890d37fd",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/44f47593-556b-4fda-afa5-7a71eefcd228.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "720p",
    "ratio": "9:16",
    "duration": 5
  }
}

💡 Se desideri che il personaggio riproduca esattamente la composizione della foto (anziché “la stessa persona in un’altra scena”), puoi utilizzare first_frame (primo fotogramma del video generato), facendo partire il video da questa foto.

Callback asincrona

Poiché l’API di generazione video SeeDance richiede un tempo di generazione più 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 complessivo: il client avvia la richiesta specificando callback_url, l’API restituisce immediatamente una risposta contenente task_id; una volta completato il compito, la piattaforma invia i risultati generati in formato JSON POST a callback_url, i risultati contengono anch’essi task_id per facilitare l’associazione.

{
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}

Quando il compito è completato, il contenuto inviato dalla piattaforma a callback_url è il seguente:

{
  "success": true,
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
  "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
  "data": {
    "task_id": "cgt-20251222073134-54qcw",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}

Il campo task_id nei risultati è lo stesso di quello restituito nella richiesta, tramite questo campo è possibile associare il 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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusione

Attraverso questo documento, hai appreso come utilizzare l’API di generazione video SeeDance per generare video tramite parole chiave, immagini di riferimento e il riferimento a volti / personaggi di Seedance 2.0. Speriamo che questo documento ti aiuti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Proxy

Avanzato

SeeDance Videos Generation API integrazione descrittiva

Processo di richiesta

Uso di base

Descrizione dei parametri inline

Generazione di video con audio

Video generato da immagine - primo frame

Video generato da immagine - primo e ultimo frame

Riferimenti a volti e personaggi (Seedance 2.0)

Esempio 1: primo piano mantenendo l’aspetto del personaggio

Esempio 2: mettere la stessa persona in una nuova scena

Callback asincrona

Gestione degli errori

Esempio di risposta di errore

Conclusione

​Processo di richiesta

​Uso di base

​Descrizione dei parametri inline

​Generazione di video con audio

​Video generato da immagine - primo frame

​Video generato da immagine - primo e ultimo frame

​Riferimenti a volti e personaggi (Seedance 2.0)

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

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

​Callback asincrona

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

Processo di richiesta

Uso di base

Descrizione dei parametri inline

Generazione di video con audio

Video generato da immagine - primo frame

Video generato da immagine - primo e ultimo frame

Riferimenti a volti e personaggi (Seedance 2.0)

Esempio 1: primo piano mantenendo l’aspetto del personaggio

Esempio 2: mettere la stessa persona in una nuova scena

Callback asincrona

Gestione degli errori

Esempio di risposta di errore

Conclusione