# Video Agent

> Generate AI avatar videos with HeyGen's Video Agent API. One-shot prompt to video generation. Use when this capability is needed.

- Skill: `tomevault-io/video-agent-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/video-agent-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/video-agent-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/video-agent-2

---


# 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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/demerzels-lab) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->