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.

1. Be concise. No video IDs, session IDs, or raw API payloads in chat. Report the result (video link, thumbnail) not the plumbing.
2. 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."
3. 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.
4. 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.
5. 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.
6. 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.
7. 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).
8. 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.
9. 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.

user_language

en

ja

es

ko

zh

fr

de

pt

1. Communicate with the user in their language. All questions, status updates, confirmations, and error messages should be in

   user_language

   .
2. Generate scripts and narration in

   user_language

   unless the user explicitly requests a different language.
3. 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.
4. 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.
5. Voice selection must match the video language. Filter voices by

   language

   parameter and set

   voice_settings.locale

   on API calls.

1. 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.
2. 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.
3. 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.
4. CLI mode (fallback) — MCP tools NOT available AND

   heygen --version

   exits 0. Auth via

   heygen auth login

   (persists to

   ~/.heygen/credentials

   ).
5. 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

   ."

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

AVATAR-*.md

AVATAR-AGENT.md

AVATAR-USER.md

heygen-avatar

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

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

• HTML URLs cannot go in

  files[]

  (Video Agent rejects

  text/html

  ). Web pages are always Path A.
• Prefer download → upload →

  asset_id

  over

  files[]{url}

  (CDN/WAF often blocks HeyGen).
• If a URL is inaccessible, tell the user. Never fabricate content from an inaccessible source.
• Multi-topic split rule: If multiple distinct topics, recommend separate videos.

style_id

list_video_agent_styles(tag=<tag>, limit=20)

heygen video-agent styles list --tag cinematic --limit 10

cinematic

retro-tech

iconic-artist

pop-culture

handmade

print

style_id

--style-id

aspect_ratio

style_id

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.

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 — WARM GRAIN (Eksell): Earth tones — ochre, forest green, terracotta, cream.
Organic rounded compositions. 16mm film grain. Rounded sans-serif.
Gentle wipes and soft cuts.

STYLE — QUIET DRAMA (Ray): Muted warm — sepia, deep brown, soft gold.
Portrait framing. Clean serif. Strong single-source contrast.
Slow fades to black.

STYLE — HERITAGE REEL (Cassandre): Faded gold, burgundy, navy, sepia wash.
Elegant centered serif. Vignetting and aged film grain.
Iris wipe transitions.

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.

STYLE — RED WIRE (Tartakover): Red, black, white, emergency yellow.
Bold condensed all-caps. Split screens, tickers, timestamps.
Snap cuts, flash frames. Zero breathing room.

• User has no strong visual preference → browse API styles, pick one
• User wants specific brand colors/fonts/motion → prompt style
• User wants a curated look + specific media types →

  style_id

  + selective prompt additions

AVATAR-<NAME>.md

AVATAR-AGENT.md

AVATAR-USER.md

AVATAR-AGENT.md

AVATAR-USER.md

heygen-avatar

group_id

voice_id

1. Ask: "Visible presenter or voice-over only?"
2. If voice-over → no

   avatar_id

   , state in prompt.
3. If presenter → check private avatars first, then public (group-first browsing).
4. Always show preview images. Never just list names.
5. Confirm voice preferences after avatar is settled.

avatar_id

• 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

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

1. Narrator framing. With

   avatar_id

   : "The selected presenter [explains]..." Without: describe desired presenter or "Voice-over narration only."
2. Duration signal. State the target duration in the prompt.
3. Script freedom directive. ALWAYS include the script framing directive from Script.
4. Asset anchoring. Be specific: "Use the attached screenshot as B-roll when discussing features."
5. Tone calibration. Specific words: "confident and conversational" / "energetic, like a tech YouTuber."
6. One topic. State explicitly.
7. 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.
8. 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.

avatar_id

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

1. Fetch avatar look metadata:

   get_avatar_look(look_id=<avatar_id>)

   (CLI:

   heygen avatar looks get --look-id <avatar_id>

   ) → extract

   avatar_type

   ,

   preview_image_url

   ,

   image_width

   ,

   image_height

2. Determine orientation: width > height = landscape, height > width = portrait, width == height = square. Fetch fails = assume portrait.
3. Determine background:

   photo_avatar

   → Video Agent handles environment.

   studio_avatar

   → check if transparent/solid/empty.

   video_avatar

   → always has background.
4. Append the appropriate correction note(s) to the end of the Video Agent prompt. That's it. No image generation, no new looks.

avatar_id

avatar_id

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

avatar_id

--prompt

--avatar-id

--voice-id

--style-id

--orientation

landscape

portrait

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

create_video_agent(prompt=<prompt>, avatar_id=<look_id>, voice_id=<voice_id>, style_id=<optional>, orientation=<orientation>)

heygen video-agent create

--wait --timeout 45m

--wait

--wait

--timeout 45m

heygen video-agent create \
  --prompt "..." \
  --avatar-id "..." \
  --voice-id "..." \
  --orientation landscape \
  --wait --timeout 45m

{"data": {"video_id": "...", "session_id": "..."}}

--wait

--wait

heygen video-agent get --session-id <id>

session_id

https://app.heygen.com/video-agent/{session_id}

1. 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.
2. Download the MP4 locally:

   heygen video download <video_id>

   (writes the file and emits

   {"asset", "message", "path"}

   on stdout — chain on

   .path

   ).
3. 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.
4. Also share the HeyGen dashboard link for editing:

   https://app.heygen.com/videos/<video_id>

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