HeyGen

Open a voice chooser with previews of Starfish-compatible public or private voices. Use when the user wants to browse or select a voice themselves. If they ask you to pick any voice, use list_voices without opening this chooser, then create_speech once for their script. The chooser sends only the selected voice and the user's chosen action back to the assistant. Create speech requests exactly one create_speech call with one agreed script, or a question if the script is missing or ambiguous; Add to chat only adds the voice for reference without requesting generation.

choose_voice

For a file already attached in chat that the user wants to use in HeyGen, if import_asset_from_chat is listed and a usable host-provided file reference is available, call import_asset_from_chat instead of asking the user to upload or select the same attachment again. Reuse the returned HeyGen asset_id in subsequent tool calls. Never invent a file_id or download_url. Open one widget for browsing uploaded and generated assets, filtering by source and media type, selecting an existing asset, or uploading a new local file when attachment import is not usable. The widget sends the selected asset reference back to the conversation. The widget's file bytes travel directly from the browser to storage, never through an MCP tool.

open_asset_library

Finalizes every uploaded file in a batch once all PUTs return 200. Files are ingested independently. Returns 202 with the `batch_id`; poll get_asset_batch for progress. Safe to repeat.

complete_asset_batch

Seal a multipart upload by submitting every part's number and ETag. The object does not exist until this succeeds.

internal_avatar_complete_multipart_upload

Finalize a file uploaded by the asset uploader widget and return its reusable asset ID.

internal_asset_complete_upload

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_ai_clipping, or subscribe to the ai_clipping.success / ai_clipping.fail webhooks.

create_ai_clipping

Returns up to 100 presigned upload URLs in one call. PUT each file to its `upload_url` with the returned headers, then call complete_asset_batch. Check resource status before retrying an unknown outcome; repeating creation can create duplicate work.

create_asset_upload_batch

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.

create_avatar_consent

Create the workspace's first brand glossary. Call list_brand_glossaries first; creation is refused with 409 if any active glossary exists, regardless of its name. Existing glossaries remain usable. Reuse the existing glossary ID with update_brand_glossary; if several older glossaries exist, ask which one to use. To add entries, call get_brand_glossary and preserve existing rules in any list sent to update_brand_glossary, because supplied lists replace that category across all languages. Only create when the workspace has no glossary. After an unknown create outcome, call list_brand_glossaries before retrying.

create_brand_glossary

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_brand_kit until status is `completed`. Check resource status before retrying an unknown outcome; repeating creation can create duplicate work.

create_brand_kit

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. $0.30 per source minute, 1-minute minimum. Poll GET /v3/filler-word-removals/{id} or use webhooks.

create_filler_word_removal

Creates a folder at the root or inside `parent_id`. Pass its `folder_id` to create_video_from_avatar / create_video_from_cinematic_avatar / create_video_from_image / create_video_from_studio or create_video_translation to file output there. Names need not be unique, so store the ids you receive. Check resource status before retrying an unknown outcome; repeating creation can create duplicate work.

create_folder

Generate one to five portraits with heygen-image-1 and mode identity_remix. Supply one to five identity_images and exactly one reference_images item for clothing, pose, composition and background. Custom prompts are not supported. Requires workspace access. Returns generation_id; poll get_image_generation until completed, failed or cancelled. Return the image URLs on completion; partial results are not returned. Honor retry delays or wait 30 seconds between polls. Each submission creates a new generation; check status before retrying an unknown outcome.

create_image_generation

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.

create_lipsync

Submits up to 100 lipsync payloads as one batch, and items run independently. Returns 202 with a `batch_id`; poll get_lipsync_batch. Check resource status before retrying an unknown outcome; repeating creation can create duplicate work.

create_lipsync_batch

Mint a link the user opens on their phone to record footage or consent when this device has no camera. The link carries its own short-lived credential, so the phone needs no sign-in.

internal_avatar_create_handoff_link

Turn an uploaded still into a photo avatar and start its training. Takes the storage key the upload was written to.

internal_avatar_create_photo

The speech synthesis tool for MCP. Supports public catalog voices and compatible private clones, including HeyGen Voice (Video TTS) via engine='heygen_voice'. Synthesizes speech from text with a catalog voice and returns an audio URL, its duration and optional word timestamps. Omit engine to use the voice's saved default and settings, or set it per request; choose an ElevenLabs model with settings: {model_id: 'eleven_v4'}. Requests that omit engine use HeyGen Voice for most public catalog voices. Set engine: 'heygen_voice' to explicitly request HeyGen Voice, or 'starfish' for Starfish. The legacy 'orca' input remains accepted; response engine values retain 'orca' for compatibility. Professional-clone-only model synthesis and Turbo are not exposed through MCP. HTTP 400: the saved default or explicit engine is unsupported, not allowed on your plan, or incompatible with the requested locale or language. HTTP 403 (ai_vendor_access_restricted): workspace vendor policy blocks ElevenLabs and all of its model variants. After a generation error or timeout, ask the user before another generation; never retry automatically. Widget-capable chat hosts also display an inline audio player when its bundle is available. Clients without widgets receive the audio URL. Listening, seeking, and downloading do not require another generation call. The player Regenerate button makes one user-requested call using the original speech request; do not repeat that call from the conversation. One Create speech selection authorizes one call with the selected voice and one agreed script, not a batch or alternate versions. If the script is ambiguous, ask before generating. After an error or timeout, ask the user before retrying. To return only the result without opening the player (for example, several clips generated in parallel), call create_speech_without_player.

create_speech

The speech synthesis tool for MCP. Supports public catalog voices and compatible private clones, including HeyGen Voice (Video TTS) via engine='heygen_voice'. Synthesizes speech from text with a catalog voice and returns an audio URL, its duration and optional word timestamps. Omit engine to use the voice's saved default and settings, or set it per request; choose an ElevenLabs model with settings: {model_id: 'eleven_v4'}. Requests that omit engine use HeyGen Voice for most public catalog voices. Set engine: 'heygen_voice' to explicitly request HeyGen Voice, or 'starfish' for Starfish. The legacy 'orca' input remains accepted; response engine values retain 'orca' for compatibility. Professional-clone-only model synthesis and Turbo are not exposed through MCP. HTTP 400: the saved default or explicit engine is unsupported, not allowed on your plan, or incompatible with the requested locale or language. HTTP 403 (ai_vendor_access_restricted): workspace vendor policy blocks ElevenLabs and all of its model variants. After a generation error or timeout, ask the user before another generation; never retry automatically. Never opens the audio player on any host: returns the same audio URL JSON as create_speech, so use it when the user does not need to listen inline, such as when a skill or workflow generates several clips in parallel. Use create_speech when the user should listen in the inline player. Each call consumes speech quota; one agreed script authorizes one call.

create_speech_without_player

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

create_template

Submit up to 100 video creation payloads in one request and return a batch id immediately. Videos are created asynchronously; poll get_video_batch for per-item video ids and statuses.

create_video_batch

Before calling this tool, identify the source video(s) and target language(s). Explain that HeyGen will process the media and, by default, recreate the original speakers' voices and synchronize lip movements. Describe the actual selected options when they change that behavior (for example, audio-only translation or a stock voice). Ask the user to confirm that they authorize this processing and have permission from the people whose voices or likenesses will be used. For a batch, confirmation must cover every included video. Wait for an explicit affirmative response to this disclosure before submitting. An upload, public URL, or initial creation request alone is not confirmation. If the answer is ambiguous, clarify; if the user declines, do not submit. Confirmation covers only the disclosed operation and selected media; ask again if either materially changes. Do not repeat confirmation for status checks. 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.

create_video_translation

Before calling this tool, identify the source video(s) and target language(s). Explain that HeyGen will process the media and, by default, recreate the original speakers' voices and synchronize lip movements. Describe the actual selected options when they change that behavior (for example, audio-only translation or a stock voice). Ask the user to confirm that they authorize this processing and have permission from the people whose voices or likenesses will be used. For a batch, confirmation must cover every included video. Wait for an explicit affirmative response to this disclosure before submitting. An upload, public URL, or initial creation request alone is not confirmation. If the answer is ambiguous, clarify; if the user declines, do not submit. Confirmation covers only the disclosed operation and selected media; ask again if either materially changes. Do not repeat confirmation for status checks. Submits up to 100 translation payloads, each shaped like create_video_translation, 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. Check resource status before retrying an unknown outcome; repeating creation can create duplicate work.

create_video_translation_batch

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. Poll get_avatar_group/get_avatar_look until ready or failed; never repeat creation to check progress.

create_digital_twin

Before calling this tool, identify the selected recording and explain that HeyGen will process it to create a reusable voice clone that can generate new speech in the speaker's voice. Ask the user to explicitly confirm that they are the person whose voice is being cloned and authorize creating and using the clone, or that they have obtained explicit authorization from the person whose voice is being cloned to create and use the clone. Also ask them to confirm that they authorize proceeding. Wait for an explicit affirmative response to this disclosure before submitting. An upload, public URL, or initial creation request alone is not confirmation. If the answer is ambiguous, clarify; if the user declines, do not submit. Confirmation covers only the disclosed operation and selected media; ask again if either materially changes. Do not repeat confirmation for status checks. Create one instant voice from a single recording. Check resource status before retrying an unknown outcome; repeating creation can create duplicate work.

create_instant_audio_voice

Generate a Look Pack's looks into the avatar an existing look belongs to. After this returns look IDs, call show_avatar_looks once in the same turn with those look IDs (up to 12), including while they are still processing. The preview widget refreshes itself until generation finishes; do not poll get_avatar_look or get_avatar_group from the conversation. Never write preview_image_url or any other look image link as a markdown image or link; hosts cannot display these private links, and the widget shows the image.

create_look_pack_looks

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. After this returns look IDs, call show_avatar_looks once in the same turn with those look IDs (up to 12), including while they are still processing. The preview widget refreshes itself until generation finishes; do not poll get_avatar_look or get_avatar_group from the conversation. Never write preview_image_url or any other look image link as a markdown image or link; hosts cannot display these private links, and the widget shows the image.

create_photo_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. After this returns look IDs, call show_avatar_looks once in the same turn with those look IDs (up to 12), including while they are still processing. The preview widget refreshes itself until generation finishes; do not poll get_avatar_look or get_avatar_group from the conversation. Never write preview_image_url or any other look image link as a markdown image or link; hosts cannot display these private links, and the widget shows the image.

create_prompt_avatar

Restyle an existing avatar look into a single look template; the results are added to its avatar. After this returns look IDs, call show_avatar_looks once in the same turn with those look IDs (up to 12), including while they are still processing. The preview widget refreshes itself until generation finishes; do not poll get_avatar_look or get_avatar_group from the conversation. Never write preview_image_url or any other look image link as a markdown image or link; hosts cannot display these private links, and the widget shows the image.

create_template_looks

Creates a direct talking-avatar video from a specific HeyGen avatar. This is the Avatar Video route: one presenter speaking directly to the audience against a fixed background, at any length, including any request with supplied audio or a script that must be spoken word for word. Visual productions with scene action, demonstrations or B-roll use HeyGen Video 1 (text_to_video, image_to_video, reference_to_video). When `open_avatar_creator` is listed, the default HeyGen video experience uses the user's confirmed, ready private digital twin as the visible presenter. Never invent an avatar ID or silently substitute a stock, studio, photo, or automatically selected avatar when that digital-twin ID is missing. Use this tool when the user supplies or selects an avatar ID and provides an exact script or audio source. This is the preferred tool for direct requests such as “create a video with avatar X saying Y.” Pass the user's script verbatim. Do not rewrite, expand, or creatively interpret it unless the user explicitly requests editing. Do not substitute a different avatar. Prefer this tool over video_agent.generate whenever both avatar_id and a script or audio source are known. Use video_agent.generate only when the user explicitly asks for HeyGen Video Agent, for a video longer than 15 seconds, or for a narration-driven video with B-roll. When an Avatar Video request has no confirmed avatar ID, use prepare_avatar_video instead. After this tool returns a video_id, pick one of two follow-ups: - If the avatar video is one part of a larger workflow, such as A-roll that will be edited, combined with other footage, or captioned before the final result, do not call show_video. Poll get_video with the video_id to track status until it is completed or failed, then continue the workflow. - If the avatar video is the final result with no further editing needed, call show_video with that ID once in the same turn and stop status checks. The inline player tracks generation and displays the video automatically when it completes.

create_video_from_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 15 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. Use this direct tool instead of video_agent.generate when the user supplies the source and content supported by this tool's input schema, unless the user explicitly asks for HeyGen Video Agent. After this tool returns a video_id, call show_video with that ID once in the same turn. The inline player will track generation and refresh itself, so do not make further status calls unless the user explicitly asks.

create_video_from_cinematic_avatar

Create a lip-synced video from an image of a person. The image must show a clearly visible, human-like face: a photo, or a realistic illustration of a person. Images without a detectable face are rejected with 400. For non-human or stylized characters (mascots, animals, objects), use image_to_video or reference_to_video instead. Provide an image via URL, asset ID. The image will be animated with lip-sync to the provided audio or generated speech. Use this direct tool instead of video_agent.generate when the user supplies the source and content supported by this tool's input schema, unless the user explicitly asks for HeyGen Video Agent. After this tool returns a video_id, call show_video with that ID once in the same turn. The inline player will track generation and refresh itself, so do not make further status calls unless the user explicitly asks.

create_video_from_image

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. Use this direct tool instead of video_agent.generate when the user supplies the source and content supported by this tool's input schema, unless the user explicitly asks for HeyGen Video Agent. After this tool returns a video_id, call show_video with that ID once in the same turn. The inline player will track generation and refresh itself, so do not make further status calls unless the user explicitly asks.

create_video_from_studio

Soft-deletes an AI clip job and its clips.

delete_ai_clipping

Permanently deletes an asset. The asset must belong to the caller's workspace and not already be deleted.

delete_asset

Permanently deletes an avatar group and all its associated looks. Cannot delete public or community groups.

delete_avatar_group

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.

delete_avatar_look

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.

delete_brand_glossary

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.

delete_brand_kit

Permanently deletes a lipsync job and its associated files. This action cannot be undone.

delete_lipsync