如何使用 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);
}