ChatGPT
Install the HeyGen plugin from the ChatGPT plugin directory.
Codex
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: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.
Menu names vary slightly by agent. For click-by-click instructions, see the per-product setup guides below.
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. 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 all videos in the account. Filterable by folder_id or title substring. |
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. 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 only to professional clones. Instant clones, including Turbo, accept and ignore these controls. ### 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)
- Claude (Web, Desktop, and Code)
- Codex (the HeyGen plugin in the app, the MCP server in the CLI; see Codex)
- Cursor (available in the Cursor marketplace)
- Gemini CLI
- Lovable
- Manus
- Superhuman
- and more
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: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 getInvalid redirect_uri: not registered for this client. Use the HeyGen API with an API key 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 getInvalid 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?
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.
