home / skills / davila7 / claude-code-templates / heygen-best-practices

heygen-best-practices skill

safe

/cli-tool/components/skills/development/heygen-best-practices

This skill helps you master HeyGen API usage for avatar video creation by outlining best practices and practical guidance.

npx playbooks add skill davila7/claude-code-templates --skill heygen-best-practices

Review the files below or copy the command above to add this skill to your agents.

Files (20)

SKILL.md

2.5 KB

---
name: heygen-best-practices
description: Best practices for HeyGen - AI avatar video creation API
metadata:
  tags: heygen, video, avatar, ai, api, text-to-video
---

## When to use

Use this skill whenever you are dealing with HeyGen API code to obtain domain-specific knowledge for creating AI avatar videos, managing avatars, handling video generation workflows, and integrating with HeyGen's services.

## How to use

Read individual rule files for detailed explanations and code examples:

### Foundation
- [rules/authentication.md](rules/authentication.md) - API key setup, X-Api-Key header, and authentication patterns
- [rules/quota.md](rules/quota.md) - Credit system, usage limits, and checking remaining quota
- [rules/video-status.md](rules/video-status.md) - Polling patterns, status types, and retrieving download URLs
- [rules/assets.md](rules/assets.md) - Uploading images, videos, and audio for use in video generation

### Core Video Creation
- [rules/avatars.md](rules/avatars.md) - Listing avatars, avatar styles, and avatar_id selection
- [rules/voices.md](rules/voices.md) - Listing voices, locales, speed/pitch configuration
- [rules/scripts.md](rules/scripts.md) - Writing scripts, pauses/breaks, pacing, and structure templates
- [rules/video-generation.md](rules/video-generation.md) - POST /v2/video/generate workflow and multi-scene videos
- [rules/video-agent.md](rules/video-agent.md) - One-shot prompt video generation with Video Agent API
- [rules/dimensions.md](rules/dimensions.md) - Resolution options (720p/1080p) and aspect ratios

### Video Customization
- [rules/backgrounds.md](rules/backgrounds.md) - Solid colors, images, and video backgrounds
- [rules/text-overlays.md](rules/text-overlays.md) - Adding text with fonts and positioning
- [rules/captions.md](rules/captions.md) - Auto-generated captions and subtitle options

### Advanced Features
- [rules/templates.md](rules/templates.md) - Template listing and variable replacement
- [rules/video-translation.md](rules/video-translation.md) - Translating videos, quality/fast modes, and dubbing
- [rules/streaming-avatars.md](rules/streaming-avatars.md) - Real-time interactive avatar sessions
- [rules/photo-avatars.md](rules/photo-avatars.md) - Creating avatars from photos (talking photos)
- [rules/webhooks.md](rules/webhooks.md) - Registering webhook endpoints and event types

### Integration
- [rules/remotion-integration.md](rules/remotion-integration.md) - Using HeyGen avatar videos in Remotion compositions

Overview

This skill captures pragmatic best practices for working with the HeyGen AI avatar video creation API. It summarizes authentication, quota handling, video generation patterns, asset management, and customization options to help you build reliable, cost-effective video workflows. The guidance is focused on production-ready integration and common pitfalls to avoid.

How this skill works

The skill inspects common API workflows and operational needs: authentication via API keys, quota and credit checks, POST /v2/video/generate flows, polling for video status, and asset upload patterns. It also covers avatar and voice selection, multi-scene composition, templates, captions, and webhook-driven automation for long-running jobs.

When to use it

When building or integrating HeyGen video generation into an app or pipeline.
When you need guidance on managing API keys, quotas, and usage efficiency.
When implementing multi-scene or templated videos with assets and captions.
When automating long-running video jobs using webhooks and polling best practices.
When converting photos to avatars, streaming interactive avatars, or doing translations/dubbing.

Best practices

Store X-Api-Key securely in environment variables or secret manager; never hard-code keys.
Check quota and remaining credits before heavy batch jobs; implement graceful backoff.
Use POST /v2/video/generate for deterministic jobs and rely on webhooks for asynchronous completion.
Upload and reuse shared assets (images, audio) to avoid repeated uploads and save credits.
Design scripts with clear pacing, pauses, and short segments to reduce rework and improve TTS quality.
Use templates and variable replacement for scalable personalization and consistent styling.

Example use cases

Automated onboarding videos: generate personalized multi-scene videos using templates and user data.
Localized marketing: translate and dub existing videos with video-translation modes for quality/speed tradeoffs.
Interactive kiosks: use streaming avatars for real-time conversations and session recording.
Content pipelines: batch-generate product videos while monitoring quota and retrying failed jobs.
Talking photo experiences: convert user photos to avatars for short personalized messages.

FAQ

How should I poll for video generation status?

Poll at increasing intervals and prefer webhooks for production; fetch status only when needed and use download URLs when the job is complete.

How do I reduce API credit usage?

Reuse uploaded assets, use lower resolution when acceptable, batch similar videos, and prefer templates to avoid repeated complex renders.