Heygen Agent Skill

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:

bin/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 as custom.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 the X-Api-Key header.

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-agent and video-generate call. 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.