video-agent

name	video-agent
description	Generate AI avatar videos with HeyGen's Video Agent API. One-shot prompt to video generation.
homepage	https://docs.heygen.com/reference/generate-video-agent
metadata	{"openclaw":{"emoji":"🎬","requires":{"bins":["python3"],"env":["HEYGEN_API_KEY"]},"primaryEnv":"HEYGEN_API_KEY"}}

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

1. Get your API key from https://app.heygen.com/settings?nav=API
2. 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