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:
importai.wavespeed.Wavespeed;
importjava.util.Map;
publicclassExample {
publicstaticvoidmain(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:
importai.wavespeed.api.Client;
Clientclient = newClient("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.
importai.wavespeed.api.Client;
// Simple retry configurationClientclient = newClient(
"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:
importai.wavespeed.Wavespeed;
Stringurl = 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:
importai.wavespeed.api.Client;
Client.RunNoThrowResultresult = 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