n8n-nodes-heygen-pro

n8n-nodes-heygen-pro is a community node for creating and monitoring HeyGen
videos in n8n. It provides dynamic avatar and voice selection, request
validation, transient-error retries, polling, and readable API errors.

Features

• Avatar picker backed by GET /v3/avatars/looks
• Voice picker backed by GET /v3/voices
• Avatar name, type, and preview links in the picker
• Five-minute in-memory caching for avatar and voice lists
• Explicit list operations that can bypass and refresh the cache
• Text or public audio URL input
• Color, image URL, and video URL backgrounds
• Safe retries with idempotency keys for v3 video creation
• Polling with configurable interval and timeout
• Human-friendly authentication, balance, avatar, voice, and video errors
• No OAuth requirement

Installation

n8n Community Nodes

1. Open Settings > Community Nodes in n8n.
2. Select Install.
3. Enter n8n-nodes-heygen-pro.
4. Confirm the installation.

Self-Hosted npm Installation

From the n8n installation directory:

npm install n8n-nodes-heygen-pro

Restart n8n after installation.

Credentials

Create a HeyGen API credential and enter the API key from the HeyGen
dashboard. The credential sends:

X-Api-Key: <configured credential>

The credential test calls GET https://api.heygen.com/v3/users/me. OAuth is
not used.

Operations

Usage Examples

Create an Avatar Video

1. Select Create Avatar Video.
2. Optionally choose an avatar type.
3. Select the avatar by name and preview. The node stores the look ID
   internally and sends it as avatar_id.
4. Choose Text and select a voice, or choose Audio URL.
5. Configure the background.

Example output:

{
  "video_id": "v_8f40bfc",
  "status": "processing"
}

Get Video Status from a Previous Node

Set Video ID to an expression:

{{ $json.data.video_id }}

Missing or empty expression results are reported as Video ID is required.
instead of a parameter lookup error.

Example output:

{
  "video_id": "v_8f40bfc",
  "status": "completed",
  "video_url": "https://files.heygen.ai/video/v_8f40bfc.mp4",
  "thumbnail_url": "https://files.heygen.ai/thumb/v_8f40bfc.jpg",
  "duration": 24.6
}

Generate and Wait

Select Generate and Wait, configure the same fields as an avatar video,
then set:

• Poll Interval: 10
• Max Wait Time: 900

The node returns only after HeyGen reports completed, or fails with HeyGen's
rendering reason.

Create a Template Video

Set Template ID from workflow data:

{{ $json.template_id }}

Example Template Variables:

{
  "script": {
    "name": "script",
    "type": "text",
    "properties": {
      "content": "Welcome to the product update."
    }
  },
  "headline": {
    "name": "headline",
    "type": "text",
    "properties": {
      "content": "June Product Update"
    }
  }
}

HeyGen currently exposes Template generation through
POST /v2/template/{template_id}/generate because a v3 replacement is not yet
available.

Create a Video Agent Video

Enter a prompt of up to 10,000 characters. Avatar and voice are optional; when
selected, their IDs remain hidden behind dynamic resource pickers.

Example output:

{
  "session_id": "session_42d12",
  "video_id": "v_712ab",
  "status": "processing"
}

Background Compatibility

HeyGen v3 currently supports color and image backgrounds. Video URL
backgrounds are routed through HeyGen's supported v2 Studio endpoint because
v3 has no video-background equivalent. All other avatar-video requests use
POST /v3/videos.

Retry Behavior

The node retries transient 408, 409, 429, and 5xx responses with
bounded exponential backoff. It respects Retry-After when HeyGen provides
the header. Mutation retries are enabled only for requests protected by an
Idempotency-Key.

Build

Requirements:

• Node.js 20.19 or newer
• npm

npm install
npm run lint
npm test
npm run build

Compiled files are written to dist/.

Local Development

npm run dev

The project uses the official @n8n/node-cli development workflow.

Publish

1. Confirm npm run lint, npm test, and npm run build pass.
2. Create an npm trusted publisher for the repository's
   .github/workflows/publish.yml workflow.
3. Bump the package version.
4. Push a tag such as v1.0.1.

The included GitHub Actions workflow publishes with npm provenance, as
required for n8n Creator Portal verification from May 1, 2026.

For an interactive manual release:

npm run release

Security

API keys are stored through n8n credentials and injected only into the
X-Api-Key request header. The package has no runtime dependencies and does
not log credential values.

License

MIT