Como Usar o SDK JavaScript do WaveSpeedAI

O SDK JavaScript WaveSpeedAI fornece uma maneira simples de integrar geração de imagens e vídeos com IA em suas aplicações Node.js e TypeScript. Este guia cobre tudo o que você precisa para começar.

Pré-requisitos

Antes de começar, certifique-se de que você tem:

Node.js 18+ instalado em sua máquina
Uma chave de API WaveSpeedAI em wavespeed.ai/settings/api-keys

Instalação

Instale o SDK usando npm:

npm install wavespeed

Ou com yarn:

yarn add wavespeed

Configurando a Autenticação

O SDK precisa de sua chave de API para autenticar solicitações. Você tem duas opções:

Opção 1: Variável de Ambiente (Recomendado)

Defina a variável de ambiente WAVESPEED_API_KEY:

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

Em seguida, use o SDK diretamente:

import wavespeed from "wavespeed";

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

Opção 2: Passe a Chave de API Diretamente

Importe a classe Client e passe sua chave de API para o construtor:

import { Client } from "wavespeed";

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

Gerando Sua Primeira Imagem

Aqui está um exemplo completo que gera uma imagem 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

O método run() gerencia todo o fluxo de trabalho: enviando a solicitação, sondando a conclusão e retornando o resultado.

Carregando Arquivos

Para fluxos de trabalho que requerem imagens de entrada (como imagem para vídeo), use o método upload() para obter uma URL que WaveSpeedAI possa acessar:

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

Opções de Configuração

Opções do Cliente

Configure o comportamento de repetição ao inicializar o 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
});

Opções de Execução

Configure chamadas individuais de run():

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
  }
);

Trabalhando com Diferentes Modelos

Texto para Imagem

Gere imagens a partir de descrições 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"
  }
);

Imagem para Vídeo

Transforme imagens estáticas em vídeos:

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 para Vídeo

Gere vídeos diretamente 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

O SDK inclui definições de TypeScript. Aqui está um exemplo com segurança de tipo:

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

Tratamento de Erros

Para aplicações de produção, configure repetições e trate erros adequadamente:

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);
}