Quickstart - Reactor

JavaScript
React
Python

Connect to a real-time world model with the imperative Reactor client and render frames into a <video> element. By the end of this guide you’ll have real-time AI video streaming wired into your app.

Want a ready-to-run app instead of wiring it up by hand? Scaffold a complete project — SDK installed and secure auth already configured — in one command:

npx create-reactor-app my-app --model=helios

See the React tab for the full CLI walkthrough.

Prerequisites

Node.js 18+
A Reactor API key

Install the SDK

npm install @reactor-team/js-sdk

pnpm add @reactor-team/js-sdk

Mint a token on your server

Exchange your API key for a short-lived token on the server so the key never reaches the browser:

token.ts

const r = await fetch("https://api.reactor.inc/tokens", {
  method: "POST",
  headers: { "Reactor-API-Key": process.env.REACTOR_API_KEY! },
});
const { jwt } = await r.json();

For more information, see Authentication.

Connect and render frames

Create a Reactor object, attach the model’s video track to a <video> element, then connect with the token from your server. Helios stays idle until it has a prompt and a start command, so send those once the session is ready:

main.ts

import { Reactor } from "@reactor-team/js-sdk";

const video = document.querySelector("video")!;

const reactor = new Reactor({ modelName: "helios" });

reactor.on("trackReceived", (name: string, track: MediaStreamTrack) => {
  if (name !== "main_video") return;
  video.srcObject = new MediaStream([track]);
  void video.play();
});

// Once the session is ready, send a prompt and start generating.
reactor.on("statusChanged", async (status: string) => {
  if (status !== "ready") return;
  await reactor.sendCommand("set_prompt", { prompt: "A serene mountain landscape at sunrise" });
  await reactor.sendCommand("start", {});
});

const jwt = await getToken(); // fetch the token minted on your server
await reactor.connect(jwt);

Run your app

Serve the page and open it in your browser.

The <video> element starts playing once the track arrives, and real-time AI video streams to your page. Try editing the prompt to steer what the model generates. See the Helios reference for the full set of commands.

Connect a React app to a real-time world model. By the end of this guide, real-time AI video streams to your browser.

Prerequisites

Node.js 18+
A Reactor API key
Familiarity with Next.js Route Handlers. Real-time video streaming relies on a server route to mint short-lived tokens, so it works a little differently from a typical client-only gen-AI call.

Option 1: CLI command

The fastest way to get started. create-reactor-app generates a ready-to-run Next.js app for the model you pass with --model, with the SDK installed and secure auth already configured.

Create your app

npx create-reactor-app my-app --model=helios

pnpm create reactor-app my-app --model=helios

This clones the example application and installs dependencies.

Add your API key

Move into the new directory and create your .env file:

cd my-app
cp .env.example .env

Add your API key to .env:

.env

REACTOR_API_KEY=rk_your_api_key_here

Run your app

npm run dev

pnpm dev

Open http://localhost:3000. Click Connect, then enter a prompt. The model begins generating video in real time.

Option 2: Manual setup

Install the SDK

npm install @reactor-team/js-sdk

pnpm add @reactor-team/js-sdk

Create a token route

Add an API route that exchanges your key for a short-lived token:

api/token/route.ts

import { NextResponse } from "next/server";

export async function POST() {
  const r = await fetch("https://api.reactor.inc/tokens", {
    method: "POST",
    headers: { "Reactor-API-Key": process.env.REACTOR_API_KEY! },
  });
  const { jwt } = await r.json();

  return NextResponse.json({ jwt });
}

For more information, see Authentication.

Build your component

Fetch the token from your backend and pass it to the SDK. Helios stays idle until it has a prompt and a start command, so a small AutoStart component sends those once the session is ready:

app/page.tsx

"use client";

import { use, useEffect } from "react";
import { ReactorProvider, ReactorView, useReactor } from "@reactor-team/js-sdk";

async function getToken() {
  const r = await fetch("/api/token", { method: "POST" });
  const { jwt } = await r.json();
  return jwt;
}

const tokenPromise = getToken();

// Once the session is ready, send a prompt and start generating.
function AutoStart() {
  const { status, sendCommand } = useReactor((s) => s);

  useEffect(() => {
    if (status !== "ready") return;
    sendCommand("set_prompt", { prompt: "A serene mountain landscape at sunrise" });
    sendCommand("start", {});
  }, [status, sendCommand]);

  return null;
}

export default function App() {
  const token = use(tokenPromise);

  return (
    <ReactorProvider modelName="helios" jwtToken={token} connectOptions={{ autoConnect: true }}>
      <ReactorView className="w-full aspect-video" />
      <AutoStart />
    </ReactorProvider>
  );
}

Run your app

Start your dev server and open the app in your browser.

npm run dev

pnpm dev

Your app connects, the <ReactorView> mounts, and real-time AI video streams in. Try editing the prompt to steer what the model generates. See the Helios reference for the full set of commands.

Connect a Python script to a real-time world model and receive frames as NumPy arrays.

Prerequisites

Python 3.10+
A Reactor API key

Install the SDK

pip install reactor-sdk

Set your API key

export REACTOR_API_KEY=rk_your_api_key_here

Write your script

main.py

import asyncio
import os
from reactor_sdk import Reactor, ReactorStatus

async def main():
    reactor = Reactor(
        model_name="helios",
        api_key=os.environ["REACTOR_API_KEY"],
    )

    @reactor.on_frame
    def on_frame(frame):
        # (H, W, 3) uint8 RGB
        print(f"Frame: {frame.shape}")

    # Helios stays idle until it has a prompt and a start command.
    @reactor.on_status(ReactorStatus.READY)
    async def on_ready(status):
        await reactor.send_command("set_prompt", {"prompt": "A serene mountain landscape at sunrise"})
        await reactor.send_command("start", {})

    await reactor.connect()
    await asyncio.Event().wait()  # run until interrupted

asyncio.run(main())

Run it

python main.py

Frame: (768, 1280, 3) prints to the console as the model generates frames.

Next steps

Authentication

How to set up secure, production-ready auth for your app.

Using the SDK

Connect, send commands, receive video, and publish input from JavaScript, React, or Python.

Helios model

All available commands and the messages Helios emits.

​Prerequisites

​Prerequisites

​Option 1: CLI command

​Option 2: Manual setup

​Prerequisites

​Next steps

Authentication

Using the SDK

Helios model

Prerequisites

Prerequisites

Option 1: CLI command

Option 2: Manual setup

Prerequisites

Next steps