Python SDK types

`FileRef`

A reference to an uploaded file, returned by upload_file(). Pass into send_command() to attach files to a command.

Definition

@dataclass(frozen=True)
class FileRef:
    upload_id: str    # Upload identifier
    name: str         # Filename
    mime_type: str    # MIME type (e.g. "image/jpeg")
    size: int         # File size in bytes

See File Uploads for usage examples.

`ReactorStatus`

Connection state enum. A str subclass, so it compares equal to the plain string too (ReactorStatus.READY == "ready").

Definition

from reactor_sdk import ReactorStatus

class ReactorStatus(str, Enum):
    DISCONNECTED = "disconnected"  # No active connection
    CONNECTING   = "connecting"    # Negotiating with the Reactor Platform
    WAITING      = "waiting"       # Waiting for a GPU to be assigned
    READY        = "ready"         # Connected to the model

`ReactorError`

Raised when a native operation fails — connect(), send_command(), upload_file(), request_clip(), and similarly for any other async method backed by the native library — and the payload of the "error" event / on_error. The same class either way: what on_error hands you is not a separate type that happens to agree with the exception, it is the exception. It is also the base class of a small hierarchy: every code in the error codes table below has its own subclass, so you can catch a specific failure by class instead of parsing .code.

Definition

class ReactorError(Exception):
    code: str = "INTERNAL_ERROR"

    def __init__(
        self,
        message: str,
        *,
        code: str | None = None,
        recoverable: bool = False,
        status: int | None = None,
        operation: str | None = None,
        retry_after_ms: float | None = None,
        timestamp_ms: float | None = None,
    ) -> None: ...

str

required

A stable, matchable code — see Error codes below, or a code the platform sent for a request it rejected and this package doesn’t have a class for.

str

required

The human-readable explanation.

bool

Whether the same call could succeed later. True is about the moment — a timeout, a 5xx, a transport that dropped — so waiting or reconnecting is worth something. False is about the request itself.

int

The HTTP status, when the failure came from one; None otherwise.

str

Which call failed, e.g. "connect", "send_command". None for a failure that isn’t tied to a specific call, like a transport that dropped on its own.

float

A backoff hint in milliseconds, when the platform sent one.

float

When this happened. Only ever set on the on_error event — a raised exception is already happening now, so there’s nothing this would tell you that catching it doesn’t.

Example

from reactor_sdk import ReactorError, UnauthorizedError, ConflictError

try:
    await reactor.connect()
except UnauthorizedError:
    token = await refresh()          # a specific, actionable failure
except ConflictError:
    ...                              # a previous run left the session orphaned
except ReactorError as error:
    if error.recoverable:
        await asyncio.sleep((error.retry_after_ms or 1000) / 1000)
        await reactor.reconnect()
    else:
        raise

The full list of subclasses: NetworkError, UnauthorizedError, NotFoundError, ConflictError, RateLimitedError, BadRequestError, ServerError, VersionMismatchError, DecodeError, InvalidStateError, SessionTerminalError, MessageTooLargeError, TransportError, DisconnectedError, RequestTimeoutError, AbortedError. All import from reactor_sdk directly. except ReactorError still catches every one of them, so existing broad except blocks keep working.

ConflictError and VersionMismatchError are real, current exceptions — don’t confuse them with the identically-named classes from the older aiortc-based py-sdk, which this package is not. Their codes and fields follow the table below, not that earlier library’s shape.

There is no component field. Earlier releases split codes by which tier of the platform failed (api, gpu); that field was removed because it wasn’t something a caller could act on, and it was possible for the same failure to be reported under two different codes depending on which tier noticed it first. Match on code alone.

Error codes

Every code in the table below has a matching exception class — the same code, the same fields, whether you catch it as an exception or receive it through on_error.

Code	Exception class	Recoverable	Description
`NETWORK_ERROR`	`NetworkError`	Usually	The request never got a reply — DNS, TLS, a refused socket
`UNAUTHORIZED`	`UnauthorizedError`	No	401/403 — the token is missing, expired, or not scoped for this call
`NOT_FOUND`	`NotFoundError`	No	404 — no such model, session, or upload
`CONFLICT`	`ConflictError`	No	409 — the session is in a state that doesn’t allow this, usually a previous run left it orphaned
`RATE_LIMITED`	`RateLimitedError`	Yes	429 — too many requests
`BAD_REQUEST`	`BadRequestError`	No	A 4xx other than the ones above — the request itself was wrong
`SERVER_ERROR`	`ServerError`	Yes	5xx — the Reactor Platform failed; the same request may work later
`VERSION_MISMATCH`	`VersionMismatchError`	No	This client and the platform disagree on the protocol — upgrade `reactor-sdk`
`DECODE_FAILED`	`DecodeError`	No	A reply arrived and could not be understood
`INVALID_STATE`	`InvalidStateError`	No	The operation isn’t allowed from the client’s current state, e.g. called before `connect()` or after leaving `ready`
`SESSION_TERMINAL`	`SessionTerminalError`	No	The session reached a state it cannot leave — start a new one
`MESSAGE_TOO_LARGE`	`MessageTooLargeError`	No	The payload exceeds what the data channel accepts — use `upload_file()` instead
`TRANSPORT_ERROR`	`TransportError`	Usually	The media transport failed
`DISCONNECTED`	`DisconnectedError`	Yes	The connection went away, in flight or after being established — `reconnect()` is the way back
`REQUEST_TIMEOUT`	`RequestTimeoutError`	Usually	The operation was sent and nothing came back in time
`ABORTED`	`AbortedError`	Usually	The operation was abandoned before it finished

Codes are open-ended. A command or a control request the model itself rejects reports the platform’s own code, which this list cannot enumerate — that raises the base ReactorError with code set to whatever arrived. Match on error.code for anything not in the table; never assume an unrecognized code means the error was malformed.

`TrackKind` / `TrackDirection`

Enums describing a Track. Both are str subclasses, so they compare equal to the plain string too.

Definition

from reactor_sdk import TrackKind, TrackDirection

class TrackKind(str, Enum):
    VIDEO = "video"
    AUDIO = "audio"

class TrackDirection(str, Enum):
    SENDONLY = "sendonly"  # Client input: you push frames into it
    RECVONLY = "recvonly"  # Model output: you receive frames from it

See Track for the object these describe.

`TrackList`

The type of reactor.tracks — a list[Track] subclass with filters that chain, for finding the track you mean without hardcoding its name.

Definition

class TrackList(list[Track]):
    def with_kind(self, kind: TrackKind | str) -> TrackList: ...
    def with_direction(self, direction: TrackDirection | str) -> TrackList: ...
    def one(self) -> Track: ...

Everything a list does keeps working — iterate, index, len() — and the filters return another TrackList, so they compose in either order:

Example

reactor.tracks                                              # every track
reactor.tracks.with_kind(TrackKind.VIDEO)                   # or "video"
reactor.tracks.with_direction(TrackDirection.RECVONLY)      # or "recvonly"

# The one you mean, with an error naming the candidates if there is not exactly one.
output = reactor.tracks.with_direction("recvonly").with_kind("video").one()

A track whose kind or direction the session hasn’t declared yet matches neither filter — there is nothing to match it against until the model’s capabilities arrive, shortly after connect(). one() raises ValueError if zero or more than one track matches, naming the candidates so the filter can be narrowed.

`Clip`

Returned by request_clip() / request_recording().

Definition

@dataclass(frozen=True)
class Clip:
    session_id: str
    kind: str
    start_marker: float
    end_marker: float
    now_marker: float
    predicted_ready_at_ms: float
    playlist_url: str

playlist_url is an HLS manifest — see Recordings for how to preview or download it.

`AuthError`

Raised by fetch_jwt() when an API key cannot be exchanged for a token — including automatically, inside connect(), when the Reactor constructor was given api_key rather than jwt.

Definition

class AuthError(RuntimeError):
    pass

`fetch_jwt()`

Exchanges an API key for a JWT. Used internally by connect() when the constructor was given api_key; call directly only if you need the token itself.

Signature

fetch_jwt(
    api_key: str,
    api_url: str = DEFAULT_API_URL,
    *,
    models: list[str] | None = None,
    max_sessions: int | None = None,
    expires_after: int | None = None,
) -> str

str

required

Your Reactor API key (rk_...).

str

The API URL. Defaults to the same production Reactor API endpoint the Reactor constructor itself defaults to — pass it explicitly only to mint a token against a different one.

list[str]

Scope the token to only create/operate sessions on these models. Omit for an unscoped token with the full permissions the key’s roles allow.

int

Caps how many sessions a scoped token may create. Ignored for unscoped tokens.

int

Token lifetime in seconds; the server clamps this to its own ceiling.

Returns the token as a str. Raises AuthError if the exchange fails for any reason, including a response with no token.

In most cases you don’t need this directly. Pass api_key to the Reactor constructor and the SDK handles the exchange automatically during connect().

`download_clip()`

Fetches every segment a Clip’s playlist_url names and concatenates them. Reactor does not host clips, so this — not a URL you can hand to a player directly — is how you get one onto disk or into memory. See Recordings for the full flow.

Signature

await download_clip(
    clip: Clip,
    path: str | os.PathLike | None = None,
    *,
    on_progress: Callable[[int, int], None] | None = None,
) -> bytes | None

Clip

required

A Clip from request_clip() / request_recording().

str | os.PathLike

Stream the download straight here instead of returning it. Omitting this returns the assembled bytes instead — see the Note below on which one to reach for.

Callable[[int, int], None]

Called after each segment finishes, as on_progress(done, total). Runs on the worker thread the fetch was dispatched to, not the event loop — fine for a counter or a log line, not a place to touch anything that isn’t thread-safe.

Example

clip = await reactor.request_clip(10)

await download_clip(clip, "clip.ts")   # streamed straight to the file, returns None
data = await download_clip(clip)       # no path: returns the assembled bytes instead

Given path, streams each segment straight to the file and returns None — nothing beyond one segment is ever held in memory. This is the one to reach for with request_recording(), which has no upper bound on a session’s length. Without path, assembles and returns the full bytes instead, which does mean holding the whole clip in memory: fine for a short request_clip() result, not the default choice for a long recording.

Built on urllib.request — the fetch itself is synchronous, dispatched to a thread internally (asyncio.to_thread) so the call above is the whole thing, not something you wrap yourself. Raises urllib.error.URLError (a fetch failed) or urllib.error.HTTPError (a non-2xx response — playlist_url and its segments expire) for a failure, and ValueError if the playlist names no segments at all.

Returns interleaved MPEG-TS bytes, not an MP4 — playable as-is by most players (ffplay, VLC, mpv), but remux with ffmpeg -i clip.ts -c copy clip.mp4 first if you specifically need that container.

Get Started

Concepts

SDK Reference

Resources

Python SDK types

`FileRef`

`ReactorStatus`

`ReactorError`

Error codes

`TrackKind` / `TrackDirection`

`TrackList`

`Clip`

`AuthError`

`fetch_jwt()`

`download_clip()`

​FileRef

​ReactorStatus

​ReactorError

​Error codes

​TrackKind / TrackDirection

​TrackList

​Clip

​AuthError

​fetch_jwt()

​download_clip()

`FileRef`

`ReactorStatus`

`ReactorError`

Error codes

`TrackKind` / `TrackDirection`

`TrackList`

`Clip`

`AuthError`

`fetch_jwt()`

`download_clip()`