HeyGen Video Agent

Generate videos with a single prompt using HeyGen's Video Agent API. The Video Agent takes your prompt and automatically creates an AI avatar video.

Reference Files

references/prompt-optimizer.md - Write effective prompts for professional results

Setup

Get your API key from https://app.heygen.com/settings?nav=API
Set the environment variable:
```
export HEYGEN_API_KEY="your-api-key"
```

Generate a Video

python3 {baseDir}/scripts/generate.py --prompt "Create a 30-second explainer video about AI agents"

Options:

--prompt: The video generation prompt (required)
--poll: Wait for video completion and show URL
--out-dir: Output directory for downloaded video (default: ./heygen-output)
--download: Download the video when complete (requires --poll)

Examples:

# Quick submit (returns video_id immediately)
python3 {baseDir}/scripts/generate.py --prompt "Introduce our new product feature"

# Wait for completion and get video URL
python3 {baseDir}/scripts/generate.py --prompt "Create a welcome message for new users" --poll

# Wait and download the video
python3 {baseDir}/scripts/generate.py --prompt "Explain how to use the dashboard" --poll --download

Check Video Status

python3 {baseDir}/scripts/status.py --video-id <video_id>

Options:

--video-id: The video ID from generate.py (required)
--poll: Keep checking until complete
--download: Download video when complete
--out-dir: Output directory for downloaded video

API Reference

Generate Video:

Endpoint: POST https://api.heygen.com/v1/video_agent/generate
Auth: x-api-key: <your-api-key>
Body: { "prompt": "your video prompt" }
Response: { "data": { "video_id": "..." } }

Check Status:

Endpoint: GET https://api.heygen.com/v1/video_status.get?video_id=<id>
Auth: x-api-key: <your-api-key>
Response includes: status (pending, processing, completed, failed), video_url (when complete)

Notes

Video generation typically takes 1-5 minutes depending on length
The Video Agent automatically selects appropriate avatars and voices based on your prompt
For more control over avatar/voice selection, see HeyGen's standard video API