> ## 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.
# Wan Videos Generation API Integrazione Istruzioni
> Tongyi Wansiang Video Generation 集成指南 - XHuoAPI
Questo documento presenterà un'istruzione per l'integrazione dell'API Wan Videos Generation, che consente di generare video ufficiali di Tongyi Wanxiang tramite l'immissione di parametri personalizzati.
## Processo di Richiesta
Per utilizzare l'API, è necessario prima andare alla pagina corrispondente [Wan Videos Generation API](https://api.xhuoapi.ai/documents/52b0f490-1bbf-4fe5-b60e-96626d333d2c) per richiedere il servizio corrispondente. Una volta entrati nella pagina, fare clic sul pulsante "Acquire", come mostrato nell'immagine:
Se non si è ancora effettuato il login o la registrazione, si verrà automaticamente reindirizzati alla pagina di accesso per registrarsi e accedere. Dopo aver effettuato il login o la registrazione, si tornerà automaticamente alla pagina corrente.
Alla prima richiesta, verrà offerto un credito gratuito, che consente di utilizzare gratuitamente l'API.
## Utilizzo di Base
Per prima cosa, è necessario comprendere il modo di utilizzo di base, che consiste nell'immettere la parola chiave `prompt`, l'azione `action`, l'immagine di riferimento del primo fotogramma `image_url` e il modello `model`, per ottenere il risultato elaborato. È necessario prima passare un campo `action`, il cui valore è `text2video`, che include principalmente due tipi di azioni: video da testo (`text2video`), video da immagine (`image2video`). Inoltre, è necessario immettere il modello `model`, attualmente disponibili i modelli `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-i2v-flash`, `wan2.6-t2v`, i dettagli sono i seguenti:
Possiamo vedere che qui abbiamo impostato le intestazioni della richiesta, tra cui:
* `accept`: il formato della risposta desiderato, 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, principalmente `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-i2v-flash`, `wan2.6-t2v`.
* `action`: l'azione per il compito di generazione video, che include principalmente tre azioni: video da testo (`text2video`), video da immagine (`image2video`). Quando si tratta di video da testo, attualmente supporta solo il modello `wan2.6-t2v`, mentre per video da immagine supporta solo i modelli `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-i2v-flash`.
* `image_url`: quando si sceglie l'azione video da immagine `image2video`, è necessario caricare il link dell'immagine di riferimento del primo fotogramma, attualmente supportato solo dai modelli `wan2.6-i2v`, `wan2.6-i2v-flash`.
* `reference_video_urls`: opzionale per video da immagine, specifica i link video di riferimento per la generazione, attualmente supportato solo dal modello `wan2.6-r2v`.
* `size`: specifica la risoluzione del video generato, nel formato larghezza\*altezza. Il valore predefinito e i valori enumerabili disponibili dipendono dal parametro model, le regole specifiche possono essere consultate nella [documentazione ufficiale](https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=api#/api/?type=model\&url=2865250).
* `duration`: la durata della generazione video, supporta principalmente 5, 10, 15.
* `shot_type`: opzionale, specifica il tipo di inquadratura del video generato, ovvero se il video è composto da un'inquadratura continua o da più inquadrature alternate. Condizione di attivazione: attiva solo quando "prompt\_extend": true. Priorità dei parametri: shot\_type > prompt. Ad esempio, se shot\_type è impostato su "single", anche se il prompt contiene "generare video a più inquadrature", il modello restituirà comunque un video a singola inquadratura, le regole specifiche possono essere consultate nella [documentazione ufficiale](https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=api#/api/?type=model\&url=2865250).
* `negative_prompt`: opzionale, parole chiave inverse, utilizzate per descrivere contenuti che non si desidera vedere nel video, possono limitare il contenuto del video. Supporta cinese e inglese, lunghezza massima di 500 caratteri, la parte in eccesso verrà automaticamente troncata. Esempi: bassa risoluzione, errori, qualità peggiore, bassa qualità, difetti, dita in eccesso, proporzioni errate, ecc.
* `resolution`: specifica il livello di risoluzione del video generato, utilizzato per regolare la chiarezza del video (totale pixel). Il modello ridimensionerà automaticamente in base al livello di risoluzione selezionato, mantenendo il rapporto di aspetto del video il più vicino possibile a quello dell'immagine di input img\_url, ulteriori spiegazioni possono essere consultate nella [documentazione ufficiale](https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=api#/api/?type=model\&url=2867393).
* `audio_url`: URL del file audio, il modello utilizzerà questo audio per generare il video. Modalità d'uso consultare la [documentazione ufficiale](https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=api#/api/?type=model\&url=2867393).
* `audio`: se generare un video con audio. Priorità dei parametri: audio > audio\_url. Quando audio=false, anche se viene fornito audio\_url, l'output sarà comunque un video muto, e la fatturazione sarà calcolata come video muto, il valore predefinito è true.
* `prompt_extend`: se attivare la riscrittura intelligente del prompt. Se attivato, utilizza un grande modello per riscrivere intelligentemente il prompt di input. Per prompt più brevi, l'effetto di generazione migliora notevolmente, ma aumenterà il tempo di elaborazione, il valore predefinito è true.
* `prompt`: parola chiave.
* `callback_url`: URL per il callback dei risultati.
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, qui abbiamo ottenuto il seguente risultato:
```json theme={null}
{
"success": true,
"video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
"state": "completed",
"task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
```
Il risultato restituito contiene diversi campi, descritti come segue:
* `success`, lo stato attuale del compito di generazione video.
* `task_id`, l'ID del compito di generazione video attuale.
* `video_url`, il link del video generato dal compito di generazione video attuale.
* `state`, lo stato attuale del compito di generazione video.
Possiamo vedere che abbiamo ottenuto informazioni soddisfacenti sul video, dobbiamo solo ottenere il video generato di Tongyi Wanxiang in base all'indirizzo del link video `video_url` nel risultato.
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/wan/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "text2video",
"model": "wan2.6-t2v",
"prompt": "Astronauti che si spostano dallo spazio a un vulcano",
"duration": 5
}'
```
## Funzione Video da Immagine
Se si desidera generare un video utilizzando un'immagine di riferimento o un video di riferimento, è possibile impostare il parametro `action` su `image2video` e inserire il link dell'immagine di riferimento o del video di riferimento. Successivamente, è necessario compilare le parole chiave da espandere per personalizzare la generazione del video, specificando i seguenti contenuti:
* `model`: il modello per generare il video, principalmente `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-i2v-flash`, `wan2.6-t2v`.
* `image_url`: quando si sceglie l'azione di generare un video da un'immagine `image2video`, è necessario caricare il link dell'immagine di riferimento per il primo fotogramma, attualmente supportato solo dai modelli `wan2.6-i2v`, `wan2.6-i2v-flash`.
* `reference_video_urls`: opzionale durante la generazione di un video da un'immagine, specifica il link del video di riferimento per la generazione, attualmente supportato solo dal modello `wan2.6-r2v`.
* `prompt`: parole chiave.
Esempio di compilazione:
Dopo aver completato la compilazione, il codice generato automaticamente è il seguente:
Codice Python corrispondente:
```python theme={null}
import requests
url = "https://api.xhuoapi.ai/v1/wan/videos"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"action": "image2video",
"model": "wan2.6-i2v",
"prompt": "Astronauti si spostano dallo spazio a un vulcano",
"duration": 5,
"image_url": "https://cdn.xhuoapi.ai/r9vsv9.png",
"callback_url": "https://www.baidu.com/"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
Cliccando su Esegui, si può notare che si ottiene un risultato, come segue:
```json theme={null}
{
"success": true,
"video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
"state": "completed",
"task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
```
Si può notare che il contenuto del risultato è coerente con quanto sopra, realizzando così la funzionalità di espansione del video.
## Callback asincrona
Poiché il tempo di generazione dell'API Wan Videos Generation è relativamente lungo, circa 1-2 minuti, se l'API non risponde per un lungo periodo, la richiesta HTTP manterrà la connessione, causando un consumo aggiuntivo di risorse di sistema. Pertanto, questa API offre anche supporto per callback asincroni.
Il flusso complessivo è: quando il client avvia la richiesta, specifica un campo `callback_url` aggiuntivo. Dopo che il client ha avviato la richiesta API, l'API restituirà immediatamente un risultato, contenente un campo `task_id`, che rappresenta l'ID del compito corrente. Quando il compito è completato, il risultato del video generato verrà inviato al `callback_url` specificato dal client in formato JSON POST, includendo anche il campo `task_id`, in modo che il risultato del compito possa essere associato tramite l'ID.
Di seguito, vediamo un esempio per capire come operare concretamente.
Innanzitutto, il callback Webhook è un servizio in grado di ricevere richieste HTTP; gli sviluppatori dovrebbero sostituirlo con l'URL del server HTTP che hanno costruito. Qui, per comodità di dimostrazione, utilizziamo un sito Web pubblico di esempio per Webhook [https://webhook.site/](https://webhook.site/), aprendo questo sito si ottiene un URL Webhook, come mostrato nell'immagine:
Copia questo URL e utilizzalo come Webhook; l'esempio qui è `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`.
Successivamente, possiamo impostare il campo `callback_url` su questo URL Webhook, riempiendo i parametri corrispondenti, come mostrato nell'immagine:
Cliccando su Esegui, si può notare che si ottiene immediatamente un risultato, come segue:
```
{
"task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}
```
Dopo un momento, possiamo osservare il risultato del video generato su `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`, come mostrato nell'immagine:
Il contenuto è il seguente:
```json theme={null}
{
"success": true,
"video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
"state": "completed",
"task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
```
Si può vedere che nel risultato c'è un campo `task_id`, mentre gli altri campi sono simili a quelli sopra, consentendo di associare il compito tramite questo campo.
## 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 Wan Videos Generation per generare video inserendo parole chiave e un'immagine di riferimento per il primo fotogramma. 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.