> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Prompting Guide
> Write Video Agent prompts that land on the first cut. Set the duration, direct the look with a style paragraph, and paste a script for scene-by-scene control.
The prompt is the whole interface to the [Video Agent](/docs/video-agent). The agent makes every decision you leave open, so the more direction you give, the closer the first cut lands to what you pictured. A good prompt reads like a creative brief: what the video is, how long it runs, and what it should look like.
This page builds one real prompt step by step — and ends with the video it produced.
## Put the duration in the prompt
The agent paces scenes to the length you ask for. Lead with it: *"Make a 30-second portrait real estate market update…"* produces a video paced to 30 seconds, scene by scene.
## Add a style paragraph
Describe the video you want, then add a short style paragraph: what the graphics should look like, the colors, the energy, how things move. The agent reads it and makes every visual decision through it — anything you leave out, it decides for you.
```text Example prompt theme={null}
Make a 45-second portrait video introducing our new app to Gen Z.
Style: Arcade Cabinet – Pixel Power-Up. CRT Black #111111, Neon Cyan #00E5FF,
Electric Magenta #FF2DAA, Power-Up Yellow #FFD400, Pixel Grass Green #4CFF4C.
Chunky pixel art, scanlines, glowing vector HUD, and bold bitmap typography.
Sprites pop in with 8-bit bounce, score counters tick rapidly, and power-ups
burst into pixel particles. Transitions are CRT glitches, screen wipes, and
coin-in flashes. Playful, nostalgic, and unmistakably arcade.
```
A style paragraph that works has a consistent anatomy: a **name** for the style, the **exact palette** (hex codes and all), the **art direction**, **how things move**, **what the transitions are**, and one closing line for the **vibe**. Five or six sentences, and every graphic in the video has a rulebook — because scenes are [built in code with Hyperframes](/docs/video-agent#powered-by-hyperframes), the agent follows it literally. Prefer a pre-built look instead? Pass a `style_id` — see [Styles & References](/docs/styles-and-references).
## Paste your script for exact control
If you already have a script, paste the whole thing in and the agent follows it scene by scene, building the visuals around your exact words. Combine it with the style paragraph and a duration for the tightest brief:
```text Example prompt with script theme={null}
Make a 30-second portrait real estate market update for Austin, Texas,
presented by Ava. Follow the script below exactly, scene by scene. Use motion
graphics for every stat, and stock footage of the Austin skyline and
neighborhoods for texture between them.
Style: Elevated Estates – Quiet Luxury. Ivory #F7F4EE, Charcoal Ink #1E1E1C,
Sage #A6BB94, Deep Forest #24352A, Brushed Brass #C9A227. Editorial serif
headlines over generous whitespace, hairline rules, small-caps labels, and
full-bleed architectural photography with soft depth. Numbers count up gently,
chart lines draw themselves in, and photography drifts in slow parallax.
Transitions are soft crossfades, ivory paper wipes, and hairline reveals.
Calm, polished, and quietly luxurious.
Script:
Scene 1 (0-5s) - Ava on camera, skyline behind her.
"Austin, here's your market minute for July."
Scene 2 (5-12s) - Motion graphic: median price counts up to $450K, sage trend
line drawing upward.
"The metro median now sits at four hundred fifty thousand, up one percent from
last summer, and prices are firming."
Scene 3 (12-19s) - Motion graphic: inventory bars stepping down, brass accent
on the final bar.
"Inventory tells the story. Active listings are down fifteen percent from a
year ago, at four and a half months of supply."
Scene 4 (19-25s) - Stock footage of a front door and porch, stat card
overlay: 24 DAYS.
"And well-priced homes are moving in about twenty-four days."
Scene 5 (25-30s) - Ava on camera, hairline rule and small-caps CTA card.
"The window favors sellers again. Thinking about a move? Let's talk before fall."
```
## The output
This is the video that prompt produced — one prompt, one pass:
The first cut is a draft. To close the gap to post-ready, keep talking to the agent in [chat mode](/docs/interactive-sessions) — revise a single scene ("change the background of scene two") while every other scene holds still. Prompt for the 90, edit for the 10.
## More levers
1. **Attach reference files.** Pass slides, images, or documents in the `files` array — the agent folds them into the video as visual context or content sources. See [Upload Assets](/docs/upload-assets).
2. **Pin a specific avatar or voice** with `avatar_id` (see [Avatars](/docs/avatars)) and `voice_id` (see [Browse Voices](/docs/voices/search-voices)) for consistency, or omit them to let the agent choose.
3. **Apply your brand once** with `brand_kit_id` from [`GET /v3/brand-kits`](/reference/list-brand-kits) — colors, fonts, and logo ship on-brand by default on every video after.
4. **Set `orientation`** when you know the target platform (`"portrait"` for mobile/social, `"landscape"` for presentations).
5. **Review the plan before it builds.** With `"mode": "chat"`, the agent comes back with a scene-by-scene plan you can push back on before production starts. See [Interactive Sessions](/docs/interactive-sessions).
For more worked examples, see the [Video Agent prompt guide](https://www.heygen.com/blog/video-agent-prompt-guide) on the blog.
The prompt is the whole interface to the [Video Agent](/docs/video-agent). The agent makes every decision you leave open, so the more direction you give, the closer the first cut lands to what you pictured. A good prompt reads like a creative brief: what the video is, how long it runs, and what it should look like.
This page builds one real prompt step by step — and ends with the video it produced.
## Put the duration in the prompt
The agent paces scenes to the length you ask for. Lead with it: *"Make a 30-second portrait real estate market update…"* produces a video paced to 30 seconds, scene by scene.
## Add a style paragraph
Describe the video you want, then add a short style paragraph: what the graphics should look like, the colors, the energy, how things move. The agent reads it and makes every visual decision through it — anything you leave out, it decides for you.
```text Example prompt theme={null}
Make a 45-second portrait video introducing our new app to Gen Z.
Style: Arcade Cabinet – Pixel Power-Up. CRT Black #111111, Neon Cyan #00E5FF,
Electric Magenta #FF2DAA, Power-Up Yellow #FFD400, Pixel Grass Green #4CFF4C.
Chunky pixel art, scanlines, glowing vector HUD, and bold bitmap typography.
Sprites pop in with 8-bit bounce, score counters tick rapidly, and power-ups
burst into pixel particles. Transitions are CRT glitches, screen wipes, and
coin-in flashes. Playful, nostalgic, and unmistakably arcade.
```
A style paragraph that works has a consistent anatomy: a **name** for the style, the **exact palette** (hex codes and all), the **art direction**, **how things move**, **what the transitions are**, and one closing line for the **vibe**. Five or six sentences, and every graphic in the video has a rulebook — because scenes are [built in code with Hyperframes](/docs/video-agent#powered-by-hyperframes), the agent follows it literally. Prefer a pre-built look instead? Pass a `style_id` — see [Styles & References](/docs/styles-and-references).
## Paste your script for exact control
If you already have a script, paste the whole thing in and the agent follows it scene by scene, building the visuals around your exact words. Combine it with the style paragraph and a duration for the tightest brief:
```text Example prompt with script theme={null}
Make a 30-second portrait real estate market update for Austin, Texas,
presented by Ava. Follow the script below exactly, scene by scene. Use motion
graphics for every stat, and stock footage of the Austin skyline and
neighborhoods for texture between them.
Style: Elevated Estates – Quiet Luxury. Ivory #F7F4EE, Charcoal Ink #1E1E1C,
Sage #A6BB94, Deep Forest #24352A, Brushed Brass #C9A227. Editorial serif
headlines over generous whitespace, hairline rules, small-caps labels, and
full-bleed architectural photography with soft depth. Numbers count up gently,
chart lines draw themselves in, and photography drifts in slow parallax.
Transitions are soft crossfades, ivory paper wipes, and hairline reveals.
Calm, polished, and quietly luxurious.
Script:
Scene 1 (0-5s) - Ava on camera, skyline behind her.
"Austin, here's your market minute for July."
Scene 2 (5-12s) - Motion graphic: median price counts up to $450K, sage trend
line drawing upward.
"The metro median now sits at four hundred fifty thousand, up one percent from
last summer, and prices are firming."
Scene 3 (12-19s) - Motion graphic: inventory bars stepping down, brass accent
on the final bar.
"Inventory tells the story. Active listings are down fifteen percent from a
year ago, at four and a half months of supply."
Scene 4 (19-25s) - Stock footage of a front door and porch, stat card
overlay: 24 DAYS.
"And well-priced homes are moving in about twenty-four days."
Scene 5 (25-30s) - Ava on camera, hairline rule and small-caps CTA card.
"The window favors sellers again. Thinking about a move? Let's talk before fall."
```
## The output
This is the video that prompt produced — one prompt, one pass:
The first cut is a draft. To close the gap to post-ready, keep talking to the agent in [chat mode](/docs/interactive-sessions) — revise a single scene ("change the background of scene two") while every other scene holds still. Prompt for the 90, edit for the 10.
## More levers
1. **Attach reference files.** Pass slides, images, or documents in the `files` array — the agent folds them into the video as visual context or content sources. See [Upload Assets](/docs/upload-assets).
2. **Pin a specific avatar or voice** with `avatar_id` (see [Avatars](/docs/avatars)) and `voice_id` (see [Browse Voices](/docs/voices/search-voices)) for consistency, or omit them to let the agent choose.
3. **Apply your brand once** with `brand_kit_id` from [`GET /v3/brand-kits`](/reference/list-brand-kits) — colors, fonts, and logo ship on-brand by default on every video after.
4. **Set `orientation`** when you know the target platform (`"portrait"` for mobile/social, `"landscape"` for presentations).
5. **Review the plan before it builds.** With `"mode": "chat"`, the agent comes back with a scene-by-scene plan you can push back on before production starts. See [Interactive Sessions](/docs/interactive-sessions).
For more worked examples, see the [Video Agent prompt guide](https://www.heygen.com/blog/video-agent-prompt-guide) on the blog.