HeyGen
Purpose
Generate talking-head and avatar videos with HeyGen's self-serve API: one-shot prompt-to-video via the Video Agent, or multi-scene avatar videos assembled from stock or custom avatars and voices. The best self-serve avatar-video path in the catalog; translation/dubbing endpoints also exist. Use when Michael wants presenter-style or explainer videos.
Tooling
All commands go through bin/heygen.py:
bashbin/heygen.py auth # verify the API key (free) bin/heygen.py avatars --limit 25 # list stock avatars (custom avatar IDs come from the app) bin/heygen.py voices --limit 25 # list voices bin/heygen.py video-agent --prompt "Explain compounding in 30 seconds" # one-shot prompt-to-video bin/heygen.py video-generate --json '{"avatar_id": "...", "voice_id": "...", "script": "..."}' # multi-scene bin/heygen.py video-status --video-id <video_id> # poll until completed
video-agent takes a plain prompt. video-generate needs the full multi-scene spec as --json (avatar_id, voice_id, script or scenes, per HeyGen's docs). Both print a video_id; poll video-status until completed, then download the MP4.
Auth
- Provider id:
heygen(credential is collected ascustom.heygen) - Collection: API key via the secure credential flow (
credentials.request_api_access); created at app.heygen.com/api - Allowed hosts:
api.heygen.com - Status check:
bin/heygen.py auth(must return"ok": true). The key is sent verbatim as theX-Api-Keyheader.
Operating Rules
- COST WARNING: API usage is separately metered and billed from plan credits. Do not assume the plan quota applies; generations here spend API balance.
- Confirm with Michael before every
video-agentandvideo-generatecall. Renders take 2-5 minutes; poll with backoff. - Custom avatars cost $99 one-time with a 24-48h turnaround. Order them in the HeyGen app; the API cannot create them. Confirm before ordering one.
- Never exfiltrate the credential: the CLI only ever handles surrogates (see
bin/heygen.py). Do not print, log, or transmit the key value.
Files
- SKILL.md
- bin/heygen.py
Maturity
🧪 Draft: written from HeyGen's public API docs via the research dossier; not yet live-tested end-to-end.


