WAN 2.5 API Quickstart en WaveSpeed: Autenticación, Parámetros y Solicitudes de Ejemplo

Hola, soy Dora. Originalmente, no planeé probar la API WAN 2.5 en WaveSpeed esta semana. Una pequeña molestia me llevó allá: necesitaba algunas variaciones de imagen consistentes para un borrador, y mis herramientas habituales eran demasiado interactivas o demasiado inteligentes para su propio bien. Quería algo aburrido y confiable, scripteable, versionado, fácil de revertir.

Así que abrí la documentación, preparé té, e implementé un pequeño script. Esto es lo que anoté en el camino, probado en enero de 2026, sin barniz. Se trata menos de “características” y más de las partes que hicieron que el trabajo se sintiera más ligero una vez que estuvieron en su lugar.

Descripción general de la API

Si has tocado cualquier API moderna de IA, el enfoque de WaveSpeed para WAN 2.5 te resultará familiar. HTTP entra, JSON sale. Envías un prompt (y a veces una imagen), y devuelve un artefacto terminado o un ID de trabajo que puedes sondear.

Algunos detalles básicos que observé antes de escribir cualquier código:

Versionado: WAN 2.5 se expone como una versión distinta, lo que importa para la reproducibilidad. Me apegué a la ruta de versión explícita en las URL en lugar de un alias “latest”. Esa pequeña decisión me evita cambios silenciosos de comportamiento en el futuro.
Modos: Algunos flujos de trabajo son síncronos (pequeños, rápidos), otros se generan como trabajos. Si estás haciendo generaciones de mayor resolución o trabajo por lotes, espera un flujo asincrónico con un endpoint de estado o webhooks.
Formatos: Las respuestas JSON típicamente incluyen un estado, una URL de activo o payload en base64, y algunos metadatos (seed, pasos, tiempo). Conservo los metadatos, útiles cuando quieres reproducir una apariencia más tarde.
Límites: El tamaño de imagen, recuento de pasos y concurrencia están limitados. Los valores predeterminados fueron suficientes para borradores, pero me encontré con un límite una vez que intenté aumentar la resolución. Más sobre límites de velocidad abajo.

La versión corta: es un camino directo si eres cómodo con REST. El truco está en acertar los pocos bits aburridos (claves, params, reintentos) para que puedas olvidarte de ellos.

Esa simplicidad es parte de por qué construimos WaveSpeed de la forma en que lo hicimos. Quería que WAN 2.5 (y otros modelos) se sintieran scripteable, versionado, y aburrido de la mejor manera. Si estás implementando esto tú mismo, puedes explorarlo aquí.

Autenticación y clave

Generé una clave de API de WaveSpeed en el panel de control y la coloqué en una variable de entorno. Nada sofisticado, pero me ahorró buscar secretos en todos los archivos.

Obtén una clave de la configuración de tu cuenta en WaveSpeed. Está vinculada a tu organización/proyecto.
Guárdala localmente como una variable de entorno: WAVESPEED_API_KEY. Usé un archivo .env para desarrollo y el almacén de secretos de mi CI para ejecuciones.
Usa autenticación Bearer en el encabezado: Authorization: Bearer $WAVESPEED_API_KEY.
Si rotas claves, hazlo durante horas de bajo tráfico. Aprendí esto de la manera silenciosa cuando una rotación programada interrumpió un trabajo largo.

Si tu equipo necesita claves con alcance limitado, verifica la configuración del panel de control. Prefiero la ruta de menor privilegio para cualquier cosa vinculada a una automatización. Una fricción menor: si estás ejecutando desde múltiples máquinas, etiqueta las claves claramente por host o servicio, ayuda cuando auditas el uso más tarde.

Parámetros requeridos

Los nombres exactos pueden diferir por endpoint, pero aquí está la forma mínima que usé para Wan 2.5 en WaveSpeed. Trata estos como un esqueleto, confirma los nombres de campo en la documentación oficial de tu cuenta.

model: Establecí esto explícitamente a wan-2.5 (o la cadena exacta más cercana en tu plan). Mantiene el comportamiento estable entre actualizaciones.
input: Una cadena de prompt. La mantuve corta y concreta. WAN tiende a responder mejor a frases claras y simples que a sopa de adjetivos.
mode o task: Generación de imagen versus variación/upscale. Si estás pasando una imagen de origen, esto importa.
output: Pedí una URL de imagen por defecto. Base64 está ahí, pero las URLs son más amables con la memoria.

Cuando olvidé establecer explícitamente el modelo, obtuve un valor predeterminado sensato, pero mis resultados cambiaron sutilmente entre ejecuciones. No está mal, solo no reproducible. Bloquear la versión eliminó esa oscilación.

Parámetros opcionales

Aquí es donde se encuentra el control real. Solo toqué un puñado el primer día.

seed: Activo esto una vez que me gusta una apariencia. Estabiliza el ambiente para variaciones.
steps: Pasos más altos pueden impulsar los detalles a costa del tiempo y créditos. Aumenté en pequeños incrementos (por ejemplo, 24 → 32) y observé los retornos.
guidance o cfg_scale: Aprieta la adherencia al prompt. Demasiado alto y se vuelve frágil.
size o resolution: Aquí es donde los costos saltan. Hago borradores pequeños, luego vuelvo a ejecutar finales en tamaños objetivo.
image: Para variaciones, pasa una URL de imagen de origen o carga. Empareja con un parámetro de intensidad si es compatible.
safety o moderation flags: Déjalos activados a menos que tu flujo de trabajo realmente necesite manejo personalizado.
user o metadata: Agrego un ID de solicitud o etiqueta de proyecto para rastrear ejecuciones en registros más tarde.

Pequeña observación: cambiar dos controles a la vez hizo difícil saber qué ayudó. Cambié una cosa por ejecución y mantuve notas en comentarios. Anticuado, pero funcionó.

Patrones de solicitud de muestra

Probé tres formas simples: un curl rápido, un pequeño script de Python y un trabajo en segundo plano para asincrónico.

Borrador sincrónico (curl)

Esto fue suficiente para verificar la cordura de mi clave y prompt antes de conectar cualquier otra cosa.

Endpoint de ejemplo, confirma la ruta exacta en la documentación de tu cuenta y región:

POST https://api.wavespeed.ai/wan/v2.5/generations

Encabezados:

Authorization: Bearer $WAVESPEED_API_KEY
Content-Type: application/json

Cuerpo (mínimo):

{
  "model": "wan-2.5",
  "input": "quiet studio light, sketch on kraft paper",
  "output": { "format": "url" }
}

Lo que observé:

200 con un resultado y metadatos → estás bien.
202 con un id de trabajo → cambia a flujo asincrónico.
4xx → algo en el payload o autenticación está mal.

Pequeño asistente de Python

Escribí una pequeña función para manejar encabezados, tiempos de espera y json. Devolvía una URL o lanzaba una excepción limpia. Nada mágico, solo el tipo de envoltorio en el que no piensas dos veces.

Bits prácticos:

Establece un tiempo de conexión corto y un tiempo de lectura un poco más largo.
Maneja 429 con un reintento y jitter.
Registra el seed, pasos y tamaño para cada ejecución.

Flujo asincrónico (trabajos)

Para imágenes más grandes o lotes, obtuve un 202 y un id de trabajo. El bucle fue simple:

POST trabajo,

Sondea GET /jobs/{id} cada pocos segundos,
Detente en estado terminal (exitoso/fallido),
Obtén la URL del activo.

Si tu stack le gusta los webhooks, WaveSpeed también expone callbacks. Me apegué al sondeo al principio, es una parte móvil menos durante la configuración.

Códigos de error

Mantuve un pequeño mapa junto a mi editor. Valió la pena más rápido de lo esperado.

400 Bad Request: Generalmente una discrepancia de nombre de campo o tipo. Una vez envié el tamaño como cadena, no como objeto. La solución fue obvia una vez que me detuve y leí el mensaje.
401 Unauthorized: Clave faltante o malformada. Verifica tu encabezado Bearer y espacios finales.
403 Forbidden: La clave existe pero carece de alcance para el endpoint o nivel de modelo.
404 Not Found: Ruta de endpoint incorrecta o un id de trabajo que expiró.
409 Conflict: A veces lo verás cuando actualizas un trabajo que ya se resolvió. Sondea de nuevo, no sigas empujando.
429 Too Many Requests: Estás más allá de un límite por minuto u por organización. Retrocede con reintentos exponenciales.
500/503 Server Errors: Raro en mis pruebas, pero planifica para ello. Un pequeño bucle de reintento mantuvo mis scripts tranquilos.

Pequeño hábito que ayudó: propagué el código de error y el id de solicitud (si está presente) a mis registros. Cuando algo sale mal, el soporte puede usar ese id para rastrearlo.

Límites de velocidad

Choqué contra límites de velocidad una vez que me volví perezoso con la concurrencia. Fácil de hacer, más fácil de evitar.

Lo que funcionó:

Respeta los encabezados: Muchos endpoints devuelven encabezados de velocidad (por ejemplo, restante, tiempo de reinicio). Los nombres de encabezado pueden variar, verifica la documentación, pero vale la pena leerlos.
Usa un token bucket o cola simple. Limité mis scripts a un flujo pequeño y constante en lugar de ráfagas. El sistema respiró más fácil, y yo también.
Separa borradores de finales. Los borradores pueden ejecutarse pequeños y rápidos: los finales pueden ejecutarse uno por uno en segundo plano.
Caché repeticiones. Si estás probando prompts, mantén resultados anteriores durante unos minutos para no quemar la misma llamada.

También construí un retroceso muy simple: retardo base de 1s, duplicando en cada 429, con un límite de 30s y un máximo de 4 reintentos. Se sintió sin prisa y evitó abrumar el servicio.

Salvaguardas de costo

Esta fue mi preocupación principal. El trabajo con imágenes puede consumir créditos en segundo plano mientras estás haciendo té.

Algunas protecciones que establecí el primer día:

Límites de presupuesto en el panel de control: Establecí un límite mensual y alertas por correo electrónico un paso por debajo. Si tu equipo comparte una clave, las alertas te ayudan a atrapar bucles temprano.
Límites por solicitud: Obligué al tamaño y pasos a vivir bajo un máximo a menos que pasara un indicador de anulación. Me salvó de “oops, 4K todo”.
Flujo de trabajo de borrador primero: Ejecuto pequeñas vistas previas (menor resolución, menos pasos) y solo aumento los que conservo. Esto redujo mi gasto en más de la mitad en la primera tarde.
Disciplina de seed: Una vez que encontré una dirección que me gustó, fijé el seed y cambié un parámetro a la vez. Menos ejecuciones ciegas: más intencionadas.
Registros con costos: Si la respuesta incluye un crédito o campo de uso (algunos endpoints lo hacen), guárdalo. Cuando no lo hace, estima basándote en resolución y pasos y anota que es una estimación.

También puse un interruptor de apagado suave en mis scripts: si el uso del día cruzaba un umbral, los nuevos trabajos se pausaban y publicaban un mensaje en Slack. No es elegante, pero es honesto sobre las limitaciones.

Esto no ahorró tiempo al principio. Ahorró atención. Después de algunas ejecuciones, las salvaguardas se desvanecieron en el fondo, y pude pensar en el trabajo nuevamente en lugar del medidor.