HeyGen integration

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.

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 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 takes no parameters of its own — see All Operations. List All Voices takes no parameters of its own — see All Operations. List Avatar Groups takes no parameters of its 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 (upload from binary data attached to the input item), url (upload from 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.
				Options: young, male, asian, front
— 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.

Photo Avatar: Create Avatar Group

Parameter	Type	Required	Default	Description
Avatar Group Name	string	Yes	—	Name for the new avatar group.

Photo Avatar: Add Looks

Parameter	Type	Required	Default	Description
Avatar ID	string	Yes	—	The avatar ID to operate on.
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.

Photo Avatar: Get Training Status

Parameter	Type	Required	Default	Description
Generation ID	string	Yes	—	The generation or training ID to check status for.

Photo Avatar: Generate Avatar Looks

Parameter	Type	Required	Default	Description
Avatar ID	string	Yes	—	The avatar ID to operate on.
Generate Looks Options	collection	No	{}	Options for auto-generating avatar looks.
				Options: casual
— 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.

Photo Avatar: Add Motion

Parameter	Type	Required	Default	Description
Avatar ID	string	Yes	—	The avatar ID to operate on.
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.
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.
Upscale Options	collection	No	{}	Options for upscaling an avatar.
				Options: 2x
— 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. 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. Leaving this blank fails the item with “Invalid JSON in videoGenerateBody”; the field is not marked required in the panel, but the operation cannot run without it. See HeyGen API docs for the full schema.

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.

Example Configuration

Upload a document from a URL:

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

Upload a document from binary data:

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

Generate a photo avatar:

{
  "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:

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

Create an avatar group:

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

Add looks to an avatar:

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

Train an avatar group:

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

Get training status:

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

Auto-generate avatar looks:

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

Get avatar details:

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

Add motion to an avatar:

{
  "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:

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

Upscale an avatar:

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

List all avatars:

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

List all voices:

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

List avatar groups:

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

Generate a video:

{
  "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:

{
  "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:

{
  "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:

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

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

{
  "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:

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

Step 5 — poll training status:

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

Avatar enhancement (motion + sound)

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

Add motion:

{
  "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:

{
  "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:

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

Document upload then video generation

Step 1 — upload a script or document:

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

Step 2 — generate a video using the avatar:

{
  "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:

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

List all avatars:

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

List all available voices:

{
  "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.