Official Java SDK for the WaveSpeedAI inference platform
WaveSpeedAI Java Client — Official Java SDK for WaveSpeedAI inference platform. This library provides a clean, unified, and high-performance API for your Java applications.
Download wavespeed-java-sdk-0.2.5.jar from the
v0.2.5 release
and add it to your application's classpath (coordinates: ai.wavespeed:wavespeed-java-sdk:0.2.5).
The SDK is not published to Maven Central (or any other registry) yet: the release workflow currently only builds the JARs, so GitHub release assets are the official distribution channel. The release also provides source and Javadoc JARs.
Run WaveSpeed AI models with a simple API:
import ai.wavespeed.Wavespeed; import java.util.Map; public class Example { public static void main(String[] args) { Map<String, Object> output = Wavespeed.run( "wavespeed-ai/z-image/turbo", Map.of("prompt", "Cat") ); System.out.println(output.get("outputs")); // Output URL } }
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 ai.wavespeed.api.Client; Client client = new Client("your-api-key"); Map<String, Object> output = client.run( "wavespeed-ai/z-image/turbo", Map.of("prompt", "Cat") );
Map<String, Object> output = Wavespeed.run( "wavespeed-ai/z-image/turbo", Map.of("prompt", "Cat"), 36000.0, // timeout - Max wait time in seconds (default: 36000.0) 1.0, // pollInterval - Status check interval (default: 1.0) false, // enableSyncMode - Best-effort sync result attempt (default: false) null // maxRetries - Task-level retries (default: 0) );
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 throws an error 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.
Map<String, Object> output = Wavespeed.run( "wavespeed-ai/z-image/turbo", Map.of("prompt", "Cat"), true // enableSyncMode );
Configure retries at the client level. Retries only apply to idempotent
result-query GET requests; the submission POST is sent exactly once and is
never retried, because a failed submission may still have created the task
on the server. When that happens the SDK throws
ai.wavespeed.WavespeedSubmissionException.
import ai.wavespeed.api.Client; // Simple retry configuration Client client = new Client( "your-api-key", 3, // maxRetries - Task-level retries (default: 0) 5, // maxConnectionRetries - Result-query GET retries; the submission POST is never retried (default: 5) 1.0 // retryInterval - Base delay between retries in seconds (default: 1.0) );
Upload images, videos, or audio files:
import ai.wavespeed.Wavespeed; String url = Wavespeed.upload("/path/to/image.png"); System.out.println(url);
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:
import ai.wavespeed.api.Client; Client.RunNoThrowResult result = client.runNoThrow(model, input); if (result.getOutputs() != null) { System.out.println("Success: " + result.getOutputs()); System.out.println("Task ID: " + result.getDetail().getTaskId()); // For tracking/debugging } else { System.out.println("Failed: " + result.getDetail().getError()); System.out.println("Task ID: " + result.getDetail().getTaskId()); // Still available on failure }
# Run all tests mvn test # Run a single test file mvn test -Dtest=ClientTest # Run a specific test mvn test -Dtest=ClientTest#testInitWithApiKey
| Variable | Description |
|---|---|
WAVESPEED_API_KEY |
WaveSpeed API key |
WAVESPEED_CLIENT_NAME |
Channel-attribution name sent as the X-Client-Name header. Takes precedence over Client.setClientName(); defaults to wavespeed-java |
MIT
WaveSpeed AI — AI image & video generation platform. Try it in the browser: Image generator · Video generator