Quick Start

This guide covers our TypeScript SDK. For the official HeyGen API documentation, visit their Quick Start Guide.

Prerequisites

Create a HeyGen account
Get your API key from the API settings page

Note: While on the Free Trial, your videos will be watermarked.

⚠️

Never expose your API key in client-side code or commit it to version control. For browser-based applications, always use a server-side endpoint to proxy your API requests. See our Streaming SDK documentation for an example of secure token handling.

Installation

pnpm add @teamduality/heygen-typescript-sdk

Basic Usage

import { HeygenSDK } from '@teamduality/heygen-typescript-sdk'
 
const sdk = new HeygenSDK('your_api_key')
 
// Create a video
const video = await sdk.videos.create({
  background: '#ffffff',
  clips: [
    {
      avatar_id: 'your_avatar_id',
      input_text: 'Hello world!',
      voice_id: 'your_voice_id'
    }
  ]
})
 
// Check video status
const status = await sdk.videos.getStatus(video.video_id)
 
// When status.status === 'completed', download the video
if (status.status === 'completed') {
  const videoUrl = status.video_url
  // Video URL is valid for 7 days
}

Creating Videos

Our SDK supports all video creation features:

// Create with background color
const videoWithBg = await sdk.videos.create({
  background: '#008000',
  clips: [
    /* ... */
  ]
})
 
// Create with transparent background (WebM)
const transparentVideo = await sdk.videos.create({
  background: 'transparent',
  clips: [
    /* ... */
  ],
  format: 'webm'
})
 
// Create with custom dimensions
const customVideo = await sdk.videos.create({
  background: '#ffffff',
  clips: [
    /* ... */
  ],
  dimension: {
    width: 1280,
    height: 720
  }
})

Error Handling

The SDK provides typed error handling:

try {
  const video = await sdk.videos.create({
    /* ... */
  })
} catch (error) {
  if (error.code === 40119) {
    console.error('Video is too long. Please upgrade your plan.')
  }
}

Next Steps

Check out the Core SDK Reference for detailed API documentation
Learn about Interactive Avatars

For more examples and detailed API documentation, visit HeyGen’s official docs.

Overview Core SDK