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

| Operation | Purpose | | --- | --- | | Create Avatar Video | Start an avatar video and return its ID | | Get Video Status | Return normalized status and output URLs | | Create Template Video | Generate from a HeyGen template | | Create Video Agent Video | Generate a video from a natural-language prompt | | List Avatar Looks | List avatars and optionally refresh the cache | | List Voices | List voices and optionally refresh the cache | | Wait for Completion | Poll an existing video until completion or failure | | Generate and Wait | Create an avatar video, poll it, and return the final URL |

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