HeyGen Best Practices Skill: AI Avatar Video Creation Guide

What is the HeyGen Best Practices Skill?

The HeyGen Best Practices skill is a comprehensive guide for integrating with HeyGen's AI avatar video creation API. It provides Claude Code with 18+ actionable rules organized by functionality, helping you create professional AI presenter videos, manage avatars and voices, handle video generation workflows, and implement advanced features.

This skill was created by the HeyGen community and includes real-world examples, TypeScript/Python code samples, and best practices for every aspect of the HeyGen API.

graph TD
    A[Video Request] --> B[Claude + HeyGen Skill]
    B --> C[Select Avatar]
    B --> D[Choose Voice]
    B --> E[Write Script]
    C --> F[POST /v2/video/generate]
    D --> F
    E --> F
    F --> G[Poll Status]
    G --> H{Completed?}
    H -->|Yes| I[Download Video URL]
    H -->|No| G

    style B fill:#F97316,stroke:#fff,color:#000
    style I fill:#00ff41,stroke:#fff,color:#000
                    

Why You Need This Skill

Creating AI avatar videos programmatically requires understanding multiple API endpoints, matching avatars with voices, handling asynchronous video generation, and implementing proper error handling. This skill simplifies everything by:

• Organizing knowledge by function - Rules are grouped into Foundation, Core Video Creation, Customization, and Advanced Features
• Providing production-ready code - Each rule includes TypeScript and Python examples you can use directly
• Teaching best practices - Learn to use avatar's default voice, implement proper polling, and handle rate limits
• Progressive context loading - The skill loads detailed guidelines on-demand to minimize token usage

Key Feature Categories

1. Foundation (Required)

Essential knowledge for any HeyGen integration:

• Authentication - API key setup, X-Api-Key header patterns
• Quota Management - Credit system, usage limits, checking remaining quota
• Video Status - Polling patterns, status types, retrieving download URLs
• Assets - Uploading images, videos, and audio for use in videos

// Authenticated request example
const response = await fetch("https://api.heygen.com/v2/avatars", {
  headers: {
    "X-Api-Key": process.env.HEYGEN_API_KEY!,
  },
});
const { data } = await response.json();

2. Core Video Creation

The main workflow for generating AI avatar videos:

• Avatars - Listing avatars, styles (normal, closeUp, circle), avatar_id selection
• Voices - Listing voices, locales, speed/pitch configuration
• Scripts - Writing scripts, pauses/breaks, pacing, structure templates
• Video Generation - POST /v2/video/generate workflow, multi-scene videos
• Dimensions - Resolution options (720p/1080p) and aspect ratios

// Basic video generation
const videoId = await generateVideo({
  video_inputs: [{
    character: {
      type: "avatar",
      avatar_id: "josh_lite3_20230714",
      avatar_style: "normal",
    },
    voice: {
      type: "text",
      input_text: "Hello! Welcome to our product demo.",
      voice_id: avatar.default_voice_id, // Use avatar's default voice
      speed: 1.0,
    },
    background: {
      type: "color",
      value: "#1a1a2e",
    },
  }],
  dimension: { width: 1920, height: 1080 },
});

3. Video Customization

Make your videos visually appealing:

• Backgrounds - Solid colors, images, and video backgrounds
• Text Overlays - Adding text with fonts and positioning
• Captions - Auto-generated captions and subtitle options

4. Advanced Features

Take your integration to the next level:

• Templates - Template listing and variable replacement
• Video Translation - Translating videos, quality/fast modes, dubbing
• Streaming Avatars - Real-time interactive avatar sessions
• Photo Avatars - Creating avatars from photos (talking photos)
• Webhooks - Registering webhook endpoints for async notifications
• Remotion Integration - Using HeyGen videos in Remotion compositions

Installation

Install the HeyGen Best Practices skill using the Claude Code Templates CLI:

npx claude-code-templates@latest --skill=development/heygen-best-practices --yes

Where is the skill installed?

The skill is saved in .claude/skills/heygen-best-practices/ in your project directory:

your-project/
├── .claude/
│   └── skills/
│       └── heygen-best-practices/    # Skill installed here
│           ├── SKILL.md
│           └── rules/
│               ├── authentication.md
│               ├── avatars.md
│               ├── voices.md
│               ├── video-generation.md
│               ├── video-status.md
│               └── ... (18+ rule files)
├── src/
├── package.json
└── README.md

How to Use the Skill

The skill uses progressive context loading - it provides a quick reference first, then loads detailed guidelines only when needed. This approach minimizes token usage while giving you access to comprehensive information.

Basic Usage

# Start Claude Code
claude

# Request HeyGen help
> Use the heygen-best-practices skill to create a video with an AI avatar presenting our product

Claude will:

1. Load the skill's quick reference
2. Identify the relevant rules (avatars, voices, video-generation)
3. Load detailed guidelines for those specific areas
4. Generate production-ready code with proper error handling

Usage Examples

Example 1: Create a Simple Avatar Video

claude

> Use the heygen-best-practices skill to create a 30-second product demo video with a professional male avatar

Result: Claude loads the avatars, voices, and video-generation rules, then generates code that lists available avatars, selects a professional one, uses its default voice, and creates the video with proper status polling.

Example 2: Multi-Scene Video with Different Backgrounds

claude

> Use the heygen-best-practices skill to create a video with 3 scenes: intro, features, and conclusion. Each scene should have a different background color.

Result: Claude generates multi-scene video configuration with proper scene transitions and background customization.

Example 3: Implement Webhook Notifications

claude

> Use the heygen-best-practices skill to set up webhooks so I get notified when my video is ready

Result: Claude loads the webhooks rule and provides code for registering webhook endpoints and handling completion events.

Best Practices Highlights

Always Use Avatar's Default Voice

Most avatars have a pre-matched default_voice_id that provides the best lip-sync quality:

// Get avatar details to find default voice
const details = await getAvatarDetails(avatarId);

// Use the default voice for best results
const voiceId = details.default_voice_id;

Implement Proper Status Polling

Video generation is asynchronous and can take 5-15 minutes:

async function waitForVideo(videoId: string): Promise {
  const maxAttempts = 60;
  const pollInterval = 10000; // 10 seconds

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.heygen.com/v1/video_status.get?video_id=${videoId}`,
      { headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } }
    );

    const { data } = await response.json();

    if (data.status === "completed") {
      return data.video_url;
    } else if (data.status === "failed") {
      throw new Error(data.error || "Video generation failed");
    }

    await new Promise(r => setTimeout(r, pollInterval));
  }

  throw new Error("Video generation timed out");
}

Add Natural Pauses to Scripts

Use SSML-style break tags for more natural speech:

const script = `
Welcome to our demo. <break time="1s"/>
Today I'll show you three key features. <break time="0.5s"/>
First, let's look at the dashboard.
`;

Common Pitfalls Avoided

The skill helps you avoid these common HeyGen integration mistakes:

• Mismatching avatar and voice genders
• Not polling for video completion (expecting synchronous generation)
• Hardcoding API keys instead of using environment variables
• Not handling rate limits with exponential backoff
• Using the wrong endpoint for transparent background videos
• Setting insufficient timeouts for video generation

Skill Structure

The skill is organized into logical categories with 18+ rule files:

Official Documentation

For more information about skills in Claude Code, see the official skills documentation.

For HeyGen API documentation, visit docs.heygen.com.