Cómo usar el SDK de JavaScript de WaveSpeedAI

El SDK de JavaScript de WaveSpeedAI proporciona una forma simple de integrar generación de imágenes y videos con IA en tus aplicaciones de Node.js y TypeScript. Esta guía cubre todo lo que necesitas para comenzar.

Requisitos previos

Antes de comenzar, asegúrate de tener:

Node.js 18+ instalado en tu máquina
Una clave API de WaveSpeedAI desde wavespeed.ai/settings/api-keys

Instalación

Instala el SDK usando npm:

npm install wavespeed

O con yarn:

yarn add wavespeed

Configurando la autenticación

El SDK necesita tu clave API para autenticar las solicitudes. Tienes dos opciones:

Opción 1: Variable de entorno (Recomendado)

Establece la variable de entorno WAVESPEED_API_KEY:

export WAVESPEED_API_KEY="your-api-key-here"

Luego usa el SDK directamente:

import wavespeed from "wavespeed";

const output = await wavespeed.run("wavespeed-ai/z-image/turbo", { prompt: "Cat" });

Opción 2: Pasar la clave API directamente

Importa la clase Client y pasa tu clave API al constructor:

import { Client } from "wavespeed";

const client = new Client("your-api-key-here");

Generando tu primera imagen

Aquí hay un ejemplo completo que genera una imagen usando Z-Image Turbo:

import wavespeed from "wavespeed";

const output = await wavespeed.run(
  "wavespeed-ai/z-image/turbo",
  { prompt: "A serene mountain landscape at sunset with golden light" }
);

console.log(output["outputs"][0]); // URL to the generated image

El método run() maneja todo el flujo de trabajo: enviar la solicitud, sondear la finalización y devolver el resultado.

Subiendo archivos

Para flujos de trabajo que requieren imágenes de entrada (como imagen a video), usa el método upload() para obtener una URL que WaveSpeedAI pueda acceder:

import wavespeed from "wavespeed";

// Upload a local image file
const imageUrl = await wavespeed.upload("./my-image.png");

// Use the uploaded image for video generation
const video = await wavespeed.run(
  "wavespeed-ai/wan-2.1/image-to-video",
  {
    image: imageUrl,
    prompt: "Camera slowly zooms in while clouds move in the background"
  }
);

console.log(video["outputs"][0]); // URL to the generated video

Opciones de configuración

Opciones del cliente

Configura el comportamiento de reintentos al inicializar el cliente:

import { Client } from "wavespeed";

const client = new Client(process.env.WAVESPEED_API_KEY, {
  maxRetries: 3,           // Max retries for failed requests
  maxConnectionRetries: 5, // Max retries for connection errors
  retryInterval: 1.0       // Seconds between retries
});

Opciones de ejecución

Configura llamadas run() individuales:

import wavespeed from "wavespeed";

const output = await wavespeed.run(
  "wavespeed-ai/z-image/turbo",
  { prompt: "A cute orange cat wearing a tiny hat" },
  {
    timeout: 60,        // Max seconds to wait for completion
    pollInterval: 0.5,  // Seconds between status checks
    enableSyncMode: true // Use synchronous mode if available
  }
);

Trabajando con diferentes modelos

Texto a imagen

Genera imágenes a partir de descripciones de texto:

import wavespeed from "wavespeed";

const output = await wavespeed.run(
  "wavespeed-ai/z-image/turbo",
  {
    prompt: "A futuristic cityscape with flying cars and neon lights",
    size: "1024x1024"
  }
);

Imagen a video

Transforma imágenes estáticas en videos:

import wavespeed from "wavespeed";

const imageUrl = await wavespeed.upload("./landscape.jpg");

const video = await wavespeed.run(
  "wavespeed-ai/wan-2.1/image-to-video",
  {
    image: imageUrl,
    prompt: "Gentle wind blowing through the trees"
  }
);

Texto a video

Genera videos directamente a partir de texto:

import wavespeed from "wavespeed";

const video = await wavespeed.run(
  "wavespeed-ai/wan-2.1/t2v-480p",
  {
    prompt: "A golden retriever running through a field of flowers"
  }
);

Uso de TypeScript

El SDK incluye definiciones de TypeScript. Aquí hay un ejemplo type-safe:

import wavespeed from "wavespeed";

interface GenerationOutput {
  outputs: string[];
  timings?: Record<string, number>;
}

const output: GenerationOutput = await wavespeed.run(
  "wavespeed-ai/z-image/turbo",
  { prompt: "An astronaut riding a horse on Mars" }
);

const imageUrl: string = output.outputs[0];
console.log(imageUrl);

Manejo de errores

Para aplicaciones de producción, configura reintentos y maneja errores correctamente:

import { Client } from "wavespeed";

const client = new Client(process.env.WAVESPEED_API_KEY, {
  maxRetries: 3,
  maxConnectionRetries: 5,
  retryInterval: 1.0
});

try {
  const output = await client.run(
    "wavespeed-ai/z-image/turbo",
    { prompt: "A beautiful sunset over the ocean" },
    { timeout: 120 }
  );
  console.log("Generated:", output.outputs[0]);
} catch (error) {
  console.error("Generation failed:", error.message);
}