Heygen Automation

---
name: HeyGen Automation
description: "Automate AI video generation, avatar browsing, template-based video creation, and video status tracking through HeyGen's platform via Composio"
requires:
  mcp:
    - rube
executor: HYBRID
skill_id: integrations.composio.heygen-automation
status: ADOPTED
security: {level: standard, pii: false, approval_required: false}
extends: integrations.composio.meta
toolkit: heygen-automation
# Phase3: This stub routes to the meta-skill. See skills/integrations/composio/SKILL.md for full protocol.
anchors:
  - automation
  - integration
  - api
  - workflow
tier: 3
input_schema:
  - name: code_or_task
    type: string
    description: "Code snippet, script, or task description to process"
    required: true
output_schema:
  - name: result
    type: object
    description: "Result from the automated action"
  - name: status
    type: string
    description: "Execution status: success | partial | failure"
what_if_fails: >
  FALLBACK: If Heygen cannot complete, provide partial results with
  explicit gaps noted. Never block workflow silently.
  ESCALATE: If core capability is unavailable, suggest nearest alternative skill.
  RULE: Always explain what failed and what manual steps can substitute.
---

# 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](https://composio.dev/toolkits/heygen)

---

## Setup

1. Connect your HeyGen account through the Composio MCP server at `https://rube.app/mcp`
2. The agent will prompt you with an authentication link if no active connection exists
3. 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](https://composio.dev)*

## Why This Skill Exists
Stub for the `heygen-automation` toolkit in the Composio integration ecosystem.
Extends `integrations.composio.meta` — see the meta-skill for full protocol.

## When to Use
Use when automating `heygen-automation` tasks via Rube MCP (Composio).
For generic Composio queries, use `integrations.composio.meta` directly.

## What If Fails
See `skills/integrations/composio/SKILL.md` (meta-skill) for full fallback protocol.
RULE: Never block workflow — always suggest manual alternative if automation fails.