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.
This page documents the complete Helios wire surface: every command you send with
reactor.sendCommand(), the events the model emits back, and two end-to-end examples. For the
conceptual model and a quick start, see the overview.
Commands
Send commands to the model using reactor.sendCommand(). Below are all available commands:
| Command | Description |
|---|
set_prompt | Set the prompt (at chunk 0, or current chunk if running) |
schedule_prompt | Schedule a prompt at a specific chunk index |
set_image | Set or change a reference image (works mid-generation) |
set_conditioning | Set prompt and reference image together atomically (avoids a first-chunk race) |
set_image_strength | Adjust how strongly the reference image anchors output (0.0–1.0) |
set_sr_scale | Set super-resolution scale: "off", "2x", or "4x" |
set_seed | Set a seed for reproducible output. Same seed = same video |
start | Begin video generation |
pause | Pause generation |
resume | Resume generation |
reset | Reset to initial state |
set_prompt
schedule_prompt
set_image
set_conditioning
set_image_strength
set_sr_scale
set_seed
start
pause
resume
reset
set_prompt
Convenience wrapper around schedule_prompt that automatically picks the right chunk index so
you don’t have to track it yourself:
- Not started: schedules at chunk 0.
- Paused: schedules at the current chunk (takes effect on resume).
- Running: schedules at the next chunk (current chunk is already being processed).
The easiest way to change the prompt. Call set_prompt and the model figures out when to
apply it.Parameters:| Parameter | Type | Required | Description |
|---|
prompt | string | Yes | The prompt text to use for generation |
Example:// 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",
});
schedule_prompt
Schedule a prompt to be applied at a specific chunk index during video generation.Parameters:| Parameter | Type | Required | Description |
|---|
prompt | string | Yes | The prompt text to use |
chunk | integer | Yes | The chunk index at which to apply the prompt |
Behavior:
- Scheduling a prompt at a chunk that already has a prompt will overwrite it.
- Prompts scheduled in the past are rejected (e.g. if the model is at chunk 10 and you
schedule at chunk 5, an error is emitted).
- A prompt must exist at chunk 0 before calling
start.
- Prompts can be scheduled while generation is running for real-time control.
Example:// 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,
});
set_image
Set or change the reference image for image-to-video conditioning. Can be called before or
during generation.Upload the image first with uploadFile(), then pass the returned
FileRef as the image parameter. See
File Uploads for more details.Parameters:| Parameter | Type | Required | Description |
|---|
image | FileRef | Yes | A reference to an uploaded image, returned by uploadFile() |
Behavior:
- Can be set before starting or while generation is running.
- The image is rescaled to the model’s internal conditioning resolution, which is smaller than
the output frame size. The
image_accepted message reports the exact dimensions used.
- Swapping the image mid-generation is an immediate switch on the next chunk; the previous
image’s history conditioning is not blended out.
Example: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 });
set_conditioning
Set the prompt and reference image in a single atomic message (Helios SDK 0.9.0+). Use it when
both are known at once (e.g. launching a curated scene): the two ride one data-channel message,
so the first chunk is generated with the image already in place. Sending set_image and
set_prompt separately before start races, and the image can land a chunk late.Upload the image first with uploadFile(), then pass the returned
FileRef as image. See set_image for upload
details.Parameters:| Parameter | Type | Required | Description |
|---|
prompt | string | Yes | The prompt to generate from |
image | FileRef | Yes | Reference image returned by uploadFile() |
Example: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", {});
set_image_strength
Adjust how strongly the reference image anchors generation. Ignored when no reference image is
set.Parameters:| Parameter | Type | Required | Description |
|---|
image_strength | number | Yes | Anchor strength, 0.0–1.0 |
Behavior:
- The current chunk loop snapshots
image_strength together with the reference image. A new
value sent on its own is stored but is not applied until the reference image is next set
(via set_image or set_conditioning), or until generation is restarted with reset +
start.
- Set
image_strength immediately before set_image / set_conditioning if you want it to
take effect on the next chunk.
Example:await reactor.sendCommand("set_image_strength", { image_strength: 0.6 });
set_sr_scale
Set the super-resolution factor applied to each emitted frame. Takes effect on the next chunk.Parameters:| Parameter | Type | Required | Description |
|---|
sr_scale | string | Yes | One of "off", "2x", or "4x" |
Example:await reactor.sendCommand("set_sr_scale", { sr_scale: "2x" });
set_seed
Set a seed for reproducible output. Using the same seed with the same prompts will produce the
same video.Parameters:| Parameter | Type | Required | Description |
|---|
seed | integer | Yes | Seed value |
Behavior:
- If generation hasn’t started, the seed takes effect immediately.
- If generation is running, the seed takes effect on the next
reset.
Example:await reactor.sendCommand("set_seed", { seed: 42 });
start
Begin the video generation process.Parameters: None.Requirements:
- A prompt must be scheduled at chunk 0 before calling this command (via
set_prompt or
schedule_prompt).
Example:await reactor.sendCommand("start", {});
pause
Pause the video generation after the current chunk finishes processing. The model retains its
full state including history buffers.Parameters: None.Example:await reactor.sendCommand("pause", {});
resume
Resume video generation from where it was paused.Parameters: None.Example:await reactor.sendCommand("resume", {});
reset
Stop generation and reset the model to its initial state.Parameters: None.Effects:
- Halts any ongoing generation.
- Clears all scheduled prompts, history buffers, and the active reference image.
- Returns the model to a clean state ready for new prompts. The currently configured seed is
preserved; call
set_seed after reset if you want to change it.
Example:await reactor.sendCommand("reset", {});
Messages from model
Listen for messages with reactor.on("message", ...) (imperative) or the useReactorMessage()
hook (React). Every message is delivered as JSON { "type": "<name>", "data": { … } }.
| Message | When | Payload |
|---|
state | On connect, after every command, and after every chunk | Full session snapshot (see below) |
prompt_accepted | After set_prompt | { prompt: string } |
image_accepted | After set_image decodes | { width: int, height: int } |
conditions_ready | After set_prompt or set_image | { has_prompt: bool, has_image: bool } |
generation_started | After start | { prompt: string, chunk_index: int } |
chunk_complete | After each chunk emits | { chunk_index: int, frames_emitted: int, active_prompt: string } |
generation_paused | After pause | { chunk_index: int } |
generation_resumed | After resume | { chunk_index: int } |
command_error | When a command is rejected | { command: string, reason: string } |
state payload
state is the single source of truth for driving UI. Subscribe once and treat it as the
authoritative session snapshot; you generally do not need to track the individual messages above
yourself.
| Field | Type | Meaning |
|---|
running | bool | started && !paused. Equivalent to “frames are actively streaming”. |
started | bool | True once start has been accepted; stays true through pauses. Cleared by reset. |
paused | bool | True while generation is paused via pause. |
image_set | bool | True once a reference image has been set this session. Cleared only by reset. |
current_chunk | int | Zero-based index of the chunk currently being generated. 0 before the first chunk and after reset. |
current_frame | int | Running total of frames emitted on main_video since the last reset. |
current_prompt | string | null | The prompt currently driving generation, or null if none set. Stays null for the first state message after start, until the first chunk begins emitting. |
image_strength | number | Current image_strength (0.0–1.0). Ignored when no reference image is set. |
scheduled_prompts | object | Pending scheduled prompts, keyed by the chunk index at which they take effect. |
Example handler:
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;
}
});
Complete example: prompt sequence
import { Reactor } from "@reactor-team/js-sdk";
const reactor = new Reactor({
modelName: "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", {});
Complete example: image-to-video
Use a reference image to guide generation. Upload the image first, then send it together with the
prompt via set_conditioning before starting, so the very first chunk is conditioned on both.
import { Reactor } from "@reactor-team/js-sdk";
const reactor = new Reactor({
modelName: "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 });