Inicio Rápido con la API de WAN 2.7 en WaveSpeed (2026)

Hola a todos. Soy Dora. Estuve posponiendo esto. WAN 2.7 llegó. Tenía un proyecto que lo necesitaba, y me dije que lo configuraría “después de que las cosas se estabilizaran.” Ese suele ser el instinto equivocado. La superficie de la API es sencilla una vez que superas el naming de versiones — y la mayor parte de la fricción proviene de una o dos decisiones que tomas al principio y que afectan silenciosamente todo lo que viene después.

Esto no es un escaparate de características. Es lo que realmente necesité el primer día.

WAN 2.7 en la Plataforma: Model ID y Disponibilidad

Antes de escribir una sola línea de código, pasé diez minutos confirmando el string del modelo. Esto parece obvio, pero WAN tiene un patrón de nomenclatura que confunde a la gente — wan2.5-i2v, wan2.6-i2v, wan2.7-flf2v — y usar un ID desactualizado devuelve un 404 limpio sin ningún mensaje de error útil.

El catálogo de modelos es el primer lugar a verificar. Navega a la sección de generación de video, filtra por la versión 2.7, y copia el string exacto del model ID. No lo escribas de memoria.

El timing de disponibilidad también importa. WAN 2.7 se lanzó en marzo de 2026 con un conjunto significativo de nuevas capacidades — control de primer/último fotograma, síntesis de imagen a video en cuadrícula 3×3, hasta cinco referencias de video, y edición basada en instrucciones. Según la descripción general de generación de video de Alibaba Cloud Model Studio, los endpoints de inferencia alojados para nuevas versiones de WAN suelen estar disponibles en días después de un lanzamiento oficial — pero no siempre el mismo día, así que revisa la página de estado de la plataforma antes de construir cualquier cosa sensible al tiempo.

Configuración de Auth y API Key

Esta parte es rápida. Tu API key va en el encabezado Authorization como un Bearer token. La URL base sigue la región que seleccionaste durante la configuración de la cuenta — Singapur, Virginia, o Pekín para el despliegue en China Continental. Las llamadas entre regiones fallarán, no ruidosamente, sino con un error de autenticación que desperdicia veinte minutos si no lo estás esperando.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Algo que hago desde el principio: almacena la API key en una variable de entorno y nunca la hardcodees, ni siquiera en scripts de prueba locales. Una key filtrada es una sorpresa de facturación que no quieres.

La estructura de la URL base sigue las convenciones REST estándar definidas en IETF RFC 9110 (HTTP Semantics). Si has trabajado con alguna API de IA moderna, esto te resultará familiar — JSON de entrada, JSON de salida, códigos de estado que se comportan como se espera.

Parámetros Principales de la Solicitud

Aquí es donde te animaría a ir un poco más despacio. Los parámetros requeridos son pocos — model ID, prompt, tipo de entrada — pero los opcionales dan forma a la calidad de salida más de lo que esperarías.

Requeridos:

model — string exacto del modelo, verificado desde el catálogo
prompt — tu descripción en texto; para video, la especificidad importa más que la longitud
Entrada: ya sea image_url (para I2V) o solo texto para T2V

Opcionales pero prácticamente importantes:

resolution — acepta "480P", "720P", "1080P"; WAN 2.7 soporta salida nativa en 1080P hasta 15 segundos
duration — de 2 a 15 segundos; los clips más largos cuestan más y tardan más en procesarse
seed — bloquea esto una vez que encuentres una buena salida. Es el único parámetro que hace tus resultados reproducibles entre ejecuciones
negative_prompt — útil para suprimir parpadeo, desenfoque y artefactos de movimiento

Parámetros específicos de WAN 2.7 a verificar en el lanzamiento oficial de la documentación:

first_frame_url + last_frame_url — para el modo FLF2V (primer y último fotograma)
image_grid — la estructura de entrada en cuadrícula de 9 imágenes para una composición I2V más rica
edit_instruction — edición en lenguaje natural sobre un video existente

Los últimos tres son nuevos en 2.7. Los nombres de parámetros pueden cambiar entre la vista previa y la disponibilidad general. La referencia oficial de la API es la fuente autorizada — construir sobre nombres de parámetros provisionales es bajo tu propio riesgo.

Primeros Patrones de Solicitud

Texto a video (mínimo)

response = VideoSynthesis.async_call(
    model="wan2.7-t2v",      # verificar string exacto en el lanzamiento
    prompt="A slow dolly shot through a foggy pine forest at dawn.",
    resolution="720P",
    duration=5,
    seed=42
)
task_id = response.output.task_id

Imagen a video estándar

response = VideoSynthesis.async_call(
    model="wan2.7-i2v",
    img_url="https://your-cdn.com/input.jpg",
    prompt="Camera holds still. Subject turns slowly toward light.",
    resolution="720P",
    duration=5
)

Primer fotograma + último fotograma (FLF2V)

Aquí es donde WAN 2.7 hace algo que las versiones anteriores no podían hacer limpiamente. Defines el fotograma de apertura y cierre; el modelo rellena el movimiento entre ellos. No es animación en el sentido tradicional — es inferencia estructurada a partir de dos puntos de anclaje semánticos.

response = VideoSynthesis.async_call(
    model="wan2.7-flf2v",   # verificar string exacto en el lanzamiento
    first_frame_url="https://your-cdn.com/start.png",
    last_frame_url="https://your-cdn.com/end.png",
    prompt="Fixed camera. Smooth transition. Natural lighting.",
    resolution="720P",
    seed=99
)

La calidad de tu par de fotogramas importa más que el prompt. Un par bien emparejado con una relación espacial clara superará consistentemente a un prompt pulido con fotogramas de entrada no coincidentes. He probado suficientes ejecuciones como para decir esto con cierta confianza. Para referencia sobre cómo la variante de peso abierto maneja el condicionamiento de fotogramas, el repositorio del modelo WAN en Hugging Face documenta la arquitectura en detalle — útil incluso si solo estás llamando a la API alojada.

Imagen a video en cuadrícula de 9

La entrada de cuadrícula de 9 te permite pasar una disposición de 3×3 de imágenes estáticas como referencias de composición para una sola generación. Verifica la estructura exacta del payload en el lanzamiento — el parámetro probablemente acepta un array de nueve URLs de imágenes, pero trata cualquier documentación de prelanzamiento como provisional.

Manejo de Trabajos Asíncronos: Enviar → Sondear → Resultado

La generación de video nunca es sincrónica. Incluso para clips cortos, espera de 1 a 5 minutos por trabajo. El patrón es siempre el mismo: enviar → obtener un task_id → sondear → recuperar URL del resultado.

import time

def poll_for_result(task_id, interval=15, timeout=600):
    elapsed = 0
    while elapsed < timeout:
        result = VideoSynthesis.fetch(task_id)
        status = result.output.task_status
        if status == "SUCCEEDED":
            return result.output.video_url
        if status == "FAILED":
            raise Exception(f"Task failed: {result}")
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError("Job exceeded timeout")

Intervalo de sondeo: 15 segundos es la recomendación documentada de la propia referencia de API de Alibaba para el endpoint de imagen a video de Wan. No sondees más rápido — no acelerará nada y agotarás los límites de tasa.

Transiciones de estado del trabajo: PENDING → RUNNING → SUCCEEDED o FAILED. La URL del resultado es válida durante 24 horas después de la generación. Descárgala y almacénala inmediatamente — si pierdes esa ventana, el task ID también expira después de 24 horas y devuelve UNKNOWN en consultas posteriores. Aprendí esto de la manera incómoda en mi primera ejecución en lote.

Manejo de Errores

Los errores que encontrarás con más frecuencia:

Error	Causa probable	Solución
404 en modelo	Model ID incorrecto o desactualizado	Verifica el string exacto desde el catálogo
400 en entrada	Formato de imagen rechazado o URL inaccesible	Usa URLs HTTPS públicas; verifica el formato
429 Too Many Requests	Límite de tasa alcanzado	Retroceso exponencial con jitter
Estado de tarea UNKNOWN	Task ID expirado (ventana de 24h)	Sondea antes; descarga el resultado inmediatamente

Para los 429: retrocede, agrega jitter, no reintentes en bucles cerrados. La documentación HTTP de MDN sobre el comportamiento del encabezado Retry-After explica el patrón estándar — los encabezados de respuesta a menudo te dicen exactamente cuándo reintentar.

Los límites de tasa de trabajos de video para WAN 2.7 se publican por separado de los límites de generación de imágenes. Los trabajos de alta resolución o mayor duración típicamente cuentan contra un límite de trabajos concurrentes, no solo un límite de solicitudes por minuto. Verifica contra la documentación del nivel de tu cuenta.

Estimación de Costos

Los precios de WAN 2.7 no estaban finalizados en el momento de escribir esto. A partir de lo que es consistente en toda la familia de modelos WAN, los costos escalan en tres dimensiones:

Resolución — 1080P cuesta significativamente más que 720P por segundo de salida
Duración — facturado por segundo de video generado
Complejidad de entrada — las entradas de múltiples referencias pueden tener un multiplicador; confirma en el lanzamiento

Una fórmula de estimación aproximada:

costo estimado = duración (segundos) × multiplicador de resolución × precio unitario por segundo

Antes de ejecutar un lote, prueba un clip en cada combinación de resolución y duración que planeas usar. La descripción general de facturación de Alibaba Cloud para Model Studio tendrá costos unitarios por segundo una vez que se publiquen las tarifas oficiales de WAN 2.7. Los costos de generación de video se acumulan más rápido que los de generación de imágenes — la resolución es la palanca más importante.

Preguntas Frecuentes

¿Está WAN 2.7 disponible el mismo día que el lanzamiento oficial de Alibaba?

No siempre. Los endpoints de API alojados típicamente se activan en días después de un lanzamiento de peso abierto, a veces el mismo día, a veces una semana después. Monitorea el registro de cambios de la plataforma directamente. El repositorio GitHub del modelo WAN ha sido históricamente donde el equipo de Alibaba documenta primero los cambios de esquema para nuevos lanzamientos de peso abierto.

¿Son compatibles las llamadas a la API de WAN 2.5 con WAN 2.7?

Los payloads estándar de T2V e I2V de imagen única deberían ser estructuralmente compatibles — las nuevas características de 2.7 parecen ser aditivas en lugar de rupturistas. Dicho esto, necesitarás actualizar el string del model ID, y cualquier código que use parámetros específicos de 2.5 debería probarse antes de tratarlo como un reemplazo directo. Los modos de cuadrícula de 9 y FLF2V requieren estructuras de payload completamente nuevas.

¿Cuál es el límite de tasa para los trabajos de video de WAN 2.7?

Verifica contra el nivel de tu cuenta en tiempo de ejecución. Como punto de partida funcional: pon en cola los trabajos con un goteo constante en lugar de ráfagas. Maneja los 429 con retroceso exponencial. Registra el request_id de cada respuesta — es el campo más útil cuando algo sale mal y necesitas rastrearlo.

La mecánica aquí no es complicada. Lo que realmente lleva tiempo es construir buenos activos de entrada — los pares de fotogramas, las imágenes de referencia, los prompts que permanecen específicos sin volverse rígidos. Una vez que esos son estables, el lado de la API se vuelve rutinario.

Actualizaré esto una vez que la documentación oficial de parámetros de WAN 2.7 esté disponible y haya tenido la oportunidad de probar el formato de cuadrícula de 9 de principio a fin. Esa es la parte que más me intriga.

Publicaciones anteriores: