Vai al contenuto principale
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 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.
  • 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.
  • 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.
  • audio_url: URL del file audio, il modello utilizzerà questo audio per generare il video. Modalità d’uso consultare la documentazione ufficiale.
  • 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: 
{
  "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: 
curl -X POST 'https://api.acedata.cloud/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: 
import requests

url = "https://api.acedata.cloud/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.acedata.cloud/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: 
{
  "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/, 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: 
{
  "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

{
  "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.