---

name: prompt-optimizer description: Write production-quality prompts for HeyGen Video Agent — from basic ideas to fully art-directed scene-by-scene scripts

Video Agent Prompt Optimizer

Write effective prompts for the HeyGen Video Agent API. Based on patterns from 40+ produced videos.

The core insight: Video Agent is an HTML interpreter. It renders layouts, typography, and structured content natively. Describe B-roll as layered text motion graphics with action verbs ("slams in," "types on," "counts up") — not layout specs ("upper-left, 48pt").

Reference Files

Workflow: Brief to Prompt

1. Pull data — Research the topic: web search, APIs, internal docs. Gather real quotes, stats, handles
2. Synthesize a thesis — Not a list. A story. "X is happening because Y — here's the proof." Group into 3-5 themes with a narrative arc
3. Choose a style — Match mood first, content second. Ask: "What should the viewer FEEL?" See visual-styles.md
4. Write the avatar — Thematic wardrobe matching content's emotional context. Brand logos and content-specific props in the set (see Avatar Guide below)
5. Extract critical text — List every number, quote, handle, and label that must appear literally
6. Break into scenes — One concept per scene. Rotate scene types. Never 3+ of same type in a row. At least 2 pure B-roll scenes
7. Write voiceover — Spell out numbers in VO ("one-point-eight-five million"), use figures on screen ("1.85M"). Narration on EVERY scene including B-roll
8. Layer each B-roll scene — L1 background, L2 hero, L3 supporting, L4 info bar, L5 effects. Every element must MOVE
9. Add music direction — Reference artists, describe energy arc
10. Add narration style — How to deliver: fast/slow, where to pause, emotional register per section

Prompt Anatomy

Every production-quality prompt follows this structure:

FORMAT:    What kind of video, how long, what energy
TONE:      Emotional register, references
AVATAR:    Detailed physical + environment description (60-100 words)
STYLE:     Named aesthetic with colors, typography, motion rules, transitions
CRITICAL ON-SCREEN TEXT:  Exact strings that must appear
SCENE-BY-SCENE:  Individual scene breakdowns with VO and layered visuals
MUSIC:     Genre, reference artists, energy arc
NARRATION STYLE:  How to deliver the voiceover

FORMAT

FORMAT: 75-second high-energy tech daily briefing. Think: a creator who just got amazing news.
FORMAT: Bloomberg-style strategy briefing. 100-120 seconds. CEO-delivered.

TONE

TONE: Confident, direct, data-backed. Highlights hit hard. Lowlights are honest — no spin.
TONE: Edgy, punk tech commentary. Vice News meets The Face magazine — raw, confrontational.

CRITICAL ON-SCREEN TEXT

List every exact string that must appear on screen. Without this, the agent may summarize, round numbers, or rephrase quotes.

CRITICAL ON-SCREEN TEXT (display literally):
- "$141M ARR — All-Time High"
- "1.85M Signups — +28% MoM"
- Quote: "Use technology to serve the message, not distract from it." — Shalev Hani
- "@username" — exact social handle

MUSIC & NARRATION

MUSIC: Driving electronic, heavy bass drops on key numbers. Run the Jewels meets
a tech keynote. Builds relentlessly, only softens for customer stories.

NARRATION STYLE: High energy throughout. Let numbers PUNCH — pause before big ones,
then deliver hard. Customer stories get warmth. The close should feel like a mic drop.

Avatar Description Guide

The avatar is NOT a fixed headshot — design it for each video like a movie character. Think costume designer + set designer.

Thematic Wardrobe Rule

The avatar's outfit and environment MUST match the content's emotional/cultural context:

What to Specify

Template

AVATAR: [Clothing — fabric, color, fit, accessories, posture].
[Setting — specific props, brand logos, what's on the walls].
[Monitors/desk — content visible on screens, items on desk].
[Lighting — direction, color temperature]. [Mood of the space].
60-100 words. 3+ content-specific props. Brand elements visible.

Scene Types

Rotation is mandatory. Never 3+ of the same type in a row. Every prompt needs at least 2 pure B-roll scenes.

Voiceover on EVERY scene. Every B-roll scene MUST include a VOICEOVER: line. Silent B-roll = broken video.

Scene Anatomy

A-ROLL:

SCENE 1 — A-ROLL (10s)
[Avatar center-frame, excited, hands gesturing]
VOICEOVER: "The exact script for this scene."
Lower-third: "TITLE TEXT" white on blue bar.

B-ROLL with layers:

SCENE 2 — FULL SCREEN B-ROLL (12s)
[NO AVATAR — motion graphic only]
VOICEOVER: "The exact script for this scene."
LAYER 1: Dark #1a1a1a background with subtle grid lines pulsing.
LAYER 2: "HEADLINE" SLAMS in from left in white Bold 100pt at -5 degrees.
LAYER 3: Three data cards CASCADE from right, staggered 0.3s.
LAYER 4: Bottom ticker SLIDES in: "supporting text scrolling continuously."
LAYER 5: Grid lines RIPPLE outward from impact point.
Hard cut.

A-ROLL + OVERLAY:

SCENE 3 — A-ROLL + OVERLAY (10s)
[SPLIT — Avatar LEFT 35%. Content RIGHT 65%. NO overlap.]
Avatar gestures toward content side.
VOICEOVER: "The exact script for this scene."
RIGHT SIDE: "HEADLINE" in cyan 60pt. Three stats COUNT UP below.

Alternate which side the avatar appears on between overlay scenes.

The Visual Layer System

Break B-roll into 5 stacked layers. This is the most powerful technique for motion graphics scenes.

Every B-roll: 4+ layers. Every overlay content side: 3+ layers. Every element must MOVE.

Motion Vocabulary

High Energy

Medium Energy

Low Energy

Transition Types

Timing Guidelines

Common video lengths: Social clip: 30-45s (5-7 scenes) | Briefing: 60-75s (7-9 scenes) | Deep dive: 90-120s (10-13 scenes)

Speaking pace: ~150 words/minute. Calculate: words / 150 * 60 = seconds

What Doesn't Work

Patterns that consistently produce poor results:

Layout language — Screen coordinates cause empty/black B-roll:

❌ "UPPER-LEFT: headline in 48pt Helvetica"
❌ "CENTER-SCREEN: display at coordinates (400, 300)"
✅ "135K" SLAMS in from left, white Impact 120pt, fills 40% of frame.

Named artists without specs — "Ikko Tanaka style" means nothing to Video Agent. Translate to concrete rules:

❌ "Use an Ikko Tanaka style"
✅ "Flat color blocks, maximum 3 colors per frame, 60% negative space, typography as primary element"

Style examples injected into prompts — Full example scenes from a style library confuse the agent. Use the style's rules, not example scenes.

Forced short B-roll (≤5 seconds) — Too short for rendering. Every tested video with 5s B-roll had empty/black screens. Use 10-15s.

Content as a list, not a story — "Here are 5 tweets" produces flat videos. Always synthesize: "X is happening because Y — here's the proof."

Production Insights

Style Performance (from 40+ videos)

Duration by Approach

Quality Checklist

• Thesis-driven — story, not bullet points
• Style named with colors, typography, motion, transitions (see visual-styles.md)
• Avatar has thematic wardrobe + branded environment (60-100 words)
• Critical text listed — every stat, quote, label
• Scenes rotate types — never 3+ same type. At least 2 B-roll scenes
• Every scene has VOICEOVER — including B-roll
• B-roll scenes have 4+ layers, every element has motion verbs
• B-roll scenes are 10-15 seconds (never ≤5s)
• Brand logos appear when discussing companies
• Every element moves — no static frames