heygen-avatar

name	heygen-avatar
description	HeyGen avatar-video provider reference for Synthex. Documents the real env-driven HeyGen v2 client and its ElevenLabs voice pairing. NEVER call createAvatarVideo without a consent record. NEVER hard-code HEYGEN_API_KEY (Vercel env only). NEVER silently mock a live call — no key hard-blocks unless allowMockFallback is explicitly set. ALWAYS prefer an ElevenLabs audio_url (lip-sync) over HeyGen text TTS. Activate on ANY request to generate, poll, or debug HeyGen avatar videos, or wire avatar+voice generation.
metadata	{"author":"synthex","version":"1.0","type":"reference-skill","epic":"SYN-1005","triggers":["heygen","avatar video","avatar lip-sync","generate avatar","video_status","elevenlabs voice clone"],"requires":[]}
context	fork

HeyGen Avatar Provider

Client

lib/marketing-agency/heygen/client.ts → createHeyGenClient(config?) returns:

• createAvatarVideo(request) → { id, provider:'heygen', status }
• getVideoStatus(videoId) → { status: queued|processing|completed|failed, videoUrl? }
• waitForCompletion(videoId, { timeoutMs, intervalMs, sleep? }) → final job (bounded poll)

config: { apiKey?, baseUrl?, fetchImpl?, allowMockFallback? }. apiKey defaults to process.env.HEYGEN_API_KEY. is injectable for tests.