Skip to main content

Wan - video editing (2.1)

Le modèle unifié de montage vidéo Wan 2.1 prend en charge plusieurs modalités d'entrée, notamment le texte, les images et les vidéos, pour une large gamme de tâches de génération et de montage vidéo.

Documentation associée : guide utilisateur

Périmètre

Pour garantir le succès des appels, le modèle, l'URL de l'endpoint et la clé API doivent se trouver dans 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 du modèle. Les URL HTTP sont prises en charge.
  • Configurer une clé API : sélectionnez une région, obtenez une clé API, puis configurez-la dans vos variables d'environnement.
Les exemples de code de cette rubrique concernent 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.

Appel HTTP

Le traitement par le modèle unifié de montage vidéo nécessite entre 5 et 10 minutes. L'API utilise donc un processus asynchrone articulé autour de deux étapes principales : « créer une tâche -> interroger le résultat ».

Étape 1 : Créer une tâche

  • Singapore
  • Beijing
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesisRemplacez {WorkspaceId} par votre véritable ID d'espace de travail.

Paramètres de la requête

  • Référence multi-images
  • Repeinture vidéo
  • Montage local
  • Extension vidéo
  • Outpainting vidéo
API keys for the Singapore and China (Beijing) regions are different. Obtain an API key
The following URL is for the Singapore region. For the China (Beijing) region, use this URL instead: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
# The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
    curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    --header 'X-DashScope-Async: enable' \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
        "model": "wan2.1-vace-plus",
        "input": {
            "function": "image_reference",
            "prompt": "In the video, a girl gracefully emerges from a misty, ancient forest. Her steps are light, and the camera captures her every nimble moment. When she stops to look at the lush woods around her, a smile of surprise and joy blossoms on her face. This scene, frozen in an interplay of light and shadow, records her wonderful encounter with nature.",
            "ref_images_url": [
                "http://wanx.alicdn.com/material/20250318/image_reference_2_5_16.png",
                "http://wanx.alicdn.com/material/20250318/image_reference_1_5_16.png"
            ]
        },
        "parameters": {
            "prompt_extend": true,
            "obj_or_bg": ["obj","bg"],
            "size": "1280*720"
        }
    }'
En-têtes de la requête
Content-Type string (Required)Type de contenu de la requête. Doit être application/json.
Authorization string (Required)Authentifie la requête à l'aide d'une clé API Model Studio. Exemple : Bearer sk-xxxx.
X-DashScope-Async string (Required)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 renvoyée.
Corps de la requête
  • Référence multi-images
  • Repeinture vidéo
  • Montage local
  • Extension vidéo
  • Outpainting vidéo
model string (Required)Nom du modèle. Exemple : wan2.1-vace-plus.
input object (Required)Entrée de base, telle que le prompt.

Properties

promptstring(Required)Décrit les éléments et les caractéristiques visuelles à inclure dans la vidéo générée.Prend en charge le chinois et l'anglais. La longueur maximale est de 800 caractères, chaque caractère chinois ou lettre comptant comme un seul caractère. Le texte dépassant cette limite est automatiquement tronqué.Pour les techniques de prompting, consultez le Guide de prompts Texte-vers-Vidéo/Image-vers-Vidéo.functionstring(Required)Nom de la fonctionnalité. Pour la référence multi-images, la valeur est image_reference.La référence multi-images accepte jusqu'à 3 images de référence. Ces images peuvent contenir des entités et des arrière-plans, tels que des personnes, des animaux, des vêtements et des scènes. Utilisez un prompt pour décrire le contenu vidéo souhaité, et le modèle combinera les multiples images pour générer un contenu vidéo cohérent.ref_images_urlarray[string] (Required)Tableau d'URL d'images de référence.
  1. URL publique :
Vous pouvez fournir 1 à 3 images de référence. Si vous en fournissez plus de 3, seules les 3 premières seront utilisées.Exigences relatives aux images :
  • Format : JPG, JPEG, PNG, BMP, TIFF ou WEBP.
  • Résolution : la largeur et la hauteur doivent se situer dans la plage de [360, 2000] pixels.
  • Taille : jusqu'à 10 Mo.
  • L'URL ne doit pas contenir de caractères chinois.
Recommandations :
  • Lorsque vous utilisez une image de référence pour une entité, nous vous recommandons de n'inclure qu'une seule entité par image. L'arrière-plan doit être de couleur unie (par exemple, blanc) afin de mieux mettre en valeur l'entité.
  • Si vous utilisez un arrière-plan issu d'une image de référence, vous ne pouvez fournir qu'une seule image d'arrière-plan, laquelle ne doit contenir aucune entité.
parameters object (Optional)Paramètres de traitement vidéo, tels que les paramètres de filigrane.

Properties

obj_or_bg array[string] (Optional)Ce paramètre permet d'identifier la finalité de chaque image de référence et correspond un à un au paramètre ref_images_url. Chaque élément du tableau précise si l'image à la position correspondante est un « sujet » ou un « arrière-plan » :
  • obj : indique que l'image constitue l'entité de référence.
  • bg : spécifie que l'image sert de référence d'arrière-plan (une seule autorisée au maximum).
Notes d'utilisation :
  • Nous vous recommandons de transmettre ce paramètre ; sa longueur doit être identique à celle de ref_images_url, faute de quoi une erreur sera signalée.
  • Ce paramètre peut être omis et prendra par défaut la valeur ["obj"] uniquement si ref_images_url est un tableau à un seul élément.
Exemple : ["obj", "obj", "bg"].size string (Optional)Résolution de la vidéo générée (largeur*hauteur). Le modèle prend en charge la génération de vidéos 720p. Valeurs valides :
  • 1280*720 (par défaut) : le format d'image vidéo est 16:9, où 1280 correspond à la largeur et 720 à la hauteur.
  • 720*1280 : le format d'image vidéo est 9:16.
  • 960*960 : le format d'image vidéo est 1:1.
  • 832*1088 : le format d'image vidéo est 3:4.
  • 1088*832 : le format d'image vidéo est 4:3.
duration integer (Optional)Durée de la vidéo générée, en secondes. Cette valeur est fixée à 5.prompt_extendbool (Optional)Indique s'il faut activer la réécriture du prompt. Si cette option est activée, un grand modèle de langage (LLM) réécrit le prompt d'entrée. Cela peut améliorer considérablement les résultats pour les prompts courts, mais augmente le temps de traitement.
  • true (par défaut) : active la réécriture du prompt.
  • false : désactive la réécriture du prompt.
seedinteger(Optional)La graine de nombre aléatoire contrôle l'aléatoire du contenu généré par le modèle. La plage de valeurs pour le paramètre seed est [0, 2147483647].Si vous ne spécifiez pas de graine, celle-ci est générée automatiquement. Pour obtenir des résultats reproductibles, utilisez la même valeur de graine pour plusieurs requêtes.watermark bool(Optional)Indique s'il faut ajouter un filigrane « Généré par IA » dans le coin inférieur droit de l'image.
  • false (par défaut) : n'ajoute pas de filigrane.
  • true : ajoute un filigrane.

Paramètres de 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 objectSortie de la tâche asynchrone.

Properties

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. Renvoyé uniquement pour les requêtes ayant échoué. Consultez les Codes d'erreur.
message stringMessage d'erreur détaillé. Renvoyé uniquement pour les requêtes ayant échoué. Consultez les Codes d'erreur.

Étape 2 : Interroger le résultat par ID de tâche

  • Singapore
  • China (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.

Paramètres de la requête

  • Interroger le résultat de la tâche
Remplacez {task_id} par la valeur task_id renvoyé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 de la requête
Authorization string (Required)Authentifie la requête à l'aide d'une clé API Model Studio. Exemple : Bearer sk-xxxx.
Paramètres de chemin d'URL
task_id string (Required)ID de la tâche.

Paramètres de réponse

  • Tâche réussie
  • Échec de la tâche
Les données de la tâche, y compris l'état de la tâche et l'URL de la vidéo, sont disponibles pendant 24 heures, puis supprimées automatiquement. Enregistrez rapidement la vidéo générée.
{
    "request_id": "851985d0-fbba-9d8d-a17a-xxxxxx",
    "output": {
        "task_id": "208e2fd1-fcb4-4adf-9fcc-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-05-15 16:14:44.723",
        "scheduled_time": "2025-05-15 16:14:44.750",
        "end_time": "2025-05-15 16:20:09.389",
        "video_url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.mp4?xxxxxx",
        "orig_prompt": "In the video, a girl gracefully walks out from a misty, ancient forest. Her steps are light, and the camera captures her every nimble moment. When the girl stops and looks around at the lush woods, a smile of surprise and joy blossoms on her face. This scene, frozen in a moment of interplay between light and shadow, records her wonderful encounter with nature.",
        "actual_prompt": "A girl in a light-colored long dress slowly walks out from a misty, ancient forest, her steps as light as a dance. She has slightly curly long hair, a delicate face, and bright eyes. The camera follows her movements, capturing every nimble moment. When she stops, turns, and looks around at the lush woods, a smile of surprise and joy blossoms on her face. Sunlight filters through the leaves, casting mottled shadows and freezing this beautiful moment of harmony between human and nature. The style is a fresh and natural portrait, combining medium and full shots with a level perspective and slight camera movement."
    },
    "usage": {
        "video_duration": 5,
        "video_ratio": "standard",
        "video_count": 1
    }
}
outputobjectInformations sur la sortie de la tâche.

Properties

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.
submit_time stringHeure de soumission de la tâche. L'heure est en UTC+8 et le format est AAAA-MM-JJ HH:mm:ss.SSS.scheduled_time stringHeure d'exécution de la tâche. L'heure est en UTC+8 et le format est AAAA-MM-JJ HH:mm:ss.SSS.end_time stringHeure de fin de la tâche. L'heure est en UTC+8 et le format est AAAA-MM-JJ HH:mm:ss.SSS.video_urlstringURL de la vidéo MP4 (H.264) générée. Ce lien est valide pendant 24 heures.orig_prompt stringPrompt d'entrée original.actual_prompt stringPrompt utilisé pour la génération après réécriture du prompt. Ce champ n'est renvoyé que si la réécriture du prompt est activée.code stringCode d'erreur. Renvoyé uniquement pour les requêtes ayant échoué. Consultez les Codes d'erreur.message stringMessage d'erreur détaillé. Renvoyé uniquement pour les requêtes ayant échoué. Consultez les Codes d'erreur.
usage objectStatistiques pour la sortie de la tâche. Fourni uniquement pour les tâches réussies.

Properties

video_duration integerDurée de la vidéo générée, en secondes.video_ratio stringFormat d'image de la vidéo générée. La valeur est toujours standard.video_count integerNombre de vidéos générées.
request_id stringIdentifiant unique de la requête pour le suivi et le dépannage.

Limitations

  • Durée de conservation des données : l'ID de tâche task_id et l'URL de la vidéo video_url ne sont conservés que pendant 24 heures. Passé ce délai, il n'est plus possible de les interroger ni de les télécharger.
  • Prise en charge audio : cette fonctionnalité ne génère actuellement que des vidéos muettes. Pour générer de l'audio, utilisez la Synthèse vocale.

Codes d'erreur

Si un appel de modèle échoue avec un message d'erreur, consultez les Codes d'erreur pour le dépannage.

FAQ

Q : Comment mettre en liste d'autorisation les domaines de stockage vidéo ?

R : Les vidéos générées par les modèles sont stockées dans OSS. L'API renvoie une URL publique temporaire. Pour configurer une liste d'autorisation de pare-feu pour cette URL de téléchargement, notez ce qui suit : le stockage sous-jacent peut changer dynamiquement. Cette rubrique ne fournit pas de liste d'autorisation de noms de domaine OSS fixe afin d'éviter les problèmes d'accès causés par des informations obsolètes. Si vous avez des exigences en matière de contrôle de sécurité, contactez votre gestionnaire de compte pour obtenir la liste la plus récente des noms de domaine OSS.