Z-Image Java SDK for RunAPI

The Z-Image Java SDK is the language-specific package for Z-Image on RunAPI. Use it when your Java application needs typed builders, strict request validation, task status lookup, local polling helpers, file uploads, account helpers, and consistent RunAPI errors for Z-Image workflows.

This README is the Java package guide inside the public z-image-sdk repository. For the repository overview, start at ../README.md; for model details, use https://runapi.ai/models/z-image; for API reference, use https://runapi.ai/docs#z-image; for SDK docs, use https://runapi.ai/docs#sdk-z-image.

Requirements

The Java SDK targets Java 8 bytecode and is tested on Java 8, 11, 17, and 21.

Install

Gradle:

dependencies {
  implementation("ai.runapi:runapi-z-image:0.1.1")
}

Maven:

<dependency>
  <groupId>ai.runapi</groupId>
  <artifactId>runapi-z-image</artifactId>
  <version>0.1.1</version>
</dependency>

Use the BOM when multiple RunAPI Java modules are installed:

dependencies {
  implementation(platform("ai.runapi:runapi-bom:0.1.1"))
  implementation("ai.runapi:runapi-z-image")
}

Maven BOM:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>ai.runapi</groupId>
      <artifactId>runapi-bom</artifactId>
      <version>0.1.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Quick Start

import ai.runapi.zimage.ZImageClient;
import ai.runapi.zimage.types.TextToImageParams;
import ai.runapi.zimage.types.CompletedTextToImageResponse;
import ai.runapi.zimage.types.TextToImageModel;

ZImageClient client = ZImageClient.builder()
    .apiKey(System.getenv("RUNAPI_API_KEY"))
    .build();

CompletedTextToImageResponse result = client.textToImage().run(
    TextToImageParams.builder()
        .model(TextToImageModel.Z_IMAGE)
        .prompt("A bilingual poster with crisp typography")
        .aspectRatio("1:1")
        .build()
);

The client builder reads RUNAPI_API_KEY when .apiKey(...) is omitted. Set RUNAPI_BASE_URL or .baseUrl(...) only when using a non-default RunAPI endpoint.

Task Lifecycle

Most media endpoints are asynchronous. create(params) submits a task and returns its id, get(id) fetches the latest task state, and run(params) creates the task and polls until it reaches a terminal state. Synchronous resources expose run(params) only.

import ai.runapi.core.polling.TaskCreateResponse;
import ai.runapi.zimage.ZImageClient;
import ai.runapi.zimage.types.TextToImageParams;
import ai.runapi.zimage.types.TextToImageResponse;
import ai.runapi.zimage.types.TextToImageModel;

ZImageClient client = ZImageClient.builder()
    .apiKey(System.getenv("RUNAPI_API_KEY"))
    .build();

TextToImageParams params = TextToImageParams.builder()
    .model(TextToImageModel.Z_IMAGE)
    .prompt("A bilingual poster with crisp typography")
    .aspectRatio("1:1")
    .build();

TaskCreateResponse task = client.textToImage().create(params);
TextToImageResponse status = client.textToImage().get(task.getId());

Files

Each model package depends transitively on ai.runapi:runapi-core, so you can upload files through any model client.

import ai.runapi.core.files.FileCreateParams;
import ai.runapi.core.files.FileUploadResponse;
import java.nio.file.Paths;

FileUploadResponse uploaded = client.files().create(
    FileCreateParams.fromPath(Paths.get("input.png"))
        .fileName("input.png")
        .build()
);

URL and base64 sources use the same entry point:

FileUploadResponse fromUrl = client.files().create(
    FileCreateParams.fromUrl("https://cdn.runapi.ai/public/samples/input.png")
        .fileName("input.png")
        .build()
);

FileUploadResponse fromBase64 = client.files().create(
    FileCreateParams.fromBase64("iVBORw0KGgo...")
        .fileName("input.png")
        .build()
);

RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.

Request Options

import ai.runapi.core.RequestOptions;
import java.time.Duration;

RequestOptions options = RequestOptions.builder()
    .pollingInterval(Duration.ofSeconds(3))
    .pollingMaxWait(Duration.ofMinutes(20))
    .maxRetries(0)
    .build();

Per-request options can override timeout, retries, headers, and polling behavior.

Error Handling

All SDK errors extend RunApiException.

import ai.runapi.core.errors.RateLimitException;
import ai.runapi.core.errors.RunApiException;
import ai.runapi.core.errors.ValidationException;

try {
  client.textToImage().run(params);
} catch (ValidationException error) {
  System.err.println(error.getMessage());
} catch (RateLimitException error) {
  System.err.println(error.getRetryAfter());
} catch (RunApiException error) {
  System.err.println(error.getCode() + " " + error.getStatusCode());
}

Links

• Model page: https://runapi.ai/models/z-image
• SDK docs: https://runapi.ai/docs#sdk-z-image
• Product docs: https://runapi.ai/docs#z-image
• Pricing and rate limits: https://runapi.ai/models/z-image
• Full catalog: https://runapi.ai/models
• Repository: https://github.com/runapi-ai/z-image-sdk

License

Licensed under the Apache License, Version 2.0.