Как использовать JavaScript SDK WaveSpeedAI

JavaScript SDK WaveSpeedAI предоставляет простой способ интеграции генерации AI изображений и видео в ваши приложения Node.js и TypeScript. Это руководство охватывает все, что вам нужно для начала работы.

Предварительные требования

Перед тем как начать, убедитесь, что у вас есть:

Node.js 18+ установленный на вашем компьютере
API ключ WaveSpeedAI из wavespeed.ai/settings/api-keys

Установка

Установите SDK с помощью npm:

npm install wavespeed

Или с помощью yarn:

yarn add wavespeed

Настройка аутентификации

SDK требует ваш API ключ для аутентификации запросов. У вас есть два варианта:

Вариант 1: Переменная окружения (рекомендуется)

Установите переменную окружения WAVESPEED_API_KEY:

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

Затем используйте SDK напрямую:

import wavespeed from "wavespeed";

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

Вариант 2: Передача API ключа напрямую

Импортируйте класс Client и передайте ваш API ключ конструктору:

import { Client } from "wavespeed";

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

Генерирование вашего первого изображения

Вот полный пример, который генерирует изображение с использованием 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

Метод run() обрабатывает весь рабочий процесс: отправку запроса, опрос на завершение и возврат результата.

Загрузка файлов

Для рабочих процессов, которые требуют входных изображений (например, изображение-в-видео), используйте метод upload() для получения URL, доступного WaveSpeedAI:

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

Параметры конфигурации

Параметры Client

Настройте поведение повтора при инициализации клиента:

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

Параметры Run

Настройте отдельные вызовы 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
  }
);

Работа с различными моделями

Текст-в-изображение

Генерируйте изображения из текстовых описаний:

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

Изображение-в-видео

Преобразуйте статические изображения в видео:

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

Текст-в-видео

Генерируйте видео непосредственно из текста:

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

Использование TypeScript

SDK включает определения TypeScript. Вот пример, безопасный по типам:

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

Обработка ошибок

Для производственных приложений настройте повторы и обрабатывайте ошибки правильно:

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