Create videos from a text prompt using HeyGen's Video Agent. Use when: (1) Creating a video from a description or idea, (2) Generating explainer, demo, or marketing videos from a prompt, (3) Making a video without specifying exact avatars, voices, or scenes, (4) Quick video prototyping or drafts, (5) One-shot prompt-to-video generation, (6) User says "make me a video" or "create a video about X".
Generate complete videos from a text prompt. Describe what you want and the AI handles script writing, avatar selection, visuals, voiceover, pacing, and captions automatically.
All requests require the X-Api-Key header. Set the HEYGEN_API_KEY environment variable.
curl -X POST "https://api.heygen.com/v1/video_agent/generate" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "Create a 60-second product demo video."}'
If HeyGen MCP tools are available (mcp__heygen__*), prefer them over direct HTTP API calls — they handle authentication and request formatting automatically.
| Task | MCP Tool | Fallback (Direct API) |
|---|---|---|
| Generate video from prompt | mcp__heygen__generate_video_agent |
POST /v1/video_agent/generate |
| Check video status / get URL | mcp__heygen__get_video | GET /v2/videos/{video_id} |
| List account videos | mcp__heygen__list_videos | GET /v2/videos |
| Delete a video | mcp__heygen__delete_video | DELETE /v2/videos/{video_id} |
If no HeyGen MCP tools are available, use direct HTTP API calls as documented in the reference files.
Always use prompt-optimizer.md guidelines to structure prompts with scenes, timing, and visual styles.
With MCP tools:
mcp__heygen__generate_video_agent with prompt and config (duration_sec, orientation, avatar_id)mcp__heygen__get_video with the returned video_id to poll status and get the download URLWithout MCP tools (direct API):
POST /v1/video_agent/generate — see video-agent.mdGET /v2/videos/<id> — see video-status.md| Task | MCP Tool | Read |
|---|---|---|
| Generate video from prompt | mcp__heygen__generate_video_agent | prompt-optimizer.md → visual-styles.md → video-agent.md |
| Check video status / get download URL | mcp__heygen__get_video | video-status.md |
| Upload reference files for prompt | — | assets.md |
This skill is for prompt-based video creation — describe what you want, and the AI handles the rest.
If the user needs precise control over specific avatars, exact scripts, per-scene voice/background configuration, or multi-scene composition, use the avatar-video skill instead.
| User Says | This Skill | Avatar Video Skill |
|---|---|---|
| "Make me a video about X" | ✓ | |
| "Create a product demo" | ✓ | |
| "I want avatar Y to say exactly Z" | ✓ | |
| "Multi-scene video with different backgrounds" | ✓ | |
| "Transparent WebM for compositing" | ✓ |
config.duration_sec for predictable lengthconfig.avatar_id for consistency across videos