WaveSpeed JavaScript SDK

Official JavaScript/TypeScript SDK for the WaveSpeed inference platform

🌐 Visit wavespeed.ai • 📖 Documentation • 💬 Issues

---

Introduction

WaveSpeed JavaScript/TypeScript SDK — Official JS/TS SDK for the WaveSpeed inference platform. This library offers a clean, unified, and high-performance API for your applications.

Installation

npm install wavespeed

API Client

Run WaveSpeed AI models with a simple API:

importwavespeedfrom'wavespeed';constoutput=awaitwavespeed.run("wavespeed-ai/z-image/turbo",{prompt: "Cat"});console.log(output["outputs"][0]);// Output URL

Authentication

Set your API key via environment variable (You can get your API key from https://wavespeed.ai/accesskey):

export WAVESPEED_API_KEY="your-api-key"

Or pass it directly:

import{Client}from'wavespeed';constclient=newClient("your-api-key");constoutput=awaitclient.run("wavespeed-ai/z-image/turbo",{prompt: "Cat"});

Options

constoutput=awaitwavespeed.run("wavespeed-ai/z-image/turbo",{prompt: "Cat"},{timeout: 36000.0,// Max wait time in seconds (default: 36000.0)pollInterval: 1.0,// Status check interval (default: 1.0)enableSyncMode: false,// Best-effort sync result attempt (default: false)});

Sync Mode

Use enableSyncMode: true to ask the API to wait for the result in the initial request. If the server-side sync wait times out, the SDK raises WavespeedSyncTimeoutException with the task ID/result URL; the task continues processing and can be queried later.

Note: Not all models support sync mode. Check the model documentation for availability.

constoutput=awaitwavespeed.run("wavespeed-ai/z-image/turbo",{prompt: "Cat"},{enableSyncMode: true});

Retry Configuration

Configure retries at the client level:

import{Client}from'wavespeed';constclient=newClient("your-api-key",{maxRetries: 0,// Replacement task attempts (default: 0)maxConnectionRetries: 5,// Result-query GET retries; POST is never retriedretryInterval: 1.0,// Base delay between retries in seconds (default: 1.0)});

Upload Files

Upload images, videos, or audio files:

importwavespeedfrom'wavespeed';consturl=awaitwavespeed.upload("/path/to/image.png");console.log(url);

Getting Task ID and Debug Information

If you need access to the task ID for logging, tracking, or debugging, use runNoThrow() instead of run(). This method returns detailed information and does not throw exceptions:

constresult=awaitclient.runNoThrow(model,input);if(result.outputs){console.log("Success:",result.outputs);console.log("Task ID:",result.detail.taskId);// For tracking/debugging}else{console.log("Failed:",result.detail.error.message);// Error messageconsole.log("Task ID:",result.detail.taskId);// Still available on failureconsole.log("Stack trace:",result.detail.error.stack);// Full stack trace// Check specific error typesif(result.detail.errorinstanceofWavespeedTimeoutException){console.log("Request timed out");}elseif(result.detail.errorinstanceofWavespeedConnectionException){console.log("Connection failed");}elseif(result.detail.errorinstanceofWavespeedPredictionException){console.log("Prediction failed");}}

Running Tests

# Run all tests
npm test# Run a single test file
npm test -- tests/test_api.ts
# Run a specific test
npm test -- tests/test_api.ts -t "run success"

Environment Variables

API Client

Variable	Description
WAVESPEED_API_KEY	WaveSpeed API key
WAVESPEED_CLIENT_NAME	Client name reported in the X-Client-Name attribution header (takes priority over the clientName option)

License

MIT

---

WaveSpeed AI — AI image & video generation platform. Try it in the browser: Image generator · Video generator