> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# SeeDance Videos Generation API integrazione
> ByteDance Seedance Video Generation 集成指南 - XHuoAPI
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](https://api.xhuoapi.ai/documents/seedance-videos) 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:
```json theme={null}
{
"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.xhuoapi.ai/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:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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 linea | Campo corrispondente | Descrizione | Intervallo di valori |
| ------------------ | -------------------- | ------------------------------ | ------------------------------------------------------------- |
| `--rs` | `resolution` | Risoluzione di output | `480p` / `720p` / `1080p` |
| `--rt` | `ratio` | Rapporto d'aspetto | `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive` |
| `--dur` | `duration` | Durata del video (secondi) | 2–12 |
| `--frames` | `frames` | Numero di fotogrammi del video | Interi che soddisfano 25+4n in \[29, 289] |
| `--fps` | `framespersecond` | Frame rate | Solo supporta `24` |
| `--seed` | `seed` | Seme casuale | -1 a 4294967295 |
| `--cf` | `camerafixed` | Se la telecamera è fissa | `true` / `false` |
| `--wm` | `watermark` | Se aggiungere un watermark | `true` / `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`:
```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, 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:
```python theme={null}
import requests
url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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:
```python theme={null}
import requests
url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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.
```json theme={null}
{
"task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}
```
Quando il compito è completato, il contenuto inviato dalla piattaforma al `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.xhuoapi.ai/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
```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 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.