Overview - HeyGen Documentation

Add HeyGen as a connector in your AI agent and start generating videos in a few clicks — no API key and nothing to install. Usage draws on your existing HeyGen plan’s credits.

Add HeyGen to Your Agent

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.

Paste the HeyGen MCP endpoint

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

https://mcp.heygen.com/mcp/v1/

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.

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.

Menu names vary slightly by agent. For click-by-click instructions, see the per-product setup guides below.

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 message to an existing session. Use to answer agent questions, add context, or request edits to a generated video. Only valid for sessions created in chat mode.
`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 all videos in the account. Filterable by folder_id or title substring.
`create_video`	Creates a video from a HeyGen avatar or an arbitrary image. Supports scripts or pre-recorded audio for lip-sync. Supports the Avatar III, Avatar IV, and Avatar V engines; set the ‘engine’ field to select. Avatar IV is used by default when ‘engine’ is omitted.
`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.

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.
`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 the template by replacing its variables (text, image, video, audio, character, voice). Use scene_ids to select, reorder, or repeat scenes — scenes must already exist in the template; the API cannot create new ones. Returns the created video object; poll `GET /v3/videos/{video_id}` or use webhooks for completion. Idempotent replays return the original creation-time snapshot (status and URLs as of the first request), not the video’s current state.

Voices

Tool Name	Description
`list_voices`	Returns a paginated list of voices, filterable by type, engine, language, and gender. Use engine=starfish for voices compatible with the TTS endpoint.
`design_voice`	Returns up to 3 voices matching a natural language description (e.g. ‘warm, confident female narrator’). Use the seed parameter to get different batches of results.
`clone_voice`	Creates a voice clone from an audio file. Returns a voice_clone_id that can be polled via `GET /v3/voices/{voice_clone_id}` until the status is ‘complete’. The resulting voice can be used with `POST /v3/voices/speech` and `POST /v3/videos`.
`create_speech`	Synthesize speech audio from text using a specified voice. The voice must support the starfish engine — use GET /v3/voices?engine=starfish to find compatible voices. Supports plain text and SSML. Speed range: 0.5–2.0x. Returns a URL to the generated audio file along with duration and optional word-level timestamps.
`get_voice`	Returns details for a specific voice, including clone workflow status when available. Use this to poll a voice clone until its status is ‘complete’.
`delete_voice`	Deletes a voice clone owned by the caller. The voice must not be in use by any template. The voice is removed from your voice list and no longer counts against your voice clone limit. Deleting an already-deleted or unknown voice returns 404 `voice\_not\_found` (not 200) — a delete-then-list flow should treat that 404 as success, not an error.

Audio

Tool Name	Description
`search_audio_sounds`	Semantically search the audio catalog by natural-language description — set type=music (the default) for background music (e.g. ‘upbeat lofi hip-hop’, ‘tense cinematic riser’) or type=sound_effects for SFX (e.g. ‘whoosh for a scene change’, ‘cash register cha-ching’). Returns tracks ranked by similarity, each with a pre-signed download URL, plus cursor-based pagination.

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.
`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 per the requested output_settings. Poll `GET /v3/ai-clipping/{id}` or subscribe to 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`	Submit up to 100 video-translation payloads (identical in shape to POST /v3/video-translations) as a single batch. A payload targeting multiple output_languages expands to one batch item per language, and each item is created and processed independently so one bad source does not fail the rest. Returns 202 with a batch_id; poll `GET /v3/video-translations/batches/{batch_id}` for progress. Pass an Idempotency-Key header to make retries safe — the same key returns the same batch.
`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 in one request, addressed by comma-separated video_translation_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids. Each returned entry carries its id as video_id (the status read model is shared with the videos batch API).

Lipsync Batches

Tool Name	Description
`create_lipsync_batch`	Submit up to 100 lipsync payloads as a single batch. Each payload becomes one batch item, created and processed independently so one bad source does not fail the rest. Returns 202 with a batch_id; poll `GET /v3/lipsyncs/batches/{batch_id}` for progress. Pass an Idempotency-Key header to make retries safe — the same key returns the same batch.
`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 in one request, addressed by comma-separated lipsync_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids. Each returned entry carries its id as video_id (the status read model is shared with the videos batch API).

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`	Finalize every uploaded file in a batch. Call after all upload PUTs return 200. Each file is validated and ingested asynchronously and independently, so one bad file does not fail the rest. Returns 202 with the batch_id; poll `GET /v3/assets/batches/{batch_id}` for per-item progress. Idempotent: a repeated call re-drives the same batch.
`create_asset_upload_batch`	Request up to 100 presigned direct-to-S3 upload URLs in a single call. Returns a batch_id and one upload slot per file (asset_id + presigned upload_url + required headers). PUT each file’s bytes to its upload_url, then call POST /v3/assets/complete/batches to finalize the whole batch. This is synchronous — no bytes flow through the API. Pass an Idempotency-Key header to make retries safe (the same key returns the same batch).
`bulk_asset_statuses`	Returns statuses for up to 100 assets in one request, addressed by comma-separated asset_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids. Each returned entry carries its id as video_id (the status read model is shared with the videos batch API).

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_avatar`	Creates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous.
`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.
`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 and its backing resource. Supported types: photo_avatar, digital_twin, and kit-based looks. Studio avatar (model_index) types cannot be deleted via the API. Warning: deleting the last look in a group also deletes the parent group. Subsequent requests referencing that group id (e.g. `POST /v3/avatars` with `avatar\_group\_id`) return 404 not found.
`get_avatar_group`	Returns details for a specific avatar group including name, gender, preview URLs, looks count, and training status.
`delete_avatar_group`	Permanently deletes an avatar group and all its associated looks. Cannot delete public or community groups.
`create_avatar_consent`	Initiates the consent flow for an avatar group and returns a URL for the user to complete approval in their browser. Required before a private avatar can be used for video generation.

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.

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`	List brand glossaries (custom term mappings, a.k.a. brand voices) in the authenticated user’s workspace. A brand glossary enforces custom term translations during video translation — for example, translating “Reformer” as Pilates equipment instead of as a political activist. Brand glossaries are created and edited in the HeyGen web app under Brand Kit; this endpoint is read-only for discovery. Pass the returned `brand\_glossary\_id` (or the legacy alias `brand\_voice\_id`) on POST /v2/video_translate to apply the glossary during translation.
`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.

Supported Products

HeyGen Remote MCP works with any MCP-compatible agent, including:

Claude (Web, Desktop, and Code)
Cursor (available in the Cursor marketplace)
Gemini CLI
Lovable
Manus
Superhuman
OpenAI
and more

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

Connect Your Own Agent

You can integrate HeyGen Remote MCP into any custom agent or application that supports the Model Context Protocol. Just point it to the endpoint:

https://mcp.heygen.com/mcp/v1/

For security, HeyGen Remote MCP uses domain whitelisting. If your agent runs on a domain that isn’t already whitelisted, you’ll need to request access before it can connect. To request domain whitelisting, submit your domain via the Integration Intake form.

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, works everywhere

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. 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.

​Add HeyGen to Your Agent

​What You Can Do

​Video Agent

​Videos

​Templates

​Voices

​Audio

​Video Translate

​AI Clipping

​Batches

​Video Translation Batches

​Lipsync Batches

​Asset Batches

​User

​Avatars

​Assets

​Lipsync

​Brand

​Supported Products

​Connect Your Own Agent

​Remote MCP

​FAQ

Add HeyGen to Your Agent

What You Can Do

Video Agent

Videos

Templates

Voices

Audio

Video Translate

AI Clipping

Batches

Video Translation Batches

Lipsync Batches

Asset Batches

User

Avatars

Assets

Lipsync

Brand

Supported Products

Connect Your Own Agent

Remote MCP

FAQ