Skip to main content

Wan - Référence de l'API de remplacement de personnage vidéo

Remplace le personnage principal d'une vidéo par un personnage issu d'une image, tout en conservant la scène originale, l'éclairage et la tonalité pour une intégration transparente.

  • Fonctionnalités principales : Substitue le personnage d'une vidéo par une personne provenant d'une image spécifiée, en préservant les actions, les expressions et l'environnement de la vidéo originale.
  • Cas d'usage : Idéal pour remplacer des personnages lors de la création de contenus dérivés et en post-production.
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 à https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapour : de https://dashscope-intl.aliyuncs.com à https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} correspond à votre ID d'espace de travail, disponible sur la page Workspace Details dans la console Alibaba Cloud Model Studio. Le domaine existant reste pleinement fonctionnel.

Exemples

wan2,2-animate-mix prend en charge deux modes de service : le mode standard (wan-std) et le mode professionnel (wan-pro). Consultez la section Facturation et limitation du débit pour connaître les différences de performance et de tarification.
Image du personnageVidéo de référenceVidéo générée (mode standardwan-std)Vidéo générée (mode professionnelwan-pro)
mix_input_image

HTTP

Obtenez une clé API et exportez-la en tant que variable d'environnement.
Les régions Chine (Pékin) et Singapour disposent de clés API et d'endpoints de requête distincts. Elles ne sont pas interchangeables. Les appels interrégionaux entraînent des échecs d'authentification ou des erreurs de service.
Le remplacement de personnage étant une opération longue, l'API utilise une invocation asynchrone : créez une tâche, puis interrogez régulièrement le système pour obtenir le résultat.

Étape 1 : Créer une tâche

Singapour :POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis Pékin :POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2video/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

  • Remplacement de personnage vidéo
Voici l'URL de la région Singapour. Remplacez {WorkspaceId} par votre ID d'espace de travail Bailian. Les URL varient selon la région.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \
        --header 'X-DashScope-Async: enable' \
        --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
        --header 'Content-Type: application/json' \
        --data '{
            "model": "wan2.2-animate-mix",
            "input": {
                "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg",
                "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4",
                "watermark": true
            },
            "parameters": {
                "mode": "wan-std"
            }
          }'
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. Définissez cette valeur à wan2.2-animate-mix.
input object (Obligatoire)Images et vidéo d'entrée pour le remplacement de personnage.

Propriétés

image_url string (Obligatoire)URL HTTP ou HTTPS accessible publiquement pour l'image du personnage. L'URL ne doit pas contenir de caractères non ASCII (par exemple, des caractères chinois). Si c'est le cas, encodez l'URL avant de la transmettre.
  • Format : JPG, JPEG, PNG, BMP ou WEBP.
  • Résolution : La largeur et la hauteur doivent chacune se situer dans la plage [200, 4096] pixels. Le rapport d'aspect doit être compris entre 1:3 et 3:1.
  • Taille du fichier : Jusqu'à 5 Mo.
  • Exemple : https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg
video_url string (Obligatoire)URL HTTP ou HTTPS accessible publiquement pour la vidéo de référence. L'URL ne doit pas contenir de caractères non ASCII (par exemple, des caractères chinois). Si c'est le cas, encodez l'URL avant de la transmettre.Astuce : Une résolution et une fréquence d'images plus élevées améliorent la qualité du résultat.
  • Format : MP4, AVI ou MOV.
  • Résolution : La largeur et la hauteur doivent chacune se situer dans la plage [200, 2048] pixels. Le rapport d'aspect doit être compris entre 1:3 et 3:1.
  • Taille du fichier : Jusqu'à 200 Mo.
  • Durée : De 2 à 30 secondes.
  • Exemple : https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4
watermark boolean (Facultatif)Ajoute un filigrane « AI Generated » dans le coin inférieur droit de la vidéo générée.
  • false (par défaut) : Aucun filigrane.
  • true : Filigrane ajouté.
parameters object (Obligatoire)

Propriétés

check_image boolean (Facultatif)Détermine si l'image d'entrée est vérifiée avant le traitement.
  • true (par défaut) : Vérifie l'image d'entrée avant le traitement.
  • false : Ignore la vérification et traite l'image directement.
mode string (Obligatoire)Mode de service. Deux modes sont disponibles :
  • wan-std : Mode standard. Génération plus rapide à moindre coût. Idéal pour les aperçus rapides et les animations de base.
  • wan-pro : Mode professionnel. Animations plus fluides et meilleure qualité visuelle, avec un temps de traitement plus long et un coût plus élevé.
Pour plus de détails, consultez les sections Exemples et Facturation et limitation du débit.

Paramètres de la réponse

  • Réponse réussie
  • Réponse d'erreur
Conservez 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.
message stringMessage d'erreur détaillé. Retourné uniquement pour les requêtes ayant échoué. Consultez la section Codes d'erreur.
code stringCode d'erreur. 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

  • Chine (Pékin)
  • Singapour
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}Lors de l'appel, remplacez {WorkspaceId} par votre véritable ID d'espace de travail.
  • Singapour
  • Chine (Pékin)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Lors de l'appel, remplacez {WorkspaceId} par votre véritable ID d'espace de travail.
  • Recommandation d'interrogation : La génération vidéo prend plusieurs minutes. Mettez en place 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 : Une fois la tâche réussie, 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 0385dc79-5ff8-4d82-bcb6-xxxxxx par votre véritable task_id.
Voici l'URL de la région Singapour. Remplacez {WorkspaceId} par votre ID d'espace de travail Bailian. Les URL varient selon la région.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx \
        --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 URL
task_id string (Obligatoire)ID de la tâche.

Paramètres de la réponse

  • Tâche réussie
  • Échec de la tâche
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": "a67f8716-18ef-447c-a286-xxxxxx",
    "output": {
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-18 15:32:00.105",
        "scheduled_time": "2025-09-18 15:32:15.066",
        "end_time": "2025-09-18 15:34:41.898",
        "results": {
            "video_url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxx.mp4?Expires=xxxxxx"
        }
    },
    "usage": {
        "video_duration": 5,2,
        "video_ratio": "standard"
    }
}
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.
submit_time stringHeure de soumission de la tâche. L'heure est au format 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 au format 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 au format UTC+8 et le format est AAAA-MM-JJ HH:mm:ss.SSS.results object

Propriétés

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.
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 objectRetourné uniquement pour les tâches réussies.

Propriétés

video_duration floatDurée de la vidéo générée, en secondes.video_ratio stringMode de service utilisé pour cette requête. Retourne standard pour le mode wan-std, ou pro pour le mode wan-pro.
request_id stringIdentifiant unique de la requête pour le suivi et le dépannage.

Limitations

Rétention des données : Les ID de tâche et les URL vidéo sont conservés pendant 24 heures. Téléchargez la vidéo sur votre appareil local avant leur expiration. Modération du contenu : Tout le contenu d'entrée et de sortie est soumis à modération. Un contenu prohibé retourne les erreurs IPInfringementSuspect ou DataInspectionFailed. Pour plus de détails, consultez la section Codes d'erreur.

Facturation et limitation du débit

  • Pour le quota gratuit et le prix unitaire, consultez la section Tarification des modèles.
  • Pour les limites de débit, consultez la section Série Wan.
  • Détails de facturation :
    • La facturation repose sur la durée de la vidéo générée (en secondes), uniquement pour les vidéos produites avec succès. L'entrée n'est pas facturée.
    • Les appels échoués et les erreurs de traitement n'entraînent aucun frais et ne consomment pas de quota gratuit.

Codes d'erreur

En cas d'échec d'un appel, consultez la section Codes d'erreur.

FAQ

Q : Comment consulter l'utilisation des appels de modèle ?

R : Les données d'invocation présentent un délai d'environ 1 heure. Consultez les métriques (volume d'invocations, nombre et taux de réussite) sur la page Monitoring (Singapour ou Pékin). Pour plus d'informations, consultez Comment consulter les historiques d'invocation de modèle ?

Q : Comment améliorer la qualité des vidéos générées ?

R : Pour obtenir de meilleurs résultats :
  1. Cadrez le personnage de manière cohérente dans l'image d'entrée et la vidéo de référence.
  2. Maintenez des proportions corporelles cohérentes entre l'image et la vidéo.
  3. Utilisez des sources haute définition : des images floues ou des vidéos à faible fréquence d'images réduisent la précision des détails.

Q : Comment convertir un lien vidéo temporaire en lien permanent ?

R : La conversion directe n'est pas prise en charge. Configurez votre backend pour télécharger la vidéo et la téléverser vers Object Storage Service (OSS) afin d'obtenir un lien d'accès permanent.
import requests

def download_and_save_video(video_url, save_path):
    try:
        response = requests.get(video_url, stream=True, timeout=300) # Set timeout
        response.raise_for_status() # Raise an exception if the HTTP status code is not 200
        with open(save_path, 'wb') as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)
        print(f"Video successfully downloaded to: {save_path}")
        # Logic for uploading to permanent storage can be added here
    except requests.exceptions.RequestException as e:
        print(f"Failed to download video: {e}")

if __name__ == '__main__':
    video_url = "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxxx"
    save_path = "video.mp4"
    download_and_save_video(video_url, save_path)

Q : Le lien vidéo retourné peut-il être lu directement dans un navigateur ?

R : Cela n'est pas recommandé, car les liens expirent après 24 heures. Téléchargez et stockez la vidéo sur votre backend, puis diffusez-la via un lien permanent.

Q : Comment obtenir la liste d'autorisation de noms de domaine pour le stockage vidéo ?

R : Les vidéos générées par les modèles sont stockées dans OSS. L'API retourne 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 de contrôle de sécurité, contactez votre gestionnaire de compte pour obtenir la dernière liste de noms de domaine OSS.