bulk_asset_statuses
ChatGPTReturns 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.
bulk_lipsync_statuses
ChatGPTReturns 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.
bulk_video_statuses
ChatGPTReturns 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.
bulk_video_translation_statuses
ChatGPTReturns 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.
choose_voice
ChatGPTOpen 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.
clone_voice
ChatGPTCreates 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.
complete_asset_batch
ChatGPTFinalizes 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.
create_ai_clipping
ChatGPTSubmit 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.
create_asset_upload_batch
ChatGPTReturns 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_avatar_consent
ChatGPTInitiates 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.
create_brand_glossary
ChatGPTCreates 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.
create_brand_kit
ChatGPTCreates 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_digital_twin
ChatGPTCreates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous. (type: digital_twin)
create_filler_word_removal
ChatGPTSubmits 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_folder
ChatGPTCreates 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_image_generation
ChatGPTGenerate 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_lipsync
ChatGPTReplaces 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_batch
ChatGPTSubmits 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_look_pack_looks
ChatGPTGenerate a Look Pack's looks into the avatar an existing look belongs to.
create_photo_avatar
ChatGPTCreates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous. (type: photo)
create_prompt_avatar
ChatGPTCreates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous. (type: prompt)
create_speech
ChatGPTSynthesize speech audio from text using a specified voice. The voice must support the starfish engine — use GET /v3/voices?engine=starfish to find compatible voices. Supports plain text and SSML. Speed range: 0.5–2.0x. Returns a URL to the generated audio file along with duration and optional word-level timestamps.
create_template
ChatGPTCreates 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_looks
ChatGPTRestyle an existing avatar look into a single look template; the results are added to its avatar.
create_video_batch
ChatGPTSubmit 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_from_avatar
ChatGPTCreate a video from a HeyGen avatar (video or photo avatar). Provide an avatar_id to use a previously created avatar. The server automatically selects the appropriate engine based on the avatar type (video avatar or photo avatar).
create_video_from_cinematic_avatar
ChatGPTCreate a video from a text prompt plus avatar and asset references (Cinematic Avatar). Cinematic Avatar generates a video from a natural-language `prompt guided by reference content: one to three avatar looks and optional reference assets (images / videos / audio). Unlike the avatar and image` modes there is no script or voice — motion and speech are driven entirely by the prompt and the supplied references. Backed by the Seedance generation pipeline. 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
ChatGPTCreate a video by animating an arbitrary image. Provide an image via URL, asset ID. The image will be animated with lip-sync to the provided audio or generated speech.
create_video_from_studio
ChatGPTCreate 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_translation
ChatGPTTranslates 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_batch
ChatGPTBefore 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.
delete_ai_clipping
ChatGPTSoft-deletes an AI clip job and its clips.
delete_asset
ChatGPTPermanently deletes an asset. The asset must belong to the caller's workspace and not already be deleted.
delete_avatar_group
ChatGPTPermanently deletes an avatar group and all its associated looks. Cannot delete public or community groups.
delete_avatar_look
ChatGPTDeletes 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_brand_glossary
ChatGPTDeletes 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_kit
ChatGPTDeletes 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_lipsync
ChatGPTPermanently deletes a lipsync job and its associated files. This action cannot be undone.
delete_template
ChatGPTSoft-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.
delete_video
ChatGPTPermanently deletes a video and its associated files. This action cannot be undone.
delete_video_translation
ChatGPTPermanently deletes a video translation and its associated files. This action cannot be undone.
design_voice
ChatGPTReturns 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.
generate_from_template
ChatGPTGenerates a video from a template by filling its variables. Use scene_ids to select, reorder or repeat the template's existing scenes. Poll get_video or use webhooks for completion. An idempotent replay returns the original response, not the video's current state.
get_ai_clipping
ChatGPTReturns the full job resource including produced clips, statuses, and presigned download URLs.
get_asset
ChatGPTReturns metadata for an asset in the caller's workspace — including owner, upload timestamp, file type, and a publicly accessible URL.
get_asset_batch
ChatGPTReturns 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.
get_avatar_creation_status
ChatGPTReport in plain text how the user's avatar creation is progressing — photo training, footage training, consent validation, voice cloning, and the preview video. Call when the user asks whether their avatar is ready. Requires the job ids from the guided flow; it starts nothing and changes nothing.
get_avatar_group
ChatGPTReturns details for a specific avatar group including name, gender, preview URLs, looks count, and training status.
get_avatar_look
ChatGPTReturns details for a specific avatar look including supported engines, preferred orientation, preview URLs, and training status.
get_brand_glossary
ChatGPTReturns 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. Tone settings are not returned here.
get_brand_kit
ChatGPTReturns 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.
get_current_user
ChatGPTReturns the authenticated user's profile, remaining credits or balance, and billing details.
get_filler_word_removal
ChatGPTReturns 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).
get_folder
ChatGPTReturns 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.
get_image_generation
ChatGPTReturn the generation job status and ordered images with fresh download URLs once the entire job completes.
get_lipsync
ChatGPTReturns details for a lipsync job including status, video_url, caption_url, and failure info if applicable.
get_lipsync_batch
ChatGPTReturns 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).
get_model_video
ChatGPTReturns 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. After creation returns video_id, call show_video once with that ID in the same turn, including while generation is pending. Do not ask the user whether to show it. The inline player receives completion/failure push updates and uses recovery reads. Do not poll get_model_video from the conversation to wait for generation. Use get_model_video only for an explicit status or model-details request. On failed or cancelled, explain failure_message without regenerating unless the user asks.
get_template
ChatGPTReturns 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.
get_video
ChatGPTReturns details for a video including status, video_url, thumbnail_url, duration, and failure info if applicable.
get_video_agent_resource
ChatGPTReturns a single session resource (image, video, draft, avatar, voice, etc.) by its resource_id.
get_video_agent_session
ChatGPTReturns the current status, progress, video_id, and recent chat messages for a session.
get_video_batch
ChatGPTReturns batch aggregate status and one page of items with their video ids and statuses. Item statuses are one of queued, processing, completed, or failed.
get_video_scenes
ChatGPTReturns 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.
get_video_translation
ChatGPTReturns details for a translation job including status, output language, video_url, and failure info if applicable.
get_video_translation_batch
ChatGPTReturns 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).
get_voice
ChatGPTReturns details for a specific voice, including clone workflow status when available. Use this to poll a voice clone until its status is 'complete'.
image_to_video
ChatGPTAnimate a first-frame image with a prompt. Output follows the image proportions; aspectRatio is ignored. Produces a 5–15 second clip; follow the input schema for resolution, assets and reference limits. After creation returns video_id, call show_video once with that ID in the same turn, including while generation is pending. Do not ask the user whether to show it. The inline player receives completion/failure push updates and uses recovery reads. Do not poll get_model_video from the conversation to wait for generation. Use get_model_video only for an explicit status or model-details request. On failed or cancelled, explain failure_message without regenerating unless the user asks. 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.
import_asset_from_chat
ChatGPTImport a file the user already attached to ChatGPT into their HeyGen workspace. Prefer this tool over the asset library or direct upload tools for a usable host-provided file reference, even when widgets are available. Attachment import does not require widget support. Do not ask the user to select the same attachment again. Use the host-provided file reference; never invent download_url or file_id, and never send base64 or file bytes. Call only when the user requests sending that file to HeyGen. Accepts files up to 200 MiB supported by HeyGen's asset upload API. New imports allow 6 attempts per minute per user and 20 per workspace. If busy or rate limited, wait retry_after_seconds before retrying. Completion-only retries do not consume this import allowance. Returns a reusable HeyGen asset_id after upload finalization; processing can continue afterward. Reuse that asset_id in later calls instead of importing the same file again. Only if an error includes resumeAssetId, pass it with the original file on the next call to retry completion without another upload. Resumed results omit the file name and ChatGPT file_id because they cannot be verified against the saved upload. For terminal completion failures, follow next_steps to correct the cause before starting a fresh import. If no usable host file reference is available, use open_asset_library when listed to let the user choose a file. In clients without widgets, use create_asset_upload and complete_asset_upload only when listed and the client can read the file bytes and perform an HTTP PUT: create_asset_upload, PUT the file bytes to its upload_url with upload_headers, then call complete_asset_upload. If neither path is usable, ask the user to upload through HeyGen and provide the resulting asset reference.
internal_asset_complete_upload
ChatGPTFinalize a file uploaded by the asset uploader widget and return its reusable asset ID.
internal_asset_create_upload
ChatGPTGive the asset uploader widget a presigned direct-upload destination for one file.
internal_asset_picker_list
ChatGPTList one page of accessible workspace assets for the asset picker widget.
internal_asset_picker_select
ChatGPTValidate current read access to an asset before the widget sends its ID to the conversation.
internal_asset_upload_event
ChatGPTRecord a bounded asset uploader widget state for aggregate funnel monitoring.
internal_avatar_bind_passcode
ChatGPTBind an issued passcode to the consent recording by its content hash, so the recording cannot be swapped afterwards.
internal_avatar_complete_multipart_upload
ChatGPTSeal a multipart upload by submitting every part's number and ETag. The object does not exist until this succeeds.
internal_avatar_continue_voice_clone
ChatGPTAnswer a voice clone that paused for source review: proceed true keeps the flagged recording, false abandons the job.
internal_avatar_create_handoff_link
ChatGPTMint 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_multipart_upload
ChatGPTOpen an S3 multipart upload and return its per-part presigned URLs, for media too large for a single PUT.
internal_avatar_create_photo
ChatGPTTurn an uploaded still into a photo avatar and start its training. Takes the storage key the upload was written to.
internal_avatar_create_voice_clone
ChatGPTStart cloning the user's voice from their footage audio, bound to the avatar look being trained. Returns the job id to poll. file_url is the storage URL the footage was uploaded to.
internal_avatar_discard_photo_group
ChatGPTDelete the photo-avatar group created by an avatar flow the user chose to exit.
internal_avatar_expire_handoff
ChatGPTExpire a phone capture credential that is no longer displayed by the widget.
internal_avatar_flow_state
ChatGPTAggregated status of every avatar-creation job the caller names: photo training, footage training, consent validation, voice clone, and preview render. Holds the connection open while work is running.
internal_avatar_get_passcode
ChatGPTIssue the short passcode the user reads aloud during the consent recording, plus the id the recording is bound against.
internal_avatar_get_photo_upload_url
ChatGPTIssue presigned destinations for photo-avatar stills, optionally scoped to an existing avatar group.
internal_avatar_get_realtime_credential
ChatGPTMint a short-lived credential scoped to HeyGen's realtime consent verifier for the active recording attempt.
internal_avatar_get_upload_urls
ChatGPTIssue presigned destinations for the avatar's motion footage, its thumbnail, and the consent recording. Pass parts to open a multipart upload for footage larger than a single PUT can carry. Pass content_type so imported stills and footage receive the correct storage-key extension.
internal_avatar_get_voice_options
ChatGPTList the voice engines the cloned voice can be rendered with, each with an audition clip where one could be generated.
internal_avatar_get_voice_preview
ChatGPTRender one audition clip when the user presses Play on a voice option.
internal_avatar_get_voice_previews
ChatGPTRender audition clips for voice options after the picker is already visible.
internal_avatar_get_voice_upload_url
ChatGPTIssue a presigned destination for a fresh voice recording.
internal_avatar_handoff_status
ChatGPTCheck a phone capture session and return the staged upload after the phone finishes.
internal_avatar_select_voice
ChatGPTCommit the chosen voice engine and make that voice the avatar group's primary.
internal_avatar_start_preview_video
ChatGPTRender the short 'meet your avatar' preview video for a finished avatar group. Poll the flow state for its progress. Needs the photo avatar, the trained footage avatar, and the selected voice — the preview shows all three together.
internal_avatar_submit_media_evaluation
ChatGPTStart an advisory quality evaluation of uploaded footage and return the workflow id its findings are read back with.
internal_avatar_validate_consent
ChatGPTSubmit the uploaded consent recording for validation and return the id to poll. signature is the user's typed legal name, which the recording is checked against.
internal_cancellation_action
ChatGPTWidget-only cancellation action. Confirm requires the reviewed plan fingerprint after an explicit user confirmation click. Every subscription change requires explicit user acceptance. On timeout refresh status instead of automatically repeating a billing action.
internal_cancellation_snapshot
ChatGPTRead the owned Cicero session and current billing status. Never repeats a billing mutation.
internal_create_video_archive
ChatGPTPrepare a ZIP for an explicit multi-video download. Reuse the operation ID when retrying the same selection.
internal_get_video_archive
ChatGPTCheck an owned video ZIP job and get a fresh download link when every video is archived.
internal_get_video_status
ChatGPTRefresh status and signed playback data for an already-mounted HeyGen video player. This tool is driven by the widget and is not intended for model selection. The poll argument is an ignored cache-buster that prevents hosts from replaying a stale response for identical calls.
internal_get_video_subscription
ChatGPTRead the current video status and prepare realtime updates for an already-mounted player. The widget uses this tool on mount and when its subscription expires. Subscription credentials are returned only in widget metadata. The poll argument is an ignored cache-buster. This tool is driven by the widget and is not intended for model selection.
internal_list_videos
ChatGPTLoad or search the next video gallery page with the current folder filter.
internal_prepare_video_download
ChatGPTPrepare a browser handoff only after an explicit Download in HeyGen widget click. Never invoke on the user's behalf.
internal_voice_list_voices
ChatGPTBrowse speech-compatible voices. HeyGen Library supports language, accent (locale), gender, age, use-case tags and catalog search. Keep filters unchanged when paging with a token.
list_ai_clipping
ChatGPTReturns a cursor-paginated list of AI clip jobs in the authenticated user's workspace, newest first.
list_avatar_groups
ChatGPTReturns a paginated list of avatar groups (characters). Each group contains one or more looks. Filterable by ownership.
list_avatar_looks
ChatGPTReturns 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.
list_avatars
ChatGPTFor avatar discovery questions such as "what avatars can I use?", "what avatars do I have?", "show me my avatars", or "what public avatars are available?", call list_avatars when listed to open the gallery in the same turn. Do not answer with a text list of avatars or IDs instead. Default to private avatars; use ownership="public" for public or preset avatars. If list_avatars is not listed, call list_avatar_groups, then list_avatar_looks for the selected group. Browsing alone does not start avatar creation or video generation. Browse avatars visually, then open an avatar to see its looks. Defaults to your private avatars; use ownership='public' for presets. With group_id, opens that avatar's looks. Call list_avatars once to open the gallery, then let the user browse and choose inside it. The widget handles pagination, ownership tabs, and opening an avatar's looks. Do not call list_avatars again to follow nextToken, prefetch pages, or enumerate the library; each assistant call opens another widget. Only reopen the gallery when the user explicitly asks. The gallery lets the user choose a look; do not choose one for them. A look ID, not a group ID, is the avatar_id for video creation. Selection does not start generation or establish consent or engine eligibility. Requires widget support. Other clients use list_avatar_groups and list_avatar_looks.
list_brand_glossaries
ChatGPTLists 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.
list_brand_kits
ChatGPTReturns 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 video_agent.generate to generate on-brand videos.
list_lipsyncs
ChatGPTReturns a paginated list of all lipsync jobs in the account.
list_look_templates
ChatGPTLists the look templates and Look Packs your workspace can apply with create_look_pack_looks / create_template_looks. Send an item's id as template_id and its type as type. Filter by gender to match your avatar.
list_model_audio_voices
ChatGPTReturns model-backed audio voices, ordered newest first. With the default type=private, these are the voices in the caller's workspace, professional and instant; mode tells them apart. With type=public, these are the voices HeyGen provides to every workspace. Use limit and token to retrieve additional pages.
list_templates
ChatGPTReturns 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.
list_video_agent_session_videos
ChatGPTReturns all videos produced within a Video Agent session, sorted newest-first.
list_video_agent_sessions
ChatGPTReturns a paginated list of video agent sessions for the authenticated user, sorted newest-first.
list_video_agent_styles
ChatGPTReturns 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').
list_video_translation_languages
ChatGPTReturns all supported target language names for video translation.
list_video_translations
ChatGPTReturns a paginated list of all video translation jobs in the account.
list_videos
ChatGPTReturns a paginated list of all videos in the account. Filterable by folder_id or title substring.
list_voices
ChatGPTReturns a paginated list of voices, filterable by type, engine, language, and gender. Use engine=starfish for voices compatible with the TTS endpoint.
lookup_videos
ChatGPTList video IDs and metadata as paginated JSON without opening a widget. Use this for selecting a video for a follow-up tool, including 'show my latest video'. Choose the newest completed item and verify it with get_video before presenting it. Explain if a newer failed attempt was skipped; if none are playable, report that without opening failed players. For browsing the library, use list_videos instead.
open_asset_library
ChatGPTOpen one widget for browsing uploaded and generated assets, filtering by source and media type, selecting an existing asset, or uploading a local file. The widget sends the selected asset reference back to the conversation. The file bytes travel directly from the browser to storage, never through an MCP tool.
open_avatar_creator
ChatGPTOpens the guided digital-twin setup interface when the user asks to create a private digital twin or when a video prerequisite requires it. Call this tool only when the server instructions describe the guided creator flow. Call it immediately when prepare_avatar_video returns it as requiredTool; do not ask for separate chat confirmation. Do not call it after the user explicitly says they do not want to create a digital twin in this conversation. Calling this tool only reads account and resumable-flow state and displays the interface; it does not upload media, clone a voice, create an avatar, start training, or persist user data. Those actions occur only after the user reviews the setup and explicitly acts inside the interface. Pass pendingVideoPrompt exactly when returned by the prerequisite so the widget can resume the original video request. Do not substitute a stock, studio, or photo avatar unless the user explicitly requests that alternative.
prepare_avatar_video
ChatGPTFor an ambiguous video-creation request such as "create a HeyGen video", ask once: "Would you like an avatar video, best for an avatar speaking your script, or a general AI video using HeyGen Video 1, our own AI video model?" Ask before avatar setup or generation. Skip this question when the request or conversation already makes the video type clear, including an avatar-speaking request, a general generative scene, a named model, or an explicit Video Agent workflow. For general AI video, use text_to_video, image_to_video, or reference_to_video as appropriate; do not require avatar setup or an avatar showcase. Follow the guided avatar workflow only for an avatar-speaking video. Call this tool only when the server instructions describe the guided avatar-video workflow. In that workflow, use this first for an avatar-speaking video request whenever no specific avatar ID is known, whether or not the user already supplied a topic or script. Call it again for later relevant video requests unless the user explicitly declines digital-twin setup in the current conversation. Do not treat hesitation, deferral, or choosing another presenter for one video as a decline. Checks whether their private digital twin is ready and returns authoritative instructions for the next step. Pass the existing request as pendingVideoPrompt when present. Follow the returned instructions before asking a follow-up question or selecting a generation tool. Do not use this prerequisite when the user explicitly requests Video Agent or polished multi-scene production such as graphics or B-roll.
reference_to_video
ChatGPTGenerate a clip guided by reference images, videos, audio or avatar references. See reference inputs for required combinations. Produces a 5–15 second clip; follow the input schema for resolution, assets and reference limits. After creation returns video_id, call show_video once with that ID in the same turn, including while generation is pending. Do not ask the user whether to show it. The inline player receives completion/failure push updates and uses recovery reads. Do not poll get_model_video from the conversation to wait for generation. Use get_model_video only for an explicit status or model-details request. On failed or cancelled, explain failure_message without regenerating unless the user asks. 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.
search_audio_sounds
ChatGPTSearches 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.
set_template_variables
ChatGPTReplaces 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_template. A text variable with match turns that text into a {{name}} placeholder.
show_video
ChatGPTDisplay a validated or newly created HeyGen video in the inline, self-updating player. For "show me all my HeyGen videos", "show my videos", or other library-browsing requests, call list_videos and present the gallery or list. Do not automatically play a result unless the user selects a video or asks for a specific one. Call this directly after text_to_video, image_to_video, reference_to_video, or avatar video creation returns a video_id, including while generation is pending. The player receives terminal push updates and uses recovery reads to display the finished video. For a user-supplied existing video ID (including a list_videos result), call get_video first and call this tool only if that lookup succeeds and status is not failed. Already-failed videos return an error without a player. Do not use show_video to probe candidate videos. The player refreshes the signed playback URL when it mounts and tracks generation status by itself until the video completes or fails. The avatar creator widget can send a completion follow-up containing the video_id of its newly created Meet Your Avatar preview. Call show_video directly with that ID; do not create another video.
stop_video_agent_session
ChatGPTHalts an active agent run at its next checkpoint. Partial results are preserved.
submit_feedback
ChatGPTSubmit concise product feedback to HeyGen after the user gives feedback or you observe a meaningful terminal failure that did not recover. Set source=user only for feedback the user actually expressed; use source=agent for your own observation. Always include toolName and resourceIds when a project, session, video, or other resource exists for this issue — a report with no resource ID and no tool name is usually not root-causable later. Include the exact observed error, but never credentials, raw media, unrelated conversation text, or an invented cause or user opinion. For usability or performance complaints (e.g. "too slow", "stuck", "hung"), also include pipelineStep (which stage was slow — compose, magic_edit, render_video, or other) and elapsedSeconds (how long it actually took), and set expectedBaseline when the user states or implies what they expected (e.g. "usually under 2 minutes", "faster in the web app") — these turn a vague "too slow" into a diagnosable report. Do not report expected validation, consent, or billing guidance unless the user says it is a problem. If you know the current host application and surface, provide reportedClientName and reportedClientSurface; otherwise omit them. Report the host, such as ChatGPT, Codex desktop, Codex CLI, Claude, or Grok, never the model name and never an inferred client. Submit once per issue and do not retry a failed feedback submission in a loop. Submission is best effort and does not confirm durable storage or operator review. Do not automatically report historical failures found while browsing. Follow the client consent policy and briefly tell the user after submitting feedback.
text_to_video
ChatGPTGenerate a HeyGen Video from a text prompt. For a starting image use image_to_video; for references use reference_to_video. Produces a 5–15 second clip; follow the input schema for resolution, assets and reference limits. After creation returns video_id, call show_video once with that ID in the same turn, including while generation is pending. Do not ask the user whether to show it. The inline player receives completion/failure push updates and uses recovery reads. Do not poll get_model_video from the conversation to wait for generation. Use get_model_video only for an explicit status or model-details request. On failed or cancelled, explain failure_message without regenerating unless the user asks. 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.
update_avatar_group
ChatGPTUpdates 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.
update_avatar_look
ChatGPTUpdates the display name of an avatar look. Only supported for photo avatar and digital twin look types.
update_brand_glossary
ChatGPTUpdates a brand glossary. A field you omit is left untouched, a list you send replaces the existing list in full, and an empty array removes every entry. A name already used in the workspace returns 409. Tone settings are never modified by this endpoint.
update_brand_kit
ChatGPTUpdates 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.
update_lipsync
ChatGPTUpdates the display title of a lipsync job.
update_template
ChatGPTRenames a template. Other properties are edited in the HeyGen editor or through set_template_variables. Returns the template detail.
update_video_translation
ChatGPTUpdates the display title of a video translation job.
video_agent.generate
ChatGPTThe primary tool for video creation using HeyGen's Video Agent. Use this tool to generate videos on behalf of the user. WHEN TO CALL: - If the user explicitly requests this tool or mentions "HeyGen Video Agent", invoke it. - User provides a SPECIFIC topic AND narrative details, script, or style instructions (e.g., "Make a 30-second product demo for our AI scheduling app with a professional tone" or "Create a video explaining basketball rules with an energetic narrator"). - High-intent users: Specific topic + content/narrative/script provided. NEVER CALL WHEN: - The request is vague or lacks a specific topic (e.g., "Make me a video" or "Help me with a video about coding"). Instead, stay in chat and help the user define their topic, narrative, and style before calling this tool. SESSION MANAGEMENT: - First call: Leave session_id empty. A new session will be created automatically. - Subsequent calls (continuing a conversation): Pass the session_id returned from the previous tool call. This continues the conversation and keeps the agent in the loop. - New video request: If the user explicitly asks to start a completely new video, leave session_id empty to create a fresh session. INPUTS: - prompt: (Required) The user's direct request for the video. - conversation_context: (Optional) All relevant context from the conversation that informs this request. IMPORTANT: Always include the actual content being referenced—never use vague references like "the script above", "as mentioned", or "that idea". Expand all pronouns and references into the actual material. - session_id: (Optional) Session ID from a previous tool call to continue the conversation.
