> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# SeeDance Videos Generation API integrazione descrittiva
> ByteDance Seedance Video Generation API guide - Ace Data Cloud
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](https://platform.acedata.cloud/console/applications) 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](https://platform.acedata.cloud/console/coin).
> 📘 Documentazione completa: [SeeDance Videos Generation API →](https://platform.acedata.cloud/documents/seedance-videos)
## 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:
```json theme={null}
{
"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:
```shell theme={null}
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`:
```json theme={null}
{
"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:
```python theme={null}
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:
```python theme={null}
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:
```python theme={null}
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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.
```json theme={null}
{
"task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}
```
Quando il compito è completato, il contenuto inviato dalla piattaforma a `callback_url` è il seguente:
```json theme={null}
{
"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
```json theme={null}
{
"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.