WaveSpeedAI

Cómo Usar la API Z-Image-Turbo en WaveSpeed (Guía Paso a Paso)

Cómo Usar la API Z-Image-Turbo en WaveSpeed (Guía Paso a Paso)

Una cosa pequeña me trajo aquí. Soy Dora. Ese día, necesitaba una foto de producto limpia para una variación de página de aterrizaje, y mis herramientas de imagen habituales se sentían más pesadas que la tarea. Seguía escuchando hablar de la Z-Image-Turbo​ ​​​API​. No del tipo de menciones ruidosas, más como si apareciera silenciosamente en registros de cambios y notas de ingeniería. Así que lo intenté.

La usé durante una semana a finales de enero de 2026, principalmente para generar visuales de marketing simples y algunas texturas de concepto para un prototipo. Nada elaborado. Quería ver dónde encajaba sin rediseñar mi stack. Aquí está lo que funcionó, lo que no, y cómo lo integré sin hacer un desastre.

Requisitos previos

Crear una cuenta en WaveSpeed

Comencé por crear una cuenta en WaveSpeed. El flujo fue básico: correo electrónico, contraseña, verificación. Sin sorpresas. Me gustó que el panel de control no intentara venderme nada antes de que pudiera probar.

Obtén tu clave API

Después del registro, fui a la sección de desarrollador y generé una clave. La etiqueté para mi proyecto de prueba y la almacené en mi archivo .env local. Una pequeña nota: creé una segunda clave para staging más adelante. Mantener las claves limitadas por entorno me salvó de adivinar qué llamadas golpeaban mi plan pagado.

Conceptos básicos de la API

Estructura de la URL del punto de conexión

Usé un único punto de conexión de generación para la mayoría de casos. El patrón se veía así:

  • Base: api.wavespeed.ai
  • Ruta con versión: /v1
  • Ruta del producto: /z-image-turbo
  • Acción: /generate

Así que una URL típica se veía como /v1/z-image-turbo/generate. Evito codificar versiones porque cambian. Dejé la base y la versión en la configuración para poder actualizar más tarde sin reescribir llamadas.

Configuración del encabezado de autenticación

La autenticación era un token Bearer estándar. Lo que ayudó fue mantener la configuración del encabezado centralizada:

  • Authorization: Bearer YOUR_API_KEY
  • Content-Type: application/json

Probé con un tiempo de espera pequeño (10s) primero, luego lo aumenté. Cuando el servicio está bajo carga, la generación de imágenes puede tomar más tiempo que una llamada REST típica. Es mejor planificarlo que reintentar agresivamente e impactara los límites de velocidad.

Parámetros principales explicados

prompt, Escribir prompts efectivos

No soy un poeta de prompts. Lo que funcionó aquí fue lenguaje simple y literal, y una pista de estilo clara. Para fotos de producto, encontré una estructura estable:

  • Asunto: “un auricular inalámbrico negro mate en un fondo blanco sin costuras”
  • Ángulo o lente: “ángulo de 45 grados, iluminación suave de estudio”
  • Pistas de contexto: “sombra mínima, sin reflejos”

Evité acumular estilos (“cinematográfico, sombrío, editorial, brillante”) porque las imágenes se desviaban. Los prompts cortos y simples dieron resultados más predecibles.

Dos pasadas me ayudaron a iterar:

  • Primera pasada: prompt amplio para ver composición.
  • Segunda pasada: añade restricciones solo donde sea necesario (longitud de sombra, textura de fondo).

size, Resoluciones admitidas (256-1536)

Usé tamaños cuadrados y verticales principalmente. La API aceptaba valores comunes desde 256 hasta 1536. Me adherí a 512 para vistas previas rápidas y 1024 para activos finales. 1536 produjo buenos detalles pero costó más tiempo y tokens. Si estás generando muchas variantes, comienza en pequeño y amplía o vuelve a ejecutar prompts seleccionados con un tamaño mayor.

seed, Control de reproducibilidad

Seed importó más de lo que esperaba. Cuando encontré un aspecto que me gustó, guardé el seed para poder ajustar solo una variable (como la densidad de fondo) sin derivar demasiado. Si cambié el prompt mucho, limpié el seed para evitar luchar contra el sesgo anterior del modelo. En la práctica: registré prompt, tamaño y seed por ID de imagen. Hizo que los re-renders fueran aburridos, de una manera buena.

output_format, JPEG vs PNG vs WebP

  • JPEG: ligero y rápido. Bueno para vistas previas y activos web sin transparencia.
  • PNG: ​sin pérdida, más grande. Lo usé para superposiciones de UI o cuando necesitaba un borde limpio.
  • WebP: ​un punto medio sólido. Más pequeño que PNG, más limpio que JPEG agresivo.

Cuando estaba procesando por lotes, establecí vistas previas en JPEG y finales en PNG o WebP dependiendo del destino. Mezclar formatos en una ejecución es posible, pero lo mantuve consistente por trabajo para reducir la contabilidad.

Ejemplos de código

Inicio rápido con cURL Aquí está el camino más corto que usé para hacer una prueba de cordura del punto de conexión. Me gusta comenzar con cURL porque hace que los mensajes de error sean obvios.

Bash

curl -X POST https://api.wavespeed.ai/v1/z-image-turbo/generate \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a matte black wireless earbud on a white seamless background, soft studio lighting",
    "size": 1024,
    "seed": 12345,
    "output_format": "webp",
    "enable_sync_mode": true
  }' \
  --output preview.webp

Si el modo de sincronización está habilitado y es compatible con tu solicitud, la respuesta devuelve datos de imagen binaria o un campo base64 (depende de los encabezados y la configuración del servidor). Lo guardé directamente en un archivo durante las pruebas.

Implementación en Python Mantuve la versión de Python simple. Requests, un tiempo de espera y verificaciones de error básicas.

Python

import os
import requests
import base64

API_KEY = os.getenv("WAVESPEED_API_KEY")
URL = "https://api.wavespeed.ai/v1/z-image-turbo/generate"

payload = {
    "prompt": "cozy reading nook by a window, soft morning light, minimalist",
    "size": 1024,
    "output_format": "png",
    "enable_sync_mode": True,
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

resp = requests.post(URL, json=payload, headers=headers, timeout=30)
resp.raise_for_status()

# Some deployments return JSON with base64. Others return binary directly.
content_type = resp.headers.get("Content-Type", "")
if "application/json" in content_type:
    data = resp.json()
    img_b64 = data.get("image_base64")
    if not img_b64:
        raise RuntimeError("No image in response")
    with open("output.png", "wb") as f:
        f.write(base64.b64decode(img_b64))
else:
    with open("output.png", "wb") as f:
        f.write(resp.content)

print("Saved output.png")

Ejemplo de JavaScript/Node.js En Node, prefiero fetch con AbortController para los tiempos de espera.

JavaScript

import fetch from 'node-fetch';
import { writeFileSync } from 'fs';

const API_KEY = process.env.WAVESPEED_API_KEY;
const URL = "https://api.wavespeed.ai/v1/z-image-turbo/generate";

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000);

const payload = {
  prompt: "abstract paper texture, soft fibers, off-white, subtle grain",
  size: 512,
  output_format: "jpeg",
  enable_sync_mode: true,
};

try {
  const resp = await fetch(URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
    signal: controller.signal,
  });

  if (!resp.ok) {
    throw new Error(`${resp.status} ${resp.statusText}`);
  }

  const buffer = Buffer.from(await resp.arrayBuffer());
  writeFileSync("out.jpg", buffer);
  console.log("Saved out.jpg");
} catch (err) {
  console.error("Request failed:", err.message);
} finally {
  clearTimeout(timeoutId);
}

Modo asincrónico vs sincrónico

enable_sync_mode explicado

Cuando enable_sync_mode era verdadero, las imágenes pequeñas (512–1024) a menudo llegaban de una sola vez. Eso fue agradable para vistas previas y casos puntuales. Pero el modo de sincronización agota el tiempo bajo carga pesada o tamaños más grandes. Cuando golpeé ese límite, la API devolvió una ID de trabajo en lugar de una imagen.

Sondeo de resultados

Asincrónico tomó un segundo para conectar, luego estuvo bien. El flujo:

  • POST una solicitud de generación con enable_sync_mode establecido en falso (u omítelo).
  • Recibe una job_id en el JSON.
  • Sondea un punto de conexión de estado cada 1–2 segundos con retroceso exponencial.
  • Cuando el estado es completado, descarga la imagen de la URL proporcionada.

Limité el sondeo a ~30 segundos antes de fallar elegantemente. En producción, cambiaría a un webhook si el servicio lo ofrece. El sondeo funciona, pero no es romántico.

Manejo de errores

Códigos de error comunes

Lo que vi durante las pruebas:

  • 400: un campo malo (tamaño fuera de rango, formato desconocido). Arregla tu carga útil.
  • 401: token Bearer faltante o inválido. Verifica el encabezado y el alcance de la clave.
  • 404: ruta de punto de conexión incorrecta o trabajo no encontrado (generalmente un error tipográfico).
  • 429: límite de velocidad. Retrocede y reintenta más tarde.
  • 500/503: problema de servicio transitorio. Reintenta con jitter.

Registré cuerpos de respuesta porque a menudo contenían una pista en lenguaje simple, útil cuando el tamaño o el seed fueron rechazados.

Mejores prácticas de límite de velocidad

Usé un token bucket en el cliente, con una cola corta. Si la API devolvía 429, retrocedía exponencialmente y añadía jitter aleatorio (50–200ms) para evitar rebaños ensordecedores. Además, procesar solicitudes por lotes (ver abajo) redujo picos de ráfagas.

Consejos de producción

Patrón de procesamiento por lotes

Generar una imagen por solicitud se sentía simple, pero malgastaba sobrecarga. Me mudé a un pequeño tamaño de lote (3–5 prompts cada uno) y obtuve un rendimiento más estable. Escribí resultados en una carpeta con fecha con un archivo manifest.json que guardaba prompt, tamaño, seed y ruta de salida. Ese manifesto resultó útil cuando un interesado dijo, “¿Podemos hacer lo mismo, pero con una luz más cálida?” Solo aumenté el seed o ajusté el prompt y volví a ejecutar.

Optimización de costos

Tres cosas importaron:

  • Disciplina de tamaño: vista previa a 512, finalizar a 1024 solo cuando sea necesario. 1536 solo para uso intensivo de cultivo.
  • Ajuste de formato: JPEG para vistas previas; WebP para la mayoría de compilaciones web; PNG cuando la transparencia es innegociable.
  • Parada temprana: si los primeros fotogramas se veían mal, cancelaba el trabajo en lugar de esperar. Ahorró centavos, que se suman.

Una nota más práctica: limité el gasto total diario en mis scripts. No es glamoroso, pero me protegió de un bucle desbocado.

Algunas observaciones finales. La API de Z-Image-Turbo no se sintió mágica. Probablemente por eso me gustó. Fue constante una vez que establecí los guardarraíles: seeds fijos para reproducibilidad, lotes pequeños, tiempos de espera conservadores. El modo de sincronización fue agradable para vistas previas; asincrónico tenía sentido para todo lo demás. Si ya estás nadando en herramientas de IA, esta no gritará para llamar la atención. Se sentará tranquilamente en la tubería y hará su trabajo.

Aún tengo curiosidad acerca de cómo maneja prompts ruidosos a resoluciones más altas. Esa es una prueba para otro día.