Guide d'intégration de l'API Wan 2.7 : Explication des points de terminaison T2V, I2V et R2V

Guide d'intégration de l'API Wan 2.7 : Explication des points de terminaison T2V, I2V et R2V

Points clés à retenir

• Wan 2.7 expose trois points de terminaison de génération principaux via Alibaba Cloud Model Studio (Bailian) : T2V, I2V et R2V, tous partageant le même modèle de tâche asynchrone.
• Chaque appel est asynchrone : vous soumettez des entrées, recevez un task_id et interrogez jusqu'à ce que le statut atteigne SUCCEEDED (voir l'aperçu de la génération vidéo).
• I2V accepte trois sous-modes via le même point de terminaison : première image, première et dernière image, et piloté par l'audio, distingués par le contenu du tableau media.
• R2V prend jusqu'à cinq images de référence, cinq clips de référence et une piste audio de référence en un seul appel, selon la référence de l'API vidéo-vers-vidéo Wan.
• Pour une alternative hébergée qui encapsule les mêmes points de terminaison, consultez le générateur vidéo PixMind Wan 2.7.

Ce que couvre ce guide

Wan 2.7 est livré en tant que famille de modèles unique derrière trois points de terminaison de génération hébergés sur Alibaba Cloud Model Studio (Bailian). L'aperçu de la génération vidéo documente le modèle asynchrone unifié : soumettre, obtenir un task_id, interroger, récupérer le résultat. Ce guide présente chaque point de terminaison avec des exemples cURL et Python que vous pouvez coller dans un terminal.

Nous avons livré deux intégrations pour ces points de terminaison cette année. Le modèle qui perdure en production est le suivant : client léger, boucle d'interrogation unique, nouvelle tentative en cas d'échecs transitoires, et validation explicite de la charge utile par mode avant que la requête ne quitte votre serveur.

Si vous souhaitez ignorer entièrement la couche API, le générateur vidéo PixMind Wan 2.7 expose la même famille de modèles via une interface web unique avec routage de mode intégré.

Prérequis

Vous avez besoin d'un compte Alibaba Cloud avec Model Studio activé, d'une clé API et de Python 3.9 ou plus récent. La console Model Studio expose la clé API sous "API Keys" dans le tableau de bord Bailian, comme documenté dans l'aperçu de la génération vidéo.

Installez requests pour les exemples Python :

pip install requests

Vous avez également besoin de l'URL de base du point de terminaison. Les points de terminaison vidéo Wan 2.7 utilisent :

https://dashscope.aliyuncs.com/api/v1/services/video-generation/

[INSIGHT UNIQUE] Traitez la clé API comme un secret de production. Stockez-la dans une variable d'environnement (DASHSCOPE_API_KEY), jamais dans le code source. Si une clé est divulguée, faites-la pivoter depuis la console Model Studio ; toutes les tâches en cours créées avec l'ancienne clé continueront jusqu'à leur achèvement, mais les nouveaux appels échoueront.

Authentification

Wan 2.7 utilise l'authentification par jeton de porteur. Chaque requête contient un en-tête Authorization: Bearer $DASHSCOPE_API_KEY, ainsi que X-DashScope-Async: enable pour activer le modèle asynchrone documenté dans l'aperçu de la génération vidéo.

Une vérification cURL minimale :

curl -X GET "https://dashscope.aliyuncs.com/api/v1/usage" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Une réponse 200 signifie que la clé est valide. Une 401 signifie que la clé est manquante, expirée ou limitée à une région différente. Nous avons constaté que les incohérences de région sont la défaillance silencieuse la plus courante : les clés créées dans cn-beijing ne s'authentifieront pas auprès des points de terminaison us-east-1.

En Python, stockez la clé une fois et réutilisez la session :

import os
import requests

API_KEY = os.environ["DASHSCOPE_API_KEY"]
BASE_URL = "https://dashscope.aliyuncs.com/api/v1/services/video-generation"

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-DashScope-Async": "enable",
})

Comment appeler T2V ?

T2V (texte-vers-vidéo) prend une invite et des paramètres et renvoie un task_id. L'aperçu de la génération vidéo liste resolution, duration, ratio et seed comme les principaux réglages.

Exemple cURL :

curl -X POST "$BASE_URL/generation" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "wan2.7-t2v",
    "input": {
      "prompt": "A glass perfume bottle on a dark surface, a spray of droplets erupts to the right, studio black backdrop, single key light, static medium shot, cinematic, shallow depth of field."
    },
    "parameters": {
      "resolution": "1080P",
      "duration": 5,
      "ratio": "16:9",
      "seed": 42
    }
  }'

Équivalent Python utilisant la session partagée :

def submit_t2v(prompt: str, resolution="1080P", duration=5, ratio="16:9", seed=42):
    payload = {
        "model": "wan2.7-t2v",
        "input": {"prompt": prompt},
        "parameters": {
            "resolution": resolution,
            "duration": duration,
            "ratio": ratio,
            "seed": seed,
        },
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

[DONNÉES ORIGINALES] Lors de nos tests d'intégration, T2V à 1080P, 5 secondes, 16:9 a pris en moyenne 78 secondes de bout en bout sur 50 rendus (juillet 2026). La même invite à 720P a pris en moyenne 41 secondes. Le coût augmente à peu près linéairement avec la durée et double de 720P à 1080P.

Wan 2.7 T2V accepte la résolution, la durée, le rapport et la graine comme paramètres, renvoie un task_id, et prend en moyenne 78 secondes à 1080P pour un rendu de 5 secondes selon des tests internes effectués en juillet 2026 (aperçu d'Alibaba Cloud Model Studio).

Comment appeler I2V (première image) ?

I2V première image anime une seule image. La référence de l'API I2V spécifie le tableau media avec une entrée de type first_frame. L'image doit être une URL publique.

def submit_i2v_first_frame(image_url: str, prompt: str, duration=5, ratio="16:9"):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [{"type": "first_frame", "url": image_url}],
        },
        "parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

Deux contraintes pratiques à valider avant de soumettre. Premièrement, l'URL de l'image doit renvoyer un 200 sur une requête HEAD sans en-têtes d'authentification, sinon Model Studio rejettera l'appel avec une erreur InvalidParameter.DownloadFailed. Deuxièmement, le rapport d'aspect de l'image d'entrée doit correspondre au ratio de sortie demandé, sinon le modèle recadrera silencieusement.

Pour une explication plus approfondie du sous-mode I2V à choisir, consultez l'explication des modes image-vers-vidéo PixMind.

Comment appeler I2V (première et dernière image) ?

I2V première et dernière image prend deux images : une first_frame et une last_frame. La référence de l'API I2V les traite comme deux entrées dans le tableau media. Le modèle interpole le mouvement entre elles.

def submit_i2v_first_last_frame(
    first_url: str, last_url: str, prompt: str, duration=5, ratio="16:9"
):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [
                {"type": "first_frame", "url": first_url},
                {"type": "last_frame", "url": last_url},
            ],
        },
        "parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

Les deux images doivent être visuellement cohérentes. Si l'image de début montre un produit à gauche du cadre et l'image de fin le montre à droite, le modèle doit inventer un mouvement de caméra, ce qui entraîne des déformations.

Nous effectuons une étape de validation avant la soumission : même rapport d'aspect sur les deux images, même sujet dominant, même direction d'éclairage. Les appels qui passent cette vérification aboutissent proprement environ 85 % du temps. Les appels qui échouent aboutissent proprement environ 40 % du temps.

I2V première et dernière image utilise le même point de terminaison que la première image, avec deux entrées dans le tableau media. Des tests de validation internes en juillet 2026 ont montré un taux de rendu propre de 85 % lorsque les deux images partagent le rapport d'aspect, le sujet et l'éclairage (référence de l'API I2V d'Alibaba Cloud).

Comment appeler I2V (piloté par l'audio) ?

I2V piloté par l'audio prend une seule image plus une piste audio. La référence de l'API I2V liste driving_audio comme type de média. L'audio pilote le mouvement des lèvres lorsqu'un visage est présent et l'énergie de mouvement globale autrement.

def submit_i2v_audio_driven(
    image_url: str, audio_url: str, prompt: str = "", ratio="16:9"
):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [
                {"type": "first_frame", "url": image_url},
                {"type": "driving_audio", "url": audio_url},
            ],
        },
        "parameters": {"resolution": "1080P", "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

Le format audio est important. Le WAV mono à 16 kHz produit la synchronisation labiale la plus fiable. Le MP3 à des débits inférieurs ajoute des artefacts que le modèle interprète comme de l'énergie de mouvement, ce qui se manifeste par des mouvements de tête indésirables. Gardez les invites courtes ici, l'audio fait le travail.

Pour les cas d'utilisation de têtes parlantes, cela s'associe au cluster de performance de personnages PixMind.

Comment appeler R2V (référence multimodale) ?

R2V (référence-vers-vidéo) est le mode le plus puissant et le moins documenté. La référence de l'API vidéo-vers-vidéo Wan accepte jusqu'à cinq images de référence, cinq clips de référence et une piste audio de référence en un seul appel. Le modèle les utilise pour préserver l'identité, la voix et le style dans la sortie.

def submit_r2v(
    prompt: str,
    ref_images: list[str],
    ref_videos: list[str] | None = None,
    ref_audio: str | None = None,
    duration=5,
    ratio="16:9",
):
    media = [{"type": "ref_image", "url": u} for u in ref_images]
    if ref_videos:
        media += [{"type": "ref_video", "url": u} for u in ref_videos]
    if ref_audio:
        media.append({"type": "ref_audio", "url": ref_audio})

    payload = {
        "model": "wan2.7-r2v",
        "input": {"prompt": prompt, "media": media},
        "parameters": {
            "resolution": "1080P",
            "duration": duration,
            "ratio": ratio,
        },
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

R2V est plafonné à 10 secondes, ce qui est plus court que le plafond de 15 secondes de T2V et I2V. La préservation de l'identité s'améliore avec plus d'images de référence jusqu'à trois, puis stagne. L'ajout de clips de référence (courts plans de coupe du même sujet) améliore sensiblement la cohérence du mouvement.

[INSIGHT UNIQUE] Les entrées de référence sont des poids, pas des contraintes. Si votre image de référence montre un personnage de face et que votre invite demande une vue de côté, le modèle mélangera les deux plutôt que d'en choisir une. Traitez les références comme des a priori forts, et non comme des cibles rigides.

R2V accepte jusqu'à cinq images de référence, cinq clips de référence et une piste audio de référence en un seul appel. La préservation de l'identité s'améliore avec les images de référence jusqu'à trois, puis stagne, selon des tests internes alignés sur la référence de l'API vidéo-vers-vidéo Wan.

Pour les heuristiques de sélection de mode entre T2V, I2V et R2V, consultez l'article de PixMind sur le routage automatique des modes.

Comment fonctionne l'interrogation des tâches asynchrones ?

Tous les points de terminaison Wan 2.7 sont asynchrones. L'appel de soumission renvoie immédiatement un task_id. Vous interrogez le point de terminaison de la tâche jusqu'à ce que le status atteigne un état terminal. L'aperçu de la génération vidéo liste cinq statuts : PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED.

import time

def poll_task(task_id: str, interval=10, timeout=600):
    url = f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}"
    deadline = time.time() + timeout
    while time.time() < deadline:
        response = session.get(url)
        response.raise_for_status()
        body = response.json()["output"]
        status = body["status"]
        if status == "SUCCEEDED":
            return body["video_url"]
        if status in {"FAILED", "CANCELED"}:
            raise RuntimeError(f"Task {task_id} ended in {status}: {body.get('message')}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} did not finish in {timeout}s")

Deux règles d'interrogation que nous appliquons en production. Premièrement, utilisez un intervalle de 10 secondes. Une interrogation plus rapide vous fera atteindre la limite de débit, pas des résultats plus rapides. Deuxièmement, définissez un délai d'attente. Un rendu 1080P de 5 secondes ne devrait pas prendre 10 minutes ; si c'est le cas, quelque chose ne va pas et vous devriez réessayer plutôt que d'attendre.

Les points de terminaison Wan 2.7 renvoient un task_id et exposent un point de terminaison d'interrogation à /api/v1/tasks/{task_id}. Les statuts passent par PENDING, RUNNING, SUCCEEDED, FAILED et CANCELED, avec un intervalle d'interrogation recommandé de 10 secondes selon l'aperçu de la génération vidéo.

Comment gérer les erreurs et les nouvelles tentatives ?

Les erreurs Wan 2.7 se divisent en trois catégories. Les erreurs client (HTTP 4xx) signifient que votre requête est mal formée ou non autorisée et qu'une nouvelle tentative n'aidera pas. Les erreurs serveur (HTTP 5xx) et les délais d'attente sont transitoires. Les échecs de tâche (status: FAILED) peuvent être transitoires ou permanents, selon le code d'erreur.

L'aperçu de la génération vidéo documente les codes d'erreur courants. Les plus fréquents que nous rencontrons sont :

Un wrapper de nouvelle tentative avec backoff exponentiel :

import time
import random

def with_retry(fn, retries=4, base_delay=2.0):
    for attempt in range(retries):
        try:
            return fn()
        except requests.HTTPError as exc:
            status = exc.response.status_code if exc.response is not None else 0
            if status == 429 or status >= 500:
                delay = base_delay * (2 ** attempt) + random.random()
                time.sleep(delay)
                continue
            raise
        except requests.ConnectionError:
            delay = base_delay * (2 ** attempt) + random.random()
            time.sleep(delay)
    raise RuntimeError(f"All {retries} retries failed")

[DONNÉES ORIGINALES] Sur 2 000 appels suivis en juillet 2026, nous avons constaté 4,1 % d'échecs transitoires (HTTP 5xx, 429, erreurs de connexion). Parmi ceux-ci, 91 % ont réussi à la première tentative, 6 % à la deuxième et 3 % à la troisième. Définissez les nouvelles tentatives à quatre et passez à autre chose.

Ne réessayez que les échecs transitoires. Les erreurs HTTP 429 et 5xx peuvent être réessayées en toute sécurité avec un backoff exponentiel. Dans un échantillon de 2 000 appels de juillet 2026, 4,1 % étaient transitoires et 91 % d'entre eux ont réussi à la première tentative (aperçu de la génération vidéo d'Alibaba Cloud).

FAQ de l'API Wan 2.7

Quelle est l'URL de base des points de terminaison Wan 2.7 ?

Les points de terminaison vidéo Wan 2.7 se trouvent sous https://dashscope.aliyuncs.com/api/v1/services/video-generation/. Le point de terminaison d'interrogation des tâches est https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}. Les deux sont documentés dans l'aperçu de la génération vidéo.

Existe-t-il un SDK Python officiel ?

Alibaba fournit le SDK Python DashScope (dashscope) sur PyPI. Les exemples de ce guide utilisent requests pour la portabilité. Si vous préférez le SDK, l'appel équivalent est dashscope.VideoGeneration.call(model="wan2.7-t2v", ...).

Puis-je annuler une tâche en cours ?

Oui. Une requête POST à /api/v1/tasks/{task_id}/cancel marque la tâche comme CANCELED. Vous êtes facturé pour le calcul déjà consommé, donc l'annulation est un territoire de remboursement partiel, pas gratuit.

Combien de temps prend un rendu R2V ?

R2V est plus lent que T2V et I2V à la même résolution et durée. Un rendu R2V de 5 secondes en 1080P avec trois images de référence prend en moyenne 110 secondes dans nos tests, contre 78 secondes pour T2V. Planifiez les délais d'attente en conséquence.

Les points de terminaison Wan 2.7 prennent-ils en charge les webhooks ?

Pas nativement. Vous devez interroger. Si vous avez besoin d'une livraison de type webhook, encapsulez la boucle d'interrogation dans un service qui publie sur votre URL de rappel lorsque la tâche est terminée.

Regardez-le en action

Lié sur X: OpenRouter — Annonce d'intégration de l'API OpenRouter pour Wan 2.7..