<!-- BusyBot node reference — https://busybot.net/tools/heygen/ -->

> Node: HeyGen (`heygen`) · Action (binary) · v1
> Category: Utility · Credentials: HeyGen API (`heygenApi`)
> Updated: 2026-08-16

# HeyGen

> Generate videos and manage photo avatars with HeyGen

## Overview

The HeyGen tool integrates with the HeyGen AI video generation platform. It supports three resources: Document (upload), Photo Avatar (generate photos, manage avatar groups, add looks/motion/sound effects, train, upscale, list avatars/voices/groups), and Video (generate via the v2 API). It uses dual base URLs — api.heygen.com for most operations and upload.heygen.com for document uploads. Document upload supports both binary file upload and URL-based upload.

**Category:** Utility  
**Tool Name:** `heygen`  
**Version:** 1

**Appearance:** Icon: `lucide-Video` | Color: `#5046E5`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **HeyGen API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/heygen-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Document | `document` |
| Photo Avatar | `photoAvatar` |
| Video | `video` |

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Upload | `upload` | Upload a document to HeyGen |
| Generate Photo | `generatePhoto` | Generate a photo avatar from an image |
| Check Generation Status | `checkGenerationStatus` | Check status of a photo generation |
| Create Avatar Group | `createAvatarGroup` | Create a new avatar group |
| Add Looks | `addLooks` | Add looks to an avatar |
| Train Avatar Group | `trainAvatarGroup` | Train an avatar group |
| Get Training Status | `getTrainingStatus` | Check training status of an avatar group |
| Generate Avatar Looks | `generateAvatarLooks` | Auto-generate looks for an avatar |
| Get Avatar Details | `getAvatarDetails` | Get details of a specific avatar |
| Add Motion | `addMotion` | Add motion to an avatar |
| Add Sound Effect | `addSoundEffect` | Add sound effect to an avatar |
| Upscale Avatar | `upscaleAvatar` | Upscale an avatar image |
| List All Avatars | `listAllAvatars` | List all avatars (v2 API) |
| List All Voices | `listAllVoices` | List all available voices (v2 API) |
| List Avatar Groups | `listAvatarGroups` | List all avatar groups |
| Generate | `generate` | Generate a video using HeyGen v2 API |

`Upload` is the only Document operation, `Generate` is the only Video operation, and the remaining fourteen operations belong to Photo Avatar.

### Parameters

`List All Avatars`, `List All Voices` and `List Avatar Groups` take no parameters of their own — see All Operations.

#### Document: Upload

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Upload Source | `options` | No | `binary` | Whether to upload from binary data or a URL. |
| | | | | Options: `binary` (a file attached to the input item), `url` (a public URL) |
| Binary Property | `string` | No | `data` | Name of the binary property containing the document to upload. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. _(shown when Upload Source is `binary`)_ |
| Document URL | `string` | No | — | Public URL of the document to upload. Used when Upload Source is set to URL. _(shown when Upload Source is `url`)_ |

#### Photo Avatar: Generate Photo

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Generate Photo Options | `collection` | No | `{}` | Options for photo avatar generation. |
| — Name | `string` | No | — | Name for the generated photo avatar. |
| — Image URL | `string` | No | — | Source image URL for the photo avatar. |
| — Age | `options` | No | — | Age category for the avatar. |
| | | | | Options: `young`, `middle`, `old` |
| — Gender | `options` | No | — | Gender for the avatar. |
| | | | | Options: `male`, `female` |
| — Ethnicity | `options` | No | — | Ethnicity for the avatar. |
| | | | | Options: `asian`, `african`, `caucasian`, `hispanic` |
| — Orientation | `options` | No | — | Face orientation for the avatar. |
| | | | | Options: `front`, `left`, `right` |

#### Photo Avatar: Check Generation Status

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Generation ID | `string` | Yes | — | The generation or training ID to check status for. Supports expressions. |

#### Photo Avatar: Create Avatar Group

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Avatar Group Name | `string` | Yes | — | Name for the new avatar group. Supports expressions. |

#### Photo Avatar: Add Looks

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Avatar ID | `string` | Yes | — | The avatar ID to operate on. Supports expressions. |
| Add Looks Options | `collection` | No | `{}` | Options for adding looks to an avatar. |
| — Look Name | `string` | No | — | Name for the new look. |
| — Image URL | `string` | Yes | — | URL of the image for the look. |

#### Photo Avatar: Train Avatar Group

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Avatar ID | `string` | Yes | — | The avatar ID to operate on. Supports expressions. |

#### Photo Avatar: Get Training Status

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Generation ID | `string` | Yes | — | The generation or training ID to check status for. Supports expressions. |

#### Photo Avatar: Generate Avatar Looks

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Avatar ID | `string` | Yes | — | The avatar ID to operate on. Supports expressions. |
| Generate Looks Options | `collection` | No | `{}` | Options for auto-generating avatar looks. |
| — Number of Looks | `number` | No | `3` | Number of looks to generate. |
| — Style | `options` | No | `casual` | Style for the generated looks. |
| | | | | Options: `casual`, `business`, `formal` |

#### Photo Avatar: Get Avatar Details

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Avatar ID | `string` | Yes | — | The avatar ID to operate on. Supports expressions. |

#### Photo Avatar: Add Motion

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Avatar ID | `string` | Yes | — | The avatar ID to operate on. Supports expressions. |
| Add Motion Options | `collection` | No | `{}` | Options for adding motion to an avatar. |
| — Motion Name | `string` | No | — | Name for the motion. |
| — Video URL | `string` | Yes | — | URL of the video for the motion. |

#### Photo Avatar: Add Sound Effect

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Avatar ID | `string` | Yes | — | The avatar ID to operate on. Supports expressions. |
| Add Sound Effect Options | `collection` | No | `{}` | Options for adding a sound effect to an avatar. |
| — Sound Name | `string` | No | — | Name for the sound effect. |
| — Audio URL | `string` | Yes | — | URL of the audio file for the sound effect. |

#### Photo Avatar: Upscale Avatar

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Avatar ID | `string` | Yes | — | The avatar ID to operate on. Supports expressions. |
| Upscale Options | `collection` | No | `{}` | Options for upscaling an avatar. |
| — Scale | `options` | No | `2x` | Upscale factor. |
| | | | | Options: `2x`, `4x` |

#### Video: Generate

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Video Generate Body (JSON) | `string` | No\* | — | **Mandatory for Video → Generate** (\*not flagged required in the panel, but the operation cannot run without it — a blank value fails the item with `Invalid JSON in videoGenerateBody`). Full JSON body for the HeyGen v2 video generation API. The v2 API has a complex nested structure — pass the complete request body as a JSON string. See HeyGen API docs for the full schema. Supports expressions. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `3` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. The HeyGen API response for the chosen operation is merged into the item JSON at the top level, so the response fields sit alongside the fields the item already carried; binary data on the input item is forwarded unchanged. The field names are whatever the HeyGen endpoint returns for that operation — a list operation returns its collection, an upload returns the stored document's details, and a status check returns the current state of the job.

Three operations start asynchronous work rather than finishing it:

| Operation | What comes back | How to follow up |
|-----------|-----------------|------------------|
| `generatePhoto` | The submitted photo-generation job | Feed its identifier to `checkGenerationStatus` through the Generation ID parameter |
| `trainAvatarGroup` | The submitted training job | Feed its identifier to `getTrainingStatus` through the Generation ID parameter |
| `generate` (Video) | The submitted video job | Track the job with HeyGen — this node has no video-status operation of its own |

Reference the merged response fields downstream by expression, using the names HeyGen returned for the operation you ran.

## Usage Examples

- Generate a video with a HeyGen avatar
- Create a photo avatar from an image URL
- Upload a document to HeyGen
- List all available HeyGen avatars
- Train an avatar group
- Add motion or sound effects to an avatar

## Example Configuration

Upload a document from a URL:

```json
{
  "resource": "document",
  "operation": "upload",
  "uploadSource": "url",
  "documentUrl": "https://example.com/myfile.pdf"
}
```

Upload a document from binary data:

```json
{
  "resource": "document",
  "operation": "upload",
  "uploadSource": "binary",
  "binaryPropertyName": "data"
}
```

Generate a photo avatar:

```json
{
  "resource": "photoAvatar",
  "operation": "generatePhoto",
  "generatePhotoOptions": {
    "name": "Professional Avatar",
    "image_url": "https://example.com/source-photo.jpg",
    "age": "young",
    "gender": "male",
    "ethnicity": "asian",
    "orientation": "front"
  }
}
```

Check generation status:

```json
{
  "resource": "photoAvatar",
  "operation": "checkGenerationStatus",
  "generationId": "gen_abc123xyz"
}
```

Create an avatar group:

```json
{
  "resource": "photoAvatar",
  "operation": "createAvatarGroup",
  "avatarGroupName": "Marketing Team Avatars"
}
```

Add looks to an avatar:

```json
{
  "resource": "photoAvatar",
  "operation": "addLooks",
  "avatarId": "avatar_abc123",
  "addLooksOptions": {
    "look_name": "Business Casual",
    "image_url": "https://example.com/look-business.jpg"
  }
}
```

Train an avatar group:

```json
{
  "resource": "photoAvatar",
  "operation": "trainAvatarGroup",
  "avatarId": "avatar_abc123"
}
```

Get training status:

```json
{
  "resource": "photoAvatar",
  "operation": "getTrainingStatus",
  "generationId": "train_def456xyz"
}
```

Auto-generate avatar looks:

```json
{
  "resource": "photoAvatar",
  "operation": "generateAvatarLooks",
  "avatarId": "avatar_abc123",
  "generateLooksOptions": {
    "num_looks": 3,
    "style": "casual"
  }
}
```

Get avatar details:

```json
{
  "resource": "photoAvatar",
  "operation": "getAvatarDetails",
  "avatarId": "avatar_abc123"
}
```

Add motion to an avatar:

```json
{
  "resource": "photoAvatar",
  "operation": "addMotion",
  "avatarId": "avatar_abc123",
  "addMotionOptions": {
    "motion_name": "Greeting Wave",
    "video_url": "https://example.com/motion-wave.mp4"
  }
}
```

Add a sound effect to an avatar:

```json
{
  "resource": "photoAvatar",
  "operation": "addSoundEffect",
  "avatarId": "avatar_abc123",
  "addSoundEffectOptions": {
    "sound_name": "Office Ambience",
    "audio_url": "https://example.com/office-sound.mp3"
  }
}
```

Upscale an avatar:

```json
{
  "resource": "photoAvatar",
  "operation": "upscaleAvatar",
  "avatarId": "avatar_abc123",
  "upscaleOptions": {
    "scale": "2x"
  }
}
```

List all avatars:

```json
{
  "resource": "photoAvatar",
  "operation": "listAllAvatars"
}
```

List all voices:

```json
{
  "resource": "photoAvatar",
  "operation": "listAllVoices"
}
```

List avatar groups:

```json
{
  "resource": "photoAvatar",
  "operation": "listAvatarGroups"
}
```

Generate a video:

```json
{
  "resource": "video",
  "operation": "generate",
  "videoGenerateBody": "{\"video_inputs\":[{\"character\":{\"type\":\"avatar\",\"avatar_id\":\"avatar_abc123\",\"avatar_style\":\"normal\"},\"voice\":{\"type\":\"text\",\"input_text\":\"Hello, welcome to our product demo.\",\"voice_id\":\"voice_xyz789\"}}],\"dimension\":{\"width\":1280,\"height\":720}}"
}
```

High-concurrency batch avatar listing:

```json
{
  "resource": "photoAvatar",
  "operation": "listAllAvatars",
  "maxConcurrency": 10
}
```

### Full photo avatar creation pipeline

A typical avatar creation workflow involves multiple sequential operations.

Step 1 — generate the photo:

```json
{
  "resource": "photoAvatar",
  "operation": "generatePhoto",
  "generatePhotoOptions": {
    "name": "Sales Rep Avatar",
    "image_url": "https://cdn.example.com/headshot.jpg",
    "age": "young",
    "gender": "male",
    "ethnicity": "asian",
    "orientation": "front"
  }
}
```

Step 2 — poll generation status, using the generation ID from the step 1 output:

```json
{
  "resource": "photoAvatar",
  "operation": "checkGenerationStatus",
  "generationId": "{{$json.generationId}}"
}
```

Step 3 — add looks, using the avatar ID from the step 1 output:

```json
{
  "resource": "photoAvatar",
  "operation": "addLooks",
  "avatarId": "{{$json.avatarId}}",
  "addLooksOptions": {
    "look_name": "Formal Suit",
    "image_url": "https://cdn.example.com/formal-look.jpg"
  }
}
```

Step 4 — train the avatar group:

```json
{
  "resource": "photoAvatar",
  "operation": "trainAvatarGroup",
  "avatarId": "{{$json.avatarId}}"
}
```

Step 5 — poll training status:

```json
{
  "resource": "photoAvatar",
  "operation": "getTrainingStatus",
  "generationId": "{{$json.trainingId}}"
}
```

### Avatar enhancement (motion + sound)

After an avatar is trained, enhance it with motion and audio.

Add motion:

```json
{
  "resource": "photoAvatar",
  "operation": "addMotion",
  "avatarId": "avatar_abc123",
  "addMotionOptions": {
    "motion_name": "Presenter Gestures",
    "video_url": "https://cdn.example.com/presenter-motion.mp4"
  }
}
```

Add a sound effect:

```json
{
  "resource": "photoAvatar",
  "operation": "addSoundEffect",
  "avatarId": "avatar_abc123",
  "addSoundEffectOptions": {
    "sound_name": "Subtle Background",
    "audio_url": "https://cdn.example.com/bg-audio.mp3"
  }
}
```

Upscale for production quality:

```json
{
  "resource": "photoAvatar",
  "operation": "upscaleAvatar",
  "avatarId": "avatar_abc123",
  "upscaleOptions": {
    "scale": "2x"
  }
}
```

### Document upload then video generation

Step 1 — upload a script or document:

```json
{
  "resource": "document",
  "operation": "upload",
  "uploadSource": "url",
  "documentUrl": "https://cdn.example.com/video-script.pdf"
}
```

Step 2 — generate a video using the avatar:

```json
{
  "resource": "video",
  "operation": "generate",
  "videoGenerateBody": "{\"video_inputs\":[{\"character\":{\"type\":\"avatar\",\"avatar_id\":\"avatar_abc123\",\"avatar_style\":\"normal\"},\"voice\":{\"type\":\"text\",\"input_text\":\"Thank you for reviewing our proposal.\",\"voice_id\":\"voice_xyz789\"}}],\"dimension\":{\"width\":1920,\"height\":1080}}"
}
```

### Discover available resources

Before building an avatar pipeline, discover what's available.

List all avatar groups:

```json
{
  "resource": "photoAvatar",
  "operation": "listAvatarGroups"
}
```

List all avatars:

```json
{
  "resource": "photoAvatar",
  "operation": "listAllAvatars"
}
```

List all available voices:

```json
{
  "resource": "photoAvatar",
  "operation": "listAllVoices"
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

The HeyGen tool generates AI videos, manages photo avatars, and uploads documents by integrating with the HeyGen API across dual endpoints for standard operations and file ingestion. Use it when a workflow requires programmatic video creation via the v2 API, photo avatar customization with looks, motion, and sound effects, or document ingestion through binary or URL-based uploads. It outputs a main channel containing video generation results, avatar group data, or upload confirmations, and an error channel for failed API responses.