Skip to main content

HeyGen Provider Guide

Talking-head avatar videos via HeyGen's V2 API


Overview

HeyGen generates studio-quality avatar videos from a portrait + script. NeuroLink dispatches via output: { mode: 'avatar' }.

Key Facts

  • Endpoints: POST /v2/video/generate, GET /v1/video_status.get
  • Async: Submit + poll
  • Output: MP4 (default) / WebM
  • Requires: HeyGen account-bound avatar id

Quick Start

1. Get an API Key + Avatar ID

https://app.heygen.com/settings/api and pick an avatar id from your avatar library.

2. Configure

HEYGEN_API_KEY=your-key
HEYGEN_TEST_AVATAR_ID=avatar_xxx # Optional — for the avatar test suite

3. Generate

import { NeuroLink } from "@juspay/neurolink";
import { writeFileSync } from "node:fs";

const ai = new NeuroLink();
const result = await ai.generate({
provider: "vertex", // unused — driven by output.avatar
output: {
mode: "avatar",
avatar: {
provider: "heygen",
image: "avatar_xxx", // HeyGen avatar id
text: "Hello from NeuroLink", // HeyGen runs TTS internally
voice: "voice_xxx", // HeyGen voice id (optional)
},
},
});
if (result.avatar?.buffer) {
writeFileSync("./avatar.mp4", result.avatar.buffer);
}

CLI Usage

pnpm run cli generate "Hello world" \
--provider heygen \
--avatarImage avatar_xxx \
--avatarVoice voice_xxx \
--avatarOutput ./avatar.mp4

Configuration Reference

Environment VariableRequiredDescription
HEYGEN_API_KEYYesHeyGen API key
HEYGEN_TEST_AVATAR_IDNoOptional avatar id for test runs

See Also