Reactor

inc.reactor.sdk.Reactor represents a client connection and its session. It implements AutoCloseable and is thread-safe. Operations such as connecting and sending commands return CompletableFuture values. See Installation for dependencies and a complete example, and the Reactor Javadoc for every overload. The snippets below use an open Reactor reactor; command and media operations need a connected session. Import SDK types from inc.reactor.sdk.

Create a client

Build ReactorOptions with the API URL and the model’s full owner/name, then call Reactor.open(options). Opening a client does not connect it.

Option	Meaning
`ReactorOptions.builder(apiUrl, modelName)`	API URL and model name, such as `https://api.reactor.inc` and `reactor/helios`
`.jwt(token)`	JWT obtained from your backend
`.local(true)`	Enable local development, including accepting a local self-signed certificate
`.dispatcher(dispatcher)`	Choose the executor for control events; defaults to a client-owned background thread

For a local model, set the API URL to http://localhost:8080 and .local(true) explicitly. For Swing, .dispatcher(javax.swing.SwingUtilities::invokeLater) delivers control events on the UI thread. Frame callbacks run separately; see Track.

Authentication

Use .jwt(token) in applications distributed to users. A trusted backend can exchange its API key with Reactor.fetchJwt(apiUrl, apiKey), which returns CompletableFuture<String>. That two-argument call grants everything the key allows. To issue a scoped token, use the four-argument overload:

var scope = JsonValue.object()
        .putArray("models", java.util.List.of(JsonValue.of("reactor/helios")))
        .put("max_sessions", 1)
        .put("expires_after", 3600)
        .build();
String token = Reactor.fetchJwt("https://api.reactor.inc", apiKey, scope, false).join();

Run this exchange on your backend, where apiKey is held securely. See Authentication for token scope and expiry.

Session lifecycle

Method	Behavior
`connect()`	Create a session and establish the connection
`connect(sessionId, connectionId)`	Join an existing session; pass `null` for a new connection slot
`reconnect()`	Re-establish the connection on the same session
`disconnect()`	Leave the session, ending it if this client created it
`close()`	Release the client and settle pending operations; safe to call more than once
`status()`	Read the current `ConnectionStatus`
`sessionId()`	Read an `Optional<String>` containing the current session ID

Call disconnect() before close() to end a session you created. Use try-with-resources so the client is released even on failure. A session joined by ID remains available to its owner after you disconnect. To restore a connection on the same session, call reconnect() without first calling disconnect(). Receiving tracks resume after reconnect. Sending tracks must be published again before pushing frames. join() waits and wraps an asynchronous failure in CompletionException. Future cancellation stops waiting for the result; it does not undo an operation already sent. See Errors for handling failures.

Commands and schema

Use command names and arguments from the model’s API reference. requestSchema() returns the running model’s schema as CompletableFuture<JsonValue>.

var reply = reactor.sendCommand("set_prompt", JsonValue.object()
        .put("prompt", "a mountain landscape")
        .build()).join();
reply.ifPresent(message -> System.out.println(message.dataOrNull().toJsonString()));

sendCommand(name) sends a command with no arguments. Both overloads return CompletableFuture<Optional<CommandReply>>. An empty optional means the model acknowledged the command without returning a message; it is a successful result.

Upload files

uploadFile(Path) uploads a file; uploadBytes(byte[], name, mimeType) uploads bytes already in memory. Both return a FileRef. Pass uploaded files separately from JSON arguments, keyed by the command’s parameter name:

var image = reactor.uploadFile(java.nio.file.Path.of("photo.jpg")).join();
reactor.sendCommand("set_image", JsonValue.object().build(),
        java.util.Map.of("image", image)).join();

This example requires a model with a set_image command accepting an image parameter. When a model accepts file references inside a list or nested object, insert FileRef.toJsonValue() into the JSON arguments instead. See File uploads.

Recordings

requestClip(durationSeconds) requests a recent window; requestRecording() requests the session recording. Each returns a Clip once the request is accepted. The media may not be ready yet. downloadClip waits for readiness and assembles a playable file:

var clip = reactor.requestClip(10.0).join();
var saved = reactor.downloadClip(clip, java.nio.file.Path.of("clip.mp4"),
        (done, total) -> System.out.println(done + "/" + total)).join();
System.out.println(saved.path());

Pass null instead of a progress callback if you do not need updates. An overload accepts readyTimeoutSeconds before the callback: it bounds the wait beyond the clip’s predicted ready time. The default waits while the session can still produce the clip. Keep the session open until the download completes. Closing the client while a download is running fails its future but does not cancel the download; the file may still arrive. See Recordings.

Events

Register handlers before connecting when you need the initial lifecycle events. Each registration returns a Subscription; call close() on it to remove the handler.

Registration	Payload
`onStatus(handler)`	`ConnectionStatus`
`onError(handler)`	`ReactorException`
`onMessage(handler)`	Model message as `JsonValue`
`onRuntimeMessage(handler)`	Platform message as `JsonValue`
`onCapabilities(handler)`	Session capabilities as `JsonValue`
`onSessionId(handler)`	`Optional<String>`, empty when the session ID clears

Control events use the configured dispatcher. Media callbacks are registered on individual tracks.

Connection statistics

getStats() returns CompletableFuture<Stats> for inspecting the connection. Use setBitrate(minBps, startBps, maxBps) to set connection bitrate bounds in bits per second; a negative value leaves that bound unset. See the Stats Javadoc for available measurements.

Get Started

Concepts

SDK Reference

Resources

Create a client

Authentication

Session lifecycle

Commands and schema

Upload files

Recordings

Events

Connection statistics

​Create a client

​Authentication

​Session lifecycle

​Commands and schema

​Upload files

​Recordings

​Events

​Connection statistics

Create a client

Authentication

Session lifecycle

Commands and schema

Upload files

Recordings

Events

Connection statistics