如何使用 WaveSpeedAI JavaScript SDK

WaveSpeedAI JavaScript SDK 提供了一個簡單的方式，將 AI 影像和影片生成整合到您的 Node.js 和 TypeScript 應用程式中。本指南涵蓋了您開始所需的所有內容。

前置要求

開始之前，請確保您已擁有：

Node.js 18+ 已安裝在您的機器上
來自 wavespeed.ai/settings/api-keys 的 WaveSpeedAI API 金鑰

安裝

使用 npm 安裝 SDK：

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() 方法取得 WaveSpeedAI 可以存取的 URL：

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

組態選項

客戶端選項

初始化客戶端時設定重試行為：

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() 呼叫：

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