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](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:
   ```bash
   export HEYGEN_API_KEY="your-api-key"
   ```

## Generate a Video

```bash
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:

```bash
# 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

```bash
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