HeyGen — AI Video Generation

First-Time Setup

Step 1: Get a HeyGen API Key

1. Sign in at heygen.com
2. Go to Settings → API (app.heygen.com/settings?nav=API)
3. Copy your API token (starts with sk_V2_...)

Step 2: Create the Config File

Create /data/.openclaw/shared-files/heygen/config.json:

{
  "api_key": "sk_V2_your_api_key_here",
  "default_avatar_id": "YOUR_AVATAR_ID",
  "default_orientation": "portrait",
  "default_duration_sec": 45,
  "assets": [
    { "id": "YOUR_ASSET_ID", "label": "My Brand Image", "type": "image" }
  ],
  "avatars": [
    { "id": "YOUR_AVATAR_ID", "label": "Preferred Avatar" }
  ]
}

Config fields:

Credential Resolution Order

1. --config <path> flag passed to any script
2. HEYGEN_CONFIG_PATH environment variable
3. ~/.openclaw/openclaw.json → env.HEYGEN_CONFIG_PATH
4. Default directory: /data/.openclaw/shared-files/heygen/

Step 3: Verify

node <skill-path>/scripts/heygen-setup-check.mjs

This checks the config file, API key, API access, default avatar validity, and configured asset existence.

Step 4: Discover Avatars and Assets

# List all available avatars
node <skill-path>/scripts/heygen-list-avatars.mjs

# List all uploaded assets
node <skill-path>/scripts/heygen-list-assets.mjs

Use these to find avatar IDs and asset IDs to put in the config.

How Authentication Works

HeyGen uses a simple API key in the header. No JWT, no OAuth, no token exchange.

Every request includes: X-API-KEY: sk_V2_your_key_here

Two different base URLs:

• api.heygen.com — all endpoints (video agent, avatars, assets, status)
• upload.heygen.com — asset file uploads only

Bundled Helper Scripts

All scripts live in this skill's scripts/ directory. They output JSON to stdout.

Critical Rules for Automated / Cron Execution

These rules are NON-NEGOTIABLE when this skill runs as part of an automated pipeline or cron job:

1. ONE VIDEO PER RUN. Each execution generates exactly ONE video. Never generate a second video as a "test," "fallback," or "retry" — even if the first video appears stuck. Every generation costs real credits.

2. If polling times out, STOP. Do NOT generate another video. The video is almost certainly still processing on HeyGen's servers. Log the video ID and exit. A human or the next scheduled run can check the status later.

3. Never "test the API" by generating a video. If you need to verify API connectivity, use heygen-setup-check.mjs or heygen-list-avatars.mjs — these are read-only and cost nothing.

4. Pending ≠ failed. A video in pending or processing status for 10-15 minutes is normal during peak hours. Only treat failed status as an actual failure.

5. On timeout or errors: Log the video ID, status, and error details to the designated error log. Do NOT attempt to recover by re-generating. Exit cleanly so the issue can be reviewed.

6. Use --poll --max-attempts 40 (default ~20 minutes) when polling. If it times out, the script exits with a clear poll_timeout status. Respect that exit — do not work around it.

Video Generation Workflow

This is the core workflow. Follow these steps every time:

1. Write the Prompt

The prompt is the most important part. HeyGen's Video Agent interprets your text and generates the entire video — script, avatar performance, B-roll, transitions.

Good prompts include:

• Clear structure: Hook → Problem → Solution → CTA
• Specific timing: "Create a 45-second video"
• Visual instructions: "Show the uploaded asset when mentioning the app"
• Tone guidance: "Urgent but friendly, like warning a friend"
• Asset rules: "ONLY use the uploaded asset image for app visuals. Do NOT generate fake logos."

2. Generate the Video

# Simple — just a prompt
node scripts/heygen-generate-video.mjs "Create a 30-second explainer about our product"

# Full options — TikTok style with avatar and assets
node scripts/heygen-generate-video.mjs "Hook, problem, solution, CTA about VPN security" \
  --avatar YOUR_AVATAR_ID \
  --orientation portrait \
  --duration 45 \
  --use-config-assets

# Read prompt from a file (for long, detailed prompts)
node scripts/heygen-generate-video.mjs --prompt-file /tmp/my-prompt.txt --use-config-assets

This returns a video_id. Save it.

3. Check Status

# One-time check
node scripts/heygen-video-status.mjs <videoId>

# Auto-poll until complete (checks every 30 seconds, max 40 attempts ~20 min)
node scripts/heygen-video-status.mjs <videoId> --poll

# Custom interval and max attempts
node scripts/heygen-video-status.mjs <videoId> --poll --interval 15 --max-attempts 60

If polling times out (exit code 2), the video is likely still processing. The script outputs status: "poll_timeout" with the video ID. Do NOT generate a new video. Log the ID and check it later.

4. Deliver the Video

When status is completed, the output includes:

• video_url — the rendered video (MP4)
• video_url_caption — version with burned-in captions
• thumbnail_url — poster frame image
• gif_url — animated GIF preview
• duration — actual length in seconds

IMPORTANT: URLs expire in 7 days. Either download the video or call the status endpoint again for fresh URLs.

Asset Management

Assets are images, videos, or audio files that the Video Agent can reference in generated videos. This is how you get your own branding, screenshots, and media into videos.

Upload a New Asset

# Upload an app screenshot
node scripts/heygen-upload-asset.mjs /path/to/screenshot.png

# Upload a product video
node scripts/heygen-upload-asset.mjs /path/to/demo.mp4

Supported formats: .png, .jpg, .jpeg, .mp4, .webm, .mp3

The returned asset_id can be:

• Added to your config.json under assets for reuse
• Passed directly with --assets <id> when generating videos

List Assets

# All assets
node scripts/heygen-list-assets.mjs

# Just images
node scripts/heygen-list-assets.mjs --type image

Delete an Asset

node scripts/heygen-delete-asset.mjs <assetId>

WARNING: Deletion is irreversible. Always confirm with the user first.

Analysis Workflows

1. TikTok/Reels Content Pipeline

This is what the config is designed for — rapid vertical video production:

1. Set config: default_orientation: "portrait", default_duration_sec: 45
2. Pre-upload brand assets (logos, app screenshots)
3. For each video topic, write a prompt with Hook → Problem → Solution → CTA structure
4. Generate with --use-config-assets so the agent always has brand visuals
5. Poll until done, deliver the captioned version

2. Product Demo Videos

1. Upload product screenshots/recordings as assets
2. Write a detailed prompt describing the demo flow
3. Use landscape orientation for professional format
4. Generate, poll, deliver

3. Batch Video Production

For multiple videos on different topics:

1. Write each prompt to a separate file
2. Generate each: node scripts/heygen-generate-video.mjs --prompt-file prompt1.txt --use-config-assets
3. Collect all video IDs
4. Poll each one
5. Deliver all URLs when complete

Prompt Best Practices

DO:

• Be specific about duration: "Create a 45-second video"
• Structure the flow: "1. Hook 2. Problem 3. Solution 4. CTA"
• Reference assets explicitly: "Show the uploaded asset image when discussing the app"
• Set the tone: "Professional but approachable" or "Urgent, like warning a friend"
• Specify format context: "This is for TikTok, make it fast-paced and engaging"

DON'T:

• Leave duration vague (the API may produce very long or very short videos)
• Forget to mention assets (the agent won't use them unless told to)
• Ask for things HeyGen can't do (real-time data, live footage, specific real people)

CRITICAL ASSET RULE: Always include this in prompts when assets are attached:

"ONLY use the uploaded asset images for app/product visuals. Do NOT generate, create, or fabricate any logos, app icons, or screenshots."

This prevents the AI from hallucinating brand visuals.

Video Statuses

Typical rendering time: 1-5 minutes for a 30-60 second video, but can be 10-20 minutes during peak hours. This is normal.

Security Rules

Non-negotiable:

• Never expose the API key in chat, logs, or generated files
• Never delete assets without explicit user approval
• Never generate videos with inappropriate or harmful content
• Video URLs expire in 7 days — remind the user to download promptly

API Credits & Pricing

HeyGen charges per video based on duration:

• Credits are consumed on successful video generation
• Failed videos don't consume credits
• Check your plan limits at heygen.com/api-pricing
• Always warn users before generating long videos (>60s) as they use more credits

Troubleshooting

Deliverables This Skill Can Produce

• TikTok/Reels vertical videos with talking-head avatars
• Product demo and explainer videos
• Marketing videos with branded assets
• Educational content with AI presenters
• Batch video series on multiple topics
• Social media video ads
• Videos with burned-in captions (accessibility)