Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.reactor.inc/llms.txt

Use this file to discover all available pages before exploring further.

Reactor is the base class for every model on the platform. It speaks raw JSON over the wire: open a session, send commands by name, and receive generic message events. Typed SDKs like HeliosModel and other model-specific packages extend Reactor:
Inheritance
class HeliosModel(Reactor): ...
The typed SDKs add named methods that mirror the model’s published commands (set_prompt(), send_image(), …). Under the hood they call send_command() on this base class. Same wire protocol, just typed. You can always drop down to Reactor directly to send any command as raw JSON; see the SDK Reference overview for when each path makes sense. For the list of commands and events a specific model accepts, see the Model API Reference.

​
Constructor

Signature
Reactor(
    model_name: str,
    api_key: str | None = None,
    api_url: str = "https://api.reactor.inc",
    local: bool = False,
)
​
model_name
str
required
The name of the model to connect to.
​
api_key
str
Your Reactor API key. The SDK automatically exchanges this for a token during connect(). Required unless local=True.
​
api_url
str
default:"https://api.reactor.inc"
The API URL. Ignored if local=True.
​
local
bool
default:"False"
If True, connects to a local runtime at http://localhost:8080. No API key required.
Example
from reactor_sdk import Reactor

reactor = Reactor(model_name="your-model-name", api_key="rk_...")
The Reactor class also supports async with for automatic cleanup:
Context manager
from reactor_sdk import Reactor

async with Reactor(model_name="your-model-name", api_key="rk_...") as reactor:
    await reactor.connect()
    await reactor.send_command("start", {})

​
Methods

​
connect()

Establishes a connection to the coordinator, waits for GPU assignment, and opens a WebRTC connection to the model. If api_key was provided, fetches a token first.
Signature
await reactor.connect() -> None
Raises: RuntimeError if authentication fails or if already connected.

​
disconnect()

Closes the connection.
Signature
await reactor.disconnect(recoverable: bool = False) -> None
​
recoverable
bool
default:"False"
If True, the session is kept alive on the server and can be resumed with reconnect(). If False, the session is terminated.

​
reconnect()

Reconnects to an existing session after a recoverable disconnect.
Signature
await reactor.reconnect() -> None
Requires an active session_id from a previous connection.

​
send_command()

Sends a command to the model.
Signature
await reactor.send_command(command: str, data: Any) -> None
​
command
str
required
The command name. Must match a command defined on the model.
​
data
dict
required
The command payload. Shape depends on the command.
Example
await reactor.send_command("set_prompt", {"prompt": "a mountain landscape"})
You can also pass FileRef values from upload_file() as parameters. See File Uploads for details.

​
upload_file()

Uploads a file and returns a FileRef that can be passed into send_command().
Signature
await reactor.upload_file(
    file: BinaryIO | bytes | str | os.PathLike,
    *,
    name: str | None = None,
    mime_type: str | None = None,
) -> FileRef
​
file
BinaryIO | bytes | str | PathLike
required
The file to upload. Accepts a file path, raw bytes, or a file-like object opened in binary mode.
​
name
str
Custom filename. Inferred from the file path or file object when not given. Defaults to "upload" for raw bytes.
​
mime_type
str
MIME type. Guessed from the filename when not given. Defaults to "application/octet-stream".
Example
ref = await reactor.upload_file("photo.jpg")
await reactor.send_command("set_image", {"image": ref})
Can only be called when the status is READY.

​
publish_track()

Publishes a named media track to the model.
Signature
await reactor.publish_track(name: str, track: MediaStreamTrack) -> None
​
name
str
required
Track name. Must match a sendonly track name from the model’s capabilities.
​
track
MediaStreamTrack
required
An aiortc.MediaStreamTrack to publish.

​
unpublish_track()

Stops publishing a named track to the model.
Signature
await reactor.unpublish_track(name: str) -> None
​
name
str
required
The name of the track to stop publishing.

​
set_frame_callback()

Sets a callback to receive video frames as NumPy arrays. Equivalent to @reactor.on_frame.
Signature
reactor.set_frame_callback(callback: FrameCallback | None) -> None
​
callback
FrameCallback | None
required
A function that receives frames as (H, W, 3) uint8 RGB NumPy arrays. Pass None to stop receiving frames.

​
on()

Registers an event handler.
Signature
reactor.on(event: ReactorEvent, handler: Callable) -> None

​
off()

Removes an event handler.
Signature
reactor.off(event: ReactorEvent, handler: Callable) -> None

​
get_status()

Returns the current connection status.
Signature
reactor.get_status() -> ReactorStatus
Returns ReactorStatus.DISCONNECTED, CONNECTING, WAITING, or READY.

​
get_state()

Returns the current status and last error.
Signature
reactor.get_state() -> ReactorState

​
get_session_id()

Returns the current session ID, or None if not connected.
Signature
reactor.get_session_id() -> str | None

​
get_last_error()

Returns the most recent error, or None if no errors have occurred.
Signature
reactor.get_last_error() -> ReactorError | None

​
get_capabilities()

Returns the model’s capabilities (tracks, commands, emission FPS), or None if not yet connected.
Signature
reactor.get_capabilities() -> Capabilities | None

​
get_session_info()

Returns the full session response from the coordinator, or None if not connected.
Signature
reactor.get_session_info() -> CreateSessionResponse | None

​
get_remote_tracks()

Returns all remote tracks received from the model, keyed by track name.
Signature
reactor.get_remote_tracks() -> dict[str, MediaStreamTrack]

​
Events

EventPayloadDescription
"status_changed"ReactorStatusConnection status changed
"session_id_changed"str | NoneSession ID changed
"message"AnyApplication message from the model
"runtime_message"AnyInternal platform message
"track_received"(name: str, track: MediaStreamTrack)Named track received
"error"ReactorErrorError occurred
"session_expiration_changed"float | NoneSession expiration time updated
"capabilities_received"CapabilitiesModel capabilities received after session creation
Python events use snake_case (e.g., "status_changed") while the JavaScript SDK uses camelCase (e.g., "statusChanged").