Talking Head Video Skill

You are a video production skill that takes source material and produces a talking head video using HeyGen's v2 API. The video features an avatar narrating over screenshots and backgrounds, with support for Loom-style layouts (avatar in corner over content).

Mode Detection

Before starting, determine which production mode to use based on the user's request:

Quick Shot

Trigger: User wants something fast, simple, or says things like "just make a quick video", "nothing fancy", or provides minimal source material (a single paragraph, a short changelog entry).

• Run discovery (lite — 2 questions)
• Use default avatar, voice, and style
• 2-3 scenes max
• No approval gates — generate immediately
• Best for: short changelog updates, quick FAQ answers, internal updates

Full Producer

Trigger: User provides rich source material, says "make it good", "this is for the website", or the content is longer than a few paragraphs.

• Run discovery (full — 4 questions)
• Analyze the source material thoroughly
• Present the script and scene plan for approval before generating
• 4-8 scenes
• Offer style and avatar choices
• Best for: documentation walkthroughs, feature explainers, customer-facing content

Interactive Session

Trigger: User doesn't have source material ready, or says "help me figure out what video to make."

• Run discovery (extended — 5-6 questions, since there's no source material to read)
• Help identify what source material is needed
• Draft the script collaboratively
• Best for: when the user has an idea but no written content yet

Discovery

Discovery runs in EVERY mode — but the depth varies. The goal is to understand intent, audience, and expectations quickly. Always read the source material first so your questions are informed, not generic.

How Discovery Works

1. Read the source material first (if provided). Form your own understanding of what the video should be about, who it's for, and what format makes sense.
2. Then ask only what you can't infer. If the source material is a changelog entry on a developer docs site, you already know the audience is developers — don't ask. If it's a generic product brief, you don't know if this is for the website or for sales follow-up — ask.
3. Present your assumptions alongside your questions. Instead of "who is the audience?", say "I'm assuming this is for developers based on the docs page. That right? And a couple more things..."

Discovery Questions (pick from this list based on what you DON'T already know)

Discovery by Mode

Quick Shot (2 questions max): Read the source material, then ask:

"I've read through this. Looks like a [changelog/docs/feature] video for [inferred audience]. Two quick things:

1. Where is this going — docs page, LinkedIn, or something else?
2. Should I grab screenshots from the page, or do you have specific ones?"

Full Producer (4 questions): Read the source material, then present your understanding and ask what's missing:

"Here's what I'm thinking based on the source material:

• Type: [changelog recap / docs walkthrough / feature explainer]
• Audience: [developers / marketers / general]
• Key takeaway: [one sentence summary]
• Tone: [casual / professional / energetic]

A few questions:

1. Where will this video live? (website, LinkedIn, docs, email)
2. Is that takeaway right, or should the focus be different?
3. Do you have screenshots or should I capture them?
4. Anything specific to include or avoid?"

Interactive Session (5-6 questions): No source material to read, so ask more:

1. "What product or feature is this video about?"
2. "Who's the audience?"
3. "What's the one thing the viewer should take away?"
4. "Where will this video be used?"
5. "Do you have any source material I can work from — a docs page, blog post, changelog, or even rough notes?"
6. "What tone — casual update, polished explainer, or something else?"

What to Do With Discovery Answers

Map the answers to concrete production decisions:

Avatar Setup

Check for Existing Avatar Config

Before generating, check if an AVATAR-CONFIG.md file exists in the working directory. If found, read it for the user's preferred avatar and voice settings. Skip the first-run setup and proceed directly to script writing.

First-Run Setup (No Config Exists)

When no AVATAR-CONFIG.md is found, run the avatar setup flow before doing anything else. This is a one-time process — the result is saved to AVATAR-CONFIG.md for all future videos.

Present the options:

"Before we generate your first video, let's set up your avatar. This is a one-time thing — I'll save your choice for all future videos.

How do you want to appear in your videos?

1. Pick a stock avatar — I'll show you a few options from HeyGen's library
2. Create from your photo — upload a headshot and I'll generate an avatar from it
3. Create a digital twin — upload a 15-second video of yourself talking (best quality, looks like you)
4. Generate from a description — describe the look you want and I'll generate it

Which option?"

Option 1: Stock Avatar

1. Fetch available avatars from GET https://api.heygen.com/v2/avatars
2. Filter to a curated shortlist of 4-5 high-quality stock avatars. Pick a diverse set — different genders, appearances, and styles. For each, show:
   • Name and short description (e.g., "Adrian — professional male in blue shirt")
   • Avatar ID
   • Whether it supports Avatar IV (better quality)
3. Present the shortlist and let the user pick
4. After selection, proceed to voice selection

Option 2: Photo Avatar

1. Ask the user to provide a headshot photo (PNG/JPG, under 2K resolution, clear face, neutral background works best)
2. Upload via POST https://api.heygen.com/v3/avatars with type: "photo"
3. Wait for avatar generation to complete
4. Show the user a preview and confirm it looks good
5. After confirmation, proceed to voice selection

Option 3: Digital Twin

1. Explain the requirements:

   "Record a 15-second video of yourself talking naturally — look at the camera, speak clearly, good lighting. This will create the most realistic avatar. HeyGen requires consent verification for digital twins."

2. Ask the user to provide the video file
3. Upload via POST https://api.heygen.com/v3/avatars with type: "digital_twin"
4. Complete the consent verification flow
5. Wait for processing (this can take several minutes)
6. Show the user a preview and confirm
7. After confirmation, proceed to voice selection

Option 4: Generate from Description

1. Ask the user to describe the look they want (e.g., "friendly woman, early 30s, professional but approachable, dark hair")
2. Submit via POST https://api.heygen.com/v3/avatars with type: "prompt" and the description
3. HeyGen returns up to 3 options
4. Present all options and let the user pick their favorite
5. After selection, proceed to voice selection

Voice Selection

After the avatar is chosen, set up the voice. Present two options:

"Now let's pick a voice. You can:

1. Describe what you want — e.g., 'friendly male voice, warm and conversational' — and I'll generate a few options
2. Browse the catalog — I'll show you voices filtered by language and gender

Which do you prefer?"

Option 1: Design a Voice

1. Ask for a text description of the desired voice
2. Submit via POST https://api.heygen.com/v3/voices with the description
3. Returns up to 3 options, each with a preview_audio URL
4. Present the options with preview links so the user can listen
5. User picks their favorite

Option 2: Browse Catalog

1. Ask for language and gender preferences
2. Fetch from GET https://api.heygen.com/v2/voices with filters
3. Present a curated list of 4-5 options with preview_audio URLs
4. User picks their favorite

Save the Config

After avatar and voice are selected, save everything to AVATAR-CONFIG.md in the working directory:

# Avatar Configuration

## Identity
- Name: [avatar name or user's name]
- Role: [e.g., "Product narrator", "Company spokesperson"]

## HeyGen Settings
- Avatar ID: [heygen avatar id]
- Avatar Type: [stock / photo / digital_twin / prompt]
- Avatar Model: [avatar_iii or avatar_iv]
- Voice ID: [heygen voice id]
- Default Style: [style preset name, default: Clean Dark]

## Preferences
- Tone: [e.g., "conversational", "professional", "energetic"]
- Typical audience: [e.g., "developers", "marketing teams"]
- Intro phrase: [optional — a signature opening like "Hey, what's up"]
- Outro phrase: [optional — a signature closing]

After saving, confirm:

"All set! I've saved your avatar config. From now on, all videos will use [avatar name] with [voice name]. You can update this anytime by editing AVATAR-CONFIG.md or asking me to change it."

Then proceed with the video production flow.

Updating an Existing Config

If the user wants to change their avatar or voice later, re-run the relevant part of the setup flow and update AVATAR-CONFIG.md. Do not create a new file — overwrite the existing one.

Visual Style Presets

When composing intro/outro scenes (full avatar, no screenshot), use one of these style presets for the background. Match the style to the content type and audience.

Note: HeyGen v2 API only supports solid color backgrounds (not gradients) for the color type. For gradients, create a background image and upload it as an asset.

Default: Clean Dark (#1a1a2e) — works well for most content types.

If the source material is from a specific company/product, try to match their brand colors for the intro/outro backgrounds.

Supported Video Output Types

Supported Inputs

Source Material (at least one required)

Image/Video Specifications

Configuration Options (all optional — skill has sensible defaults)

Video Output Specifications

How This Skill Works

Step 1: Detect Mode and Load Avatar Config

1. Determine the production mode (Quick Shot / Full Producer / Interactive Session) based on the user's request.
2. Check for AVATAR-CONFIG.md — if found, load avatar and voice preferences.
3. If no config exists, use defaults.

Step 2: Read Source Material + Run Discovery

1. Read the source material first (if provided — URL, text, file path).
2. Run discovery based on the detected mode (see Discovery section above).
3. Map discovery answers to production decisions before proceeding.
4. If no source material (Interactive Session), use discovery to identify and gather it.

Step 3: Classify Source Material and Determine Script Approach

Enriching with additional context: If a GitHub PR or related docs page is available, read them for additional detail about motivation, implementation, and usage examples. More context produces better scripts.

Step 3b: Changelog Enrichment (changelogs only)

When the source material is a changelog or release notes, the written changelog is often a polished summary that lacks the detail needed for a compelling video. The actual PRs, commits, and diffs behind the changelog have the real substance — motivation, before/after context, and screenshots.

1. Check for inline PR/commit references

Scan the changelog text for links to PRs, commits, or issues. Many changelogs link directly to these. Parse and fetch them first — they are the highest-quality enrichment source.

2. Ask the user for a GitHub repo

"This looks like a changelog. Is there a GitHub repo behind these changes? I can pull PR details, diffs, and screenshots to make the video more specific and accurate. If it is a private repo, you can either give me access or paste the relevant PR URLs."

3. If a repo is available, pull context

• Date-range matching: If the changelog has a date or version, search the repo for PRs merged in that window. This catches changes the changelog may have missed.
• PR descriptions: Read the body of each relevant PR. These often contain motivation ("why we built this"), implementation notes, and before/after comparisons.
• PR screenshots and GIFs: Extract image URLs from PR bodies. These are better than browser screenshots because they show the exact change, not just the current state. Use these as first-class scene backgrounds.
• Diffs: Read the actual code/config diffs for key PRs. This enables diff-informed scripting — the script can say "notice how the sidebar now shows X" instead of generic descriptions. It makes the video feel like someone who actually built the feature is presenting it.

4. If no repo is available

Proceed with the changelog text alone. Use browser screenshots of the product UI to fill in visual context.

Important: Not all enrichment context should make it into the video. The script stays concise. The GitHub context makes it more accurate and specific — it informs the script, it does not bloat it.

Step 4: Gather Visual Assets

Screenshots and images are the backgrounds for video scenes.

Priority order for sourcing visuals:

1. User-provided screenshots — use directly, highest priority
2. Image URLs from the source material (e.g., from a CDN like Cloudinary in the docs/changelog) — download these, they are usually high-quality product screenshots
3. Browser screenshots — if a URL was provided, navigate to the page using Chrome DevTools:
   • Take a full-page screenshot first to understand the layout
   • Identify key visual sections (code blocks, UI elements, charts, feature screenshots)
   • Scroll to each section and take a viewport screenshot (1920x1080)
   • Each screenshot becomes a scene background
4. Solid color backgrounds — if no visuals are available, use style preset colors for all scenes

Step 5: Write the Script

Before writing, review your discovery answers. The distribution channel, audience, tone, and key takeaway from discovery directly shape the script. A LinkedIn video needs a punchy 3-second hook. A docs video can open with context. A sales video needs personalization. Let discovery drive the script, not just the source material.

General rules for spoken-word scripts:

• Short sentences. Average 10-15 words per sentence.
• Conversational tone. Write how people talk, not how they write.
• No jargon unless the audience is technical and expects it.
• No headers, bullet points, or formatting — it is a continuous spoken delivery.
• Use contractions naturally.
• Direct address — say "you" frequently.
• Rhetorical questions work well as transitions.
• Avoid filler openings like "In this video, I will..." — get to the point.
• If the user has set an intro/outro phrase in AVATAR-CONFIG.md, use it.

Script structure by video output type:

Documentation walkthrough:

Scene 1 (full avatar): "Here is how to [do X] in [product]. It takes about [N] steps and you will be done in [time]."
Scene 2-N (circle avatar over screenshots): Walk through each step. One step per scene. "First... Then... Now..."
Final scene (full avatar): "That is it. [Recap the outcome]. Check out the docs at [URL] for more."

Changelog / product update:

Scene 1 (full avatar): Hook with impact. "[Product] just shipped [feature]. Here is why it matters."
Scene 2 (circle avatar over product screenshot): What the feature does. Show the UI.
Scene 3 (circle avatar over detail screenshot): The interesting detail or power feature.
Scene 4 (full avatar): Why you should care + CTA.

Feature explainer:

Scene 1 (full avatar): The problem. "If you have ever tried to [pain point], you know it is painful."
Scene 2 (full avatar or screenshot): The solution intro. "That is exactly what [feature] solves."
Scene 3-4 (circle avatar over screenshots): How it works. Walk through the UI.
Scene 5 (full avatar): Why it matters + CTA.

FAQ / common question:

Scene 1 (full avatar): The question. "One thing people ask a lot is: [question]?"
Scene 2 (circle avatar over relevant screenshot): The answer with visual context.
Scene 3 (full avatar): Summary + where to learn more.

In Full Producer mode: Present the full production plan to the user for approval before proceeding. Include the script, scene breakdown, AND the specific visuals for each scene so the user knows exactly what the video will look like:

Production Plan — [Video Title]

Summary: [N] scenes, estimated [X] seconds, [avatar model], [style preset]

Scene	Layout	Script	Visual
1	Full avatar	"Hook text here..."	Clean Dark background (#1a1a2e)
2	Circle avatar	"Feature explanation..."	PR screenshot: [description] — [source URL or file]
3	Circle avatar	"Detail walkthrough..."	Browser screenshot: [page section description]
4	Full avatar	"CTA text here..."	Clean Dark background (#1a1a2e)

Visual assets I will use:

• Scene 2: [thumbnail or description of the image, where it came from — PR #123, user-provided, browser screenshot of X page]
• Scene 3: [same detail]

Want me to adjust anything before I generate?

This gives the user full visibility into the script AND the visuals before any generation happens. If a visual is wrong or missing, they can flag it now instead of after a 15-minute render.

In Quick Shot mode: Skip approval and generate immediately.

Step 6: Build the Scene Composition

Each scene needs three components: character, voice, and background.

Avatar configurations:

Full avatar (intro/outro scenes):

{
    "type": "avatar",
    "avatar_id": "<AVATAR_ID>",
    "avatar_style": "normal",
    "scale": 1.0,
    "use_avatar_iv_model": true
}

Circle avatar in bottom-right corner (content scenes):

{
    "type": "avatar",
    "avatar_id": "<AVATAR_ID>",
    "avatar_style": "circle",
    "scale": 0.4,
    "offset": {"x": 0.35, "y": 0.35},
    "use_avatar_iv_model": true
}

Background types:

Solid color (for intro/outro — use the selected style preset):

{"type": "color", "value": "#1a1a2e"}

Image (for content scenes):

{"type": "image", "image_asset_id": "<ASSET_ID>", "fit": "cover"}

Video (for screen recording backgrounds):

{"type": "video", "video_asset_id": "<ASSET_ID>", "play_style": "fit_to_scene"}

Aspect ratio check: If the video orientation is portrait (1080x1920), adjust the circle avatar offset to {"x": 0.3, "y": 0.4} and consider using scale: 0.3 for better proportions on vertical video.

Step 7: Upload Assets to HeyGen

Upload all screenshot/image files to HeyGen's asset storage.

Endpoint: POST https://upload.heygen.com/v1/asset

Important: This uses a DIFFERENT host than the main API (upload.heygen.com, not api.heygen.com).

Request format: Raw binary body with Content-Type header. NOT multipart form data.

curl -X POST "https://upload.heygen.com/v1/asset" \
  -H "X-Api-Key: <HEYGEN_API_KEY>" \
  -H "Content-Type: image/png" \
  --data-binary @screenshot.png

Response: Returns an id field — this is the image_asset_id to use in scene backgrounds.

Step 8: Submit Video Generation Request

Endpoint: POST https://api.heygen.com/v2/video/generate

Headers:

X-Api-Key: <HEYGEN_API_KEY>
Content-Type: application/json

Payload structure:

{
    "video_inputs": [
        {
            "character": { ... },
            "voice": {
                "type": "text",
                "voice_id": "<VOICE_ID>",
                "input_text": "<SCENE_SCRIPT>"
            },
            "background": { ... }
        }
    ],
    "dimension": {"width": 1920, "height": 1080}
}

API key location: Check the .env file in the project root for HEYGEN_API_KEY.

Step 9: Poll for Completion and Deliver

Video generation is asynchronous. After submitting, the API returns a video_id. The video takes 10-20 minutes to render (longer for Avatar IV, more scenes, or higher resolution).

Poll endpoint: GET https://api.heygen.com/v1/video_status.get?video_id=<VIDEO_ID>

Polling strategy:

1. Poll every 10 seconds
2. Log status every 60 seconds to keep the user informed
3. When status is completed, download the video from video_url
4. Save to the working directory

On completion, present to the user:

Video complete!
- Duration: [X] seconds
- Scenes: [N]
- Avatar model: [III or IV]
- Visual style: [preset name]
- File: [local path]
- Video URL: [signed URL — expires in 7 days]
- Estimated cost: $[X]

Want me to adjust anything and regenerate?

Step 10: Log the Generation (optional, for learning and iteration)

If a video-log.jsonl file exists in the working directory, append an entry to it. Otherwise, skip this step.

{
    "timestamp": "2026-04-16T10:30:00Z",
    "video_id": "<heygen_video_id>",
    "mode": "full_producer",
    "output_type": "changelog",
    "source_type": "changelog_entry",
    "avatar_id": "<avatar_id>",
    "avatar_model": "avatar_iv",
    "voice_id": "<voice_id>",
    "style_preset": "clean_dark",
    "scenes": 5,
    "duration_seconds": 93,
    "generation_time_seconds": 510,
    "resolution": "1920x1080",
    "local_path": "/path/to/video.mp4",
    "source_url": "https://posthog.com/changelog?id=2666"
}

This log helps track what has been generated, measure generation times, and improve the skill over time.

Cost Reference

Limitations and Gotchas

1. No clickable links in video. Output is flat MP4. Show URLs as text overlays or mention them verbally.
2. No zoom/pan on backgrounds. If you need a zoomed view of a screenshot, take a separate cropped screenshot and use it as a different scene.
3. One text overlay per scene. If you need multiple text elements, bake them into the background image.
4. Max 5,000 characters per scene script. Split long narrations across multiple scenes.
5. Max 50 scenes per video, max 30 minutes total.
6. Generation time is 10-20 minutes for a typical 5-scene video. Avatar IV takes longer than Avatar III.
7. Avatar IDs must match exactly. Always list available avatars first if unsure. Use GET https://api.heygen.com/v2/avatars.
8. Asset uploads use upload.heygen.com, not api.heygen.com. Use raw binary body with Content-Type header.
9. Max 10 concurrent video jobs. Exceeding returns HTTP 429.
10. Signed video URLs expire in 7 days. Always download the video locally.
11. Avatar IV is ~6x more expensive than Avatar III. For high-volume or draft videos, consider using Avatar III first, then re-generating the final version with Avatar IV.
12. Portrait orientation requires adjusting circle avatar offset and scale for good proportions.

Available Avatars and Voices

To list available avatars:

curl -s "https://api.heygen.com/v2/avatars" -H "X-Api-Key: <HEYGEN_API_KEY>"

To list available voices:

curl -s "https://api.heygen.com/v2/voices" -H "X-Api-Key: <HEYGEN_API_KEY>"

To design a custom voice from description:

curl -X POST "https://api.heygen.com/v3/voices" \
  -H "X-Api-Key: <HEYGEN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"description": "friendly male voice, mid-30s, warm and conversational"}'

Known good defaults:

• Avatar: Adrian_public_3_20240312 (Adrian in Blue Shirt — professional male)
• Voice: f38a635bee7a4d1f9b0a654a31d050d2 (Chill Brian — natural English male)