HeyGen API Best Practices Skill

A Claude Code skill for building AI avatar video applications with the HeyGen API — covering video generation, avatar management, template workflows, and real-time avatar streaming integration.

When to Use This Skill

Choose this skill when:

• Creating AI avatar videos programmatically via the HeyGen API
• Managing avatars, voices, and video templates
• Building automated video generation pipelines
• Integrating real-time avatar streaming into applications
• Generating personalized video content at scale

Consider alternatives when:

• You need general video editing (use FFmpeg or a video editor)
• You need text-to-speech only without avatars (use a TTS API)
• You need live video conferencing (use WebRTC tools)

Quick Start

Copy
# Set up HeyGen API access
export HEYGEN_API_KEY="your-api-key"

# Install HTTP client
npm install axios

Copy
import axios from 'axios';

const heygen = axios.create({
  baseURL: 'https://api.heygen.com/v2',
  headers: { 'X-Api-Key': process.env.HEYGEN_API_KEY }
});

// Generate a video with a talking avatar
const { data } = await heygen.post('/video/generate', {
  video_inputs: [{
    character: {
      type: 'avatar',
      avatar_id: 'Angela-inTshirt-20220820',
      avatar_style: 'normal'
    },
    voice: {
      type: 'text',
      input_text: 'Welcome to our product demo!',
      voice_id: 'en-US-JennyNeural'
    }
  }],
  dimension: { width: 1920, height: 1080 }
});

const videoId = data.data.video_id;

Core Concepts

Video Generation Pipeline

Step	API Endpoint	Purpose
1. List Avatars	GET /avatars	Get available avatar IDs
2. List Voices	GET /voices	Get available voice IDs
3. Generate	POST /video/generate	Create video with avatar and script
4. Poll Status	GET /video/{id}	Check generation progress
5. Download	GET /video/{id}	Get completed video URL

Template-Based Generation

Copy
// Create videos from templates for batch personalization
const { data } = await heygen.post('/template/generate', {
  template_id: 'template-abc123',
  variables: {
    customer_name: { value: 'Sarah' },
    product_name: { value: 'CloudSync Pro' },
    discount_code: { value: 'WELCOME20' }
  }
});

Status Polling

Copy
async function waitForVideo(videoId: string): Promise<string> {
  while (true) {
    const { data } = await heygen.get(`/video/${videoId}`);
    if (data.data.status === 'completed') return data.data.video_url;
    if (data.data.status === 'failed') throw new Error('Video generation failed');
    await new Promise(r => setTimeout(r, 10000)); // Poll every 10 seconds
  }
}

Configuration

Parameter	Type	Default	Description
avatar_id	string	—	Avatar identifier from the avatars list
voice_id	string	—	Voice identifier from the voices list
dimension.width	number	1920	Video width in pixels
dimension.height	number	1080	Video height in pixels
avatar_style	string	"normal"	Avatar style: normal, circle, closeup
speed	number	1.0	Speech speed multiplier (0.5-2.0)
background	object	—	Custom background color or image URL
test	boolean	false	Generate watermarked test video (free)

Best Practices

1. Use templates for batch personalization — instead of building each video from scratch, create a template with variable placeholders and generate personalized versions by swapping variable values.

2. Poll status with exponential backoff — video generation takes 1-5 minutes; start polling at 10 seconds, increase to 30 seconds after 2 minutes to reduce API calls.

3. Use test mode during development — set test: true to generate watermarked preview videos for free; switch to production mode only for final outputs.

4. Cache avatar and voice lists — the avatar and voice catalogs change infrequently; cache these responses for 24 hours to avoid unnecessary API calls.

5. Handle generation failures gracefully — video generation can fail due to content moderation, invalid inputs, or service issues; always check the status and implement retry logic with a maximum attempt count.

Common Issues

Video generation takes too long — Longer scripts and higher resolutions increase generation time. For faster iteration, use 720p resolution and shorter scripts during development. Full HD is only needed for final production renders.

Avatar lip sync doesn't match audio — This usually happens with unusual words, abbreviations, or non-English text in English voices. Use phonetic spelling for proper nouns and test with short clips before generating full videos.

API rate limits hit during batch generation — The API has per-minute rate limits. Implement a queue with controlled concurrency (2-3 parallel requests) and add delays between batches to stay within limits.