WaveSpeedAI Java SDK

Official Java SDK for the WaveSpeedAI inference platform

🌐 Visit wavespeed.ai • 📖 Documentation • 💬 Issues

---

Installation

Maven

<dependency>
  <groupId>ai.wavespeed</groupId>
  <artifactId>wavespeed-java-sdk</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>

Gradle

implementation 'ai.wavespeed:wavespeed-java-sdk:0.1.0-SNAPSHOT'

API Client

Run WaveSpeed AI models with a simple API:

import ai.wavespeed.WaveSpeed;
import ai.wavespeed.openapi.client.model.Prediction;
import java.util.HashMap;
import java.util.Map;

public class Example {
    public static void main(String[] args) {
        WaveSpeed client = new WaveSpeed("your-api-key");

        try {
            // Prepare input
            Map<String, Object> input = new HashMap<>();
            input.put("prompt", "A beautiful sunset over mountains");

            // Run model and wait for completion
            Prediction result = client.run("wavespeed-ai/z-image/turbo", input);

            System.out.println("Output: " + result.getOutputs());

        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Authentication

Set your API key via environment variable:

export WAVESPEED_API_KEY="your-api-key"

Or pass it directly:

WaveSpeed client = new WaveSpeed("your-api-key");

You can get your API key from https://wavespeed.ai/accesskey.

Options

Prediction result = client.run(
    "wavespeed-ai/z-image/turbo",
    input,
    300.0,     // timeout in seconds (default: 36000.0)
    2.0,       // poll interval in seconds (default: 1.0)
    false      // enable sync mode (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.

Prediction result = client.run(
    "wavespeed-ai/z-image/turbo",
    input,
    null,      // use default timeout
    null,      // use default poll interval
    true       // enable sync mode
);

Retry Configuration

Configure retries when creating the client:

WaveSpeed client = new WaveSpeed(
    "your-api-key",
    null,      // use default poll interval
    null,      // use default timeout
    0,         // task-level retries (default: 0)
    5,         // HTTP connection retries (default: 5)
    1.0        // base delay between retries in seconds (default: 1.0)
);

Upload Files

Upload images, videos, or audio files:

import ai.wavespeed.WaveSpeed;

WaveSpeed client = new WaveSpeed("your-api-key");

try {
    String downloadUrl = client.upload("/path/to/image.png");
    System.out.println("Upload URL: " + downloadUrl);
} catch (Exception e) {
    System.err.println("Upload failed: " + e.getMessage());
}

Building & Testing

Run Tests

mvn test

Build JAR

mvn clean package

Install Locally

mvn clean install

Environment Variables

Variable	Description
WAVESPEED_API_KEY	WaveSpeed API key
WAVESPEED_BASE_URL	API base URL (optional)

License

MIT