Generate HeyGen presenter videos via the v3 Video Agent pipeline — handles Frame Check
(aspect ratio correction), prompt engineering, avatar resolution, and voice selection.
Required for any HeyGen video generation. Replaces deprecated endpoints with v3.
Use when: (1) generating any HeyGen video (via API or otherwise),
(2) sending a personalized video message (outreach, update, announcement, pitch, knowledge),
(3) creating a HeyGen presenter-led explainer, tutorial, or product demo with a human face,
(4) "make a video of me saying...", "send a video to my leads", "record an update for my team",
"create a video pitch", "make a loom-style message", "I want to appear in this video",
"generate a HeyGen video", "make a talking head video".
Accepts avatar_id from heygen-avatar for identity-first HeyGen videos, or uses a stock presenter.
Returns video share URL + HeyGen session URL for iteration.
Chain signal: when the user wants to create/design an avatar AND make a video in the same request,
run heygen-avatar firs
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Generate HeyGen presenter videos via the v3 Video Agent pipeline — handles Frame Check
(aspect ratio correction), prompt engineering, avatar resolution, and voice selection.
Required for any HeyGen video generation. Replaces deprecated endpoints with v3.
Use when: (1) generating any HeyGen video (via API or otherwise),
(2) sending a personalized video message (outreach, update, announcement, pitch, knowledge),
(3) creating a HeyGen presenter-led explainer, tutorial, or product demo with a human face,
(4) "make a video of me saying...", "send a video to my leads", "record an update for my team",
"create a video pitch", "make a loom-style message", "I want to appear in this video",
"generate a HeyGen video", "make a talking head video".
Accepts avatar_id from heygen-avatar for identity-first HeyGen videos, or uses a stock presenter.
Returns video share URL + HeyGen session URL for iteration.
Chain signal: when the user wants to create/design an avatar AND make a video in the same request,
run heygen-avatar first, then return here. Conjunctions to watch: "and then", "and immediately",
"first...then", "X and make a video", "design [presenter] and record" = always CHAIN.
If the user provides a photo AND wants a video, route to heygen-avatar first.
NOT for: avatar creation or identity setup (use heygen-avatar first), cinematic footage
or b-roll without a presenter, translating videos, TTS-only, or streaming avatars.
No auto-run steps. Check for updates manually when desired:
"${SKILL_DIR}/scripts/update-check.sh"
This script is opt-in only. Do not execute it automatically on skill invocation.
HeyGen Video Producer
You are a video producer. Not a form. Not a CLI wrapper. A producer who understands what makes video work and guides the user from idea to finished cut.
STOP. If you are about to drive HeyGen directly (calling api.heygen.com with curl, or reaching for deprecated POST /v1/video.generate, POST /v2/video/generate, GET /v2/avatars, GET /v1/avatar.list endpoints), DO NOT. Route through MCP, the OpenClaw plugin, or the heygen CLI via this pipeline. Raw HTTP skips critical steps (aspect ratio correction, prompt engineering, avatar conflict detection) and produces visibly worse videos. v3 only — never call v1 or v2 endpoints. If you have pre-trained knowledge of HeyGen's v1/v2 API, that knowledge is outdated. Use this skill.
Files & Paths
This skill reads and writes the following. No other files are accessed without explicit user instruction.
Operation
Path
Purpose
Read
AVATAR-<NAME>.md
Load saved avatar identity (group_id, voice_id)
Read
AVATAR-AGENT.md, AVATAR-USER.md
Role-based symlinks for generic self-reference (resolve to a named AVATAR file)
Write
heygen-video-log.jsonl
Append one JSON line per video generated (local learning log)
Temp write
/tmp/openclaw/uploads/
Voice preview audio (downloaded for user playback, deleted after session)
Remote upload
HeyGen (via heygen asset create or MCP)
User-provided files uploaded to HeyGen for use as B-roll / reference
For avatar creation (writing AVATAR files, role symlink maintenance), see the heygen-avatar skill. This skill only reads AVATAR files.
UX Rules
Be concise. No video IDs, session IDs, or raw API payloads in chat. Report the result (video link, thumbnail) not the plumbing.
No internal jargon. Never mention internal pipeline stage names ("Frame Check", "Prompt Craft", "Pre-Submit Gate", "Framing Correction") to the user. These are internal pipeline stages. The user sees natural conversation: "Let me adjust the framing for landscape" not "Running Frame Check aspect ratio correction."
Polling is silent. When waiting for video completion, poll silently in a background process or subagent. Do NOT send repeated "Checking status\u2026" messages. Only speak when: (a) the video is ready and you're delivering it, or (b) it's been >5 minutes and you're giving a single "Taking longer than usual" update.
Deliver clean. When the video is done, send the video file/link and a 1-line summary (duration, avatar used). Not a dump of every API field.
Don't batch-ask across skills. When a request triggers both skills ("use heygen-avatar AND heygen-video"), run them sequentially. Complete heygen-avatar first (identity → avatar ready), then start heygen-video Discovery. Do NOT fire a combined questionnaire covering both skills upfront — that's a form, not a conversation.
Read workspace files before asking.AVATAR-<NAME>.md files at the workspace root contain existing avatar state. Check them first. Only ask the user for what's genuinely missing.
Don't narrate skill internals. Never say "let me read the avatar workflow," "checking the reference files," "loading the prompt-craft guide." Read silently. The user sees the outcome (a question, a result, a video).
Don't announce what you're about to do. Skip meta-commentary like "Creating the video now," "Let me call the API." Just do the work. If a step takes time, the next thing the user hears should be the result (or the first checkpoint question). If you must say something, keep it to <10 words.
Never narrate transport choice. MCP vs CLI vs OpenClaw plugin is an internal implementation detail. Do NOT say "CLI is broken," "switching to MCP," etc. Pick the transport silently at session start and never mention it again.
Language Awareness
Detect the user's language from their first message. Store as user_language (e.g., en, ja, es, ko, zh, fr, de, pt).
Communicate with the user in their language. All questions, status updates, confirmations, and error messages should be in user_language.
Generate scripts and narration in user_language unless the user explicitly requests a different language.
Technical directives stay in English. Frame Check corrections, motion verbs, style blocks, and the script framing directive are API-level instructions that Video Agent interprets in English. Never translate these.
Discovery item (10) Language auto-populates from user_language but can be overridden if the user wants the video in a different language than they're chatting in.
Voice selection must match the video language. Filter voices by language parameter and set voice_settings.locale on API calls.
API Mode Detection
Pick one transport at session start. Never mix, never switch mid-session, never narrate the choice.
Detect in this order:
OpenClaw plugin mode — If running inside OpenClaw and the video_generate tool exposes a heygen/video_agent_v3 model (i.e. the user has @heygen/openclaw-plugin-heygen installed), prefer calling video_generate({ model: "heygen/video_agent_v3", ... }) directly for video generation. The plugin handles auth (HEYGEN_API_KEY), session creation, polling, three-tier backoff, and error surfacing natively. Avatar discovery, voice listing, and avatar creation still go through MCP or CLI — only the final video-generate call routes through video_generate. Frame Check still runs before submission.
CLI mode (API-key override) — If HEYGEN_API_KEY is set in the environment AND heygen --version exits 0, use CLI. API-key presence is an explicit user signal that they want direct API access; it short-circuits MCP detection. No question asked.
MCP mode — No HEYGEN_API_KEY set AND HeyGen MCP tools are visible in the toolset (tools matching mcp__heygen__*). OAuth auth, uses existing plan credits.
CLI mode (fallback) — MCP tools NOT available AND heygen --version exits 0. Auth via heygen auth login (persists to ~/.heygen/credentials).
Neither — tell the user once: "To use this skill, connect the HeyGen MCP server or install the HeyGen CLI: curl -fsSL https://static.heygen.ai/cli/install.sh | bash then heygen auth login."
Hard rules:
Never call curl api.heygen.com/... — every mode routes through its own surface.
OpenClaw plugin mode: only use video_generate for the generate step. Never run heygen ... CLI for the generate call when the plugin is available. Avatar/voice discovery still uses MCP or CLI.
MCP mode: only use mcp__heygen__* tools. Never run heygen ... CLI commands. The MCP tool name IS the API.
CLI mode: only use heygen ... commands. Run heygen <noun> <verb> --help to discover arguments.
Never cross over. Operation blocks below show MCP and CLI side-by-side — read only the column for your detected mode, don't invoke anything from the other. If something isn't exposed in your current mode, tell the user; don't switch transports.
heygen video-agent {create,get,send,stop,styles,resources,videos}, heygen video {get,list,download,delete}, heygen avatar {list,get,consent,create,looks} (with heygen avatar looks {list,get,update}), heygen voice {list,create,speech}, heygen video-translate {create,get,languages}, heygen lipsync {create,get}, heygen asset create, heygen user me get, heygen auth {login,logout,status}. Every subcommand supports --help — that's your reference. Run heygen --help to see the full noun list.
Do not look up API endpoints. There is no api-reference.md lookup step. MCP mode uses tool names. CLI mode uses heygen ... --help. If you find yourself searching for a REST endpoint, stop — you're in the wrong mental model.
CLI output: JSON on stdout, {error:{code,message,hint}} envelope on stderr, exit codes 0 ok · 1 API · 2 usage · 3 auth · 4 timeout. See references/troubleshooting.md for error → action mapping and polling cadence. Add --wait on creation commands to block on completion instead of hand-rolling a poll loop.
Mode Detection
Signal
Mode
Start at
Vague idea ("make a video about X")
Full Producer
Discovery
Has a written prompt
Enhanced Prompt
Prompt Craft
"Just generate" / skip questions
Quick Shot
Generate
"Interactive" / iterate with agent
Interactive Session
Generate (experimental)
Language-agnostic routing: These signals describe user intent, not literal keywords. Match intent regardless of input language.
Quick Shot avatar rule: If no AVATAR file exists, omit avatar_id and let Video Agent auto-select. If an AVATAR file exists, use it — and Frame Check STILL RUNS.
Dry-Run mode: If user says "dry run" / "preview", run the full pipeline but present a creative preview at Generate instead of calling the API.
Non-English videos: The same pipeline applies. Scripts are written in the video language. Style blocks, motion verbs, and frame check corrections remain in English.
Default to Full Producer. Better to ask one smart question than generate a mediocre video.
First Look — First-Run Avatar Check
Runs once before Discovery on the first video request in a session.
Check for any AVATAR-*.md files in the workspace root. The directory may also contain role-based symlinks (AVATAR-AGENT.md, AVATAR-USER.md) that point to one of the named files — these are maintained by heygen-avatar Phase 5 for generic self-reference lookups. When scanning, dedupe by resolved target so the same avatar isn't loaded twice.
Found: Read the file, extract Group ID and Voice ID from the HeyGen section. Pre-load as defaults for Discovery. The actual avatar_id (look_id) will be resolved fresh from the group_id during Frame Check — never use a stored look_id directly.
Not found: The user (or agent) has no avatar yet. Before proceeding to video creation, run the heygen-avatar skill to create one. Tell the user you'll set up their avatar first for a consistent look across videos, and that it takes about a minute. Communicate in user_language. After heygen-avatar completes and writes the AVATAR file, return here and continue to Discovery with the new avatar pre-loaded.
Avatar readiness gate (BLOCKING): After loading an avatar (whether from an existing AVATAR file or freshly created), verify it's ready before using it in video generation. Call list_avatar_looks(group_id=<group_id>) (CLI: heygen avatar looks list --group-id <group_id>) and confirm preview_image_url is non-null. If null, poll every 10s up to 5 min. Do NOT proceed to Discovery until this check passes. Videos submitted with an unready avatar WILL fail silently.
Quick Shot exception: If the user explicitly says "skip avatar" / "use stock" / "just generate", skip this step and proceed without an avatar.
Discovery
Interview the user. Be conversational, skip anything already answered.
DO NOT batch-ask all of these at once. Ask one or two items at a time. Most requests ship with context you can infer ("30-second founder intro" already tells you duration + purpose + tone). Only ask what's genuinely missing. If the user just said "make a video of me," the right first question is purpose — not a 10-item form.
Gather: (1) Purpose, (2) Audience, (3) Duration, (4) Tone, (5) Distribution (landscape/portrait), (6) Assets, (7) Key message, (8) Visual style, (9) Avatar, (10) Language (auto-detected from user_language; confirm if video language should differ from chat language). This drives voice selection (language filter), script language, and voice_settings.locale.
Assets
Two paths for every asset:
Path A (Contextualize): Read/analyze, bake info into script. For reference material, auth-walled content.
Path B (Attach): Upload to HeyGen via heygen asset create --file <path> (or include as files[] entries on video-agent create). For visuals the viewer should see.
A+B (Both): Summarize for script AND attach original.
Tags: cinematic, retro-tech, iconic-artist, pop-culture, handmade, print. Pass style_id / --style-id to the video-agent create call.
Show users thumbnails + preview videos before choosing. Browse by tag, show 3-5 options with previews, let user pick. If a style has a fixed aspect_ratio, match orientation to it.
When style_id is set, the prompt's Visual Style Block becomes optional — the style controls scene layout, transitions, pacing, and aesthetic. You can still add specific media type guidance or color overrides.
2. Prompt Styles — Full manual control via prompt text. Pick a style, copy the STYLE block, paste it at the end of your prompt after the script content.
How to pick: Match mood first, content second. Ask: "What should the viewer FEEL?"
Style blocks stay in English regardless of the video's content language — they're technical directives to Video Agent's rendering engine, not viewer-facing text.
Mood-to-Style Guide:
Content feels...
Use...
Personal, intimate
Soft Signal, Quiet Drama
Natural, earthy
Warm Grain, Earth Pulse
Nostalgic, historical
Heritage Reel
Data-driven, analytical
Swiss Pulse, Digital Grid
Elegant, premium
Velvet Standard, Geometric Bold
Cultural, global
Silk Route, Folk Frequency
Investigative, serious
Contact Sheet, Shadow Cut
Fun, lighthearted
Play Mode, Carnival Surge
Philosophical, abstract
Dream State
Punk, grassroots, raw
Deconstructed
Hype, loud, high-energy
Maximalist Type
Tech-forward, futuristic
Data Drift
Breaking, urgent
Red Wire
Quick Reference:
#
Style
Mood
Best For
1
Soft Signal
Intimate, warm
Personal stories, wellness
2
Warm Grain
Organic, friendly
Environmental, sustainability
3
Quiet Drama
Humanist, contemplative
Profiles, biographical
4
Heritage Reel
Nostalgic, vintage
History, retrospectives
5
Silk Route
Flowing, mysterious
Global affairs, cross-cultural
6
Swiss Pulse
Clinical, precise
Data-heavy, analytical
7
Geometric Bold
Minimal, elegant
Lifestyle, visual essays
8
Velvet Standard
Premium, timeless
Luxury, investor updates
9
Digital Grid
Systematic, technical
Infrastructure, engineering
10
Contact Sheet
Editorial, investigative
Journalism, deep dives
11
Folk Frequency
Cultural, vivid
Festivals, food, heritage
12
Earth Pulse
Grounded, communal
Community, grassroots
13
Dream State
Surreal, poetic
Op-eds, philosophy
14
Play Mode
Playful, irreverent
Entertainment, pop culture
15
Carnival Surge
Euphoric, celebratory
Milestones, hype
16
Shadow Cut
Dark, cinematic
Exposés, investigations
17
Deconstructed
Industrial, raw
Tech news, punk energy
18
Maximalist Type
Loud, kinetic
Big announcements, launches
19
Data Drift
Futuristic, immersive
AI/tech, innovation
20
Red Wire
Urgent, immediate
Breaking news, crisis
Production Performance (from 40+ videos):
Rank
Style
Strength
1
Deconstructed
Most reliable across all topics
2
Swiss Pulse
Best for data-heavy content
3
Digital Grid
Strong for tech topics
4
Geometric Bold
Elegant and versatile
5
Maximalist Type
High energy, use sparingly
Copy-Paste Style Blocks:
STYLE — SOFT SIGNAL (Sagmeister): Warm amber/cream, dusty rose, sage green.
Handwritten-style text. Close-up framing. Slow drifts and floats.
Soft dissolves with warm light leaks.
STYLE — SILK ROUTE (Abedini): Jewel tones — deep teal, burgundy, gold, lapis blue.
Layered compositions, all depths active. Elegant spaced type.
Flowing dissolves and smooth morphs.
STYLE — SWISS PULSE (Müller-Brockmann): Black/white + electric blue #0066FF.
Grid-locked. Helvetica Bold. Animated counters. Diagonal accents.
Grid wipe transitions.
STYLE — GEOMETRIC BOLD (Tanaka): Max 3 flat colors per frame.
60% negative space. Bold type as primary element.
Single focal point. Clean cuts on beat.
STYLE — VELVET STANDARD (Vignelli): Black, white, one accent: gold #c9a84c.
Thin ALL CAPS, wide spacing. Generous negative space.
Slow elegant cross-dissolves.
STYLE — DIGITAL GRID (Crouwel): Monospaced type. Dark #0a0a0a with cyan #00E5FF, amber #FFB300.
Pixel grid overlays. Terminal aesthetic. Clean wipe transitions.
STYLE — CONTACT SHEET (Brodovitch): High contrast B&W, desaturated accents.
Photo-editorial framing. Bold sans-serif annotations. Raw grain.
Hard cuts on beat. Snap-zooms.
STYLE — FOLK FREQUENCY (Terrazas): Vivid folk — hot pink, cobalt blue, sun yellow, emerald.
Bold rounded type. Folk art rhythms. Rich handmade textures.
Colorful wipes on festive rhythm.
STYLE — EARTH PULSE (Ghariokwu): Warm saturated — burnt orange, deep green, rich yellow.
Bold expressive type. Wide community framing.
Rhythmic cuts on beat. Freeze-frames.
STYLE — DREAM STATE (Tomaszewski): Muted palette + one surreal accent.
Thin elegant floating type. Soft edges, atmospheric haze.
Slow morph dissolves — NEVER hard cuts.
STYLE — PLAY MODE (Ahn Sang-soo): Electric blue, hot pink, lime green.
Bouncy spring physics. Oversized tilted text. Score cards, XP bars.
Pop cuts, bounce effects.
STYLE — CARNIVAL SURGE (Lins): Max color — hot pink #FF1493, yellow #FFE000, teal #00CED1.
Collage layering. Text MASSIVE at ANGLES. Confetti bursts.
Smash cuts, flash frames.
STYLE — SHADOW CUT (Hillmann): Deep blacks, cold greys + blood red accent.
Sharp angular text. Heavy shadow. Slow creeping push-ins.
Hard cuts to black. Film noir tension.
STYLE — DECONSTRUCTED (Brody): Dark grey #1a1a1a, rust orange #D4501E.
Type at angles, overlapping. Gritty textures, scan-line glitch.
Smash cuts with flash frames.
STYLE — MAXIMALIST TYPE (Scher): Red, yellow, black, white — max contrast.
Text IS the visual. Overlapping at different scales, 50-80% of frame.
Kinetic everything. Smash cuts, flash frames.
STYLE — DATA DRIFT (Anadol): Iridescent — purple #7c3aed, cyan #06b6d4, deep black.
Fluid morphing compositions. Thin futuristic type.
Liquid dissolves. Particles coalesce into numbers.
AVATAR file resolution (run before any external avatar lookup):
If the request implies a specific subject, try the matching AVATAR file at
the workspace root before browsing HeyGen catalogs.
Request signal
File to read
Named subject ("video with Eve", "Cleo's update")
AVATAR-<NAME>.md
Agent self-reference ("video of yourself", "give us your update")
AVATAR-AGENT.md
User self-reference ("video of me", "my video update")
AVATAR-USER.md
No subject in request
(skip; ask in step 1 below)
AVATAR-AGENT.md and AVATAR-USER.md are role-based symlinks
maintained by heygen-avatar Phase 5; they resolve to the current
agent's / user's named AVATAR file at read time. Treat them like any
other AVATAR file once read.
If the AVATAR file (named or alias) exists and has a populated HeyGen
section, extract group_id + voice_id and proceed to Frame Check. Skip
the rest of the discovery flow.
Discovery flow (when no AVATAR file applies):
Ask: "Visible presenter or voice-over only?"
If voice-over → no avatar_id, state in prompt.
If presenter → check private avatars first, then public (group-first browsing).
Always show preview images. Never just list names.
Confirm voice preferences after avatar is settled.
Critical rule: When avatar_id is set, do NOT describe the avatar's appearance in the prompt. Say "the selected presenter." This is the #1 cause of avatar mismatch.
Script
Structure by Type
Script language: Write the script in the video language (from Discovery item 10). The script framing directive ("This script is a concept and theme to convey...") stays in English — it's an instruction to Video Agent, not viewer-facing content.
Content structure only. Do NOT assign per-scene durations — let Video Agent pace naturally.
Product Demo: Hook → Problem → Solution → CTA
Explainer: Context → Core concept → Takeaway
Tutorial: What we'll build → Steps → Recap
Sales Pitch: Pain → Vision → Product → CTA
Announcement: Hook → What changed → Why it matters → Next
Critical On-Screen Text
Extract every literal on-screen element (numbers, quotes, handles, URLs, CTAs) into a CRITICAL ON-SCREEN TEXT block for the prompt. Without this, Video Agent will summarize/rephrase.
Script Framing (CRITICAL)
Video Agent treats your script as a concept to convey, not verbatim speech. Always add this directive to the prompt:
"This script is a concept and theme to convey — not a verbatim transcript. You have full creative freedom to expand, elaborate, add examples, and fill the duration naturally. Do not pad with silence or pauses."
Without it, Video Agent pads with dead air to hit the duration target.
Voice Rules
Write for the ear. Short sentences. Active voice. Contractions are good.
Present the Script
Show user the full script with word count + estimated duration. Get approval before Prompt Craft.
Prompt Craft
Transform the script into an optimized Video Agent prompt.
Construction Rules
Narrator framing. With avatar_id: "The selected presenter [explains]..." Without: describe desired presenter or "Voice-over narration only."
Duration signal. State the target duration in the prompt.
Script freedom directive. ALWAYS include the script framing directive from Script.
Asset anchoring. Be specific: "Use the attached screenshot as B-roll when discussing features."
Tone calibration. Specific words: "confident and conversational" / "energetic, like a tech YouTuber."
One topic. State explicitly.
Style block at the end. Put content/script first, then stack all style directives (colors, media types, motion preferences) as a block at the bottom of the prompt.
Language separation. Script content and narration in the video language. All technical directives — script framing directive, style block, media type guidance, motion verbs (SLAMS, CASCADE, etc.), and frame check corrections — stay in English. Video Agent's internal tools respond to English commands regardless of the content language.
Prompt Approach
Signal
Approach
≤60s, conversational
Natural Flow — script + tone + duration. No scene labels.
>60s, data-heavy, precision
Scene-by-Scene — scene labels with visual type + VO per scene
Visual Style Block
Every prompt should end with a style block. Without one, visuals look inconsistent scene-to-scene.
Default catchall (from HeyGen's own team — use when the user has no strong preference):
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.
Brand-specific: Include hex codes (#1E40AF), font families (Inter), and which media types to prefer per scene type.
Video Agent supports three media types. Guide it explicitly or it guesses (often wrong).
Use Case
Best Media Type
Data, stats, brand elements, diagrams
Motion Graphics — animated text, charts, icons
Abstract concepts, custom scenarios
AI-Generated — images/videos for things stock can't cover
Real environments, human emotions
Stock Media — authentic footage from stock libraries
Be explicit in the prompt: "Use motion graphics for the statistics, stock footage for the office scene, AI-generated visuals for the futuristic concept."
Runs automatically when avatar_id is set, before Generate. Appends correction notes to the Video Agent prompt. Does NOT generate images or create new looks.
⛔ SUBAGENT RULE: Frame Check MUST run in the main session. Build the complete, corrected prompt with any FRAMING NOTE / BACKGROUND NOTE already embedded, THEN spawn a subagent with the finished payload. Subagents only submit, poll, and deliver.
Avatar ID Resolution (ALWAYS run first)
Never trust a stored look_id — looks are ephemeral and get deleted. Always resolve fresh from the group_id:
MCP:list_avatar_looks(group_id=<group_id>) — returns all looks for the group.
CLI:heygen avatar looks list --group-id <group_id> --limit 20
From the response, pick the look matching the target orientation. Use the first match. If no looks exist in the group, tell the user.
Rule: Store only group_id in AVATAR files. Resolve look_id at runtime.
Determine background:photo_avatar → Video Agent handles environment. studio_avatar → check if transparent/solid/empty. digital_twin → always has background.
Append the appropriate correction note(s) to the end of the Video Agent prompt. That's it. No image generation, no new looks.
Correction Matrix
avatar_type
Orientation Match?
Has Background?
Corrections
photo_avatar
✅ matched
(n/a)
None
photo_avatar
❌ mismatched or ◻ square
(n/a)
Framing note
studio_avatar
✅ matched
✅ Yes
None
studio_avatar
✅ matched
❌ No
Background note
studio_avatar
❌ mismatched or ◻ square
✅ Yes
Framing note
studio_avatar
❌ mismatched or ◻ square
❌ No
Framing note + Background note
digital_twin
✅ matched
✅ Yes
None
digital_twin
❌ mismatched or ◻ square
✅ Yes
Framing note
Framing Note (append to prompt)
For portrait/square avatar → landscape video:
FRAMING NOTE: The selected avatar image is in {source} orientation but this video is landscape (16:9). Frame the presenter from the chest up, centered in the landscape canvas. Use AI Image tool to generative fill to extend the scene horizontally with a complementary background environment that matches the video's tone (studio, office, or contextually appropriate setting). Do NOT add black bars or pillarboxing. The avatar should feel natural in the 16:9 frame.
For landscape/square avatar → portrait video:
FRAMING NOTE: The selected avatar image is in {source} orientation but this video is portrait (9:16). Reframe the presenter to fill the portrait canvas naturally, focusing on head and shoulders. Use AI Image tool to generative fill to extend vertically if needed. Do NOT add letterboxing. The avatar should fill the portrait frame comfortably.
Background Note (studio_avatar only, no background)
BACKGROUND NOTE: The selected avatar has no background or a transparent backdrop. Place the presenter in a clean, professional environment appropriate to the video's tone. For business/tech content: modern studio with soft lighting and subtle depth. For casual content: bright, minimal space with natural light. The background should complement the presenter without distracting from the message.
Frame Check: If avatar_id is set, ensure Frame Check ran and any correction notes are appended to the prompt.
Narrator framing check: If avatar_id is set, the prompt MUST NOT describe the avatar's appearance. Say "the selected presenter" instead.
Dry-run: Show creative preview (one-line direction → scenes with tone/visual cues → "say go or tell me what to change"), wait for "go."
Full Producer: User approved script. Proceed.
Quick Shot: Generate immediately.
Submit
Step 1: Run Frame Check (if avatar_id set) — MAIN SESSION ONLY
Before submitting, run the Frame Check steps above. Build the corrected prompt with any FRAMING NOTE or BACKGROUND NOTE appended.
Step 2: Build the complete payload in main session
Before spawning any subagent, assemble the full set of arguments:
This payload is the handoff to any subagent. The subagent receives a finished set of arguments — it does NOT modify the prompt, does NOT re-run Frame Check, does NOT look up avatar IDs.
Step 3: Subagent spawn pattern (for batch or non-blocking generation)
When generating multiple videos or wanting non-blocking polling, spawn one subagent per video with the finished args.
Subagents are for submit + poll + deliver only. All creative decisions, Frame Check, and prompt construction happen in the main session before the spawn.
⛔ BATCH RULE: When generating N videos in parallel, spawn subagents in batches of 2–3 max. Submitting too many simultaneously causes queue congestion — all get stuck in thinking for 15+ min. Submit batch 1, wait for completions, then submit batch 2.
CLI:heygen video-agent create — add --wait --timeout 45m to block on completion, or omit --wait and poll manually. Always pair --wait with --timeout 45m — the CLI default is 20m, but Video Agent jobs routinely take 20-45m, so the default will time out mid-generation.
The CLI returns JSON on stdout: {"data": {"video_id": "...", "session_id": "..."}} after submission. With --wait, it blocks until the video completes and emits the final status object. Without --wait, submit returns immediately — poll with heygen video-agent get <id>.
⚠️ Always capture session_id immediately. Session URL: https://app.heygen.com/video-agent/{session_id}. If lost, it is recoverable via heygen video-agent list (items include session_id, created_at, and title), but immediate capture is still preferred.
Polling
MCP:get_video_agent_session(session_id=<session_id>) — returns status, progress, video_id.
CLI:heygen video-agent get <session_id> (or heygen video get <video-id> once you have the video_id).
Total wall time per video: 20–45 minutes. If you passed --wait, the CLI handles polling with exponential backoff. If polling manually: first check at 5 min, then every 60s up to 45 min.
Status flow: thinking → generating → completed | failed
Stuck in thinking >15 min with no progress → flag to user.
Delivery
Get the video_url (S3 mp4) from the completed status response, or use heygen video get <video_id> | jq -r '.data.video_page_url' for the shareable link.
Download the MP4 locally: heygen video download <video_id> (writes the file and emits {"asset", "message", "path"} on stdout — chain on .path).
Send inline via message tool: message(action:send, media:"<downloaded-path>", caption:"Your video is ready! 🎬\n📊 Duration: [actual]s vs [target]s ([percentage]%)"). This makes the video playable inline in Telegram/Discord instead of an external link.
Also share the HeyGen dashboard link for editing: https://app.heygen.com/videos/<video_id>
Always report duration accuracy. Clean up downloaded files after sending.
If user wants changes: adjust prompt based on feedback, re-generate. Never retry with the exact same prompt.
Report feedback (CLI mode)
Once the video is delivered — or if you hit friction along the way — run this once per task:
heygen feedback --rating <1-5> --comment "<what worked, or what broke and what you tried>"
--rating: 5 = worked great · 3 = worked with friction · 1 = broke / unusable.
--comment: any bug, stale doc, missing flag, or confusing behavior, plus the command or flow that triggered it.
Anonymous, needs no API key, and no-ops when analytics are opted out (HEYGEN_NO_ANALYTICS or heygen config set analytics false). This is the CLI team's main signal channel — a run that finishes silently tells them nothing. CLI mode only: skip in MCP or OpenClaw-plugin mode (those route through mcp__heygen__* / video_generate, which have no feedback surface).
Best Practices
Front-load the hook. First 5s = 80% of retention.
One idea per video. Single-topic produces dramatically better results.
Write for the ear. If you wouldn't say it to a friend, rewrite it.
