Helios schema reference

// Set initial prompt (before starting)
await reactor.sendCommand("set_prompt", {
  prompt: "A serene mountain landscape at sunrise",
});

// Change prompt mid-generation. Automatically applies at the next chunk
await reactor.sendCommand("set_prompt", {
  prompt: "The landscape transitions to a stormy ocean",
});

const { setPrompt } = useHelios();

// Set initial prompt (before starting)
await setPrompt({ prompt: "A serene mountain landscape at sunrise" });

// Change prompt mid-generation. Automatically applies at the next chunk
await setPrompt({ prompt: "The landscape transitions to a stormy ocean" });

# Set initial prompt (before starting)
await reactor.send_command("set_prompt", {
    "prompt": "A serene mountain landscape at sunrise",
})

# Change prompt mid-generation. Automatically applies at the next chunk
await reactor.send_command("set_prompt", {
    "prompt": "The landscape transitions to a stormy ocean",
})

// Schedule initial prompt (required before start)
await reactor.sendCommand("schedule_prompt", {
  prompt: "A serene mountain landscape at sunrise",
  chunk: 0,
});

// Schedule a transition at chunk 10
await reactor.sendCommand("schedule_prompt", {
  prompt: "The mountain transforms into a futuristic city",
  chunk: 10,
});

const { schedulePrompt } = useHelios();

// Schedule initial prompt (required before start)
await schedulePrompt({
  prompt: "A serene mountain landscape at sunrise",
  chunk: 0,
});

// Schedule a transition at chunk 10
await schedulePrompt({
  prompt: "The mountain transforms into a futuristic city",
  chunk: 10,
});

# Schedule initial prompt (required before start)
await reactor.send_command("schedule_prompt", {
    "prompt": "A serene mountain landscape at sunrise",
    "chunk": 0,
})

# Schedule a transition at chunk 10
await reactor.send_command("schedule_prompt", {
    "prompt": "The mountain transforms into a futuristic city",
    "chunk": 10,
})

const ref = await reactor.uploadFile(imageFile);
await reactor.sendCommand("set_image", { image: ref });

// Swap mid-generation
const newRef = await reactor.uploadFile(newImageFile);
await reactor.sendCommand("set_image", { image: newRef });

const { uploadFile, setImage } = useHelios();

const ref = await uploadFile(imageFile);
await setImage({ image: ref });

// Swap mid-generation
const newRef = await uploadFile(newImageFile);
await setImage({ image: newRef });

ref = await reactor.upload_file(image_file)
await reactor.send_command("set_image", {"image": ref})

# Swap mid-generation
new_ref = await reactor.upload_file(new_image_file)
await reactor.send_command("set_image", {"image": new_ref})

const ref = await reactor.uploadFile(imageFile);
await reactor.sendCommand("set_conditioning", {
  prompt: "A cinematic slow zoom into the scene, golden hour lighting",
  image: ref,
});
await reactor.sendCommand("start", {});

const { uploadFile, setConditioning, start } = useHelios();

const ref = await uploadFile(imageFile);
await setConditioning({
  prompt: "A cinematic slow zoom into the scene, golden hour lighting",
  image: ref,
});
await start();

ref = await reactor.upload_file(image_file)
await reactor.send_command("set_conditioning", {
    "prompt": "A cinematic slow zoom into the scene, golden hour lighting",
    "image": ref,
})
await reactor.send_command("start", {})

await reactor.sendCommand("set_image_strength", { image_strength: 0.6 });

const { setImageStrength } = useHelios();

await setImageStrength({ image_strength: 0.6 });

await reactor.send_command("set_image_strength", {"image_strength": 0.6})

await reactor.sendCommand("set_sr_scale", { sr_scale: "2x" });

const { setSrScale } = useHelios();

await setSrScale({ sr_scale: "2x" });

await reactor.send_command("set_sr_scale", {"sr_scale": "2x"})

await reactor.sendCommand("set_seed", { seed: 42 });

const { setSeed } = useHelios();

await setSeed({ seed: 42 });

await reactor.send_command("set_seed", {"seed": 42})

await reactor.sendCommand("start", {});

const { start } = useHelios();

await start();

await reactor.send_command("start", {})

await reactor.sendCommand("pause", {});

const { pause } = useHelios();

await pause();

await reactor.send_command("pause", {})

await reactor.sendCommand("resume", {});

const { resume } = useHelios();

await resume();

await reactor.send_command("resume", {})

await reactor.sendCommand("reset", {});

const { reset } = useHelios();

await reset();

await reactor.send_command("reset", {})

await reactor.sendCommand("save_snapshot", { label: "before the storm" });

const { saveSnapshot } = useHelios();

await saveSnapshot({ label: "before the storm" });

await reactor.send_command("save_snapshot", {"label": "before the storm"})

// Restore the newest snapshot and continue with the current prompt.
await reactor.sendCommand("rewind", {});

// Restore snapshot 2, then steer the restored scene somewhere new.
await reactor.sendCommand("rewind", { snapshot_index: 2 });
await reactor.sendCommand("set_prompt", {
  prompt: "The same clearing, now under heavy snowfall",
});

const { rewind, setPrompt } = useHelios();

// Restore the newest snapshot and continue with the current prompt.
await rewind({});

// Restore snapshot 2, then steer the restored scene somewhere new.
await rewind({ snapshot_index: 2 });
await setPrompt({ prompt: "The same clearing, now under heavy snowfall" });

# Restore the newest snapshot and continue with the current prompt.
await reactor.send_command("rewind", {})

# Restore snapshot 2, then steer the restored scene somewhere new.
await reactor.send_command("rewind", {"snapshot_index": 2})
await reactor.send_command("set_prompt", {
    "prompt": "The same clearing, now under heavy snowfall",
})

reactor.on("message", (msg) => {
  if (msg.type === "snapshot_list") {
    for (const s of msg.data.snapshots) {
      console.log(`#${s.snapshot_index} · chunk ${s.chunk} · ${s.label || "unlabelled"}`);
    }
  }
});

await reactor.sendCommand("list_snapshots", {});

const { listSnapshots } = useHelios();

useHeliosSnapshotList((msg) => {
  for (const s of msg.snapshots) {
    console.log(`#${s.snapshot_index} · chunk ${s.chunk} · ${s.label || "unlabelled"}`);
  }
});

await listSnapshots();

@reactor.on_message
def handle(msg):
    if msg["type"] == "snapshot_list":
        for s in msg["data"]["snapshots"]:
            label = s["label"] or "unlabelled"
            print(f"#{s['snapshot_index']} · chunk {s['chunk']} · {label}")

await reactor.send_command("list_snapshots", {})

reactor.on("message", (msg) => {
  switch (msg.type) {
    case "state":
      console.log(`Chunk ${msg.data.current_chunk} · frame ${msg.data.current_frame}`);
      console.log(`Running: ${msg.data.running} · prompt: ${msg.data.current_prompt}`);
      break;
    case "image_accepted":
      console.log(`Reference image set: ${msg.data.width}x${msg.data.height}`);
      break;
    case "generation_started":
      console.log(`Generation started: ${msg.data.prompt}`);
      break;
    case "command_error":
      console.error(`${msg.data.command} rejected: ${msg.data.reason}`);
      break;
  }
});

import {
  useHeliosState,
  useHeliosImageAccepted,
  useHeliosGenerationStarted,
  useHeliosCommandError,
  type HeliosStateMessage,
} from "@reactor-models/helios";

function StateDisplay() {
  const [snapshot, setSnapshot] = useState<HeliosStateMessage | null>(null);

  // `state` fires on connect, after every command, and after every chunk.
  useHeliosState((msg) => setSnapshot(msg));
  useHeliosImageAccepted((msg) => console.log(`Reference image set: ${msg.width}x${msg.height}`));
  useHeliosGenerationStarted((msg) => console.log(`Generation started: ${msg.prompt}`));
  useHeliosCommandError((msg) => console.error(`${msg.command} rejected: ${msg.reason}`));

  if (!snapshot) return null;

  return (
    <div>
      Running: {snapshot.running ? "Yes" : "No"} | Chunk: {snapshot.current_chunk} | Frame:{" "}
      {snapshot.current_frame}
    </div>
  );
}

@reactor.on_message
def handle(msg):
    data = msg["data"]
    if msg["type"] == "state":
        print(f"Chunk {data['current_chunk']} · frame {data['current_frame']}")
        print(f"Running: {data['running']} · prompt: {data['current_prompt']}")
    elif msg["type"] == "image_accepted":
        print(f"Reference image set: {data['width']}x{data['height']}")
    elif msg["type"] == "generation_started":
        print(f"Generation started: {data['prompt']}")
    elif msg["type"] == "command_error":
        print(f"{data['command']} rejected: {data['reason']}")

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

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

// Set up video display
const videoElement = document.getElementById("video") as HTMLVideoElement;
reactor.on("trackReceived", (name, track, stream) => {
  videoElement.srcObject = stream;
  videoElement.play().catch(console.warn);
});

// Listen for state updates
reactor.on("message", (msg) => {
  if (msg.type === "state") {
    document.getElementById("info")!.textContent =
      `Chunk: ${msg.data.current_chunk} | Frame: ${msg.data.current_frame}`;
  }
  if (msg.type === "chunk_complete") {
    console.log(`Now showing: ${msg.data.active_prompt}`);
  }
});

// Connect (see Authentication guide for how to obtain a token)
await reactor.connect(token);

// Set a seed for reproducibility
await reactor.sendCommand("set_seed", { seed: 42 });

// Schedule prompts for a cinematic sequence
await reactor.sendCommand("schedule_prompt", {
  prompt: "A peaceful forest at dawn, soft morning light filtering through the trees",
  chunk: 0,
});

await reactor.sendCommand("schedule_prompt", {
  prompt: "Sunlight breaking through the canopy, golden rays illuminating the forest floor",
  chunk: 5,
});

await reactor.sendCommand("schedule_prompt", {
  prompt: "A deer walking through the misty forest clearing",
  chunk: 10,
});

// Start generation
await reactor.sendCommand("start", {});

import {
  HeliosProvider,
  HeliosMainVideoView,
  useHelios,
  useHeliosState,
  useHeliosChunkComplete,
} from "@reactor-models/helios";

// Token minted on your server; see Authentication.
async function getJwt() {
  const r = await fetch("/api/reactor/token");
  const { jwt } = await r.json();
  return jwt;
}

function App() {
  return (
    // Pass a resolver, not a static string: the SDK re-calls it on every
    // Coordinator hop, so the session survives the token aging out.
    <HeliosProvider getJwt={getJwt}>
      <PromptSequence />
      {/* HeliosMainVideoView handles <video> setup, srcObject, and autoplay. */}
      <HeliosMainVideoView className="h-full w-full" videoObjectFit="contain" />
    </HeliosProvider>
  );
}

function PromptSequence() {
  const { status, setSeed, schedulePrompt, start } = useHelios();

  // `state` is the single source of truth for chunk/frame progress.
  useHeliosState((msg) => console.log(`Chunk: ${msg.current_chunk} | Frame: ${msg.current_frame}`));
  useHeliosChunkComplete((msg) => console.log(`Now showing: ${msg.active_prompt}`));

  async function run() {
    // Set a seed for reproducibility
    await setSeed({ seed: 42 });

    // Schedule prompts for a cinematic sequence
    await schedulePrompt({
      prompt: "A peaceful forest at dawn, soft morning light filtering through the trees",
      chunk: 0,
    });
    await schedulePrompt({
      prompt: "Sunlight breaking through the canopy, golden rays illuminating the forest floor",
      chunk: 5,
    });
    await schedulePrompt({
      prompt: "A deer walking through the misty forest clearing",
      chunk: 10,
    });

    // Start generation
    await start();
  }

  return (
    <button disabled={status !== "ready"} onClick={run}>
      Start sequence
    </button>
  );
}

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

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

// Set up video display
const videoElement = document.getElementById("video") as HTMLVideoElement;
reactor.on("trackReceived", (name, track, stream) => {
  videoElement.srcObject = stream;
  videoElement.play().catch(console.warn);
});

// Connect
await reactor.connect(token);

// Upload a reference image
const fileInput = document.getElementById("file") as HTMLInputElement;
const imageFile = fileInput.files![0];
const imageRef = await reactor.uploadFile(imageFile);

// Set the image and prompt atomically. Sending set_image + set_prompt
// separately before start races: the image can land a chunk late, so the
// first chunk renders from the prompt alone. set_conditioning commits both
// in one message. See set_conditioning above.
await reactor.sendCommand("set_conditioning", {
  image: imageRef,
  prompt: "A cinematic slow zoom into the scene, golden hour lighting, gentle motion",
});

// Start generation
await reactor.sendCommand("start", {});

// Later: swap to a new image mid-generation
const newInput = document.getElementById("new-file") as HTMLInputElement;
const newRef = await reactor.uploadFile(newInput.files![0]);
await reactor.sendCommand("set_image", { image: newRef });

import { HeliosProvider, HeliosMainVideoView, useHelios } from "@reactor-models/helios";

// Token minted on your server; see Authentication.
async function getJwt() {
  const r = await fetch("/api/reactor/token");
  const { jwt } = await r.json();
  return jwt;
}

function App() {
  return (
    <HeliosProvider getJwt={getJwt}>
      <ImageToVideo />
      <HeliosMainVideoView className="h-full w-full" videoObjectFit="contain" />
    </HeliosProvider>
  );
}

function ImageToVideo() {
  const { status, uploadFile, setImage, setConditioning, start } = useHelios();

  async function startFromImage(imageFile: File) {
    const imageRef = await uploadFile(imageFile);

    // Set the image and prompt atomically. Sending set_image + set_prompt
    // separately before start races: the image can land a chunk late, so the
    // first chunk renders from the prompt alone. set_conditioning commits both
    // in one message. See set_conditioning above.
    await setConditioning({
      image: imageRef,
      prompt: "A cinematic slow zoom into the scene, golden hour lighting, gentle motion",
    });

    // Start generation
    await start();
  }

  // Later: swap to a new image mid-generation
  async function swapImage(newImageFile: File) {
    const newRef = await uploadFile(newImageFile);
    await setImage({ image: newRef });
  }

  return (
    <>
      <input
        type="file"
        disabled={status !== "ready"}
        onChange={(e) => e.target.files?.[0] && startFromImage(e.target.files[0])}
      />
      <input
        type="file"
        disabled={status !== "ready"}
        onChange={(e) => e.target.files?.[0] && swapImage(e.target.files[0])}
      />
    </>
  );
}

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

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

// The buffer is the authority on what can still be rewound to, so mirror
// it rather than remembering every index we've saved.
let snapshots: {
  snapshot_index: number;
  chunk: number;
  label: string;
  prompt: string;
}[] = [];

reactor.on("message", (msg) => {
  switch (msg.type) {
    case "snapshot_saved":
      console.log(`Saved #${msg.data.snapshot_index} at chunk ${msg.data.chunk}`);
      // Re-read the buffer so an eviction drops out of our copy too.
      void reactor.sendCommand("list_snapshots", {});
      break;
    case "snapshot_list":
      snapshots = msg.data.snapshots;
      break;
    case "rewind_complete":
      console.log(`Back at chunk ${msg.data.chunk}`);
      break;
    case "rewind_failed":
      console.error(`Rewind buffer: ${msg.data.reason}`);
      break;
  }
});

await reactor.connect(token);

await reactor.sendCommand("set_prompt", {
  prompt: "A forest clearing at dawn, mist between the trees, static wide shot",
});
await reactor.sendCommand("start", {});

// Once a few chunks have generated, mark the moment.
await reactor.sendCommand("save_snapshot", { label: "clearing" });

// Take the scene somewhere.
await reactor.sendCommand("set_prompt", {
  prompt: "The same clearing, now under heavy snowfall",
});

// That direction didn't land. Go back and try another one.
const checkpoint = snapshots.find((s) => s.label === "clearing");
if (checkpoint) {
  await reactor.sendCommand("rewind", { snapshot_index: checkpoint.snapshot_index });
  await reactor.sendCommand("set_prompt", {
    prompt: "The same clearing, now in full autumn colour",
  });
}

import {
  HeliosProvider,
  HeliosMainVideoView,
  useHelios,
  useHeliosSnapshotList,
  useHeliosSnapshotSaved,
  useHeliosRewindFailed,
} from "@reactor-models/helios";

interface Snapshot {
  snapshot_index: number;
  chunk: number;
  label: string;
  prompt: string;
}

function Snapshots() {
  const { status, saveSnapshot, rewind, setPrompt, listSnapshots } = useHelios();
  const [snapshots, setSnapshots] = useState<Snapshot[]>([]);

  // The buffer is the authority: an entry the model stops listing has been
  // evicted, so its row goes with it.
  useHeliosSnapshotList((msg) => setSnapshots(msg.snapshots as Snapshot[]));
  useHeliosSnapshotSaved(() => void listSnapshots());
  useHeliosRewindFailed((msg) => console.error(`Rewind buffer: ${msg.reason}`));

  async function rewindTo(snapshot: Snapshot) {
    await rewind({ snapshot_index: snapshot.snapshot_index });
    // Rewinding restores the latents but not the prompt. Re-send the one
    // captured at save time so both land on the same chunk boundary.
    if (snapshot.prompt) await setPrompt({ prompt: snapshot.prompt });
  }

  return (
    <>
      <button disabled={status !== "ready"} onClick={() => saveSnapshot({})}>
        Save snapshot
      </button>
      {snapshots.map((s) => (
        <button key={s.snapshot_index} onClick={() => rewindTo(s)}>
          Rewind to {s.label || `#${s.snapshot_index}`} (chunk {s.chunk})
        </button>
      ))}
    </>
  );
}

function App() {
  return (
    <HeliosProvider getJwt={getJwt}>
      <Snapshots />
      <HeliosMainVideoView className="h-full w-full" videoObjectFit="contain" />
    </HeliosProvider>
  );
}

from reactor_sdk import Reactor

reactor = Reactor(model_name="reactor/helios", api_key=api_key)

# The buffer is the authority on what can still be rewound to, so mirror
# it rather than remembering every index we've saved.
snapshots: list[dict] = []

@reactor.on_message
async def handle(msg):
    global snapshots
    data = msg["data"]
    if msg["type"] == "snapshot_saved":
        print(f"Saved #{data['snapshot_index']} at chunk {data['chunk']}")
        # Re-read the buffer so an eviction drops out of our copy too.
        await reactor.send_command("list_snapshots", {})
    elif msg["type"] == "snapshot_list":
        snapshots = data["snapshots"]
    elif msg["type"] == "rewind_complete":
        print(f"Back at chunk {data['chunk']}")
    elif msg["type"] == "rewind_failed":
        print(f"Rewind buffer: {data['reason']}")

await reactor.connect()

await reactor.send_command("set_prompt", {
    "prompt": "A forest clearing at dawn, mist between the trees, static wide shot",
})
await reactor.send_command("start", {})

# Once a few chunks have generated, mark the moment.
await reactor.send_command("save_snapshot", {"label": "clearing"})

# Take the scene somewhere.
await reactor.send_command("set_prompt", {
    "prompt": "The same clearing, now under heavy snowfall",
})

# That direction didn't land. Go back and try another one.
checkpoint = next((s for s in snapshots if s["label"] == "clearing"), None)
if checkpoint:
    await reactor.send_command("rewind", {"snapshot_index": checkpoint["snapshot_index"]})
    await reactor.send_command("set_prompt", {
        "prompt": "The same clearing, now in full autumn colour",
    })