# Prompt Craft Reference

Production-quality prompt engineering for HeyGen Video Agent. Combines official HeyGen guidance with patterns validated across 80+ test videos.

Load this when the user wants cinematic/polished output, scene-by-scene control, or specific visual styles.

---

## Prompting Levels (from HeyGen Official Guide)

### Level 1: Basic
Just describe content. Video Agent fills in the rest.
```
"Introduce HeyGen to knowledge workers, talk about its Talking Avatar models"
```

### Level 2: Script-Driven (RECOMMENDED DEFAULT)
Paste a full video script. Agent follows scene-by-scene while improving flow, timing, and visuals.
This is "the single biggest upgrade most people miss." — HeyGen docs

### Level 3: Scene-by-Scene (Maximum Control)
```
Scene 1: [Scene Type]
  Visual: [Describe exact visual]
  VO/Script: "[What the avatar says]"
```

**Official recommendation:** Don't assign per-scene timestamps. Natural flow + tone description outperforms rigid scene structure.

---

## Prompt Anatomy (Production Quality)

```
FORMAT:    What kind of video, how long, what energy
TONE:      Emotional register, references
AVATAR:    "The selected presenter" (when avatar_id set) or delivery style
STYLE:     Colors, typography, motion rules, transitions (see Style Block)
CRITICAL ON-SCREEN TEXT:  Exact strings that must appear literally
SCENE-BY-SCENE:  (if >60s) Individual scene breakdowns with VO and visual type
MUSIC:     Genre, energy arc
```

**Rule: Content/script first, style block at the end.** Keeps creative intent clean and technical specs organized.

### Critical On-Screen Text

List every exact string. Without this, Video Agent rephrases, summarizes, or rounds numbers.

```
CRITICAL ON-SCREEN TEXT (display literally):
- "$141M ARR — All-Time High"
- "1.85M Signups — +28% MoM"
- Quote: "Use technology to serve the message." — Shalev Hani
```

---

## Style Block

Every prompt should end with a style block. Without one, visuals look inconsistent scene-to-scene.

### The HeyGen Catchall (official team recommendation)
```
Use minimal, clean styled visuals. Blue, black, and white as main colors.
Leverage motion graphics as B-rolls and A-roll overlays. Use AI videos when necessary.
When real-world footage is needed, use Stock Media.
Include an intro sequence, outro sequence, and chapter breaks using Motion Graphics.
```

### Style Presets (from HeyGen docs)

| Style | Best For | Prompt Language |
|-------|----------|-----------------|
| Minimalistic | Corporate, Tech, SaaS | "Use minimalistic, clean visuals with lots of white space" |
| Cartoon/Animated | Education, Kids | "Use cartoon-style illustrated visuals" |
| Bold & Vibrant | Marketing, Social | "Use bold, vibrant colors and dynamic visuals" |
| Cinematic | Brand films, High-end | "Use cinematic quality visuals with dramatic lighting" |
| Flat Design | Modern, App demos | "Use flat design style with geometric shapes" |
| Gradient Modern | Tech, Startup | "Use modern gradient backgrounds and sleek transitions" |
| Retro/Vintage | Nostalgia, Creative | "Use retro-inspired visuals with warm tones" |

### Brand Colors

Be explicit with hex codes and fonts:
```
Use #1E40AF as primary blue, #F8FAFC as background white, #0F172A for text.
Font: Inter family throughout.
```

Without defined colors, visuals look inconsistent scene-to-scene.

---

## Media Types & When to Use Each

Video Agent supports three media types. Guide it explicitly or it guesses (often wrong).

### Motion Graphics
Animated text, icons, charts, shapes, transitions.
- **A-roll overlays:** lower thirds, bullet points, animated callouts
- **B-roll scenes:** animated explanations, data viz, process flows
- **Chapter cards:** section breaks, intros, outros
- **Best for:** Data, statistics, brand elements, technical diagrams

### AI-Generated Images & Videos
- Conceptual illustrations, abstract concepts
- Custom scenarios stock can't cover
- Stylized visuals in particular artistic style
- **Best for:** Abstract concepts, custom scenarios, product mockups

### Stock Media
Real-world footage from stock libraries.
- Authentic scenes (offices, cities, people)
- Industry-specific (medical, manufacturing, retail)
- **Best for:** Real environments, human emotions, establishing shots

### Decision Matrix

| Content Type | Motion Graphics | AI Generated | Stock Media |
|---|---|---|---|
| Data/Statistics | ✅ Best | ❌ | ❌ |
| Abstract Concepts | ✅ Good | ✅ Best | ❌ |
| Real Environments | ❌ | ⚠️ Can work | ✅ Best |
| Brand Elements | ✅ Best | ❌ | ❌ |
| Human Emotions | ❌ | ⚠️ Uncanny | ✅ Best |
| Custom Scenarios | ⚠️ Limited | ✅ Best | ⚠️ May not exist |
| Technical Diagrams | ✅ Best | ❌ | ❌ |

---

## Scene Types

| Type | Format | When |
|------|--------|------|
| **A-ROLL** | Avatar speaking to camera | Intros, key insights, CTAs, emotional beats |
| **FULL SCREEN B-ROLL** | No avatar, motion graphics only | Data visualization, info-dense content |
| **A-ROLL + OVERLAY** | Split frame: avatar + content | Presenting data while maintaining human connection |

**Rotation is mandatory.** Never 3+ of the same type in a row.

**Voiceover on EVERY scene.** Silent B-roll = broken video.

### Scene-by-Scene Template (HeyGen Official Format)

```
Scene 1: [Scene Type]
  Visual: [Describe exact visual — include media type]
  VO/Script: "[What the avatar says]"
```

### Detailed Scene Templates (validated in testing)

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

**B-ROLL with layered motion:**
```
SCENE 2 — FULL SCREEN B-ROLL
[NO AVATAR — motion graphic only]
VOICEOVER: "The exact script for this scene."
Dark background with subtle grid. "HEADLINE" SLAMS in from left.
Three data cards CASCADE from right, staggered. Bottom ticker SLIDES in.
```

**A-ROLL + OVERLAY:**
```
SCENE 3 — A-ROLL + OVERLAY
[Avatar LEFT 35%. Content RIGHT 65%.]
VOICEOVER: "The exact script for this scene."
RIGHT SIDE: Stats COUNT UP below headline.
```

---

### Non-English Videos

The same prompt structure applies regardless of language:
1. **Script/narration:** In the video language
2. **Style block:** Always English (Video Agent directive)
3. **Motion verbs:** Always English (SLAMS, CASCADE, etc.)
4. **Critical on-screen text:** In whatever language should appear on screen
5. **Scene labels:** English (Scene 1, Scene 2) — structural, not rendered

---

## Example Prompts (from HeyGen Official Guide)

### Compliance Training
```
Use a professional female avatar. Make a compliance training video explaining phishing
in detail. Use examples and list top watch-outs. Leverage motion graphics as A-roll
overlay and B-roll to help explain core concepts.
```

### Educational Explainer (Voice-Over Only)
```
Create a 1-minute video about camera aperture. Use minimal science diagrams and
visualizations. No avatar needed, only voice-over. Cool neutrals (navy, cyan),
thin-line diagrams, and slow elegant motion. B-roll is abstract scientific
illustrations. Sequencing: definition → diagram expansion → conceptual layering.
```

### Brand Story (Animated)
```
Make a video telling the story of how Twitch got started. Use cartoon-style
animations and overlays. I want Twitch's iconic colors and fonts. Use motion
graphics overlays and AI-generated B-roll.
```

### Product Introduction (Japanese — non-English example)
```
日本のナレッジワーカー向けにHeyGenを紹介する1分間のビデオを作成してください。
トーキングアバターモデルの特徴を説明し、具体的な活用例を3つ含めてください。
ナレーターは選択されたプレゼンターが説明します。

CRITICAL ON-SCREEN TEXT (display literally):
- "HeyGen アバター V"
- "3分で動画作成"
- "API連携対応"

STYLE — SWISS PULSE (Müller-Brockmann): Black/white + electric blue #0066FF.
Grid-locked. Helvetica Bold. Animated counters. Diagonal accents.
Grid wipe transitions.
```

Note: Script content is in Japanese but STYLE block and scene labels remain in English — these are Video Agent directives, not viewer-facing content.

---

## Motion Vocabulary

Every visual element should have a motion verb. Static frames look dead.

### High Energy
- **SLAMS** — `"$95M" SLAMS in from left at -5 degrees`
- **CRASHES** — `Title CRASHES in from right, screen-shake on impact`
- **PUNCHES** — `Quote card PUNCHES up from bottom`

### Medium Energy
- **CASCADE** — `Three cards CASCADE from top, staggered 0.3s`
- **SLIDES** — `Ticker SLIDES in from right, continuous scroll`
- **FILLS** — `Progress bar FILLS 0 to 90% in orange`
- **DRAWS** — `Chart line DRAWS itself left to right`

### Low Energy
- **types on** — `Quote types on word by word in italic white`
- **fades in** — `Logo fades in at center, held 3 seconds`
- **COUNTS UP** — `"1.85M" COUNTS UP from 0 in amber`

---

## Pro Tips (from HeyGen community)

1. **Save your catchall as a template.** Find a style combo that works, reuse it. Consistency builds brand.
2. **Iterate in conversation.** Video Agent remembers context within a session. "Make the intro shorter" or "swap B-roll in scene 3 for stock footage" without re-prompting everything.
3. **Stack style at the end.** Content first, style directives last.
4. **Describe B-roll as motion verbs** ("slams in," "counts up"), NOT layout coordinates ("upper-left, 48pt").

---

## What Doesn't Work

- **Layout coordinates** — "upper-left: headline in 48pt" → blank frames. Use motion verbs.
- **Named artists without specs** — "Ikko Tanaka style" means nothing. Translate to colors + shapes + motion.
- **B-roll under 5 seconds** — Causes black/empty frames. 10s+ minimum.
- **Static elements** — Every element needs a motion verb.
- **Per-scene timestamps** — Makes delivery robotic (per HeyGen's own research). Use overall duration only.