Wan-R2V accepte des entrées multimodales (images, vidéos et audio) pour générer des vidéos mettant en scène un ou plusieurs personnages, tout en préservant leur apparence et leur voix d'une scène à l'autre.
Références : Guide utilisateur
Pour garantir le succès des appels API, le modèle, l'URL de l'endpoint et la clé API doivent tous appartenir à la même région. Les appels interrégionaux échoueront.
La génération vidéo nécessitant généralement entre 1 et 5 minutes, l'API fonctionne par invocation asynchrone. Le processus se déroule en deux étapes : créer une tâche, puis interroger le résultat.
Remplacez
Remplacez
Les noms des paramètres du SDK correspondent en grande partie à ceux de l'API HTTP. La structure des paramètres est encapsulée selon les spécificités du langage.
Les tâches reference-to-video prennent généralement entre 1 et 5 minutes. Le SDK encapsule le flux asynchrone HTTP et prend en charge les appels synchrones et asynchrones.
Définissez region en fonction de la région où se trouve le modèle (elle est passée à la construction du Client ; la valeur de region varie selon la région) :
Remplacez
Définissez baseHttpApiUrl en fonction de la région du modèle :
Remplacez
Si l'appel du modèle échoue et retourne un message d'erreur, consultez la section Codes d'erreur pour obtenir une solution.
Seul wan2.7 prend en charge la référence vocale. Dans l'objet
Disponibilité
Pour garantir le succès des appels API, le modèle, l'URL de l'endpoint et la clé API doivent tous appartenir à la même région. Les appels interrégionaux échoueront.
- Sélectionner un modèle : confirmez la région du modèle.
- Sélectionner une URL : choisissez l'URL de l'endpoint correspondant à la région. Les URL HTTP sont prises en charge.
- Configurer une clé API : sélectionnez une région, obtenez une clé API, puis configurez la clé API comme variable d'environnement.
L'exemple de code présenté dans cette rubrique s'applique à la région Singapour.
HTTP
La génération vidéo nécessitant généralement entre 1 et 5 minutes, l'API fonctionne par invocation asynchrone. Le processus se déroule en deux étapes : créer une tâche, puis interroger le résultat.
Étape 1 : Créer une tâche et obtenir l'ID de tâche
- Singapore
- Beijing
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis{WorkspaceId} par votre véritable ID d'espace de travail.
- Une fois la tâche créée, utilisez le
task_idretourné pour interroger le résultat. Cetask_idreste valide pendant 24 heures. Ne créez pas de tâches en double. Utilisez plutôt un mécanisme d'interrogation pour récupérer le résultat. - Pour un guide destiné aux débutants, consultez Appeler des API avec Postman ou cURL.
Paramètres de la requête |
Vous pouvez transmettre plusieurs ressources de référence (images et vidéos) et spécifier une voix pour générer une vidéo. |
En-têtes | |
Content-Type string (Obligatoire)Type de contenu de la requête. Doit être défini à application/json. | |
Authorization string (Obligatoire)Authentifie la requête à l'aide d'une clé API Model Studio. Exemple : Bearer sk-xxxx. | |
X-DashScope-Async string (Obligatoire)Active le traitement asynchrone. Les requêtes HTTP ne prennent en charge que les appels asynchrones. La valeur doit être enable. | |
Corps de la requête | |
model string (Obligatoire)Nom du modèle. Pour consulter la liste des modèles et leurs tarifs, reportez-vous à la section Tarification des modèles.Exemple : wan2.7-r2v, wan2.7-r2v-2026-06-12. | |
input object (Obligatoire)Informations d'entrée de base, telles que le prompt.
Propriétés prompt string (Obligatoire)Prompt textuel décrivant les éléments souhaités et les caractéristiques visuelles de la vidéo générée.Prend en charge le chinois et l'anglais. Chaque caractère chinois, lettre et signe de ponctuation compte pour un caractère. Le texte dépassant la limite est automatiquement tronqué.
media. Les images et les vidéos sont comptées séparément ; ainsi, « Image 1 » et « Video 1 » peuvent coexister. S'il n'y a qu'une seule image ou vidéo de référence, simplifiez la référence en utilisant « the reference image » ou « the reference video ».Description de la scène : par exemple, si l'image de référence 1 représente un chat et l'image 2 une pièce. Pour décrire le chat jouant dans la pièce, deux méthodes s'offrent à vous. La première consiste à utiliser directement les identifiants, comme « Image 1 is playing in Image 2 ». La seconde enrichit la description avec le sujet et la scène, par exemple « The cat from Image 1 is playing in the room from Image 2 ».Lorsque l'image de référence est un storyboard multi-panneaux, décrivez la scène au format multi-plans dans le prompt. Il n'est pas nécessaire de décrire chaque panneau : fournissez les plans clés, et le modèle reconnaîtra automatiquement la logique des panneaux pour compléter les scènes restantes. Pour obtenir les meilleurs résultats, n'utilisez qu'une seule image multi-panneaux à la fois.Pour des conseils sur l'utilisation des prompts, consultez le Guide des prompts texte-vers-vidéo/image-vers-vidéo.negative_prompt string (Facultatif)Prompt négatif décrivant le contenu à exclure de la vidéo générée. Utilisez-le pour contraindre la sortie.Prend en charge le chinois et l'anglais. Longueur maximale : 500 caractères. Le texte dépassant cette limite est automatiquement tronqué.Exemple : low resolution, error, worst quality, low quality, disfigured, extra fingers, bad proportions.media array (Obligatoire)Tableau de ressources multimédias (images, vidéos et audio) utilisées comme références visuelles et sonores. Les images peuvent inclure plusieurs vues, couramment utilisées pour référencer des personnages, des accessoires et des décors.
Propriétés type string (Obligatoire)Type de la ressource multimédia. Valeurs valides :
string (Obligatoire)URL de la ressource multimédia. Chaque valeur peut pointer vers une image ou une vidéo.
Transmettre une image de référence (type=reference_image) URL ou données encodées en Base64 de l'image de référence. L'image peut représenter un sujet (personne, animal ou objet) ou un arrière-plan. Lorsqu'elle inclut un sujet, elle ne doit contenir qu'un seul personnage.Limites relatives aux images :
Transmettre une vidéo de référence (type=reference_video) URL de la vidéo de référence. La vidéo doit inclure un sujet (personne, animal ou objet). Évitez d'utiliser des vidéos d'arrière-plans ou de scènes vides. Lorsque la vidéo comprend un sujet, elle ne doit contenir qu'un seul personnage. Si la vidéo contient de l'audio, la voix peut également servir de référence.Limites relatives aux vidéos :
string (Facultatif)URL audio spécifiant la voix du personnage principal dans la ressource de référence (image ou vidéo). Utilisez ce paramètre avec reference_image ou reference_video. L'audio sert uniquement de référence vocale et ne détermine pas le contenu parlé. Pour obtenir les meilleurs résultats, faites correspondre la langue de l'audio de référence à celle du prompt.Logique audio :
| |
parameters object (Facultatif)Paramètres de traitement vidéo, tels que la résolution de la vidéo.
Propriétés resolution string (Facultatif)Niveau de résolution de la vidéo générée. Contrôle le nombre total de pixels.
string (Facultatif)Rapport d'aspect de la vidéo générée.Comportement :
integer (Facultatif)Durée de la vidéo générée, en secondes.
boolean (Facultatif)Active la réécriture du prompt. Lorsqu'elle est activée, un modèle réécrit le prompt d'entrée avant la génération. Cela améliore considérablement la qualité des prompts courts, mais augmente le temps de traitement.
boolean (Facultatif)Ajoute un filigrane. Le texte du filigrane est « AI Generated », placé dans le coin inférieur droit de la vidéo.
integer (Facultatif)La graine de nombre aléatoire doit être un entier compris dans l'intervalle [0, 2147483647].Si aucune valeur n'est spécifiée, une graine aléatoire est générée. Une graine fixe améliore la reproductibilité.La génération du modèle étant probabiliste, une même graine ne garantit pas des résultats identiques. | |
Paramètres de la réponse |
Enregistrez le task_id pour interroger l'état et le résultat de la tâche. |
output objectInformations de sortie de la tâche.
Propriétés task_id stringID de la tâche. Valide pour les requêtes pendant 24 heures.task_status stringÉtat de la tâche.
Valeurs d'énumération
| |
request_id stringIdentifiant unique de la requête pour le suivi et le dépannage. | |
code stringCode d'erreur. Retourné uniquement pour les requêtes ayant échoué. Consultez la section Codes d'erreur. | |
message stringMessage d'erreur détaillé. Retourné uniquement pour les requêtes ayant échoué. Consultez la section Codes d'erreur. |
Étape 2 : Interroger le résultat par ID de tâche
- Singapore
- Beijing
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}{WorkspaceId} par votre véritable ID d'espace de travail.
- Recommandation d'interrogation : la génération vidéo prenant plusieurs minutes, utilisez un mécanisme d'interrogation avec un intervalle raisonnable, par exemple 15 secondes.
- Transition d'état de la tâche : PENDING → RUNNING → SUCCEEDED ou FAILED.
- Lien du résultat : lorsqu'une tâche réussit, une URL vidéo valide pendant 24 heures est retournée. Téléchargez et enregistrez la vidéo dans un stockage permanent, tel que OSS.
- Validité du task_id:24 heures**. Passé ce délai, les requêtes retournent l'état de la tâche comme
UNKNOWN.
Paramètres de la requête |
Remplacez {task_id} par la valeur task_id retournée par l'appel API précédent. Le task_id est valide pour les requêtes pendant 24 heures, Remplacez {WorkspaceId} par votre véritable ID d'espace de travail. |
En-têtes | |
Authorization string (Obligatoire)Authentifie la requête à l'aide d'une clé API Model Studio. Exemple : Bearer sk-xxxx. | |
Paramètres de chemin | |
task_id string (Obligatoire)ID de la tâche. |
Paramètres de la réponse |
Les URL vidéo ne sont valides que pendant 24 heures, puis sont automatiquement purgées. Enregistrez rapidement les vidéos générées. |
outputobjectInformations de sortie de la tâche.
Propriétés task_id string (Obligatoire)ID de la tâche.task_status stringÉtat de la tâche.
Valeurs d'énumération
stringHeure de soumission de la tâche. L'heure est en UTC+8 et le format est YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringHeure d'exécution de la tâche. L'heure est en UTC+8 et le format est YYYY-MM-DD HH:mm:ss.SSS.end_time stringHeure de fin de la tâche. L'heure est en UTC+8 et le format est YYYY-MM-DD HH:mm:ss.SSS.video_url stringURL de la vidéo générée. Retournée uniquement lorsque task_status est SUCCEEDED.Valide pendant 24 heures. La vidéo est au format MP4 avec un encodage H.264.orig_prompt stringPrompt d'entrée original, correspondant au paramètre de requête prompt.code stringCode d'erreur. Retourné uniquement pour les requêtes ayant échoué. Consultez la section Codes d'erreur.message stringMessage d'erreur détaillé. Retourné uniquement pour les requêtes ayant échoué. Consultez la section Codes d'erreur. | |
usage objectStatistiques de sortie. Renseigné uniquement pour les tâches réussies.
Propriétés input_video_duration integerDurée de la vidéo d'entrée, en secondes.output_video_duration integerDurée de la vidéo de sortie, en secondes.duration integerDurée totale de la vidéo. Le coût est calculé sur la base de cette valeur.Formule : duration = input_video_duration + output_video_duration.SR integerNiveau de résolution de la vidéo générée. Exemple : 720.ratio stringRapport d'aspect de la vidéo générée. Exemple : 16:9.video_count integerNombre de vidéos générées. La valeur est toujours 1. | |
request_id stringIdentifiant unique de la requête pour le suivi et le dépannage. |
DashScope SDK
Les noms des paramètres du SDK correspondent en grande partie à ceux de l'API HTTP. La structure des paramètres est encapsulée selon les spécificités du langage.
Les tâches reference-to-video prennent généralement entre 1 et 5 minutes. Le SDK encapsule le flux asynchrone HTTP et prend en charge les appels synchrones et asynchrones.
Le temps de traitement réel dépend de la longueur de la file d'attente et de l'état du service.
SDK Python
Définissez region en fonction de la région où se trouve le modèle (elle est passée à la construction du Client ; la valeur de region varie selon la région) :
- Singapore
- Beijing
region="ap-southeast-1"{WorkspaceId} par votre véritable ID d'espace de travail.
- Appel synchrone
- Appel asynchrone
Un appel synchrone bloque l'exécution jusqu'à la fin de la génération vidéo et retourne directement le résultat.
Exemple de requête
Exemple de réponse
L'URL video_url est valide pendant 24 heures. Téléchargez la vidéo sans tarder.
SDK Java
Définissez baseHttpApiUrl en fonction de la région du modèle :
- Singapore
- Beijing
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";{WorkspaceId} par votre véritable ID d'espace de travail.
- Appel synchrone
- Appel asynchrone
Un appel synchrone bloque l'exécution jusqu'à la fin de la génération vidéo et retourne directement le résultat.
Exemple de requête
Exemple de réponse
L'URL video_url est valide pendant 24 heures. Téléchargez la vidéo sans tarder.
Codes d'erreur
Si l'appel du modèle échoue et retourne un message d'erreur, consultez la section Codes d'erreur pour obtenir une solution.
FAQ
Comment ajouter une voix à un sujet (référence vocale) ?
Seul wan2.7 prend en charge la référence vocale. Dans l'objet media, vous pouvez transmettre une URL audio via le paramètre reference_voice pour spécifier une voix de référence pour une image ou une vidéo de référence.