Skip to main content

Wan - reference-to-video API reference

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

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.
Alibaba Cloud Model Studio a publié des domaines spécifiques aux espaces de travail pour les régions Chine (Pékin) et Singapour. Ces nouveaux domaines dédiés offrent des performances supérieures et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :
  • Chine (Pékin) : de https://dashscope.aliyuncs.com vers https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapour : de https://dashscope-intl.aliyuncs.com vers https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} correspond à votre ID d'espace de travail, disponible sur la page Workspace Details de la console Alibaba Cloud Model Studio. Le domaine existant reste pleinement fonctionnel.

HTTP

Cette API utilise le nouveau protocole et prend en charge le modèle wan2.7.
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
Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.
  • Une fois la tâche créée, utilisez le task_id retourné pour interroger le résultat. Ce task_id reste 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

  • Référence multi-sujets (image + vidéo + voix)
  • Référence par image unique (image multi-panneaux)
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.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
            -H 'X-DashScope-Async: enable' \
            -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
            -H 'Content-Type: application/json' \
            -d '{
            "model": "wan2.7-r2v-2026-06-12",
            "input": {
                "prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, '\''The sunshine is so nice today.'\'' Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, '\''That sounds lovely. Can you sing it again?'\''",
                "media": [
                    {
                        "type": "reference_image",
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg",
                        "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3"
                    },
                    {
                        "type": "reference_video",
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
                        "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3"
                    },
                    {
                        "type": "reference_image",
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
                    },
                    {
                        "type": "reference_image",
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
                    },
                    {
                        "type": "reference_image",
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
                    }
                ]
            },
            "parameters": {
                "resolution": "720P",
                "ratio": "16:9",
                "duration": 10,
                "prompt_extend": false,
                "watermark": true
            }
        }'
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.
Si cet en-tête de requête est absent, l'erreur « current user api does not support synchronous calls » est retournée.
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é.
  • wan2.7-r2v, wan2.7-r2v-2026-06-12 : jusqu'à 5 000 caractères.
Identifiants de référence : dans les prompts, utilisez des identifiants tels que « Image 1, Image 2 » pour les images et « Video 1, Video 2 » pour les vidéos. Insérez un espace entre le mot et le chiffre, et mettez la première lettre en majuscule. L'ordre des identifiants doit correspondre à l'ordre des ressources dans le tableau 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.
  • Chaque élément du tableau est un objet média contenant les champs type et url.
  • L'ordre des éléments dans le tableau correspond aux identifiants de référence dans le prompt. Les images et les vidéos étant comptées séparément, « Image 1 » et « Video 1 » peuvent coexister.
    • Le premier élément reference_video du tableau correspond à Video 1, le second à Video 2, et ainsi de suite.
    • Le premier élément reference_image du tableau correspond à Image 1, le second à Image 2, et ainsi de suite.

Propriétés

type string (Obligatoire)Type de la ressource multimédia. Valeurs valides :
  • reference_image : image de référence fournissant la référence visuelle pour un personnage principal (personne, animal ou objet) ou un décor.
  • reference_video : vidéo de référence fournissant la référence visuelle et vocale pour un personnage principal (personne, animal ou objet). Évitez d'utiliser des vidéos de scènes vides.
  • first_frame : première image de la vidéo. La vidéo générée démarre à partir de cette image, qui contient généralement le personnage principal (personne, animal ou objet). Vous pouvez combiner une première image avec des références de sujet pour un contrôle conjoint. Cas d'usage courants :
    • Le sujet apparaît déjà dans la première image : utilisez une référence de sujet pour renforcer la cohérence ou ajouter une référence vocale.
    • Le sujet n'apparaît pas dans la première image : utilisez une référence de sujet pour définir les caractéristiques d'un nouveau sujet apparaissant au cours de la vidéo.
Limites des ressources :
  • Maximum d'une image de première image.
  • Au moins une image de référence ou une vidéo de référence. Images de référence + Vidéos de référence ≤ 5.
  • Lorsqu'elle est utilisée pour un personnage principal, la ressource de référence ne doit contenir qu'un seul personnage.
url 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 :
  • Formats : JPEG, JPG, PNG (le canal alpha n'est pas pris en charge), BMP ou WEBP.
  • Résolution : la largeur et la hauteur doivent être comprises entre 240 et 8 000 pixels.
  • Rapport d'aspect : de 1:8 à 8:1.
  • Taille du fichier : jusqu'à 20 Mo.
Formats d'entrée pris en charge :
  1. URL publique :
  2. Chaîne d'image encodée en Base64 :
    • Format des données : data:{MIME_type};base64,{base64_data}.
    • Exemple : data:image/png;base64,GDU7MtCZzEbTbmRZ...... (La chaîne encodée étant trop longue, seul un extrait est affiché.)
    • Pour plus d'informations, consultez Transmettre une image.

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 :
  • Formats : MP4 ou MOV.
  • Durée : de 1 à 30 secondes.
  • Résolution : la largeur et la hauteur doivent être comprises entre 240 et 4 096 pixels.
  • Rapport d'aspect : de 1:8 à 8:1.
  • Taille du fichier : jusqu'à 100 Mo.
Formats d'entrée pris en charge :
  1. URL publique :
reference_voice 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 :
  • Comportement par défaut : si reference_video contient de l'audio mais que reference_voice n'est pas spécifié, l'audio original de la vidéo est utilisé.
  • Priorité : si reference_video (avec audio) et reference_voice sont tous deux fournis, reference_voice est prioritaire et remplace l'audio original de la vidéo.
Limites relatives à l'audio :
  • Formats : WAV ou MP3.
  • Durée : de 1 à 10 secondes.
  • Taille du fichier : jusqu'à 15 Mo.
Formats d'entrée pris en charge :
  1. URL publique :
parameters object (Facultatif)Paramètres de traitement vidéo, tels que la résolution de la vidéo.

Propriétés

resolution string (Facultatif)
La resolution influe directement sur le coût. Vérifiez le tarif dans la console Model Studio avant d'effectuer l'appel.
Niveau de résolution de la vidéo générée. Contrôle le nombre total de pixels.
  • wan2.7-r2v, wan2.7-r2v-2026-06-12 : les valeurs valides sont 720P et 1080P. La valeur par défaut est 1080P.
ratio string (Facultatif)Rapport d'aspect de la vidéo générée.Comportement :
  • Aucune image de première image fournie : la vidéo utilise le ratio spécifié.
  • Image de première image fournie : le paramètre ratio est ignoré. La vidéo adopte le rapport d'aspect de l'image de première image.
Valeurs valides :
  • 16:9 (par défaut)
  • 9:16
  • 1:1
  • 4:3
  • 3:4
duration integer (Facultatif)
La durée influe directement sur le coût. Consultez la tarification des modèles avant d'appeler l'API.
Durée de la vidéo générée, en secondes.
  • wan2.7-r2v, wan2.7-r2v-2026-06-12 : la valeur par défaut est 5.
    • Si le matériel de référence inclut une vidéo, la valeur doit être un entier compris entre 2 et 10.
    • Si le matériel de référence n'inclut pas de vidéo, la valeur doit être un entier compris entre 2 et 15.
prompt_extendboolean (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.
  • true (par défaut)
  • false
watermark boolean (Facultatif)Ajoute un filigrane. Le texte du filigrane est « AI Generated », placé dans le coin inférieur droit de la vidéo.
  • false (par défaut)
  • true
seed 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

  • Réponse réussie
  • Réponse d'erreur
Enregistrez le task_id pour interroger l'état et le résultat de la tâche.
{
        "output": {
            "task_status": "PENDING",
            "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
        },
        "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
    }
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

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN : la tâche n'existe pas ou son état est inconnu.
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}
Remplacez {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

  • Interroger le résultat de la tâche
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.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY"
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

  • Tâche réussie
  • Échec de la tâche
  • Requête de tâche expirée
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.
{
    "request_id": "52cade0d-905e-9b7d-a01e-xxxxxx",
    "output": {
        "task_id": "18814247-f944-4102-aa4a-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-02 22:53:19.537",
        "scheduled_time": "2026-04-02 22:53:30.427",
        "end_time": "2026-04-02 23:00:39.287",
        "orig_prompt": "Video 2 holds Image 3 and plays a soothing American country ballad in a coffee shop, while Video 1 smiles, watches Video 2, and slowly walks towards him",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?xxxx"
    },
    "usage": {
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "video_count": 1,
        "SR": 720,
        "ratio": "16:9"
    }
}
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

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN : la tâche n'existe pas ou son état est inconnu.
submit_time 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

Nécessite le SDK Python DashScope version 2.0.1 ou ultérieure.Les versions antérieures peuvent déclencher des erreurs telles que « url error, please check url! ». Pour les instructions de mise à jour, consultez Installer le SDK.
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"
Remplacez {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
import dashscope
import os
from dashscope.v2 import DashScopeError

# Voici la configuration de la région de Singapour. Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
client = dashscope.Client(
    # Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par votre API Key de Model Studio : api_key="sk-xxx"
    # Les API Key varient selon la région. Pour obtenir une API Key, voir https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

def sample_sync_call_r2v():
    # Appel synchrone, qui renvoie directement le résultat.
    # generate est un appel en une étape (soumet la tâche et attend sa fin) et retourne un Job terminé.
    print('please wait...')
    try:
        job = client.videos.generate(
            model='wan2.7-r2v-2026-06-12',
            prompt='Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, "The sunshine is so nice today." Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, "That sounds lovely. Can you sing it again?"',
            media=[
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg",
                    "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3"
                },
                {
                    "type": "reference_video",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
                    "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
                }
            ],
            resolution='720P',
            ratio='16:9',
            duration=10,
            prompt_extend=False,
            watermark=True)
        print(job)
        print(job.video_url)
    except DashScopeError as e:
        print(f"Code de statut HTTP: {e.status_code}")
        print(f"Code d'erreur: {e.code}")
        print(f"Message d'erreur: {e.message}")
        print("Consultez la documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_sync_call_r2v()
Exemple de réponse
L'URL video_url est valide pendant 24 heures. Téléchargez la vidéo sans tarder.
{
    "status_code": 200,
    "request_id": "b040d446-f9b6-977f-b9ad-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "5dab3291-393e-424d-929b-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "submit_time": "2026-04-17 17:12:49.076",
        "scheduled_time": "2026-04-17 17:13:00.384",
        "end_time": "2026-04-17 17:29:43.386",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\""
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720,
        "ratio": "16:9"
    }
}

SDK Java

Assurez-vous que la version du SDK Java DashScope est au moins 2.22.14 avant d'exécuter le code suivant.Les versions antérieures peuvent déclencher des erreurs telles que « url error, please check url! ». Pour les instructions de mise à jour, consultez Installer le SDK.
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";
Remplacez {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
// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Ref2Video {

    static {
        // The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured environment variables, replace the following line with your Model Studio API key: apiKey="sk-xxx"
    // The API key varies by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void ref2video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        List<VideoSynthesisParam.Media> media = new ArrayList<VideoSynthesisParam.Media>(){{
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg")
                    .type("reference_image")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4")
                    .type("reference_video")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png")
                    .type("reference_image")
                    .build());
        }};
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("resolution", "720P");
        parameters.put("ratio", "16:9");
        parameters.put("prompt_extend", false);
        parameters.put("watermark", true);

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-r2v-2026-06-12")
                        .prompt("Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"")
                        .media(media)
                        .duration(10)
                        .parameters(parameters)
                        .build();
        System.out.println("please wait...");
        VideoSynthesisResult result = vs.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            ref2video();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}
Exemple de réponse
L'URL video_url est valide pendant 24 heures. Téléchargez la vidéo sans tarder.
{
    "request_id": "f6365287-336f-9f2b-ab59-xxxxxx",
    "output": {
        "task_id": "cb7f1da5-a987-41de-b0a4-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxxx",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"",
        "submit_time": "2026-04-17 17:15:11.536",
        "scheduled_time": "2026-04-17 17:15:20.316",
        "end_time": "2026-04-17 17:29:44.277"
    },
    "usage": {
        "video_count": 1,
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

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.
{
    "media": [
        {
            "type": "reference_image",
            "url": "<URL of the reference image>",
            "reference_voice": "<URL of the audio>"
        },
        {
            "type": "reference_video",
            "url": "<URL of the reference video>",
            "reference_voice": "<URL of the audio>"
        }
    ]
}