Tous les produits
Search

Ce produit

    Alibaba Cloud Model Studio:Wan3.0 - Référence de l'API de génération vidéo

    Centre de documentation

    Alibaba Cloud Model Studio:Wan3.0 - Référence de l'API de génération vidéo

    Dernière mise à jour :Oct 15, 2026

    Wan3.0 est un modèle tout-en-un de génération vidéo basé sur des références. Il prend en charge les modes Texte vers vidéo , Image vers vidéo (première image / première et dernière images) et Génération vidéo basée sur des références . Ce modèle permet de générer des vidéos d'une durée maximale de 30 secondes.

    Prérequis

    Pour garantir le succès de vos appels API, assurez-vous que le modèle, l'URL de l'endpoint et la clé API appartiennent tous à la même région. Les appels interrégionaux échouent systématiquement.

    • Sélectionner un modèle : Accédez à la galerie de modèles pour en choisir un et confirmer sa région.
    • Choisir une URL : Sélectionnez l'URL de l'endpoint correspondant à votre région.
    • Configurer la clé API : Choisissez une région, puis Obtenez une clé API. Ensuite, Configurez cette clé comme variable d'environnement.

    RemarqueLes exemples de code de cette rubrique s'appliquent à la région de Singapour.

    Appel HTTP

    La génération vidéo nécessitant un temps de traitement relativement long (généralement entre 1 et 5 minutes), l'API fonctionne de manière asynchrone. Le processus complet se déroule en deux étapes principales : « Création d'une tâche -> Interrogation des résultats », détaillées ci-dessous :

    Étape 1 : Créer une tâche et obtenir son ID

    Singapore

    POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

    Beijing

    POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

    Remarque

    • 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. Évitez de créer des tâches en double ; privilégiez plutôt l'interrogation périodique pour récupérer le résultat.
    • Pour un guide destiné aux débutants, reportez-vous à Appeler des API avec Postman ou cURL.

    Paramètres de la requête

    Fichier de référence vers vidéo

    Transmettez un fichier via le type file ; le modèle analysera automatiquement son contenu pour générer la 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": "wan3.0-video",
        "input": {
            "prompt": "A high-end smart glasses product advertisement with a minimalist, futuristic, and fashionable style. The color palette features black, silver-gray, and ice-blue tones with subtle white light accents and parameter UI graphics. Opening in pure black background, a pair of smart glasses slowly emerges from darkness with refined highlights on the temple edges. The camera captures ultra-close details of lenses, nose pads, hinges, temples, and material textures, showcasing metal and high-performance composite materials. The product then rotates slowly in mid-air with minimalist motion graphics displaying core parameters. Then the camera pulls back as all parts precisely reassemble into the complete product, transitioning to a young model wearing demonstration in minimalist spaces and urban lighting environments.",
            "media": [
                {
                    "type": "file",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260806/ebapmr/glass.pptx"
                }
            ]
        },
        "parameters": {
            "resolution": "480P",
            "ratio": "adaptive",
            "duration": 10
        }
    }'

    Génération vidéo basée sur des références

    Fournissez des images, vidéos, fichiers audio, documents ou liens web de référence via input.media. Le modèle interprétera automatiquement votre intention pour produire la 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": "wan3.0-video",
        "input": {
            "prompt": "Video 1 holds Image 3 and plays a soothing country folk song on the chair in Image 4, saying: '\''The sunshine is so nice today.'\'' Image 1 holds Image 2, passes by Video 1, places Image 2 on the table next to Video 1, and says: '\''That sounds beautiful, 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"
                },
                {
                    "type": "reference_video",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4"
                },
                {
                    "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": "480P",
            "ratio": "adaptive",
            "duration": 5
        }
    }'

    Texte vers vidéo

    Générez une vidéo en utilisant uniquement un prompt, sans fournir de fichiers multimédias.

    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": "wan3.0-video",
        "input": {
            "prompt": "A kitten running on a rooftop under the moonlight, neon lights of the city flickering in the distance, cinematic quality, smooth camera movement."
        },
        "parameters": {
            "resolution": "480P",
            "ratio": "adaptive",
            "duration": 5
        }
    }'

    Première image vers vidéo

    Spécifiez strictement la première image de la vidéo à l'aide du paramètre first_frame.

    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": "wan3.0-video",
        "input": {
            "prompt": "An urban fantasy art scene. A dynamic graffiti art character. A spray-painted teenager coming to life from a concrete wall. He raps at an extremely fast pace while striking a classic, energetic rapper pose. The scene is set under a railway bridge at night with an urban vibe. Lighting comes from a solitary streetlamp, creating a cinematic atmosphere full of high energy and stunning detail. The audio of the video consists entirely of rap, with no other dialogue or noise.",
            "media": [
                {
                    "type": "first_frame",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
                }
            ]
        },
        "parameters": {
            "resolution": "480P",
            "ratio": "adaptive",
            "duration": 5
        }
    }'

    Première et dernière images vers vidéo

    Fournissez à la fois first_frame et last_frame pour définir précisément les images de début et de fin de la 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": "wan3.0-video",
        "input": {
            "prompt": "A young girl gradually transitions from a smile to laughter, the camera slowly pushing in, background lighting shifting from cool to warm tones.",
            "media": [
                {
                    "type": "first_frame",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
                },
                {
                    "type": "last_frame",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg"
                }
            ]
        },
        "parameters": {
            "resolution": "480P",
            "ratio": "adaptive",
            "duration": 5
        }
    }'
    En-têtes de requête (Headers)

    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.

    ImportantSi cet en-tête est absent, l'erreur « current user api does not support synchronous calls » est retournée.

    Corps de la requête (Request Body)

    model string (Obligatoire)

    Nom du modèle. Valeur fixe : wan3.0-video.

    input object (Obligatoire)

    Informations d'entrée de base. Vous devez fournir soit prompt, soit media.

    Propriétés

    prompt string (Conditionnellement obligatoire)

    Invite textuelle décrivant le contenu vidéo souhaité. Ce champ ou media doit être renseigné.

    Prend en charge le chinois et l'anglais. Chaque caractère chinois ou lettre compte pour un caractère, avec une limite maximale de 20 000 caractères. Tout contenu dépassant cette limite sera automatiquement tronqué.

    En mode référence, vous pouvez utiliser « Image 1 », « Vidéo 1 », etc. dans l'invite pour désigner les ressources multimédias selon leur ordre d'apparition dans le tableau media.

    media array (Conditionnellement obligatoire)

    Tableau de ressources multimédias acceptant des images, vidéos, fichiers audio, documents et pages web en entrée. Ce champ ou prompt doit être renseigné.

    • Chaque élément du tableau est un objet média contenant les champs type et url.

    • Dans le mode de génération vidéo basée sur des références, l'ordre du tableau détermine l'ordre de référence des ressources dans le prompt. Les images et les vidéos sont comptées séparément ; ainsi, Image 1 et Vidéo 1 peuvent coexister.

      • La première occurrence de reference_video dans le tableau correspond à Vidéo 1, la seconde à Vidéo 2, et ainsi de suite.
      • La première occurrence de reference_image dans le tableau correspond à Image 1, la seconde à Image 2, et ainsi de suite.
      • La première occurrence de reference_audio dans le tableau correspond à Audio 1, la seconde à Audio 2, et ainsi de suite.

    Propriétés

    type string (Obligatoire)

    Type de ressource multimédia. Valeurs valides :

    • first_frame : Première image. Une seule image maximum, utilisée strictement comme première image de la vidéo.
    • last_frame : Dernière image. Une seule image maximum, utilisée strictement comme dernière image de la vidéo.
    • reference_image : Image de référence. Jusqu'à 10 images autorisées.
    • reference_video : Vidéo de référence. Jusqu'à 5 clips, pour une durée totale n'excédant pas 15 secondes.
    • reference_audio : Audio de référence. Jusqu'à 5 clips, pour une durée totale n'excédant pas 15 secondes.
    • file : Fichier. Un seul fichier maximum ; incompatible avec le type link.
    • link : Lien web. Un seul lien maximum ; incompatible avec le type file.

    ImportantLes types reference_xx/file/link et les types first_frame/last_frame sont mutuellement exclusifs et ne peuvent pas être combinés dans une même requête.

    url string (Obligatoire)

    URL de la ressource multimédia ou données encodées en Base64.

    Image d'entrée (type=first_frame / last_frame / reference_image)

    URL de l'image ou données encodées en Base64.

    Contraintes relatives aux images :

    • Formats acceptés : JPEG, JPG, PNG (canal alpha non pris en charge), BMP, WEBP.
    • Résolution : comprise entre 240 et 8 000 pixels par côté.
    • Rapport hauteur/largeur : inférieur ou égal à 8:1.
    • Taille du fichier : 20 Mo maximum.

    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 de détails, consultez Image d'entrée.

    Vidéo d'entrée (type=reference_video)

    URL de la vidéo de référence.

    Contraintes relatives aux vidéos :

    • Formats acceptés : mp4, mov.
    • Durée : de 1 à 15 secondes par clip, pour une durée totale n'excédant pas 15 secondes.
    • Résolution : comprise entre 240 et 4 096 pixels par côté.
    • Rapport hauteur/largeur : inférieur ou égal à 8:1.
    • Taille par clip : 100 Mo maximum.

    Formats d'entrée pris en charge :

    1. URL publique :

    Audio d'entrée (type=reference_audio)

    URL du fichier audio de référence.

    Contraintes relatives aux fichiers audio :

    • Formats acceptés : wav, mp3.
    • Durée : de 1 à 15 secondes par clip, pour une durée totale n'excédant pas 15 secondes.
    • Taille du fichier : 15 Mo maximum.

    Formats d'entrée pris en charge :

    1. URL publique :

    Fichier d'entrée (type=file)

    URL du fichier.

    Contraintes relatives aux fichiers :

    • Formats acceptés : docx, doc, xlsx, xls, pptx, ppt, pdf, txt, key, pages, numbers, md.
    • Taille du fichier : 100 Mo maximum.
    • Nombre de pages : 50 pages maximum (validation effectuée pour les formats pdf, docx, doc, pptx, ppt, key, pages).

    Formats d'entrée pris en charge :

    1. URL publique :

    parameters object (Facultatif)

    Paramètres de traitement vidéo.

    Propriétés

    resolution string (Facultatif)

    Niveau de résolution de la vidéo générée. Valeur par défaut : 1080P. Valeurs valides :

    • 1080P
    • 720P
    • 480P

    ratio string (Facultatif)

    Rapport hauteur/largeur de la vidéo générée. Valeurs valides :

    • adaptive (Valeur par défaut) : Rapport adaptatif qui recommande automatiquement un format approprié en fonction des proportions des médias d'entrée et de l'intention détectée.
    • 21:9
    • 16:9
    • 4:3
    • 1:1
    • 3:4
    • 9:16

    duration integer (Facultatif)

    Durée de la vidéo générée, exprimée en secondes. Valeur par défaut : 5.

    • Sans vidéo en entrée : nombre entier compris dans l'intervalle [2, 30].
    • Avec vidéo en entrée : la somme de la durée de la vidéo d'entrée et de celle de la vidéo générée ne doit pas excéder 30 secondes.
    • Si la valeur est définie à -1 : Mode durée intelligente. Le modèle recommande alors automatiquement une durée adaptée en fonction de l'invite, du contenu et des éléments multimédias fournis.

    audio boolean (Facultatif)

    Indique si la vidéo générée doit contenir une piste audio.

    • true : Valeur par défaut. La vidéo générée inclut une piste audio.
    • false : La vidéo générée ne contient aucune piste audio.

    L'activation ou la désactivation de l'audio n'a aucun impact sur la tarification.

    seed integer (Facultatif)

    Graine aléatoire permettant de reproduire les résultats de génération. Plage de valeurs : [0, 2147483647].

    watermark boolean (Facultatif)

    Indique s'il faut ajouter un filigrane.

    • false : Valeur par défaut. Aucun filigrane n'est ajouté.
    • true : Un filigrane est appliqué à la vidéo.

    Paramètres de la réponse

    Réponse réussie

    Conservez le task_id afin de pouvoir interroger ultérieurement 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"
    }

    Réponse d'erreur

    La création de la tâche a échoué. Consultez la section Codes d'erreur.

    {
        "code": "InvalidApiKey",
        "message": "No API-key provided.",
        "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
    }

    output object

    Informations de sortie de la tâche.

    Propriétés

    task_id string

    Identifiant unique de la tâche. Valide pour les requêtes pendant 24 heures.

    task_status string

    État actuel 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 string

    Identifiant unique de la requête, utilisé pour le suivi et le dépannage.

    code string

    Code d'erreur. Retourné uniquement en cas d'échec de la requête. Consultez la section Codes d'erreur.

    message string

    Message d'erreur détaillé. Retourné uniquement en cas d'échec de la requête. Consultez la section Codes d'erreur.

    Étape 2 : Interroger les résultats à l'aide de l'ID de tâche

    Singapore

    GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

    Beijing

    GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

    Remarque

    • Recommandation d'interrogation : La génération vidéo prenant plusieurs minutes, mettez en place un mécanisme d'interrogation périodique avec un intervalle raisonnable (par exemple, toutes les 15 secondes).
    • Transition des états de tâche : PENDING → RUNNING → SUCCEEDED ou FAILED.
    • Lien de résultat : Une fois la tâche terminée avec succès, une URL vidéo valide pendant 24 heures est retournée. Téléchargez et sauvegardez rapidement la vidéo dans un stockage permanent, tel qu'OSS.
    • Validité dutask_id:24 heures**. Passé ce délai, toute interrogation retourne l'état UNKNOWN.

    Paramètres de la requête

    Interroger les résultats d'une tâche

    Remplacez {task_id} par la valeur task_id retournée lors de l'appel API précédent. Le task_id reste 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 de requête (Headers)

    Authorization string (Obligatoire)

    Authentifie la requête à l'aide d'une clé API Model Studio. Exemple : Bearer sk-xxxx.

    Paramètres de chemin URL (Path parameters)

    task_id string (Obligatoire)

    Identifiant unique de la tâche.

    Paramètres de la réponse

    Tâche réussie

    Les URL vidéo ne sont valides que pendant 24 heures avant d'être automatiquement supprimées. Pensez à sauvegarder rapidement vos vidéos générées.

    {
    "request_id": "78c9b768-0285-996c-b682-xxxxxx",
    "output": {
        "task_id": "17ed7e50-00cf-4509-aea1-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-08-06 10:01:35.452",
        "scheduled_time": "2026-08-06 10:01:35.507",
        "end_time": "2026-08-06 10:13:33.838",
        "orig_prompt": "A golden retriever running on a sunny beach, waves crashing in the background, cinematic lighting",
        "video_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/video.mp4"
    },
    "usage": {
        "video_count": 1,
        "duration": 5,
        "input_video_duration": 0,
        "output_video_duration": 5,
        "fps": 30,
        "SR": 720,
        "ratio": "16:9"
    }
}

    Échec de la tâche

    En cas d'échec, task_status passe à FAILED et un code d'erreur accompagné d'un message est retourné. Consultez la section Codes d'erreur.

    {
        "request_id": "e5e57877-c0fc-47ed-8fad-xxxxxx",
        "output": {
            "task_id": "eff1443c-ccab-4676-aad3-xxxxxx",
            "task_status": "FAILED",
            "code": "InvalidParameter",
            "message": "The two modes are mutually exclusive. Do not pass reference_xx and first_frame/last_frame at the same time."
        }
    }

    Expiration de la requête de tâche

    Le task_id est valide pendant 24 heures. Passé ce délai, toute interrogation retourne l'erreur suivante.

    {
        "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
        "output": {
            "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
            "task_status": "UNKNOWN"
        }
    }

    output object

    Informations de sortie de la tâche.

    Propriétés

    task_id string (Obligatoire)

    Identifiant unique de la tâche.

    task_status string

    État actuel 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 string

    Heure de soumission de la tâche. L'heure est indiquée au fuseau UTC+8 et le format est AAAA-MM-JJ HH:mm:ss.SSS.

    scheduled_time string

    Heure d'exécution de la tâche. L'heure est indiquée au fuseau UTC+8 et le format est AAAA-MM-JJ HH:mm:ss.SSS.

    end_time string

    Heure de fin de la tâche. L'heure est indiquée au fuseau UTC+8 et le format est AAAA-MM-JJ HH:mm:ss.SSS.

    orig_prompt string

    Invite d'entrée originale.

    video_url string

    URL de la vidéo générée. Retournée uniquement lorsque la tâche aboutit avec succès. Le format vidéo est MP4 (encodage H.264).

    code string

    Code d'erreur. Retourné uniquement en cas d'échec de la requête. Consultez la section Codes d'erreur.

    message string

    Message d'erreur détaillé. Retourné uniquement en cas d'échec de la requête. Consultez la section Codes d'erreur.

    usage object

    Statistiques de sortie. Ne comptabilise que les résultats réussis.

    Propriétés

    video_count integer

    Nombre de vidéos générées. Toujours fixé à 1.

    duration integer

    Durée totale de la vidéo, en secondes. En l'absence de vidéo de référence en entrée, elle est égale à la durée de la vidéo de sortie ; lorsqu'une vidéo de référence est fournie en entrée, elle est égale à la somme de la durée de la vidéo d'entrée et de la durée de la vidéo de sortie.

    input_video_duration integer

    Durée de la vidéo fournie en entrée, en secondes. Vaut 0 si aucune vidéo n'a été transmise.

    output_video_duration integer

    Durée de la vidéo générée en sortie, en secondes.

    fps integer

    Fréquence d'images de la vidéo générée.

    SR integer

    Résolution de la vidéo générée. Exemple : 720.

    ratio string

    Rapport hauteur/largeur de la vidéo générée. Exemple : 16:9.

    request_id string

    Identifiant unique de la requête, utilisé pour le suivi et le dépannage.