> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Connect ChatGPT, Codex, Claude, Cursor, or any other MCP-compatible agent to HeyGen and generate videos in a few clicks. Sign in with OAuth; no API key or local server needed. Usage draws on your existing HeyGen plan's credits.

**Using ChatGPT or Codex?** Install the HeyGen plugin instead of adding the endpoint by hand. It connects your HeyGen account and includes HeyGen's video skills.

> [card] [ChatGPT](https://heygen-1fa696a7.mintlify.site/mcp/open-ai.md)
>
> Install the HeyGen plugin from the ChatGPT plugin directory.

> [card] [Codex](https://heygen-1fa696a7.mintlify.site/mcp/codex-cli.md)
>
> Install the plugin in the Codex app, or add the MCP server in Codex CLI.

## Add HeyGen to Your Agent

**1. Open your agent's connector settings**

In your MCP-compatible agent (Claude, Cursor, Gemini CLI, Manus, and others), open the **Connectors** or **MCP servers** settings and choose **Add custom connector**.

**2. Paste the HeyGen MCP endpoint**

Name the connector `HeyGen` and enter the remote MCP server URL:

```text theme={null}
https://mcp.heygen.com/mcp/v1/
```

**3. Authenticate with OAuth**

Click **Connect** and sign in to HeyGen to approve access. This one-time OAuth flow links the connector to your account — no API key required.

**4. Start creating**

Ask your agent to generate a video — for example, *"Make a 30-second product explainer with HeyGen."* It calls HeyGen's tools directly and bills against your existing plan.

> [!TIP]
>
> Menu names vary slightly by agent. For click-by-click instructions, see the per-product setup guides below.

> [!NOTE]
>
> **HeyGen Video duration through MCP:** `text_to_video`, `image_to_video` and `reference_to_video` accept 5–30 seconds on all plans with `turbo` or `quality` enhancement. `duration: "auto"` selects 8–15 seconds, so set an explicit duration for a 16–30 second clip. See [Duration limits](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md#duration-limits). This limit applies to HeyGen Video, not the separate Video Agent or avatar video tools.

## What You Can Do

Once connected, your AI agent has access to the following tools:

### Video Agent

| Tool Name | Description |
| - | - |
| `list_video_agent_sessions` | Returns a paginated list of video agent sessions for the authenticated user, sorted newest-first. |
| `create_video_agent` | One-shot video generation from a prompt — agent handles scripting, avatar selection, scene composition, and rendering. Supports generate (fire-and-forget) and chat (multi-turn) modes. |
| `list_video_agent_styles` | Returns curated visual style templates available for Video Agent sessions. Each style controls scene composition, pacing, and aesthetics. Supports tag filtering (e.g. 'cinematic', 'retro-tech'). |
| `get_video_agent_session` | Returns the current status, progress, video\_id, and recent chat messages for a session. |
| `send_video_agent_message` | Sends a follow-up turn to a session created in either `generate` or `chat` mode; follow-up turns preserve the session mode. Send a `message`, a scene `edit_plan` built from `GET /v3/videos/{video_id}/scenes`, or both. Items may reference different scene snapshots from this session; none identifies the output draft. `edit_version` is not a document lock, so two edits from one version may both be accepted. Returns the current working draft in `video_id`. Poll `GET /v3/videos/{video_id}` for status. For a failed video, inspect `failure_code` and `failure_message`; the session endpoint also exposes known stop reasons in `error`. |
| `get_video_agent_resource` | Returns a single session resource (image, video, draft, avatar, voice, etc.) by its resource\_id. |
| `stop_video_agent_session` | Halts an active agent run at its next checkpoint. Partial results are preserved. |
| `list_video_agent_session_videos` | Returns all videos produced within a Video Agent session, sorted newest-first. |

### Videos

| Tool Name | Description |
| - | - |
| `list_videos` | Returns a paginated list of the videos in the account that the caller can read. Filterable by folder\_id or title substring. A page can hold fewer than `limit` videos, or none, while `has_more` is true; keep paging until `has_more` is false. |
| `create_video_from_avatar` | Create a video from a HeyGen avatar (video or photo avatar). Provide an avatar\_id to use a previously created avatar. Supports all avatar types: studio\_avatar, digital\_twin, and photo\_avatar. Optionally set `engine` to select Avatar V for eligible avatars; when omitted, the server defaults to Avatar IV. |
| `create_video_from_cinematic_avatar` | Create a Cinematic Avatar video: a 4–15 second clip of one to three avatar looks driven by a natural-language prompt, plus optional reference images, videos or audio. Use it only when the user explicitly asks for Cinematic Avatar; a style word like "cinematic" is not such a request. There is no script or voice input, so exact wording is not guaranteed: describe the scene, the action and any words the person says in the prompt. A presenter speaking to camera uses create\_video\_from\_avatar; other visual productions of 30 seconds or less use text\_to\_video. If it fails with plan\_upgrade\_required, explain that Cinematic Avatar is not included in the account's current plan, offer a talking-avatar video with create\_video\_from\_avatar instead, and wait for the user's answer. Do not retry, switch tools on your own, or promote purchases or upgrades. If a public avatar is rejected, tell the user that Cinematic Avatar cannot use public studio avatars and let them choose one of their own avatars or an AI-generated public avatar; do not substitute one. |
| `create_video_from_image` | Create a talking video by animating one image of a person, with lip movements synced to a script spoken with voice\_id or to supplied audio. Use an image of the user, of a person who agreed to have their likeness animated, or of a fictional person. The image must show one clearly visible, human-like face, such as a photo or a realistic illustration; for mascots, animals, objects or other non-human characters use image\_to\_video or reference\_to\_video instead. Renders on Avatar 6 Turbo unless `engine` selects another engine; shape the motion with `motion_expressiveness` ('default' or 'less') and `motion_prompt`. Returns video\_id. Media inputs take a HeyGen asset\_id or a public https URL, never a local or sandbox path (/mnt/data/..., file://); import or upload the file first and pass its asset\_id. |
| `create_video_from_studio` | Create a single video by composing an ordered list of whole-frame scenes. The server owns layout and center-crops each scene to the global output canvas. Output settings are global (one per request); a single video\_id is returned and rendering is all-or-nothing. MP4 only in v1 — the output container is fixed and `output_format` is not exposed. |
| `get_video_voice_capabilities` | Lists the voice engines and models offered for each language and accent when creating a video. Availability of a specific voice also depends on its ownership and setup. |
| `get_video` | Returns details for a video including status, video\_url, thumbnail\_url, duration, and failure info if applicable. |
| `delete_video` | Permanently deletes a video and its associated files. This action cannot be undone. |
| `get_video_scenes` | Returns a video's scenes as it stands now, with the `edit_version` to send when editing. Each scene has a `background`, placed `elements` and a `script`. Skip element types you do not recognize. Geometry, text content, animations and background music are not described. A video whose editor document is still being prepared returns `409 resource_not_ready`; retry after it advances. |

### Templates

| Tool Name | Description |
| - | - |
| `list_templates` | Returns a paginated list of API-ready templates in the workspace. Templates are created and edited in the HeyGen web editor; only templates with variables defined are listed. |
| `create_template` | Creates a private template from one of your videos, copying its scenes, avatars, script and media. URL-to-Video and older editor videos return `template_source_unsupported`. The template starts with no variables; declare them with `PUT /v3/templates/{template_id}/variables`. |
| `get_template` | Returns template details including its variable schema (with current default values) and scenes. Variable defaults are returned in the same shape the generate request accepts, so a response can be edited and posted back. Only draft version 4 templates (the current editor format) are supported. |
| `generate_from_template` | Generates a video from a template by filling its variables. Use `scene_ids` to select, reorder or repeat the template's existing scenes. Poll `GET /v3/videos/{video_id}` or use webhooks for completion. An idempotent replay returns the original response, not the video's current state. |
| `update_template` | Renames a template. Other properties are edited in the HeyGen editor or through `PUT /v3/templates/{template_id}/variables`. Returns the template detail. |
| `delete_template` | Soft-deletes a template. It disappears from the list and can no longer be used to generate videos; videos already generated from it are unaffected. Templates managed by another HeyGen product cannot be deleted here. |
| `set_template_variables` | Replaces a template's full set of variables: any variable you omit is removed. Media, character and voice variables bind to a node by `element_id`, listed under `composition` in `GET /v3/templates/{template_id}`. A text variable with `match` turns that text into a `{{name}}` placeholder. |

### Audio

| Tool Name | Description |
| - | - |
| `search_audio_sounds` | Searches the music or sound-effects catalog by natural-language description (`type=music` by default, or `sound_effects`). Returns tracks ranked by similarity, each with a download URL, paginated by cursor. |

### Video Translate

| Tool Name | Description |
| - | - |
| `list_video_translations` | Returns a paginated list of all video translation jobs in the account. |
| `create_video_translation` | Translates a video into one or more target languages with voice cloning and lip-sync. Returns one video\_translation\_id per language. Use mode: 'speed' (default) for fast turnaround or 'precision' for higher lip-sync quality. |
| `list_video_translation_languages` | Returns all supported target language names for video translation, and the names the caller's current plan can use. Names with a region in brackets (e.g. 'Hindi (India)') are premium dialect voices. |
| `get_video_translation` | Returns details for a translation job including status, output language, video\_url, and failure info if applicable. |
| `update_video_translation` | Updates the display title of a video translation job. |
| `delete_video_translation` | Permanently deletes a video translation and its associated files. This action cannot be undone. |

### AI Clipping

| Tool Name | Description |
| - | - |
| `list_ai_clipping` | Returns a cursor-paginated list of AI clip jobs in the authenticated user's workspace, newest first. |
| `create_ai_clipping` | Submit a source video and return a job id immediately. The job runs asynchronously and produces one or more short clips. Highlights are picked from the spoken dialogue, so music-only or silent videos fail. Clips are 20 seconds or longer; output\_settings.duration\_types picks the length bands (30, 60, 180, long). Check progress with `GET /v3/ai-clipping/{job_id}`, or subscribe to the ai\_clipping.success / ai\_clipping.fail webhooks. |
| `get_ai_clipping` | Returns the full job resource including produced clips, statuses, and presigned download URLs. |
| `delete_ai_clipping` | Soft-deletes an AI clip job and its clips. |

### Batches

| Tool Name | Description |
| - | - |
| `create_video_batch` | Submit up to 100 video creation payloads in one request and return a batch id immediately. Videos are created asynchronously; poll `GET /v3/videos/batches/{batch_id}` for per-item video ids and statuses. |
| `get_video_batch` | Returns batch aggregate status and one page of items with their video ids and statuses. Item statuses are one of queued, processing, completed, or failed. |
| `bulk_video_statuses` | Returns statuses for up to 100 videos in one request, addressed by comma-separated video\_ids and/or batch\_ids query params. Statuses are one of queued, processing, completed, or failed, plus not\_found for unknown or unowned ids. |

### Video Translation Batches

| Tool Name | Description |
| - | - |
| `create_video_translation_batch` | Submits up to 100 translation payloads, each shaped like `POST /v3/video-translations`, as one batch. A payload with several `output_languages` becomes one item per language, and items run independently. Returns 202 with a `batch_id` to poll. Send an Idempotency-Key to make retries safe. |
| `get_video_translation_batch` | Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video\_id (the batch read model is shared with the videos batch API). |
| `bulk_video_translation_statuses` | Returns statuses for up to 100 video translations by `video_translation_ids` and/or `batch_ids`: `queued`, `processing`, `completed`, `failed`, or `not_found`. Each entry's id is in `video_id`. |

### Lipsync Batches

| Tool Name | Description |
| - | - |
| `create_lipsync_batch` | Submits up to 100 lipsync payloads as one batch, and items run independently. Returns 202 with a `batch_id`; poll `GET /v3/lipsyncs/batches/{batch_id}`. Send an Idempotency-Key to make retries safe. |
| `get_lipsync_batch` | Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video\_id (the batch read model is shared with the videos batch API). |
| `bulk_lipsync_statuses` | Returns statuses for up to 100 lipsyncs by `lipsync_ids` and/or `batch_ids`: `queued`, `processing`, `completed`, `failed`, or `not_found`. Each entry's id is in `video_id`. |

### Asset Batches

| Tool Name | Description |
| - | - |
| `get_asset_batch` | Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video\_id (the batch read model is shared with the videos batch API); for asset batches it holds the asset\_id. |
| `complete_asset_batch` | Finalizes every uploaded file in a batch once all PUTs return 200. Files are ingested independently. Returns 202 with the `batch_id`; poll `GET /v3/assets/batches/{batch_id}` for progress. Safe to repeat. |
| `create_asset_upload_batch` | Returns up to 100 presigned upload URLs in one call. PUT each file to its `upload_url` with the returned headers, then call `POST /v3/assets/complete/batches`. Send an Idempotency-Key to make retries safe. |
| `bulk_asset_statuses` | Returns statuses for up to 100 assets by `asset_ids` and/or `batch_ids`: `queued`, `processing`, `completed`, `failed`, or `not_found`. Each entry's id is in `video_id`. |

### User

| Tool Name | Description |
| - | - |
| `get_current_user` | Returns the authenticated user's profile, remaining credits or balance, and billing details. |

### Avatars

| Tool Name | Description |
| - | - |
| `list_avatar_groups` | Returns a paginated list of avatar groups (characters). Each group contains one or more looks. Filterable by ownership. |
| `create_digital_twin` | Create a reusable digital twin from video footage of a person speaking. Requires their consent: call create\_avatar\_consent with the returned group ID and show the consent URL. Use create\_photo\_avatar for a still photo or create\_prompt\_avatar for a text description. Media inputs take a HeyGen asset\_id or a public https URL, never a local or sandbox path (/mnt/data/..., file://); import or upload the file first and pass its asset\_id. Poll get\_avatar\_group/get\_avatar\_look until ready or failed; never repeat creation to check progress. |
| `create_photo_avatar` | Create a photo avatar from one image of a person. Use create\_digital\_twin for speaking video footage or create\_prompt\_avatar for text alone. Media inputs take a HeyGen asset\_id or a public https URL, never a local or sandbox path (/mnt/data/..., file://); import or upload the file first and pass its asset\_id. Poll get\_avatar\_group/get\_avatar\_look until ready or failed. |
| `create_prompt_avatar` | Create an AI avatar from a text description. Use create\_photo\_avatar for an existing photo or create\_digital\_twin for speaking video footage. Media inputs take a HeyGen asset\_id or a public https URL, never a local or sandbox path (/mnt/data/..., file://); import or upload the file first and pass its asset\_id. Poll get\_avatar\_group/get\_avatar\_look until ready or failed. |
| `list_look_templates` | Lists the look templates and Look Packs your workspace can apply with `POST /v3/avatars/looks`. Send an item's `id` as `template_id` and its `type` as `type`. Filter by `gender` to match your avatar. |
| `list_avatar_looks` | Returns a paginated list of avatar looks (outfits, poses, styles). Filterable by group\_id, avatar\_type, and ownership. The look id is the avatar\_id to pass when creating a video. |
| `create_look_pack_looks` | Generate a Look Pack's looks into the avatar an existing look belongs to. |
| `create_template_looks` | Restyle an existing avatar look into a single look template; the results are added to its avatar. |
| `get_avatar_look` | Returns details for a specific avatar look including supported engines, preferred orientation, preview URLs, and training status. |
| `update_avatar_look` | Updates the display name of an avatar look. Only supported for photo avatar and digital twin look types. |
| `delete_avatar_look` | Deletes an avatar look. Photo avatar, digital twin and kit-based looks can be deleted; studio avatars cannot. Deleting the last look in a group also deletes the group. |
| `get_avatar_group` | Returns details for a specific avatar group including name, gender, preview URLs, looks count, and training status. |
| `update_avatar_group` | Updates an avatar group you own. Currently sets `default_voice_id`, the voice this avatar uses by default; any voice in your workspace works, including clones. Public avatars cannot be updated. |
| `delete_avatar_group` | Permanently deletes an avatar group and all its associated looks. Cannot delete public or community groups. |
| `create_avatar_consent` | Starts the consent flow for an avatar group and returns a URL where the subject approves in their browser. Required before a private avatar can generate video. The link expires after 24 hours and accepts one submission. |

### Assets

| Tool Name | Description |
| - | - |
| `create_asset_upload` | Begin a direct-to-S3 upload. Returns an asset\_id and a presigned upload\_url; PUT the file bytes to upload\_url, then call `POST /v3/assets/{asset_id}/complete`. Unlike `POST /v3/assets` (which proxies the bytes), this never sends the file through the API. |
| `get_asset` | Returns metadata for an asset in the caller's workspace — including owner, upload timestamp, file type, and a publicly accessible URL. |
| `delete_asset` | Permanently deletes an asset. The asset must belong to the caller's workspace and not already be deleted. |
| `complete_asset_upload` | Finalize a direct-to-S3 upload into a reusable asset. Call after the upload PUT returns 200. Idempotent: repeated calls return the same finalized asset. |

### Folders

| Tool Name | Description |
| - | - |
| `create_folder` | Creates a folder at the root or inside `parent_id`. Pass its `folder_id` to `POST /v3/videos` or `POST /v3/video-translations` to file output there. Names need not be unique, so store the ids you receive. Send an Idempotency-Key to make retries safe. |
| `get_folder` | Returns one folder in your workspace, including one in the trash (`is_trash`). Use it to check that a stored `folder_id` still exists. Deleted folders and folders in other workspaces return 404. |

### Lipsync

| Tool Name | Description |
| - | - |
| `list_lipsyncs` | Returns a paginated list of all lipsync jobs in the account. |
| `create_lipsync` | Replaces the audio on an existing video and re-animates the speaker's lip movements to match the new audio. Use mode: 'speed' for fast output or 'precision' for high-quality lip-sync. |
| `get_lipsync` | Returns details for a lipsync job including status, video\_url, caption\_url, and failure info if applicable. |
| `update_lipsync` | Updates the display title of a lipsync job. |
| `delete_lipsync` | Permanently deletes a lipsync job and its associated files. This action cannot be undone. |

### Brand

| Tool Name | Description |
| - | - |
| `list_brand_glossaries` | Lists the brand glossaries in your workspace. A glossary sets how terms are pronounced in generated speech and how they are handled in translation. Pass a `brand_glossary_id` when creating a video or translation to apply it. |
| `create_brand_glossary` | Creates a brand glossary. Pass the returned `brand_glossary_id` when creating a video or translation to apply it. `name` must be unique in the workspace, ignoring case; a duplicate returns 409. Term lists are optional and can be added later with PATCH. `pronunciation_language` and `target_language` accept scope 'all' or scope 'specific' with a base language code such as 'fr'; omission means all languages and null is invalid. Duplicate term/rule-type/language combinations return 409; distinct languages for the same term are allowed. The response includes language fields for specific-language rules. Temporary access-evaluation failures return 503; retry the request. |
| `get_brand_glossary` | Returns one brand glossary with its full term list. Pronunciations affect generated audio only, not captions. Translation rules (`do_not_translate_terms`, `forced_translations`) apply only to translation features; a list is omitted from the response when it is empty. Language-specific entries include `pronunciation_language` or `target_language`; all-languages entries omit those fields. Specific-language rules override all-languages rules, and Don't Translate takes precedence over Force Translate without deleting it. Tone settings are not returned here. Temporary access-evaluation failures return 503; retry the request. |
| `update_brand_glossary` | Updates a brand glossary. A field you omit is left untouched, a list you send replaces the existing list in full across all languages, and an empty array removes every entry. Read the glossary and preserve every entry's `pronunciation_language` or `target_language` when sending an edited list; omitting a language field means all languages. A duplicate name or term/rule-type/language combination returns 409. A concurrent-edit conflict also returns 409 without saving the update; fetch the latest glossary and reapply your changes. Clients do not supply revisions. Tone settings are never modified by this endpoint. Temporary access-evaluation failures return 503; retry the request. |
| `delete_brand_glossary` | Deletes a brand glossary. This cannot be undone. Its pronunciation terms and translation rules stop applying to anything generated afterwards; videos already generated are unaffected, and requests that still reference it keep working. |
| `list_brand_kits` | Returns brand kits available in the authenticated user's workspace. Each brand kit contains colors, fonts, and logos that can be applied to Video Agent sessions. Use the returned brand\_kit\_id with `POST /v3/video-agents` to generate on-brand videos. |
| `create_brand_kit` | Creates a brand kit by importing logos, colors and fonts from a public website; by calling it you confirm you have the rights to use those assets. The kit assembles in the background: poll `GET /v3/brand-kits/{brand_kit_id}` until status is `completed`. Send an Idempotency-Key to make retries safe. |
| `get_brand_kit` | Returns one brand kit with its colors, logos and fonts and the role each plays. While status is `loading` these are provisional; poll every 2 to 5 seconds until status is `completed`. |
| `update_brand_kit` | Updates a brand kit's name or role assignments: color roles, main logo, heading and body fonts. Omitted fields are unchanged and `null` is rejected. Each role object you send replaces the existing one in full; `{}` clears a role and it stays cleared. Role edits return 409 until the kit is `completed`; shared kits return 403. |
| `delete_brand_kit` | Deletes a brand kit and its colors, logos and fonts. This cannot be undone. Videos already rendered with it are unaffected. A kit shared from another workspace cannot be deleted and returns 403. |

### Models

| Tool Name | Description |
| - | - |
| `convert_speech` | Convert a recording into an ACTIVE instant voice in your workspace. Professional voice clones are not supported. The words and timing stay the same. The response contains one WAV URL and its duration in seconds. Use an API key with voices:write or an OAuth bearer token. OAuth requires a paid plan. The limit is 30 requests per minute per workspace member. The source can contain up to 300 seconds of audio. Use a public HTTPS URL, an uploaded asset, or base64 audio. URL downloads must finish within 60 seconds. Set a client timeout of at least 160 seconds. The optional model\_id defaults to heygen-voice-sts-0. The optional seed requests best-effort repeatable generation. Set remove\_background\_noise to true to clean the source before conversion. This adds latency. Send Idempotency-Key for safe retries. The same key and body replay the completed result without another charge for 24 hours. Keys are scoped to the workspace and this endpoint. A running request returns 409 request\_in\_progress. A different body with the same key returns 409 conflict. A keyed request continues after a client disconnect and can still be charged. Without a key, a disconnect before the charge cancels the request without a charge. After a timeout, wait before retrying with the same key. The conversion can still be running. |
| `create_speech` | Generate speech from the voice identified by `voice_id`. The request stays open until speech generation finishes. The response contains an audio URL: a 44.1 kHz mono WAV by default, or the requested `output_format`. ### Voice and settings Use an `ACTIVE` HeyGen Voice clone in your workspace. `heygen-voice-1-turbo` speaks instant clones at lower latency and refuses professional clones. `seed`, `speed`, `pitch_shift`, and `pitch_variance` apply to instant and professional clones. Omit `seed` for a random seed. Send the same `seed` again to try to repeat a result; repeats are best effort. ### Turbo Free Use `heygen-voice-1-turbo-free` for instant voices without charge, including API-key and OAuth requests. This model is available to direct users and resellers for experimentation and prototyping. It has no latency, time-to-first-audio, or availability guarantee. Per-user request limits and shared free capacity both apply. Either limit can return HTTP 429 with `code=rate_limit_exceeded`. Shared capacity can be exhausted even when you are below your own request limit. A timeout or service failure can return HTTP 500. Follow `Retry-After` when present; otherwise use exponential backoff. A free request never switches to a paid model. For streaming, HTTP 429 is returned before audio starts. ### Language Set `language` to the language of `text`. If you omit it, the language is detected from `text`. Successful responses include `Content-Language`, the language the speech was generated in. ### Limits and request ID The rate limit is 30 requests per minute per workspace member. High demand can exceed the available capacity for speech generation. The service then returns HTTP 429 with `code=rate_limit_exceeded`. This response has no `Retry-After` header. Retry the request with exponential backoff. For streaming, the service returns HTTP 429 only before the response starts. Successful responses include `X-Request-Id`. Use this ID when you contact support about the request. For instant clones, completed requests automatically retain audio for request stitching when speech retention is allowed. Pass completed IDs in `previous_request_ids` or `next_request_ids` to keep continuity. Use up to three IDs per field in playback order, from the same workspace, voice, and model, within two hours. Finish reading a stream before reusing its ID. If context is unavailable, synthesis continues with its normal defaults. Stitching is unavailable when speech retention is disabled. |
| `list_voices` | Returns model-backed audio voices. With the default `type=private`, these are the voices in the caller's workspace, professional and instant, ordered newest first; `mode` tells them apart. With `type=public`, these are the voices HeyGen provides to every workspace, best first. Filter the public list with `language`, `gender` and `age`, or search it with `query`. A public page holds at most 50 voices. Use `limit` and `token` to retrieve additional pages. A token works only with the `type` and filters that returned it. |
| `design_voice` | Design a new HeyGen voice from a description of its age, tone, accent and speaking style, in one language, and save it to the workspace. Returns voice\_id; poll get\_voice until ACTIVE with a preview\_audio\_url and let the user listen before using it. An optional speaker image conditions the voice. Design has a daily limit and designed voices count toward the workspace's voice limit. Check list\_voices before retrying an unknown outcome; repeating creation can create duplicate work. |
| `clone_voice` | Create an instant voice clone from one recording of the user's own voice or of a voice they have permission to use. Saves the voice to the workspace and returns voice\_id; poll get\_voice until ACTIVE, then use it with create\_speech. HeyGen applies the workspace's voice limits; if it refuses the request, tell the user why. Check list\_voices before retrying an unknown outcome; repeating creation can create duplicate work. |
| `create_professional_voice` | Create a professional voice clone of the user's own voice or of a voice they have permission to use, by training on at least 20 minutes of recordings of that one voice (up to 10 recordings, 1.5 GB in total). Passing the voice\_id of an existing professional voice retrains it instead and replaces its current training. Training takes time: poll get\_voice until ACTIVE or FAILED. Honor retry delays or wait 30 seconds between polls. After five minutes, share the status and voice\_id so the user can check back later. A new voice needs an available professional-voice slot in the workspace. Professional voices speak only with model heygen-voice-1. Check get\_voice before retrying an unknown outcome; repeating creation can create duplicate work. |
| `get_voice` | Returns one model-backed audio voice, owned by the caller's workspace or public, and its current lifecycle state. `PENDING` covers queued and running work, `ACTIVE` is ready for inference, and `FAILED` is terminal. An instant voice is `ACTIVE` as soon as it can speak. |
| `delete_voice` | Deletes the caller-owned model-backed audio voice. The voice is removed from subsequent reads. A professional voice cannot be deleted while its status is `PENDING`: wait for training to finish and retry. Deleting an instant voice that is still being created cancels it. Repeating a successful deletion returns the same successful response. |
| `create_look_remix` | Generate one to five portraits with identity\_remix, the default and only supported mode. Provide one to five identity\_images and exactly one item in reference\_images. The output preserves the identity while following the reference image's clothing, pose, composition, and background. Returns a generation\_id to poll. The job completes when all requested images are available; partial results are not returned. |
| `get_look_remix` | Return the generation job status and ordered images with fresh download URLs once the entire job completes. |
| `image_to_video` | Animate a first-frame image with a prompt. Optionally supply endImage to guide the ending. Output follows the first image proportions; aspectRatio is ignored. Each image is a HeyGen asset\_id (preferred) or a public https URL; never a local or sandbox path such as /mnt/data/...; import or upload the file first and pass its asset\_id. Follow the input schema for duration, resolution, assets and reference limits. Auto duration is capped at 15 seconds; set an explicit duration for a requested 16-30 second clip. Returns video\_id; poll get\_model\_video until completed, failed or cancelled. Return video\_url on completion. Do not use get\_video or show\_video for these IDs. Honor retry delays or wait 30 seconds between polls; after five minutes share the latest status and video\_id for later follow-up. Each submission creates a new generation; check status before retrying an unknown outcome. Optional callbackUrl and callbackId deliver terminal events to a user-provided HTTPS endpoint. |
| `reference_to_video` | Generate a clip guided by reference images, videos or audio. Supply at least one reference in reference\_images (up to 9), reference\_videos (up to 3) or reference\_audio (up to 3); audio-only is allowed. Each reference is a HeyGen asset\_id (preferred) or a public https URL; never a local or sandbox path such as /mnt/data/...; import or upload the file first and pass its asset\_id. Follow the input schema for duration, resolution, assets and reference limits. Auto duration is capped at 15 seconds; set an explicit duration for a requested 16-30 second clip. Returns video\_id; poll get\_model\_video until completed, failed or cancelled. Return video\_url on completion. Do not use get\_video or show\_video for these IDs. Honor retry delays or wait 30 seconds between polls; after five minutes share the latest status and video\_id for later follow-up. Each submission creates a new generation; check status before retrying an unknown outcome. Optional callbackUrl and callbackId deliver terminal events to a user-provided HTTPS endpoint. |
| `text_to_video` | Generate a HeyGen Video 1 clip from a text prompt. Use it for visual productions of 30 seconds or less, or with no stated length: scenes, animation, product footage, moving hosts, presenter plus B-roll, demonstrations and short ads. Use 5 seconds for shorter requests. A presenter only speaking to camera uses create\_video\_from\_avatar. For a starting image use image\_to\_video; for references use reference\_to\_video. Follow the input schema for duration, resolution, assets and reference limits. Auto duration is capped at 15 seconds; set an explicit duration for a requested 16-30 second clip. Returns video\_id; poll get\_model\_video until completed, failed or cancelled. Return video\_url on completion. Do not use get\_video or show\_video for these IDs. Honor retry delays or wait 30 seconds between polls; after five minutes share the latest status and video\_id for later follow-up. Each submission creates a new generation; check status before retrying an unknown outcome. Optional callbackUrl and callbackId deliver terminal events to a user-provided HTTPS endpoint. |
| `get_model_video` | Returns a HeyGen Video generation: `pending`, `processing`, `completed`, `failed` or `cancelled`. Completed results include a fresh `video_url`, duration and dimensions; failed results include `failure_code` and `failure_message`. Poll again to refresh an expired URL. |

### Filler Word Removal

| Tool Name | Description |
| - | - |
| `create_filler_word_removal` | Submits a video for filler-word removal and returns a job id. The job cuts filler words and long silences and renders one cleaned video; if nothing changes, the charge is refunded. Poll `GET /v3/filler-word-removals/{id}` or use webhooks. |
| `get_filler_word_removal` | Returns the job resource: lifecycle status, progress, and — once completed — the presigned download URL of the cleaned video plus removal statistics (num\_cuts, reduction\_pct, durations). |

## Supported Products

HeyGen Remote MCP works with MCP-compatible agents, including:

* **ChatGPT** (install the [HeyGen plugin](https://heygen-1fa696a7.mintlify.site/mcp/open-ai.md))
* **Claude** (Web, Desktop, and Code)
* **Codex** (the HeyGen plugin in the app, the MCP server in the CLI; see [Codex](https://heygen-1fa696a7.mintlify.site/mcp/codex-cli.md))
* **Cursor** (available in the [Cursor marketplace](https://cursor.com/marketplace/heygen))
* **Gemini CLI**
* **Lovable**
* **Manus**
* **Superhuman**
* and more

See the dedicated setup guide for each product for detailed instructions.

## Connect Your Own Agent

Remote MCP connects an AI agent you use to your own HeyGen account. If your agent supports custom MCP servers, add this endpoint and sign in with your HeyGen account:

```text theme={null}
https://mcp.heygen.com/mcp/v1/
```

## Building an App or Platform? Use the API

Remote MCP sign-in works only from the supported agents above, for your own HeyGen account. Apps where your users connect their HeyGen accounts, MCP gateways, and automation tools such as Make and n8n can't sign in; they get `Invalid redirect_uri: not registered for this client`. Use the [HeyGen API](https://heygen-1fa696a7.mintlify.site/docs/quick-start.md) with an [API key](https://heygen-1fa696a7.mintlify.site/docs/api-key.md) instead.

## Remote MCP

| | Remote MCP |
| - | - |
| **Setup** | Add endpoint URL, authenticate via OAuth |
| **Runs on** | HeyGen's hosted infrastructure |
| **Authentication** | OAuth (no API key needed) |
| **Billing** | Web plan + premium credits |
| **Best for** | Most users — quick setup |

## FAQ

**Do I need an API key?** No. Remote MCP uses OAuth authentication tied to your HeyGen account. No API key required.

**Does this cost extra?** No. Video generation uses the credits included in your existing HeyGen plan.

**Which HeyGen plans support this?** Remote MCP is available on all HeyGen plans.

**Can I use my custom avatars and voices?** Yes. Any avatars and voices available in your HeyGen account are accessible through Remote MCP.

**Why do I get `Invalid redirect_uri: not registered for this client`?** Remote MCP sign-in is for your own AI agent. If you're connecting from an app, gateway, or automation tool, use the HeyGen API with an API key. See [Building an App or Platform?](#building-an-app-or-platform-use-the-api)

**What's the difference between this and the HeyGen API?** The HeyGen API gives you direct REST endpoints for programmatic control. Remote MCP wraps those capabilities so AI agents can use them conversationally — without you writing integration code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.