Cara Menggunakan WaveSpeedAI JavaScript SDK

WaveSpeedAI JavaScript SDK menyediakan cara sederhana untuk mengintegrasikan generasi gambar dan video AI ke dalam aplikasi Node.js dan TypeScript Anda. Panduan ini mencakup semua yang Anda butuhkan untuk memulai.

Prasyarat

Sebelum Anda mulai, pastikan Anda memiliki:

Node.js 18+ terinstal di mesin Anda
Kunci API WaveSpeedAI dari wavespeed.ai/settings/api-keys

Instalasi

Instal SDK menggunakan npm:

npm install wavespeed

Atau dengan yarn:

yarn add wavespeed

Menyiapkan Autentikasi

SDK membutuhkan kunci API Anda untuk mengautentikasi permintaan. Anda memiliki dua opsi:

Opsi 1: Variabel Lingkungan (Direkomendasikan)

Atur variabel lingkungan WAVESPEED_API_KEY:

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

Kemudian gunakan SDK secara langsung:

import wavespeed from "wavespeed";

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

Opsi 2: Teruskan Kunci API Langsung

Impor kelas Client dan teruskan kunci API Anda ke konstruktor:

import { Client } from "wavespeed";

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

Membuat Gambar Pertama Anda

Berikut adalah contoh lengkap yang menghasilkan gambar menggunakan 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

Metode run() menangani seluruh alur kerja: mengirimkan permintaan, polling untuk penyelesaian, dan mengembalikan hasilnya.

Mengunggah File

Untuk alur kerja yang memerlukan gambar masukan (seperti image-to-video), gunakan metode upload() untuk mendapatkan URL yang dapat diakses 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

Opsi Konfigurasi

Opsi Klien

Konfigurasikan perilaku percobaan ulang saat menginisialisasi klien:

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

Opsi Jalankan

Konfigurasikan panggilan run() individual:

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

Bekerja dengan Model Berbeda

Text-to-Image

Hasilkan gambar dari deskripsi teks:

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

Image-to-Video

Ubah gambar statis menjadi video:

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

Text-to-Video

Hasilkan video langsung dari teks:

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

Penggunaan TypeScript

SDK mencakup definisi TypeScript. Berikut adalah contoh yang aman untuk tipe:

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

Penanganan Kesalahan

Untuk aplikasi produksi, konfigurasikan percobaan ulang dan tangani kesalahan dengan baik:

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