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.
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 | Submits a conversational or scene-edit turn to an existing session created in either generate or chat mode. Follow-up turns preserve the session mode: generate continues automatically, while chat may pause for user input. Provide message, edit_plan, or both. Send message to answer agent questions, add context, or request conversational changes. For deterministic scene-scoped changes, first call GET /v3/videos/{video_id}/scenes, then include that video’s ID as scene_snapshot_video_id, its edit_version, and a public scene_id in each edit_plan item. Items may reference different scene snapshots from this session, including earlier videos; none identifies the output draft. The server resolves internal Video Agent resource and storyboard scene IDs; clients must not supply them. The complete edit plan is rejected before submission if any scene is invalid or the draft changed before acceptance. Edits are asynchronous: edit_version is not a document lock, so two requests created from the same version may both be accepted. A successful edit turn returns the current working draft in video_id; further edits reuse it until rendering starts, then the next edit receives a new draft ID. Poll GET /v3/videos/{video_id} directly for status. |
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. |
get_video_scenes | Returns the video’s scenes together with the video-level context needed to use them. Describes the video as it stands now, including any edits made in the editor after it was created. The scene list is never paginated. The response includes an opaque edit_version for optimistic concurrency. A video whose editor document is still being prepared returns 409 resource_not_ready; retry after the video advances. Each scene splits by the role a thing plays: background fills the frame, elements are placed within it, and script is the audio delivered over it. A whole-frame image or clip lands in background, so code that reads only elements misses it. Element types are an open set: treat an unrecognized type as an element to skip rather than an error, and expect a type value to become more specific over time. Every element a scene places appears in elements, so the count is always truthful, but only avatar, image and video are described in full; group and mask carry their children; the rest carry an id and a type and nothing more. What this does not describe. A video may contain more than this response expresses, and a video rebuilt from it will differ in these respects: element geometry (position, size, opacity); the text inside a text element; scene and element animations and scene effects; per-scene caption styling, where only whether captions are enabled is reported; background audio, which is video-level and belongs to no scene, so a rebuild loses the music; and some per-avatar values, which this version does not return. |
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. Speech generation supports Starfish, Orca, and ElevenLabs. Each voice includes its speech default and available speech engines. |
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 with a voice from the voice catalog. Supports Starfish, Orca, and ElevenLabs. The deprecated elevenlabs_v3 engine retains its existing behavior until callers and saved defaults migrate. Select an ElevenLabs model with engine: ‘elevenlabs’ and settings: {model_id: ‘eleven_v4’} (or ‘eleven_v3’); model selection does not change the engine. Omit engine to use the voice’s saved default and settings, including your saved preference, or specify an engine for this request only. Voices without a concrete saved default retain Starfish. Unsupported selections return an error without switching engines. Breaking change: requests that omit engine now use the voice’s saved default, which is Orca for most public catalog voices. Pass engine: ‘starfish’ to explicitly request Starfish, subject to voice and workspace restrictions. HTTP 400: the saved default or explicit engine is unsupported, not allowed on your plan, or incompatible with the requested locale or language; specify a compatible engine or language. HTTP 403 (ai_vendor_access_restricted): workspace vendor policy blocks ElevenLabs and all of its model variants; choose an allowed engine from List Voices or ask a workspace admin to allow the vendor. A professional HeyGen Voice clone is synthesized by POST /v3/models/audio/tts instead. 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_look_templates | Returns the curated templates this workspace may apply with POST /v3/avatars/looks, so template ids can be discovered over the API instead of read out of the HeyGen app. Each item’s id is the template_id to send and its type is the type to send with it: look_pack for a Look Pack, which generates the number of looks in looks_count, or template for a single look template, which generates two. Packs are curated per gender, so filter with gender to get the variant matching your avatar. Enterprise custom packs assigned to the workspace are listed alongside the public ones. Flattened pack members are not listed separately. |
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_avatar_looks | Generates new looks for an existing avatar. reference_look_id is an existing look used as the identity reference; the new looks are added to its avatar. type selects the method. look_pack applies a Look Pack: template_id is a public Look Pack template, or an enterprise custom pack assigned to your workspace, and the pack decides how many looks are generated; generation is always 16:9, and aspect_ratio: "9:16" center-crops the delivered frames to portrait. template restyles the look into a single look template, producing two looks in the template’s aspect ratio. Billing happens when the request is accepted: an API key is charged 1 API credit per look generated; a connected integration is charged the method’s standard price from the workspace’s credits. Free-tier MCP access cannot use this endpoint. The response lists the new looks’ ids; poll GET /v3/avatars/looks/{id} until each is completed or failed. |
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. |
update_avatar_group | Updates an avatar group. Currently supports setting default_voice_id: the voice becomes the avatar’s default for video generation and is linked to the group if it was not already. Accepts any voice available to your workspace, including imported voice clones. Only supported for avatars you own — 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 | 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. The consent URL expires 24 hours after creation and is valid for one successful consent submission. A recording submitted after expiry fails and the group stays in pending consent status, so create a new consent link if the subject has not recorded within 24 hours. |
Assets
| Tool Name | Description |
|---|---|
list_assets | Beta — this endpoint may change with a few days’ notice. Lists a workspace member’s uploaded assets, newest first, with cursor-based pagination. Returns the same asset objects as GET /v3/assets/{asset_id}. The ‘username’ parameter (the ‘owner’ value on asset items) is required while the endpoint is in beta and will become an optional filter in a future release. Results are that member’s non-deleted assets, across all folders, that the caller has access to — each item carries ‘owner’ and ‘folder_id’. Pass the optional folder_id to narrow to one folder (empty folder_id = root-level assets); omit it for everything. |
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 in the caller’s workspace, at the root or inside another folder, and returns it. Pass the returned folder_id as folder_id to POST /v3/videos or POST /v3/video-translations to place the output in it, or as parent_id to this endpoint to nest another folder. Folders and their contents are visible in the HeyGen web app. Sibling folders may share a name; this endpoint never looks up an existing folder by name, so store the ids you receive rather than recreating a tree on retry, and send an Idempotency-Key so a retried request returns the folder the first attempt created. API keys need the videos:write scope; a key scoped only to translations can place translations in a folder but cannot create one. |
get_folder | Returns one folder in the caller’s workspace, including one that is in the trash (is_trash is true). Use it to confirm a stored folder_id still exists before placing content in it. A folder that was deleted, or that belongs to another workspace, is reported as not found. API keys need the videos:read scope. |
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 controls how custom terms are pronounced in generated speech — for example, speaking “HeyGen” as “hey-jen” — and how they are handled when a video is translated: Don’t Translate terms kept as-is, and Force Translate terms with a fixed replacement. Pass the returned brand_glossary_id when creating a video or translation to apply the glossary. Use GET /v3/brand-glossaries/{brand_glossary_id} to see which terms it remaps, POST /v3/brand-glossaries to create one, and PATCH /v3/brand-glossaries/{brand_glossary_id} to change one. |
create_brand_glossary | Creates a brand glossary in your workspace. Pass the returned brand_glossary_id when creating a video or translation to apply it. name must be unique within your workspace, compared without regard to case; a duplicate returns 409. terms, do_not_translate_terms and forced_translations may each be omitted to create an empty glossary you fill in later with PATCH /v3/brand-glossaries/{brand_glossary_id}. Pronunciations affect generated audio only — a term keeps its original spelling in captions and subtitles. do_not_translate_terms and forced_translations apply only when the glossary is used by a translation feature (video translation, Studio script translation, on-screen text translation), in every target language; they have no effect on video generation or text-to-speech requests. Tone settings are managed in the HeyGen web app and cannot be set here. |
get_brand_glossary | Returns one brand glossary with its full term list, so you can see exactly which terms are remapped and how. Use this to verify a glossary’s contents when a generated video pronounces or translates a term unexpectedly. Pronunciations affect generated audio only: a term keeps its original spelling in captions and subtitles while being spoken as its pronunciation. Translation rules apply only when the glossary is used by a translation feature — video translation, Studio script translation, and on-screen text translation: do_not_translate_terms are kept untranslated in every target language, and forced_translations replace their term with their translation in every target language. They have no effect on video generation or text-to-speech requests; only terms applies there. Either list is omitted from the response when the glossary has no rules of that kind. Tone settings are managed in the HeyGen web app under Brand Kit and are not returned here; editing a glossary through this API leaves them unchanged. |
update_brand_glossary | Updates a brand glossary. Each field is replaced independently: a field you omit is left untouched, a field you send replaces that value in full, and an empty array removes every entry from that list. There is no way to add a single entry — read the glossary, append to the list, and send the whole list back. Renaming to a name another glossary in your workspace already uses returns 409. A glossary’s tone settings are managed in the HeyGen web app and are never modified by this endpoint, so a glossary edited there keeps them through an update made here. |
delete_brand_glossary | Deletes a brand glossary. This cannot be undone: there is no way to restore a deleted brand glossary through the API. The glossary stops being returned by this API at once, and stops applying: neither its pronunciation terms nor its translation rules affect anything generated afterwards. Videos already generated with the glossary are unaffected, since their audio was synthesized at the time. A video or translation still configured with a deleted glossary keeps working rather than failing. |
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 brand assets from a public website, including logos, colors and font files found on the site. By calling this endpoint you confirm you have the rights and licenses necessary to upload, store and use those assets in HeyGen. The kit is assembled in the background: the returned brand_kit_id is usable immediately, but poll GET /v3/brand-kits/{brand_kit_id} every 2 to 5 seconds until its status is ‘completed’ before relying on its colors, logos or fonts. A website import usually settles in under two minutes. Send an Idempotency-Key header to make retries safe: without one, a retried request starts a second import of the same site. |
get_brand_kit | Returns one brand kit with the colors, logos and fonts it was built from, and which of them play which role. A brand kit imported from a website is assembled in the background: while status is ‘loading’ the collections and roles are provisional, and they are final once status is ‘completed’. Poll every 2 to 5 seconds while status is ‘loading’; a website import usually settles in under two minutes, and fonts are typically the last thing to land. |
update_brand_kit | Updates a brand kit’s name or its role assignments — which color plays which part, which logo is the main one, and which font is used for headings and body text. A field you omit is left unchanged. Creation assigns these roles automatically, with no human in the loop, so this is how a caller corrects them. Each role object is replaced in full rather than merged: send the roles you want to keep, since a role you leave out of the object is cleared. Send an empty object to clear a role entirely. A cleared role stays cleared and is not recomputed later. Sending null for any field is rejected: omit it to leave it unchanged. Role edits require an assembled kit and return 409 while status is ‘loading’ or ‘error’. Renaming is allowed at any time. Editing the colors themselves is not supported here yet. A brand kit shared into your workspace by another workspace is readable but not editable, and returns 403. |
delete_brand_kit | Deletes a brand kit, along with the colors, logos and fonts it holds. This cannot be undone: there is no way to restore a deleted brand kit through the API. A kit that is still assembling can be deleted at any time. Videos already generated with the kit are unaffected, since their brand colors were applied at render time. A video agent still configured with a deleted kit will report the id as invalid on its next use. A brand kit shared into your workspace by another workspace can be read but not deleted, and returns 403. |
Models
| Tool Name | Description |
|---|---|
generate_model_speech | Generates speech using the voice identified by voice_id and returns a URL for one completed mono PCM16 WAV file at 44.1 kHz. The request remains open until synthesis and output assembly finish. The voice must be an ACTIVE HeyGen Voice clone, instant or professional, owned by the caller’s workspace; seed, speed, pitch_shift and pitch_variance apply to professional clones only. Rate limit: 30 requests per minute per workspace member. |
list_model_audio_voices | Returns the model-backed audio voices in the caller’s workspace, ordered newest first. Use limit and token to retrieve additional pages. |
create_model_audio_voice | Creates a model-backed audio voice from one or more recordings, or retrains an existing professional voice when voice_id is supplied. Retraining requires only voice_id and source audio and retains the existing voice’s ID, name, language, and mode. The voice is PENDING and unavailable for inference while either operation runs. Poll GET /v3/models/audio/voices/{voice_id} until its status becomes ACTIVE or FAILED. Idempotency-Key is optional; omitting it means repeated creation requests create separate voices. New voices require an unoccupied professional-voice slot. Each purchased slot provides five pooled trainings per monthly billing period, including initial training; failed trainings do not consume the allowance. |
get_model_audio_voice | Returns one caller-owned model-backed audio voice and its current lifecycle state. PENDING covers queued and running work, ACTIVE is ready for inference, and FAILED is terminal. |
delete_model_audio_voice | Deletes the caller-owned model-backed audio voice. The voice is removed from subsequent reads, but a voice cannot be deleted while its status is PENDING. Wait for training to finish and retry. Repeating a successful deletion returns the same successful response. |
create_model_video | Generate a HeyGen Video with model heygen-video-1 from a text prompt, a first-frame image, or reference images, videos, and audio. Select text_to_video, image_to_video, or reference_to_video with mode. Prompts accept at most 5,000 Unicode characters. Duration is 5–15 whole seconds; resolution is 480p or 768p. Image-to-video follows the image proportions and ignores aspect_ratio. Reference-to-video requires at least one image or video, with at most nine images, three videos, three audio recordings, and twelve references total. Reference videos must be within a 1:4–4:1 ratio. Assets accept HTTPS URLs, uploaded asset IDs, or inline base64. Returns 202 with a video_id; poll GET /v3/models/videos/{video_id} for completion and the download URL. Pass an Idempotency-Key header to retry safely; without a key, each submission creates a new generation. |
get_model_video | Get a HeyGen Video generation in the caller’s workspace. Status is pending, processing, completed, failed, or cancelled. Completed results include a fresh video_url, duration, aspect_ratio, dimensions, and seed when available. Failed and cancelled results include failure_code and failure_message. Poll again to refresh an expired download URL. Missing videos and videos from another workspace return the same 404. |
Filler Word Removal
| Tool Name | Description |
|---|---|
create_filler_word_removal | Submit a video and return a job id immediately. The job runs asynchronously: it transcribes the audio, detects filler words (‘um’, ‘uh’, …), removes them along with overlong silences, and renders one cleaned video — no review step. If the run changes nothing at all, the job completes with the original video as output and the charge is automatically refunded. Pricing: $0.30 per source minute, 1-minute minimum. Poll GET /v3/filler-word-removals/{id} or subscribe to filler_word_removal.success / filler_word_removal.fail 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 any MCP-compatible agent, including:- Claude (Web, Desktop, and Code)
- Codex CLI
- Cursor (available in the Cursor marketplace)
- Gemini CLI
- Lovable
- Manus
- Superhuman
- OpenAI
- and more
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/
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 |