JavaScript SDK

The official JavaScript/TypeScript SDK for WaveSpeedAI. Run AI models in Node.js or browser environments.

Installation

npm install wavespeed

Or with yarn:

yarn add wavespeed

Quick Start

import wavespeed from 'wavespeed';
 
wavespeed.run("wavespeed-ai/z-image/turbo", {
  prompt: "A cat wearing a space suit",
  size: "1024*1024"
}, {
  pollInterval: 2.0,
  timeout: 3600
})
.then(output => {
  console.log(output["outputs"]);
})
.catch(error => {
  console.error("Generation failed:", error);
  process.exitCode = 1;
});

Authentication

Get your API key from wavespeed.ai/accesskey.

Option 1: Environment variable (recommended)

export WAVESPEED_API_KEY="your-api-key"

import wavespeed from 'wavespeed';
 
// SDK automatically reads WAVESPEED_API_KEY from environment
wavespeed.run("wavespeed-ai/z-image/turbo", { prompt: "A cat", size: "1024*1024" });

Option 2: Pass directly with Client

import { Client } from 'wavespeed';
 
const client = new Client("your-api-key");
client.run(
  "wavespeed-ai/z-image/turbo",
  { prompt: "A cat", size: "1024*1024" },
  { pollInterval: 2.0, timeout: 3600 }
)
.then(output => console.log(output.outputs))
.catch(error => { console.error(error); process.exitCode = 1; });

Configuration

Timeout & Polling

wavespeed.run("wavespeed-ai/z-image/turbo", {
  prompt: "A cat",
  size: "1024*1024"
}, {
  timeout: 36000,      // Max wait time in seconds (default: 36000)
  pollInterval: 2.0    // Status check interval
})
.then(output => console.log(output));

Use pollInterval: 2.0 as a practical default. A larger interval is appropriate for long-running tasks or high-volume workloads; avoid checking the same task more often than every 2 seconds.

Sync Mode

Some models support single-request result attempts:

wavespeed.run("wavespeed-ai/z-image/turbo", {
  prompt: "A cat",
  size: "1024*1024"
}, {
  enableSyncMode: true  // Wait for a result when supported
})
.then(output => console.log(output));

Note: If the result is not ready within the sync wait window, the SDK may surface a timeout error while the task continues processing. When the error includes a prediction ID or result URL, poll the result URL until the task reaches a terminal status. Not all models support sync mode. For production workloads and long-running tasks, async mode with polling or webhooks is more reliable. See Sync Mode for timeout and refund details.

Retry Configuration

import { Client } from 'wavespeed';
 
const client = new Client("your-api-key", {
  maxRetries: 0,              // Do not create a replacement task automatically
  maxConnectionRetries: 5,    // Retries result-query GETs, never submission POSTs
  retryInterval: 1.0
});

Submission POSTs are sent at most once because a disconnect can occur after the server has already created the task. Result-query GETs are safe to retry. Only enable task-level retries when creating a replacement task after a confirmed terminal failure is acceptable for your workload.

File Upload

Upload images, videos, or audio files to use as model inputs:

import wavespeed from 'wavespeed';
 
wavespeed.upload("/path/to/image.png")
.then(url => {
  console.log(url); // Use this URL as input for models
});

Environment Variables

Variable	Description
`WAVESPEED_API_KEY`	Your WaveSpeedAI API key

Links

Python SDK ComfyUI Integration