ranbot-ai HeyGen Automation
Automate AI-powered video creation workflows -- browse avatars and templates, generate personalized videos from templates, track processing status, and retrieve shareable URLs -- all orchestrated through the Composio MCP integration.
Toolkit docs: composio.dev/toolkits/heygen
Setup
- Connect your HeyGen account through the Composio MCP server at
https://rube.app/mcp - The agent will prompt you with an authentication link if no active connection exists
- Once connected, all
HEYGEN_*tools become available for execution
Core Workflows
1. Browse Available Templates
Retrieve pre-designed avatar templates from the HeyGen library for video creation.
Tool: HEYGEN_V2_TEMPLATES
No parameters required -- returns template IDs, names, preview images, and customization options.
Use this to discover templates before generating videos. Each template has a unique ID needed for generation.
2. Inspect Template Details & Variables
Retrieve the full structure of a template including all variables, scene mappings, and customization options.
Tool: HEYGEN_RETRIEVE_TEMPLATE_DETAILS_V3
| Parameter | Type | Required | Description |
|---|---|---|---|
template_id |
string | Yes | Template ID from HEYGEN_V2_TEMPLATES or the HeyGen dashboard |
This is a required prerequisite before generating videos -- it tells you exactly which variables must be populated.
3. Browse Available Avatars
List all realistic avatars available for video creation, useful for mapping characters to scenes.
Tool: HEYGEN_V2_AVATARS
No parameters required -- returns avatar identifiers, names, and preview images.
The list may be paginated; additional calls might be needed for the full set.
4. Generate Video from Template
Create a customized video by populating a template with your variables and content.
Tool: HEYGEN_V2_TEMPLATE_GENERATE
Provide a video title and all template variables discovered via HEYGEN_RETRIEVE_TEMPLATE_DETAILS_V3. Every required variable must be supplied with exact names and types.
5. Check Video Processing Status
Poll the processing status and retrieve metadata for a video being generated.
Tool: HEYGEN_RETRIEVE_VIDEO_STATUS_DETAILS
| Parameter | Type | Required | Description |
|---|---|---|---|
video_id |
string | Yes | Video ID returned from the generation API |
Returned URLs expire after 7 days but can be regenerated by calling this endpoint again.
6. Get Shareable Video URL
Generate a public, shareable link that allows anyone to view the video without authentication.
Tool: HEYGEN_RETRIEVE_SHARABLE_VIDEO_URL
Provide the video_id to receive a public URL for distribution.
Known Pitfalls
| Pitfall | Details |
|---|---|
| All template variables required | HEYGEN_V2_TEMPLATE_GENERATE demands every variable from HEYGEN_RETRIEVE_TEMPLATE_DETAILS_V3 with exact names and types -- missing or misnamed fields break scenes or fail generation |
| Always inspect templates first | Never skip HEYGEN_RETRIEVE_TEMPLATE_DETAILS_V3 before generation -- multi-scene templates have complex variable structures |
| Video URLs expire | URLs from HEYGEN_RETRIEVE_VIDEO_STATUS_DETAILS expire after 7 days; regenerate by calling the endpoint again |
| Paginated avatar lists | HEYGEN_V2_AVATARS may return paginated results -- additional calls may be needed for the full library |
| Processing time varies | Video generation is asynchronous; poll HEYGEN_RETRIEVE_VIDEO_STATUS_DETAILS until status is complete before using output URLs |
Quick Reference
| Tool Slug | Purpose |
|---|---|
HEYGEN_V2_TEMPLATES |
List available video templates |
HEYGEN_RETRIEVE_TEMPLATE_DETAILS_V3 |
Get template variables and scene structure |
HEYGEN_V2_AVATARS |
Browse available AI avatars |
HEYGEN_V2_TEMPLATE_GENERATE |
Generate video from a template |
HEYGEN_RETRIEVE_VIDEO_STATUS_DETAILS |
Check video processing status and get URLs |
HEYGEN_RETRIEVE_SHARABLE_VIDEO_URL |
Get a public shareable video link |
Powered by Composio