> ## 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.

# Helios prompt guide

> How to write Helios prompts that produce smooth, controllable video.

Helios generates output in continuous chunks driven entirely by your prompts. The quality of your
output depends on the specificity of your prompts. This page covers the principles behind effective
prompts, with examples drawn from real production sequences.

## Before & after

The fastest way to understand what a strong prompt looks like is to compare it to a weak one. Every
example below uses the same subject. The difference is entirely in how it's described.

**Driving scene**

<div className="rea-example rea-example-dont">
  A man driving a car through a city.
</div>

<div className="rea-example rea-example-do">
  A stylish young man grips the steering wheel of a sleek black sports car navigating a rain-slicked
  downtown street at night. He wears a dark jacket, jaw set, eyes fixed ahead with quiet intensity.
  The car's interior glows faintly amber from the dashboard instruments. Outside, neon signs and
  storefront lights blur across the hood and side windows as he threads through slow-moving traffic.
  The engine note deepens as he accelerates through a gap. Medium shot from the passenger side,
  framing his hands on the wheel and the streaming city lights beyond the windshield.
</div>

**Rain scene**

<div className="rea-example rea-example-dont">
  A woman standing in the rain looking happy.
</div>

<div className="rea-example rea-example-do">
  A young woman stands in the rain looking up at the sky with a warm, inviting smile on her face. She
  is dressed in a light, flowy dress that clings to her form as droplets of water fall around her. Her
  hair is gently tousled from the rain, framing her delicate features. The background shows a blurred
  cityscape with tall buildings and the faint glow of streetlights reflecting off wet pavement.
  Raindrops catch the light as they fall, creating a shimmering curtain around her figure. Medium
  close-up, static shot focusing on the woman's face and upper body.
</div>

**Nature scene**

<div className="rea-example rea-example-dont">
  A forest in autumn with falling leaves.
</div>

<div className="rea-example rea-example-do">
  In a serene autumn clearing bathed in the warm, golden hues of late afternoon sunlight filtering
  through tall maple trees, a carpet of vibrant red and orange leaves blankets the ground. A rustic
  wooden footbridge arches gracefully over a gently trickling stream, its aged planks dark with
  moisture. A cool breeze stirs the canopy above, sending clusters of leaves spiraling down through
  the amber light. The only sounds are the faint babble of water and the dry rustle of leaves settling
  on the forest floor. Wide shot looking down the clearing, the bridge centered in frame with the tree
  canopy forming a golden arch overhead.
</div>

Notice what every good prompt has that the bad one doesn't: a subject described physically, an
environment anchored in space, light defined by what it does to surfaces, mood shown through posture
and action rather than stated, and an explicit camera shot. The sections below break each of these
down.

<Tip>Use a fast, lightweight LLM to upsample short user inputs into detailed Helios prompts.</Tip>

## Core principles

Here's a strong opening prompt. The sections below break down exactly why it works.

> A majestic lion named Leo stands regally in the heart of a dense jungle, embodying the essence of
> a king. Leo has a golden mane that flows gracefully around his broad shoulders, and his piercing
> amber eyes survey the landscape with confidence and authority. He is positioned on a rocky
> outcrop, towering over the lush greenery below. The background showcases a vibrant jungle scene
> with tall trees, cascading vines, and dappled sunlight filtering through the canopy. Leo's posture
> is proud and commanding, with his tail held high. The scene is captured from a medium close-up
> perspective, emphasizing Leo's powerful stance and the regal aura surrounding him.

### Your first prompt is the scene bible

The opening prompt does the heavy lifting. It establishes the subject, environment, lighting, mood,
and camera framing in a single pass. Every follow-up prompt inherits this foundation. You won't need
to rebuild the world from scratch each time. Think of prompt 0 as the creative brief for the entire
sequence.

The Leo prompt above sets the subject, environment, lighting, mood, and camera framing all in one
shot:

| Element     | From the prompt                                                     |
| ----------- | ------------------------------------------------------------------- |
| Subject     | "A majestic lion named Leo ... golden mane ... piercing amber eyes" |
| Environment | "heart of a dense jungle ... rocky outcrop ... lush greenery below" |
| Lighting    | "dappled sunlight filtering through the canopy"                     |
| Mood        | "embodying the essence of a king ... proud and commanding"          |
| Camera      | "medium close-up perspective, emphasizing Leo's powerful stance"    |

### One new element per prompt

Reactor models accept multiple prompts over time. As each chunk of video is generated, the model can
receive a new prompt and the scene will evolve. The key is to introduce **exactly one** new
narrative beat per prompt: a new action, object, or event. This gives the model a clear signal about
what should change while keeping everything else stable.

> Leo maintains his regal position on the rocky outcrop as the humid jungle air settles around his
> broad shoulders. He suddenly lowers his massive head to sniff a vibrant blue butterfly that has
> fluttered near his nose, his piercing amber eyes momentarily softening with curiosity.

<Tip>
  **One change per prompt**: `a butterfly appears and Leo reacts to it`. The jungle, the outcrop,
  the lighting, and the camera all remain the same.
</Tip>

<Warning>
  Avoid prompts like `Leo jumps off the rock, chases a butterfly, crosses a river, and meets another
      lion`. That's four changes at once; the model can't handle that many variables cleanly.
</Warning>

### Re-anchor the subject

Each follow-up prompt should re-identify the main subject with a short, consistent phrase. This
prevents drift and keeps the model grounded in the character you established.

<Tip>
  The follow-up above opens with **`Leo maintains his regal position on the rocky outcrop`**. It
  doesn't re-describe his entire appearance, just enough to reconnect. A few words that suggests
  "this is the same character, in the same place".
</Tip>

### Layer the environment by depth

Spell out what's around the subject at each distance: **near** is what's directly around at ground
level, **mid** is the focal element of the scene, **far** is the backdrop or horizon. Skipping a
layer produces flat, muddy backgrounds. Succesful prompting requires coverage across all three
areas.

<Note>
  The Leo prompt covers all three: **near** is the *rocky outcrop* he stands on, **mid** is the
  *lush greenery below* and *tall trees, cascading vines*, **far** is the *jungle canopy* with
  *dappled sunlight filtering through*. Together they give the camera somewhere to land at every
  depth.
</Note>

### Always specify camera framing

Every prompt must include an explicit camera instruction. **This is not optional!** It's part of the
prompt, not a nice-to-have.

<Note>
  `The scene is captured from a medium close-up perspective, emphasizing Leo's powerful stance and
      the regal aura surrounding him`. The framing isn't just named, it explains what the camera is
  doing and why.
</Note>

| Framing             | What it captures                          |
| ------------------- | ----------------------------------------- |
| **Close-up**        | Face and fine detail                      |
| **Medium close-up** | Face and upper body                       |
| **Medium shot**     | Full action context                       |
| **Wide shot**       | Environment and scale                     |
| **Tracking shot**   | Follows subject movement                  |
| **Static shot**     | Locked camera, subject moves within frame |
| **Aerial shot**     | Overhead perspective                      |

Layer in camera motion: "slow pullback," "smooth tracking shot," "slight pan and pullback."

### Describe light by its effect

Never just say "good lighting" or "bright." Describe how light interacts with surfaces and subjects.

<Note>
  Saying `Dappled sunlight filtering through the canopy` tells the model exactly how the light
  behaves. It's filtered, it's patchy, and it's coming through leaves.
</Note>

<Tip>
  Go even further by describing what the light does to the subject: **illuminating the golden hues
  of his mane**. Light defined by its effect on a surface, not labeled as a category.
</Tip>

### Show emotion through behavior

Don't label emotions abstractly. Convey them through physical actions and body language.

<Tip>
  Confidence is shown as `his piercing amber eyes survey the landscape with confidence and
      authority` and `Leo's posture is proud and commanding, with his tail held high`. Through specific
  concrete details such as gaze, posture, and tail position, not `Leo feels confident`.
</Tip>

In the follow-up, curiosity is shown as "his piercing amber eyes momentarily softening" and "he
lowers his massive head to sniff", not "Leo was curious about the butterfly."

### Be physically specific

Go beyond **what** happens to describe **how** it happens. Include textures, materials, and physical
detail.

<Note>
  Instead of just saying `a lion's mane`, say: `A golden mane that flows gracefully around his broad
      shoulders`. Make sure to describe color, how it moves, and where it falls. `He is positioned on a
      rocky outcrop, towering over the lush greenery below`. Here, the spatial relationship is concrete.
</Note>

Ensure that your prompts contain actions that have weight and specificity. Specificity grounds the
output in a believable physical reality.

## Anatomy of a prompt sequence

A prompt sequence follows a consistent structure. Because models generate video in chunks, you can
schedule prompts ahead of time. Each chunk will evolve the scene by a single beat.

<Steps>
  <Step title="Establish the scene">
    The first prompt sets the world: character, environment, lighting, mood, and camera.

    > **A female astronaut in a full spacesuit**, including an astronaut helmet, is running swiftly away from an unknown threat. She has **a determined and focused expression** on her face. The spacesuit is sleek, silver, and equipped with various gadgets and sensors. Her hair is visible under the helmet, flowing behind her as she runs. The background shows **a desolate, rocky landscape with distant mountains and a dark, starry sky**. The scene captures **a medium shot** of the woman mid-run, emphasizing her speed and urgency.
  </Step>

  <Step title="Introduce one new element">
    Re-anchor the subject, keep the world intact, and add one new thing. In this instance, a
    glowing scanner.

    > **The silver-suited astronaut** sprints across the rocky terrain, but now she firmly clutches **a glowing red geological scanner in her right hand, its lights pulsing rhythmically** against the dark environment. Her expression remains intense under the helmet visor as she navigates the uneven ground, the sleek gadgets on her suit reflecting faint starlight. The desolate landscape stretches endlessly around her, framed by jagged mountains in the distance. The medium shot tracks alongside her movement, keeping pace with her urgent stride against the backdrop of the vast, starry void.
  </Step>

  <Step title="Progress the narrative">
    Another single beat: a drone deploys from her suit.

    > **The female astronaut** races forward across the jagged terrain, her silver spacesuit gleaming against the dark void. Suddenly, **a small drone detaches from her shoulder armor and hovers briefly before zooming ahead to scout the path**. Her face remains locked in focused determination behind the helmet visor as her hair shifts with her rapid movement. The desolate rocky ground and looming distant mountains provide a stark backdrop to her flight. The camera maintains a medium shot of the woman mid-run, emphasizing her speed and urgency.
  </Step>
</Steps>

<Info>
  Prompt changes take effect at chunk boundaries, so space your prompts to give each beat enough
  screen time. Helios chunks are 33 frames.
</Info>

## Style and aesthetic

If your sequence has a distinctive visual style, name it in the first prompt and reinforce it with
atmospheric cues in later prompts. Don't re-label the entire style every time.

**First prompt: establish the style**

> 90s VHS-style The Weather Channel scene, featuring a weatherman standing in front of a green
> screen with a large map of storm systems behind him. The weatherman, dressed in a casual but
> professional outfit, points emphatically at the rapidly moving storms on the map. His face shows
> concern and urgency as he speaks directly to the camera. **The overall scene has a vintage, grainy
> texture with the characteristic noise and color palette of old VHS recordings.** Medium close-up
> shot focusing on the weatherman's gestures and expressions.

**Later prompt: reinforce, don't restate**

> The weatherman abruptly grabs a bright red marker pen from the desk edge and begins circling a
> specific coastal city directly on the camera lens itself. The ink squeaks audibly against the
> surface as the green screen map behind him pulses with warning icons. **The VHS static buzzes
> louder, momentarily distorting his face** as he caps the marker and stares intensely through his
> red drawings. Medium close-up shot focusing on the weatherman's gestures and expressions.

<Tip>
  The second prompt never re-declares "90s VHS-style." Instead, **"VHS static buzzes louder"** and
  **"distorting his face"** reinforce the aesthetic through atmospheric detail.
</Tip>

## Background continuity

Re-reference the background briefly in each prompt to maintain spatial context, but don't repeat the
full description. Use shorthand for elements that haven't changed.

| First prompt                                                                                                                          | Follow-up shorthand                                     |
| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| "The background shows a desolate, rocky landscape with distant mountains and a dark, starry sky"                                      | "The desolate landscape stretches endlessly around her" |
| "The background showcases a vibrant jungle scene with tall trees, cascading vines, and dappled sunlight filtering through the canopy" | "The lush greenery provides a vibrant backdrop"         |
| "The background is a blurred cityscape with tall buildings and the faint glow of streetlights"                                        | "The blurred city lights reflect beautifully"           |

## Quick reference

***

## Token budget

Helios's text encoder is umt5-xxl, which has a hard cap of **exactly 512 tokens**. Everything beyond
that is silently truncated. In practice, quality starts to degrade noticeably **past \~500 tokens**,
before you even reach the hard limit, so treat 500 as your effective ceiling per prompt.

What matters more in practice is the **soft** version of this rule: if you want something to
actually show up in the output, the words describing it have to take up enough room within that
budget. A two-word mention tucked into an otherwise dense prompt usually gets ignored.

There's no exact ratio, and the right balance depends on the scene. As a starting point, give the
thing you want to see at least as much room as your other sentence-anchors. Try it, watch the
output, and tune from there.

<Tip>
  Want to see exactly how your prompt tokenizes? Paste it into the [token
  playground](https://video-prompt-tokens-playground.vercel.app/) to see total token count, and
  highlight individual sections to see how each piece weighs in.
</Tip>

***

## Runtime caveats

A few practical limits affect how a prompt sequence will play out in a live session:

* **Chunk boundaries.** Prompt changes only take effect at chunk boundaries, not mid-chunk. Space
  follow-ups so each beat gets enough screen time before the next prompt arrives. See each model's
  documentation for the chunk size.
* **Don't sit on one condition for too long.** Keeping the same text prompt across many generated
  chunks may cause details to drift and visual artifacts to appear. For Helios the only condition is
  the prompt itself, so any fresh `set_prompt` call, even a small revision that doesn't change the
  narrative, resets this and keeps the output clean for longer.
* **Model capability.** Even a well-formed prompt won't always land. If you've worked through
  [Troubleshooting](#troubleshooting) several times and the output still isn't there, you may be
  hitting a current model limitation rather than a prompt issue.

***

## Troubleshooting

When a prompt doesn't produce what you wanted, walk through this checklist before assuming the model
can't do it.

**1. Are there detail gaps?**

Walk the [scene bible](#your-first-prompt-is-the-scene-bible) checklist: subject, environment (near
/ mid / far), lighting, mood, camera. Skipped elements are the most common cause of muddy output,
and generic phrasing within them is a close second.*" He is well-lit"* is not as good as *"raking
light catches the edge of his jaw"*, *"looks happy"* vs *"warm smile, eyes crinkling"*. See
[Describe light by its effect](#describe-light-by-its-effect) and
[Show emotion through behavior](#show-emotion-through-behavior).

**2. In a follow-up, is everything in place?**

In a follow-up prompt, ensure that you re-anchor the subject, briefly-reference the background, add
**only one** new change, and reinforce the style with atmospheric cues rather than re-declaring it.
Missing any one is the usual cause of drift or chaos. See
[Style and Aesthetic](#style-and-aesthetic).

**3. Tune by emphasis**

* If something is underperforming, give its description more room: a longer phrase, more concrete
  physical detail, an extra clause. A two-word mention is easy for the rest of the prompt to drown
  out.
* If something *unwanted* keeps showing up, don't rely on omission. Describe its opposite
  explicitly, or call it out directly (*"clear cloudless sky,"* *"empty street with no people in
  frame"*). The model responds to what you write, not to what you leave out.

If none of these explain the failure, you may be hitting a current model limitation. Learn more by
reading [Runtime caveats](#runtime-caveats).

***

## Quick Reference

| Rule             | Do                                                                   | Don't                                        |
| ---------------- | -------------------------------------------------------------------- | -------------------------------------------- |
| **First prompt** | Full scene: subject + environment + light + mood + camera            | Start vague and fill in details later        |
| **Follow-ups**   | One new action or object per prompt                                  | Introduce multiple changes at once           |
| **Subject**      | Re-anchor with a short identifying phrase                            | Assume the model remembers from context      |
| **Camera**       | Always include framing and optional motion                           | Omit camera direction                        |
| **Light**        | Describe by effect on surfaces                                       | Label generically ("well-lit")               |
| **Emotion**      | Show through body language and action                                | State abstract feelings                      |
| **Detail**       | Textures, sounds, materials, reflections                             | Vague or generic descriptions                |
| **Style**        | Name once, reinforce with atmospheric cues                           | Re-declare the full style every prompt       |
| **Background**   | Brief shorthand reference                                            | Full re-description                          |
| **Exclusion**    | Name what shouldn't be there ("no people in frame", "cloudless sky") | Rely on omission to remove unwanted elements |

***

## See also

* [Helios overview](/model-api-reference/helios/overview): model specs, endpoints, and lifecycle
* [Helios tutorial](/model-api-reference/helios/tutorial): end-to-end example project
* [Concepts → Commands and messages](/concepts/commands-and-messages): the generic `sendCommand` /
  message contract