# Video Agent

> Generate AI avatar videos with HeyGen's Video Agent API. One-shot prompt to video generation.

- Skill: `kbarbel640-del/video-agent` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add kbarbel640-del/video-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kbarbel640-del/video-agent/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kbarbel640-del (https://skillmd.com/u/kbarbel640-del)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/kbarbel640-del/video-agent

---


# 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