> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# HeyGen Integration for AI Agents & Workflows

> AI video generation platform for creating talking avatar videos

{/* Self-hosted logo — build-time vendored from modulex.json / Iconify (see scripts/lib/logo.js). */}

<img src="https://mintcdn.com/modulexaillc/zKB2qsP6Q61VNLfB/logos/heygen.svg?fit=max&auto=format&n=zKB2qsP6Q61VNLfB&q=85&s=b4207c20e22aa050e4289e0c257319e7" alt="HeyGen logo" width="72" height="72" data-path="logos/heygen.svg" />

## Overview

Add **HeyGen** to any ModuleX agent or workflow. AI video generation platform for creating talking avatar videos via the HeyGen REST API (`api.heygen.com`).

<Info>
  **Categories**: AI & Machine Learning · AI · Video · Content Creation · **Auth**: API Key · **Actions**: 5
</Info>

## Authentication

### API Key Authentication

Authenticate using your HeyGen API key

<Steps>
  <Step title="Step 1">
    Go to [https://app.heygen.com](https://app.heygen.com) and sign in
  </Step>

  <Step title="Step 2">
    Navigate to Settings > API
  </Step>

  <Step title="Step 3">
    Copy your API key
  </Step>

  <Step title="Step 4">
    Paste the API key below
  </Step>
</Steps>

#### Required Credentials

| Field          | Description                                      | Required | Format                             |
| -------------- | ------------------------------------------------ | -------- | ---------------------------------- |
| HeyGen API Key | Your HeyGen API key from app.heygen.com/settings | Yes      | `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |

## Available Actions

<AccordionGroup>
  <Accordion title="create_talking_photo — Creates a talking photo video from a provided image, text, and voice">
    ### Parameters

    <ResponseField name="talking_photo_id" type="string" required>
      Identifier of the talking photo to use
    </ResponseField>

    <ResponseField name="text" type="string" required>
      The text that the character will speak
    </ResponseField>

    <ResponseField name="voice_id" type="string" required>
      Identifier of the voice to use
    </ResponseField>

    <ResponseField name="title" type="string">
      Title of the video
    </ResponseField>

    <ResponseField name="test" type="boolean">
      Set to true to use test mode (no credits charged, watermark added)
    </ResponseField>

    <ResponseField name="caption" type="boolean">
      Set to true to create video with captions
    </ResponseField>

    <ResponseField name="scale" type="string">
      Talking photo scale, value between 0 and 2.0 (default 1.0)
    </ResponseField>

    <ResponseField name="talking_photo_style" type="string">
      Talking photo crop style: square, circle
    </ResponseField>

    <ResponseField name="talking_style" type="string">
      Talking photo talking style: stable, expressive
    </ResponseField>

    <ResponseField name="expression" type="string">
      Talking photo expression style: default, happy
    </ResponseField>

    <ResponseField name="super_resolution" type="boolean">
      Whether to enhance the photo image
    </ResponseField>

    <ResponseField name="matting" type="boolean">
      Whether to apply matting to the photo
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "video_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Video Id"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Status"
        }
      },
      "required": [
        "success"
      ],
      "title": "CreateTalkingPhotoOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="create_video_from_template — Generates a video from a selected template with optional variable overrides">
    ### Parameters

    <ResponseField name="template_id" type="string" required>
      Identifier of the template to use
    </ResponseField>

    <ResponseField name="title" type="string">
      Title of the video
    </ResponseField>

    <ResponseField name="test" type="boolean">
      Set to true to use test mode (no credits charged, watermark added)
    </ResponseField>

    <ResponseField name="caption" type="boolean">
      Set to true to create video with captions
    </ResponseField>

    <ResponseField name="variables" type="object">
      Template variable overrides as a JSON object where keys are variable names and values are objects with variable properties
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "video_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Video Id"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Status"
        }
      },
      "required": [
        "success"
      ],
      "title": "CreateVideoFromTemplateOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_custom_events_options — Retrieves available options for webhook custom events">
    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "events": {
          "items": {
            "type": "string"
          },
          "title": "Events",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListCustomEventsOptionsOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_voice_id_options — Retrieves available voice options for video generation">
    ### Response

    ```json theme={null}
    {
      "$defs": {
        "VoiceInfo": {
          "additionalProperties": false,
          "description": "A voice entry returned by the list voices endpoint.",
          "properties": {
            "voice_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Voice Id"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Name"
            }
          },
          "title": "VoiceInfo",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "voices": {
          "items": {
            "$ref": "#/$defs/VoiceInfo"
          },
          "title": "Voices",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListVoiceIdOptionsOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="retrieve_video_link — Fetches the status and download link for a specific HeyGen video">
    ### Parameters

    <ResponseField name="video_id" type="string" required>
      Identifier of the HeyGen video to retrieve
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "video_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Video Id"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Status"
        },
        "video_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Video Url"
        },
        "thumbnail_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Thumbnail Url"
        },
        "duration": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Duration"
        },
        "caption_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Caption Url"
        }
      },
      "required": [
        "success"
      ],
      "title": "RetrieveVideoLinkOutput",
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Limits & Quotas

* Rate limits depend on your HeyGen plan tier (Starter, Business, Enterprise).
* Video generation consumes credits; use `test=true` to avoid credit charges during development.
* No documented per-minute rate limit; excessive requests may trigger throttling.
* Error model: non-2xx responses and timeouts are caught and returned as `success=False` + `error` rather than raising.

## Related integrations

<CardGroup cols={3}>
  <Card title="Browser Use" href="/integrations/tools/browser-use" />

  <Card title="Amazon Alexa" href="/integrations/tools/amazon-alexa" />

  <Card title="ElevenLabs" href="/integrations/tools/elevenlabs" />
</CardGroup>

## Links

* [HeyGen](https://www.heygen.com)