tomevault-io 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.