GitHub - WaveSpeedAI/wavespeed-javascript: WaveSpeedAI JavaScript/TypeScript SDK — Official JS/TS SDK for WaveSpeedAI inference platform. This library offers a clean, unified, and high-performance API for your applications.

Introduction

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

Installation

API Client

Run WaveSpeed AI models with a simple API:

import wavespeed from 'wavespeed';

const output = await wavespeed.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';

const client = new Client("your-api-key");
const output = await client.run("wavespeed-ai/z-image/turbo", { prompt: "Cat" });

Options

const output = await wavespeed.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,  // Single request mode, no polling (default: false)
  }
);

Sync Mode

Use enableSyncMode: true for a single request that waits for the result (no polling).

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

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

Retry Configuration

Configure retries at the client level:

import { Client } from 'wavespeed';

const client = new Client("your-api-key", {
  maxRetries: 0,            // Task-level retries (default: 0)
  maxConnectionRetries: 5,  // HTTP connection retries (default: 5)
  retryInterval: 1.0,       // Base delay between retries in seconds (default: 1.0)
});

Upload Files

Upload images, videos, or audio files:

import wavespeed from 'wavespeed';

const url = await wavespeed.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:

const result = await client.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 message
  console.log("Task ID:", result.detail.taskId);  // Still available on failure
  console.log("Stack trace:", result.detail.error.stack);  // Full stack trace
  
  // Check specific error types
  if (result.detail.error instanceof WavespeedTimeoutException) {
    console.log("Request timed out");
  } else if (result.detail.error instanceof WavespeedConnectionException) {
    console.log("Connection failed");
  } else if (result.detail.error instanceof WavespeedPredictionException) {
    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

License

MIT