Create Your AI Avatar Video with HeyGen + Claude: A Step-by-Step Guide

You can now make a high-converting, 30-to-60-second talking AI avatar video edited like a professional Instagram Reel or YouTube Short directly from your terminal. By connecting HeyGen with Claude Code, you simply describe what you want in plain words, and AI handles avatar generation, voice synthesis, captions, sound effects, split-screens, and final video rendering.

Creating short-form video for Instagram Reels, TikTok, and YouTube Shorts used to require hours of filming, lighting setups, multiple takes, and complicated video editing timelines in Premiere Pro or CapCut. Today, generative AI and agentic skills streamline this into an automated workflow: HeyGen generates your photo-realistic talking avatar, Claude Code downloads the raw asset, and video editing skills like HyperFrames style the final cut with kinetic captions, sound effects, transitions, and motion graphics. For our broader perspective on video content, see our guide on short-form video marketing and Instagram marketing strategy.

Before You Start: How It Works and Requirements

The workflow is simple: HeyGen creates your talking avatar video, Claude fetches the generated video and subtitle files, Claude applies dynamic editing effects using pre-built skills, and you get an export-ready 1080x1920 MP4 video.

Requirement	Details	Cost
Computer	Mac, Windows, or Linux	Included
Claude Account	Claude Pro plan ($20/month) to run Claude Code in your terminal	$20/mo
HeyGen Account	A standard HeyGen account (free trial or paid plan)	Free test credits / Paid
Setup Time	Approximately 35 to 45 minutes for first-time installation	Free

Key Terms to Know

As you set up your environment, you will encounter three core terms:

• MCP (Model Context Protocol): The standardized protocol that acts like a bridge or cable connecting Claude to HeyGen's API tools and services.
• Skill: A modular recipe or playbook that gives Claude new capabilities, such as creating avatars, generating videos, or editing with HyperFrames.
• Claude Code: Anthropic's agentic command-line interface (CLI) tool that reads local files, executes terminal commands, and coordinates production workflows.

Step 1: Download and Install Everything

Before connecting services, ensure your computer has the necessary runtimes and command-line tools installed.

Accounts and Core Applications

• Claude Pro Account: Ensure you have an active subscription at claude.ai/pricing.
• HeyGen Account: Register your account at app.heygen.com.
• Node.js (v22 or newer): Download the LTS release from nodejs.org. Verify your installation by opening a terminal and running node -v.
• FFmpeg: Required to process audio and video streams locally. Download from ffmpeg.org or install via package managers (e.g., brew install ffmpeg on macOS, or winget install Gyan.FFmpeg on Windows).
• Claude Code CLI: Install the official Anthropic Claude CLI tool.

To install Claude Code, open Terminal (macOS/Linux) or PowerShell (Windows) and paste the appropriate command:

macOS / Linux:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Once installed, restart your terminal window, type claude, press Enter, and log in to your Anthropic account via your browser.

Install the Essential Video Skills

Anthropic skills provide Claude Code with domain-specific recipes for HeyGen and video post-production. You can install them with npx:

# 1. HeyGen Avatar skill (creates and registers your avatar)
npx skills add heygen-com/skills --skill heygen-avatar

# 2. HeyGen Video skill (generates talking avatar footage and transcripts)
npx skills add heygen-com/skills --skill heygen-video

# 3. HyperFrames editing skills (motion graphics, captions, transitions, overlays)
npx hyperframes skills update

Optional advanced skills:

# Remotion skills (code-based programmatic animation and video composition)
npx skills add remotion-dev/skills

# FFmpeg Social Video skill (presets for Reels, Shorts, and TikTok)
# Inside Claude Code:
/plugin marketplace add JosiahSiegel/claude-plugin-marketplace
/plugin install ffmpeg-social-video@claude-plugin-marketplace

After installing, restart Claude Code. When you type /, you will see your registered skills including /heygen-video and /hyperframes.

Skill Name	Provider	Primary Role
HeyGen Avatar	HeyGen	Builds your custom digital avatar once from a photo or webcam video.
HeyGen Video	HeyGen	Generates talking avatar scenes, speech synthesis, and synchronized SRT subtitles.
HyperFrames	Community / HeyGen	Automates video editing with over 450 effects: kinetic captions, zoom cuts, music, and sound design.
Media Use	HyperFrames suite	Sources and creates local royalty-free background music, sound effects, and voiceovers.
Remotion	Remotion Dev	Code-driven animation engine for advanced overlays and multi-layered compositions.
FFmpeg Social Video	Community	Optimizes aspect ratios (9:16 vertical 1080x1920) and safe zones for mobile social apps.

Step 2: Connect HeyGen to Claude via MCP (5 Minutes)

You only need to connect HeyGen once. You do not need to hunt down an API key; authentication happens securely through OAuth in your browser.

1. Create a dedicated folder for your video assets (for example Videos/my-reels) and open your terminal inside that folder:

   mkdir -p ~/Videos/my-reels && cd ~/Videos/my-reels

2. Register the HeyGen Model Context Protocol (MCP) server:

   claude mcp add --transport http --scope user heygen https://mcp.heygen.com/mcp/v1/

3. Start Claude Code in this directory:

   claude

4. Type /mcp, select heygen, and choose Authenticate. A browser window will open asking you to log into HeyGen and approve the connection.
5. Verify the integration by entering this prompt in Claude Code:

   Using HeyGen, show my plan and remaining credits.

   Claude will display your active plan status and remaining generation credits.

Tip for Claude Web App users: If you also want HeyGen directly inside Claude.ai, navigate to Claude Connectors → + Add → Add custom connector. Enter Name: HeyGen and URL: https://mcp.heygen.com/mcp/v1/, then click Approve.

Step 3: Create Your Custom Avatar

You can create a personalized avatar using either a single still photo or a short video clip:

• From a photo (fastest): A high-resolution, front-facing portrait with clear lighting and neutral background. Keep your face free of dark shadows, sunglasses, and heavy filters.
• From a video (highest realism): A 2-minute recording of you speaking directly into a camera at eye level on a tripod, in a well-lit and quiet room.

Save your portrait or footage in your working directory (e.g., me.jpg or me.mp4). Inside Claude Code, run:

Use heygen-avatar to create my avatar from me.jpg. My name is [Your Name]. Ask me one question at a time.

Claude will validate the image, submit the avatar job to HeyGen, and generate a secure consent confirmation URL. Open the link in your browser to approve likeness usage (consent links are single-use and expire within 24 hours). After a few minutes, check status by asking:

Is my avatar ready?

Testing without personal media? Simply prompt Claude: Show me 5 HeyGen stock avatars for a friendly Instagram Reel.

Step 4: Generate the Raw Avatar Video

Now that your avatar exists, produce the base video in two steps: scriptwriting and video synthesis.

1. Write the Script with Strong Retention Hooks

Short-form vertical video retention depends on the first three seconds. Use this prompt in Claude Code:

Write a 45-second script (about 110 words) for my avatar.
Topic: 3 quick tips to sleep better.
Start with a strong hook in the first 3 seconds.
End with "Follow for more."
Use simple English, short sentences, and no emojis.
Give me 3 hook options first.

Script length benchmarks for vertical reels:

• 30-second reel: ~75 words
• 45-second reel: ~110 words
• 60-second reel: ~145 words

2. Render Raw Video and Captions via HeyGen

Once you select your favorite hook and finalize your script, instruct Claude to generate the video:

Use heygen-video to make this script into a vertical 9:16 video, 1080p, with my avatar and voice.
Use my script word for word.
Tell me how many credits I have before you start, and wait for my OK.
When it is ready, download the video to raw.mp4 and the captions to captions.srt in this folder.

Claude checks your account balance, requests your confirmation, and submits the render job. Once processing completes (usually 2 to 4 minutes), you will have raw.mp4 and captions.srt sitting directly in your local directory.

Step 5: Edit Like a Pro Instagram Reel with HyperFrames

A talking head alone can lose viewer attention quickly on Instagram Reels or YouTube Shorts. HyperFrames applies dynamic motion graphics, split screens, B-roll framing, and kinetic typography directly to your raw footage.

Effect Category	HyperFrames Effect Styles	Visual Function
Animated Captions	caption-kinetic-slam, caption-highlight, caption-emoji-pop, caption-neon-accent	Displays words synchronously as spoken, keeping viewers engaged on mute.
Transitions	transitions-blur, transitions-push, transitions-3d, zoom-through-transition	Smooth cuts between tips or thematic sections.
Camera Motion	cinematic-zoom, parallax-zoom, camera-shake	Subtle virtual focal length shifts to emphasize key arguments.
Split Screens	comparison-split, split-tilt-cards	Shows your talking avatar alongside supporting iconography or diagrams.
Titles & Tags	glass-shard-title, yt-lower-third	Introductory hook banner and personal branding lower thirds.
Styling Overlays	light-leak, grain-overlay	Gives digital avatar footage a warm, cinematic film feel.
Progress Indicators	mk-progress-stat, conic-progress-ring	Visual pacing markers that increase video completion rates.
Call to Action	cta-close, logo-outro	Encourages follows, bookmarks, and shares.

The Complete Editing Prompt

Run this comprehensive prompt in Claude Code to turn raw.mp4 into a complete vertical short:

Use /hyperframes to edit raw.mp4 into a premium 1080x1920 Instagram Reel:
- 0-2s: big opening title "Sleep better tonight" (glass-shard-title style)
- Captions: word-by-word animated captions from captions.srt (caption-kinetic-slam), placed in the middle of the screen, not at the bottom
- At each tip: show the tip number with a smooth transitions-push
- Tip 2: split screen, avatar on the left, a simple icon of a phone turning off on the right
- Slow cinematic-zoom on the avatar during the hook
- Light grain-overlay for a premium look
- Calm background music, low volume under my voice, a soft whoosh on each transition
- End with a "Follow for more" card (cta-close)

Show me a preview first. When I say OK, render to final.mp4.

Claude builds the editing pipeline and launches a local browser preview. You can review the timing, colors, and audio balance before final rendering.

Rapid Iterations & Fine-Tuning

If anything needs adjustment, give short natural-language feedback:

• Make the captions bigger and yellow with a 2px black outline.
• Add a 3D flip transition between tip 1 and tip 2.
• Add a lower-third banner with my name for the first 4 seconds.
• Add a subtle progress bar at the top edge that fills as the video plays.
• Lower the background music volume by 30% so my voice is clearer.

Step 6: Export, Quality Assurance, and Publishing

Once you are happy with the preview, confirm the export. Claude will compile the final assets into final.mp4.

Ask Claude to run a technical audit on the finished file:

Check final.mp4. It must be 1080x1920, MP4 container, H.264 video codec, AAC audio, 30 fps. Fix it if anything is wrong.

Final Pre-Publish Checklist:

1. Mobile Safe Zones: Are captions positioned within the middle 60% of the screen so they aren't obscured by Instagram Reels' caption text, like buttons, or bottom navigation?
2. Audio Sync: Are the avatar's lips aligned with audio transients, and is speech distinct from the backing track?
3. Hook Delivery: Does the first 2 seconds immediately spark curiosity without lag?

Transfer the video to your phone or schedule it directly through Meta Business Suite, TikTok Studio, or YouTube Studio.

Troubleshooting Common Issues

Issue	Probable Cause	Solution
claude: command not found	Path environment variable not reloaded after install	Restart your terminal or run source ~/.bashrc (or ~/.zshrc).
Claude lacks HeyGen tools	MCP authentication expired or disconnected	Type /mcp, select heygen, click Authenticate, and approve in your browser.
Skills do not appear under /	Skill cache not updated or wrong location	Ensure files are located in ~/.claude/skills/<skill-name>/SKILL.md and restart Claude Code.
"Not enough credits" error	HeyGen plan balance reached	Wait for your monthly billing reset or top up credits on your HeyGen dashboard.
Rendering stalls over 10 minutes	API queue traffic at HeyGen	Do not submit duplicate jobs. Type Check my last HeyGen video status to poll current progress.
Black side bars (pillarboxing)	Default 16:9 ratio requested	Ask Claude: Remake the video in 9:16 vertical ratio and fill the frame.
HyperFrames rendering error	Missing local media utilities	Verify that node -v and ffmpeg -version both return valid version strings in your terminal.
Captions hidden by UI icons	Subtitles placed too low	Instruct: Move captions vertically to the vertical center (Y: 50%).

Cost and Efficiency Breakdown

• Claude Pro: $20/month (Claude pricing) — required for Claude Code CLI and agentic execution.
• HeyGen Plan: Free tier available for initial testing; Creator plan starts around $29/month (HeyGen pricing).
• Skills, Node.js & FFmpeg: 100% Free and open-source.

Credit Saving Pro-Tip: Always test and finalize your script in Claude text mode before invoking heygen-video. Once HeyGen renders the video, credits are deducted. Keeping your avatar video under 45 seconds saves both rendering time and account credits.