Vai al contenuto principale
Questo documento introduce una guida all’integrazione dell’API SeeDance Videos Generation, che consente di generare video ufficiali di SeeDance inserendo parametri personalizzati.

​
Processo di richiesta

Per utilizzare l’API, è necessario prima visitare la pagina corrispondente SeeDance Videos Generation API per richiedere il servizio corrispondente. Una volta entrati nella pagina, cliccare sul pulsante “Acquire”, come mostrato nell’immagine: Se non si è ancora effettuato il login o la registrazione, si verrà automaticamente reindirizzati alla pagina di login per registrarsi e accedere. Dopo aver effettuato il login o la registrazione, si verrà riportati automaticamente alla pagina corrente. Alla prima richiesta, verrà fornito un credito gratuito, che consente di utilizzare l’API senza costi.

​
Utilizzo 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 abbiamo impostato le intestazioni della richiesta, tra cui:
  • 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, valori opzionali: 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.
  • content: array di contenuti, type può essere text o image_url.
  • resolution: risoluzione di output, valori opzionali 480p / 720p / 1080p.
  • ratio: rapporto d’aspetto, valori opzionali 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
  • duration: durata del video (secondi), intervallo 2–12.
  • 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.
  • service_tier: modalità di inferenza, default (online) o flex (offline, prezzo al 50% di quello online).
  • return_last_frame: se restituire l’URL dell’ultima immagine del video nei risultati.
  • execution_expires_after: tempo di scadenza del compito (secondi), intervallo 3600–259200.
  • callback_url: indirizzo di callback asincrono, impostato per restituire immediatamente task_id, e quando il compito è completato, il risultato verrà inviato a questo indirizzo.
Dopo aver selezionato, si può notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Try” è possibile effettuare un test, come mostrato nell’immagine sopra, e abbiamo ottenuto il seguente risultato: 
{
  "success": true,
  "task_id": "ec22ae22-0140-4033-8c86-a48b536da595",
  "trace_id": "1cc87db0-8ee5-4436-969b-35cc571a9fd5",
  "data": {
    "task_id": "cgt-20251222005129-62fhb",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/f592800a-b87c-4705-8796-cbb8018cae35.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}
Il risultato restituito ha diversi campi, descritti come segue:
  • success, lo stato attuale del compito di generazione video.
  • task_id, l’ID del compito di generazione video attuale.
  • trace_id, l’ID di tracciamento della generazione video attuale.
  • data, l’elenco dei risultati del compito di generazione video attuale.
    • task_id, l’ID del compito di generazione video sul server.
    • video_url, il link al video generato dal compito di generazione video attuale.
    • status, lo stato del compito di generazione video attuale.
      • model, il modello utilizzato per generare il video.
Possiamo vedere che abbiamo ottenuto informazioni soddisfacenti sul video, e dobbiamo solo ottenere il video generato di SeeDance dall’URL del video nel risultato data. Inoltre, se si desidera generare il codice di integrazione corrispondente, è possibile copiarlo direttamente, 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": [{"text":"Un gattino che sbadiglia verso la telecamera. --rs 720p --rt 16:9 --dur 5 --fps 24 --wm true --seed 11 --cf false","type":"text"}],
  "model": "doubao-seedance-1-0-pro-250528"
}'

​
Descrizione dei parametri in linea

Alla fine della parola chiave content[].text, è possibile 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:
Parametro in lineaCampo corrispondenteDescrizioneIntervallo di valori
--rsresolutionRisoluzione di output480p / 720p / 1080p
--rtratioRapporto d’aspetto16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive
--durdurationDurata del video (secondi)2–12
--framesframesNumero di fotogrammi del videoInteri che soddisfano 25+4n in [29, 289]
--fpsframespersecondFrame rateSolo supporta 24
--seedseedSeme casuale-1 a 4294967295
--cfcamerafixedSe la telecamera è fissatrue / false
--wmwatermarkSe aggiungere un watermarktrue / false
Pratica consigliata: utilizzare direttamente i campi di livello superiore corrispondenti (come resolution, ratio, 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, si può sentire il suono del vento"
    }
  ],
  "generate_audio": true,
  "ratio": "16:9",
  "duration": 5
}
Altri modelli non supportano questo parametro, verrà ignorato se passato.

​
Generazione video dalla prima immagine

Se si desidera generare un video a partire da un’immagine, prima di tutto 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 (ad esempio "image_url": "https://..."), deve essere utilizzato il 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 un 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 mossi dal vento. --ratio adaptive  --dur 5"
        }
    ],
    "model": "doubao-seedance-1-0-pro-250528"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
Cliccando su esegui, si può notare che si ottiene 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"
    }
}
Si può vedere che l’effetto generato è un video creato a partire da un’immagine, il risultato è simile a quanto sopra.

​
Generazione video dalla prima e ultima immagine

Se si desidera generare un video dalla prima e ultima immagine, prima di tutto il parametro content deve includere un tipo image_url, e deve essere impostato role su first_frame e last_frame, in modo da specificare il seguente contenuto:
  • role: specifica la prima o l’ultima immagine.
  • image_url
    • url link all’immagine Inoltre, content deve anche 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, si può notare che si ottiene 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"
    }
}
Si può vedere che l’effetto generato è un video creato a partire dai ruoli, il risultato è simile a quanto sopra.

​
Callback asincrona

Poiché l’API di generazione video SeeDance richiede un tempo di generazione piuttosto lungo (circa 1-2 minuti), è possibile utilizzare il campo callback_url per attivare la modalità asincrona, evitando che la connessione HTTP rimanga occupata a lungo. Flusso complessivo: 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 al callback_url, i risultati conterranno anch’essi task_id per facilitare l’associazione. 
{
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}
Quando il compito è completato, il contenuto inviato dalla piattaforma al 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, attraverso 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

{
  "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 di input e immagini di riferimento. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.