@memberjunction/ai-heygen NPM

@memberjunction/ai-heygen

A MemberJunction provider package that wraps HeyGen's video generation API, enabling AI-powered avatar video creation within the MemberJunction AI framework. This package implements the BaseVideoGenerator abstract class to provide standardized video generation capabilities.

Overview

The HeyGen provider enables you to:

Generate videos with AI-powered digital avatars
Retrieve and manage available avatar options
Customize video output with backgrounds, dimensions, and positioning
Integrate seamlessly with MemberJunction's AI architecture

Features

Avatar Video Generation: Create videos with AI-powered digital avatars speaking custom audio
Avatar Management: Retrieve and browse available avatar options with preview assets
Custom Backgrounds: Set custom background images for professional video outputs
Audio Integration: Sync avatar speech with pre-generated audio assets
Video Customization: Control output dimensions, avatar scaling, and positioning
Standardized Interface: Implements MemberJunction's BaseVideoGenerator abstract class for consistent API usage
Type-Safe Implementation: Full TypeScript support with proper typing throughout

Installation

npm install @memberjunction/ai-heygen

Requirements

Node.js 16 or higher
TypeScript 5.4.5 or higher
A valid HeyGen API key (obtain from HeyGen Dashboard)
MemberJunction Core dependencies:
- @memberjunction/ai (same version)
- @memberjunction/global (same version)

Configuration

Before using the HeyGen provider, ensure you have:

A valid HeyGen API key from your HeyGen account
Pre-uploaded audio and image assets in your HeyGen account (these will provide you with asset IDs)
Selected an avatar ID from the available options

Usage

Basic Setup

import { HeyGenVideoGenerator } from '@memberjunction/ai-heygen';

// Initialize with your API key
const heyGen = new HeyGenVideoGenerator('your-heygen-api-key');

Retrieve Available Avatars

Before creating videos, explore the available avatars:

const avatars = await heyGen.GetAvatars();

// Display available avatars
avatars.forEach(avatar => {
  console.log(`Avatar: ${avatar.name} (ID: ${avatar.id})`);
  console.log(`Gender: ${avatar.gender}`);
  console.log(`Preview Image: ${avatar.previewImageUrl}`);
  console.log(`Preview Video: ${avatar.previewVideoUrl}`);
  console.log('---');
});

// Find a specific avatar by name
const femaleAvatar = avatars.find(a => a.gender === 'female' && a.name.includes('Professional'));

Create an Avatar Video

Generate a video with an avatar speaking your content:

import { AvatarVideoParams, VideoResult } from '@memberjunction/ai';

// Configure video parameters
const videoParams: AvatarVideoParams = {
  avatarId: 'avatar-id-from-getavatars',     // Use an ID from GetAvatars()
  audioAssetId: 'your-audio-asset-id',       // Pre-uploaded audio asset ID from HeyGen
  imageAssetId: 'your-background-image-id',  // Pre-uploaded background image ID
  outputWidth: 1280,                         // Video width in pixels
  outputHeight: 720,                         // Video height in pixels
  scale: 1.0,                               // Avatar scale (1.0 = 100%)
  avatarStyle: 'normal',                    // Avatar presentation style
  offsetX: 0,                               // Horizontal position offset
  offsetY: 0                                // Vertical position offset
};

// Generate the video
const result: VideoResult = await heyGen.CreateAvatarVideo(videoParams);

if (result.success) {
  console.log('Video generation successful!');
  console.log('Video ID:', result.videoId);
  // The video ID can be used to check status or download via HeyGen's API
} else {
  console.error('Error generating video:', result.errorMessage);
}

Complete Example

Here's a complete example that demonstrates the full workflow:

import { HeyGenVideoGenerator } from '@memberjunction/ai-heygen';
import { AvatarVideoParams, VideoResult } from '@memberjunction/ai';

async function createProfessionalVideo() {
  try {
    // Initialize the HeyGen client
    const heyGen = new HeyGenVideoGenerator(process.env.HEYGEN_API_KEY);
    
    // Get available avatars
    const avatars = await heyGen.GetAvatars();
    console.log(`Found ${avatars.length} available avatars`);
    
    // Select the first professional avatar
    const professionalAvatar = avatars.find(a => 
      a.name.toLowerCase().includes('professional')
    ) || avatars[0];
    
    console.log(`Using avatar: ${professionalAvatar.name}`);
    
    // Create video with the selected avatar
    const videoParams: AvatarVideoParams = {
      avatarId: professionalAvatar.id,
      audioAssetId: 'audio_asset_123',  // Your pre-uploaded audio
      imageAssetId: 'image_asset_456',  // Your pre-uploaded background
      outputWidth: 1920,
      outputHeight: 1080,
      scale: 1.2,                      // Slightly larger avatar
      avatarStyle: 'normal',
      offsetX: 100,                    // Move avatar 100px to the right
      offsetY: 0
    };
    
    const result: VideoResult = await heyGen.CreateAvatarVideo(videoParams);
    
    if (result.success) {
      console.log(`Video created successfully! ID: ${result.videoId}`);
      // Use the video ID to check status or download the video
    } else {
      console.error(`Failed to create video: ${result.errorMessage}`);
    }
    
  } catch (error) {
    console.error('Unexpected error:', error);
  }
}

// Run the example
createProfessionalVideo();

Check Supported Methods

Check which methods are supported by the current implementation:

const supportedMethods = await heyGen.GetSupportedMethods();
console.log('Supported methods:', supportedMethods);

API Reference

HeyGenVideoGenerator Class

The main class that extends BaseVideoGenerator to provide HeyGen-specific video generation functionality. This class is registered with MemberJunction's global class registry using the @RegisterClass decorator.

Constructor

constructor(apiKey: string)

Parameters:

apiKey - Your HeyGen API key for authentication

Methods

`CreateAvatarVideo(params: AvatarVideoParams): Promise<VideoResult>`

Generates a video with an AI avatar speaking the provided audio content.

Parameters:

params - Configuration object for the avatar video (see AvatarVideoParams below)

Returns:

Promise<VideoResult> - Result object containing success status and video ID or error message

`GetAvatars(): Promise<AvatarInfo[]>`

Retrieves a list of all available avatars from HeyGen.

Returns:

Promise<AvatarInfo[]> - Array of avatar information objects

`GetSupportedMethods(): Promise<string[]>`

Returns a list of method names supported by this implementation.

Returns:

Promise<string[]> - Array of supported method names

`CreateVideoTranslation(params: any): Promise<VideoResult>`

Note: This method is not yet implemented and will throw an error if called.

Type Definitions

AvatarVideoParams

Configuration parameters for creating an avatar video:

interface AvatarVideoParams {
  avatarId: string;        // ID of the avatar (from GetAvatars)
  audioAssetId: string;    // ID of pre-uploaded audio asset
  imageAssetId: string;    // ID of pre-uploaded background image
  outputWidth: number;     // Video width in pixels
  outputHeight: number;    // Video height in pixels
  scale: number;          // Avatar scale factor (1.0 = 100%)
  avatarStyle: string;    // Avatar style (e.g., 'normal')
  offsetX: number;        // Horizontal position offset in pixels
  offsetY: number;        // Vertical position offset in pixels
}

VideoResult

Result object returned from video generation operations:

interface VideoResult {
  success: boolean;        // Whether the operation succeeded
  videoId?: string;       // ID of the generated video (if successful)
  errorMessage?: string;  // Error details (if unsuccessful)
}

AvatarInfo

Information about an available avatar:

interface AvatarInfo {
  id: string;              // Unique avatar identifier
  name: string;            // Display name of the avatar
  gender: string;          // Avatar's gender
  previewImageUrl: string; // URL to avatar preview image
  previewVideoUrl: string; // URL to avatar preview video
}

Integration Details

HeyGen API Endpoints

This package integrates with the following HeyGen API v2 endpoints:

Video Generation: https://api.heygen.com/v2/video/generate
- Used by CreateAvatarVideo() method
- Requires pre-uploaded audio and image assets
Avatar Management: https://api.heygen.com/v2/avatars
- Used by GetAvatars() method
- Returns available avatars with preview assets

Authentication

All API requests use the X-Api-Key header for authentication. The API key is passed during class instantiation and stored securely within the instance.

Error Handling

The package implements comprehensive error handling:

Network errors are caught and logged
API errors are returned in the VideoResult.errorMessage field
All methods return predictable result objects rather than throwing exceptions

Dependencies

Runtime Dependencies

@memberjunction/ai - Core AI framework interfaces and base classes
@memberjunction/global - Global utilities and class registration
axios - HTTP client for API communication (Note: This needs to be added to package.json)

Development Dependencies

typescript ^5.4.5 - TypeScript compiler
ts-node-dev ^2.0.0 - Development server with auto-reload

Build and Development

Building the Package

# From the package directory
npm run build

# From the repository root
npm run build -- --filter="@memberjunction/ai-heygen"

Development Mode

# Run in watch mode with auto-reload
npm run start

Package Structure

packages/AI/Providers/HeyGen/
├── src/
│   └── index.ts          # Main implementation file
├── dist/                 # Compiled JavaScript output
├── package.json          # Package configuration
├── tsconfig.json         # TypeScript configuration
├── typedoc.json          # Documentation generation config
└── readme.md            # This file

Integration with MemberJunction

This package follows MemberJunction's architectural patterns:

Class Registration: Uses @RegisterClass decorator for automatic registration with the global class registry
Abstract Implementation: Extends BaseVideoGenerator from @memberjunction/ai
Consistent API: Follows MemberJunction's standardized patterns for AI providers
Type Safety: Full TypeScript implementation with proper typing

Using with MemberJunction's AI System

The HeyGen provider can be dynamically loaded through MemberJunction's AI provider system:

import { AIEngine } from '@memberjunction/ai';

// The HeyGen provider will be automatically available if installed
const aiEngine = new AIEngine();
const videoGenerator = await aiEngine.GetVideoGenerator('HeyGenVideoGenerator', apiKey);