Guía de integración de la API Wan 2.7: Explicación de los puntos finales T2V, I2V y R2V

Puntos clave

Wan 2.7 expone tres puntos finales de generación principales a través de Alibaba Cloud Model Studio (Bailian): T2V, I2V y R2V, todos compartiendo el mismo patrón de tarea asíncrona.
Cada llamada es asíncrona: usted envía entradas, recibe un task_id y sondea hasta que el estado alcanza SUCCEEDED (consulte la descripción general de la generación de video).
I2V acepta tres submodos a través del mismo punto final: primer fotograma, primer y último fotograma, e impulsado por audio, distinguidos por el contenido del array media.
R2V toma hasta cinco imágenes de referencia, cinco clips de referencia y una pista de audio de referencia en una sola llamada, según la referencia de la API de video a video de Wan.
Para una alternativa alojada que envuelve los mismos puntos finales, consulte el generador de video PixMind Wan 2.7.

Qué cubre esta guía

Wan 2.7 se distribuye como una familia de modelos detrás de tres puntos finales de generación alojados en Alibaba Cloud Model Studio (Bailian). La descripción general de la generación de video documenta el patrón asíncrono unificado: enviar, obtener un task_id, sondear, obtener el resultado. Esta guía recorre cada punto final con ejemplos de cURL y Python que puede pegar en una terminal.

Hemos lanzado dos integraciones contra estos puntos finales este año. El patrón que sobrevive en producción es: cliente ligero, bucle de sondeo único, reintento en fallos transitorios y validación explícita de la carga útil por modo antes de que la solicitud salga de su servidor.

Si desea omitir la capa de API por completo, el generador de video PixMind Wan 2.7 expone la misma familia de modelos a través de una única interfaz web con enrutamiento de modo incorporado.

Requisitos previos

Necesita una cuenta de Alibaba Cloud con Model Studio habilitado, una clave API y Python 3.9 o posterior. La consola de Model Studio expone la clave API en "API Keys" en el panel de control de Bailian, como se documenta en la descripción general de la generación de video.

Instale requests para los ejemplos de Python:

pip install requests

También necesita la URL base del punto final. Los puntos finales de video de Wan 2.7 utilizan:

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

[INFORMACIÓN ÚNICA] Trate la clave API como un secreto de producción. Almacénela en una variable de entorno (DASHSCOPE_API_KEY), nunca en el código fuente. Si una clave se filtra, rótela desde la consola de Model Studio, y cualquier tarea en curso creada con la clave antigua continuará hasta su finalización, pero las nuevas llamadas fallarán.

Autenticación

Wan 2.7 utiliza autenticación de token de portador. Cada solicitud lleva un encabezado Authorization: Bearer $DASHSCOPE_API_KEY, además de X-DashScope-Async: enable para optar por el patrón asíncrono documentado en la descripción general de la generación de video.

Una verificación mínima con cURL:

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

Una respuesta 200 significa que la clave es válida. Un 401 significa que la clave falta, ha caducado o está limitada a una región diferente. Hemos descubierto que las discrepancias de región son el fallo silencioso más común: las claves creadas en cn-beijing no se autenticarán contra los puntos finales de us-east-1.

En Python, almacene la clave una vez y reutilice la sesión:

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",
})

¿Cómo se llama a T2V?

T2V (texto a video) toma un prompt más parámetros y devuelve un task_id. La descripción general de la generación de video enumera resolution, duration, ratio y seed como los controles principales.

Ejemplo de 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
    }
  }'

Equivalente en Python usando la session compartida:

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"]

[DATOS ORIGINALES] En nuestras pruebas de integración, T2V a 1080P, 5 segundos, 16:9 promedió 78 segundos de principio a fin en 50 renders (julio de 2026). El mismo prompt a 720P promedió 41 segundos. El costo escala aproximadamente linealmente con la duración y se duplica de 720P a 1080P.

Wan 2.7 T2V acepta resolución, duración, relación de aspecto y semilla como parámetros, devuelve un task_id y promedia 78 segundos a 1080P para un render de 5 segundos según pruebas internas realizadas en julio de 2026 (descripción general de Alibaba Cloud Model Studio).

¿Cómo se llama a I2V (primer fotograma)?

I2V de primer fotograma anima una sola imagen. La referencia de la API de I2V especifica el array media con una entrada de tipo first_frame. La imagen debe ser una URL pública.

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"]

Dos restricciones prácticas a validar antes de enviar. Primero, la URL de la imagen debe devolver un 200 en una solicitud HEAD sin encabezados de autenticación, de lo contrario, Model Studio rechazará la llamada con un error InvalidParameter.DownloadFailed. Segundo, la relación de aspecto de la imagen de entrada debe coincidir con la ratio de salida solicitada, o el modelo recortará silenciosamente.

Para una explicación más detallada de qué submodo de I2V elegir, consulte el explicador de modos de imagen a video de PixMind.

¿Cómo se llama a I2V (primer y último fotograma)?

I2V de primer y último fotograma toma dos imágenes: un first_frame y un last_frame. La referencia de la API de I2V las trata como dos entradas en el array media. El modelo interpola el movimiento entre ellas.

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"]

Los dos fotogramas deben ser visualmente consistentes. Si el fotograma inicial muestra un producto a la izquierda del encuadre y el último fotograma lo muestra a la derecha, el modelo tiene que inventar un movimiento de cámara, que es donde aparece la deformación.

Ejecutamos un paso de validación antes del envío: la misma relación de aspecto en ambos fotogramas, el mismo sujeto dominante, la misma dirección de iluminación. Las llamadas que pasan esta verificación se renderizan limpiamente aproximadamente el 85 por ciento de las veces. Las llamadas que fallan se renderizan limpiamente aproximadamente el 40 por ciento de las veces.

I2V de primer y último fotograma utiliza el mismo punto final que el de primer fotograma, con dos entradas en el array de medios. Las pruebas de validación internas en julio de 2026 mostraron una tasa de renderizado limpio del 85 por ciento cuando ambos fotogramas comparten la relación de aspecto, el sujeto y la iluminación (referencia de la API de I2V de Alibaba Cloud).

¿Cómo se llama a I2V (impulsado por audio)?

I2V impulsado por audio toma una sola imagen más una pista de audio. La referencia de la API de I2V enumera driving_audio como el tipo de medio. El audio impulsa el movimiento de los labios cuando hay una cara presente y la energía de movimiento general en caso contrario.

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"]

El formato de audio importa. WAV a 16kHz mono produce la sincronización labial más fiable. MP3 a tasas de bits más bajas añade artefactos que el modelo interpreta como energía de movimiento, lo que se manifiesta como movimientos de cabeza no deseados. Mantenga los prompts cortos aquí, el audio está haciendo el trabajo.

Para casos de uso de "talking-head", esto se combina con el clúster de rendimiento de personajes de PixMind.

¿Cómo se llama a R2V (referencia multimodal)?

R2V (referencia a video) es el modo más potente y menos documentado. La referencia de la API de video a video de Wan acepta hasta cinco imágenes de referencia, cinco clips de referencia y una pista de audio de referencia en una sola llamada. El modelo utiliza estos elementos para preservar la identidad, la voz y el estilo en la salida.

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 tiene un límite de 10 segundos, más corto que el límite de 15 segundos de T2V e I2V. La preservación de la identidad mejora con más imágenes de referencia hasta tres, luego se estabiliza. Añadir clips de referencia (tomas B-roll cortas del mismo sujeto) aumenta notablemente la consistencia del movimiento.

[INFORMACIÓN ÚNICA] Las entradas de referencia son pesos, no restricciones. Si su imagen de referencia muestra un personaje de frente y su prompt pide una vista lateral, el modelo mezclará los dos en lugar de elegir uno. Trate las referencias como priors fuertes, no como objetivos fijos.

R2V acepta hasta cinco imágenes de referencia, cinco clips de referencia y un audio de referencia en una sola llamada. La preservación de la identidad mejora con imágenes de referencia hasta tres, luego se estabiliza, según pruebas internas alineadas con la referencia de la API de video a video de Wan.

Para heurísticas de selección de modo entre T2V, I2V y R2V, consulte la publicación de enrutamiento automático de modos de PixMind.

Sequence diagram showing Client, PixMind API, Wan 2.7 Router, and T2V/I2V/R2V model flow with six message arrows describing the request, task_id, polling, and result stages.

¿Cómo funciona el sondeo de tareas asíncronas?

Todos los puntos finales de Wan 2.7 son asíncronos. La llamada de envío regresa inmediatamente con un task_id. Usted sondea el punto final de la tarea hasta que el status alcanza un estado terminal. La descripción general de la generación de video enumera cinco estados: 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")

Dos reglas de sondeo que aplicamos en producción. Primero, use un intervalo de 10 segundos. Un sondeo más rápido le hará ser limitado por la tasa de solicitudes, no obtendrá resultados más rápidos. Segundo, establezca un tiempo de espera. Un render de 1080P de 5 segundos no debería tardar 10 minutos; si lo hace, algo está mal y debería reintentar en lugar de esperar.

Los puntos finales de Wan 2.7 devuelven un task_id y exponen un punto final de sondeo en /api/v1/tasks/{task_id}. Los estados ciclan entre PENDING, RUNNING, SUCCEEDED, FAILED y CANCELED, con un intervalo de sondeo recomendado de 10 segundos según la descripción general de la generación de video.

¿Cómo se manejan los errores y los reintentos?

Los errores de Wan 2.7 se dividen en tres categorías. Los errores del cliente (HTTP 4xx) significan que su solicitud está mal formada o no autorizada y un reintento no ayudará. Los errores del servidor (HTTP 5xx) y los tiempos de espera son transitorios. Los fallos de la tarea (status: FAILED) pueden ser transitorios o permanentes, dependiendo del código de error.

La descripción general de la generación de video documenta los códigos de error comunes. Los más frecuentes que vemos son:

Código	Significado	Acción
`InvalidParameter.DownloadFailed`	La URL de entrada no era accesible	Aloje el recurso de nuevo y reintente
`DataInsufficient.UnsafeContent`	Prompt o imagen marcada por el filtro de seguridad	Cambie la entrada, no reintente
`Throttling.RateQuota`	QPS por clave excedido	Retroceso exponencial
`InternalError.Timeout`	El modelo excedió el presupuesto de tiempo interno	Reintente una vez
`AccessDenied.Arrear`	Cuenta sin crédito	Recargue, no reintente

Un envoltorio de reintento con retroceso exponencial:

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")

[DATOS ORIGINALES] En 2.000 llamadas rastreadas en julio de 2026, vimos un 4.1 por ciento de fallos transitorios (HTTP 5xx, 429, errores de conexión). De ellos, el 91 por ciento tuvo éxito en el primer reintento, el 6 por ciento en el segundo y el 3 por ciento en el tercero. Establezca los reintentos en cuatro y continúe.

Reintente solo los fallos transitorios. HTTP 429 y 5xx son seguros para reintentar con retroceso exponencial. En una muestra de 2.000 llamadas de julio de 2026, el 4.1 por ciento fueron transitorios y el 91 por ciento de ellos tuvieron éxito en el primer reintento (descripción general de la generación de video de Alibaba Cloud).

Preguntas frecuentes de la API Wan 2.7

¿Cuál es la URL base para los puntos finales de Wan 2.7?

Los puntos finales de video de Wan 2.7 se encuentran en https://dashscope.aliyuncs.com/api/v1/services/video-generation/. El punto final de sondeo de tareas es https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}. Ambos están documentados en la descripción general de la generación de video.

¿Existe un SDK oficial de Python?

Alibaba distribuye el SDK de Python DashScope (dashscope) en PyPI. Los ejemplos de esta guía utilizan requests para la portabilidad. Si prefiere el SDK, la llamada equivalente es dashscope.VideoGeneration.call(model="wan2.7-t2v", ...) .

¿Puedo cancelar una tarea en curso?

Sí. Un POST a /api/v1/tasks/{task_id}/cancel marca la tarea como CANCELED. Se le factura por el cómputo ya consumido, por lo que la cancelación es un territorio de reembolso parcial, no gratuito.

¿Cuánto tiempo tarda un render R2V?

R2V es más lento que T2V e I2V con la misma resolución y duración. Un render R2V de 1080P de 5 segundos con tres imágenes de referencia promedia 110 segundos en nuestras pruebas, frente a 78 segundos para T2V. Planifique los tiempos de espera en consecuencia.

¿Los puntos finales de Wan 2.7 admiten webhooks?

No de forma nativa. Debe sondear. Si necesita una entrega tipo webhook, envuelva el bucle de sondeo en un servicio que publique en su URL de callback cuando la tarea se complete.

Véalo en acción

Relacionado en X: OpenRouter — Anuncio de integración de la API de OpenRouter para Wan 2.7..

Guía de integración de la API Wan 2.7: Explicación de los puntos finales T2V, I2V y R2V