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​