The HeyGen connector lets your AI agent act in each user's HeyGen account. Each user connects their own HeyGen API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 107 tools.
- Tools
- 107
- What they doRead · write · destructive
- 49 · 44 · 1449 read44 write14 destructive
- Users sign in with
- API key
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the HeyGen connection
In AgentKit > Connections, create a HeyGen connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'heygen'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize HeyGen:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'heygen_get_current_user',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "heygen"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize HeyGen:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="heygen_get_current_user",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their HeyGen credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolheygen_download_proofread_srtGet presigned download URLs for the edited and original SRT files of a completed proofread session.Read-onlyDownload Proofread Srt
Get presigned download URLs for the edited and original SRT files of a completed proofread session. Returns srt_url, original_srt_url. Use to review or edit subtitles outside HeyGen. Needs a proofread_id for a completed session.
Inputs
proofread_idstringrequired- Unique proofread identifier
heygen_get_ai_clippingGet an AI clipping job's status, produced clips, and presigned download URLs.Read-onlyGet Ai Clipping
Get an AI clipping job's status, produced clips, and presigned download URLs. Returns id, title, status, input_language, source_duration, output_settings, clips, progress, callback_id, created_at. Use to poll a clipping job. Needs a job_id from create_ai_clipping.
Inputs
job_idstringrequired- Unique AI clip job identifier
heygen_get_api_key_infoGet non-secret metadata for the API key used by this connection: expiration and permission scopes.Read-onlyGet Api Key Info
Get non-secret metadata for the API key used by this connection: expiration and permission scopes. Returns key_id, key_name, status, scope_mode, scopes, created_at, updated_at, expires_at, expires_in_seconds. Use when a call fails with a permission error to see which scopes the key holds.
Inputs
This tool takes no inputs.
heygen_get_assetGet an asset's metadata, file type, and a publicly accessible URL.Read-onlyGet Asset
Get an asset's metadata, file type, and a publicly accessible URL. Returns id, name, type, owner, space_id, folder_id, uploaded_at, url. Use to check an asset or read its URL. Needs an asset_id from list_assets.
Inputs
asset_idstringrequired- Unique asset identifier
heygen_get_avatar_groupGet an avatar group's name, gender, preview URLs, looks count, and training status.Read-onlyGet Avatar Group
Get an avatar group's name, gender, preview URLs, looks count, and training status. Returns id, name, preview_image_url, preview_video_url, gender, created_at, looks_count, default_voice_id, consent_status, status. Use to check a group's training status. Use list_avatar_groups to browse. Needs a group_id from list_avatar_groups.
Inputs
group_idstringrequired- Unique avatar group identifier
heygen_get_avatar_lookGet one avatar look's supported engines, preferred orientation, preview URLs, and training status.Read-onlyGet Avatar Look
Get one avatar look's supported engines, preferred orientation, preview URLs, and training status. Returns id, name, avatar_type, group_id, preview_image_url, preview_video_url, gender, tags, default_voice_id, supported_api_engines. Use to inspect a look before using it in a video. Needs a look_id from list_avatar_looks.
Inputs
look_idstringrequired- Unique avatar look identifier. This is the value to pass as avatar_id to POST /v3/videos.
heygen_get_background_removalGet a background removal job's status and presigned download URLs when complete.Read-onlyGet Background Removal
Get a background removal job's status and presigned download URLs when complete. Returns id, status, layers, duration, created_at, completed_at, error. Use to poll a job. Needs a job_id from create_background_removal.
Inputs
job_idstringrequired- Background removal job id
heygen_get_brand_glossaryGet one brand glossary with its full term list.Read-onlyGet Brand Glossary
Get one brand glossary with its full term list. Returns brand_glossary_id, name, created_at, updated_at, terms, do_not_translate_terms, forced_translations. Use to inspect a glossary before updating it. Needs a brand_glossary_id from list_brand_glossaries.
Inputs
brand_glossary_idstringrequired- Unique brand glossary identifier
heygen_get_brand_kitGet one brand kit with its colors, logos, fonts, and role assignments.Read-onlyGet Brand Kit
Get one brand kit with its colors, logos, fonts, and role assignments. Returns brand_kit_id, name, status, colors, color_roles, logos, logo_roles, fonts, font_roles. Use to inspect an imported brand kit or poll its import. Needs a brand_kit_id from list_brand_kits.
Inputs
brand_kit_idstringrequired- Unique brand kit identifier
heygen_get_current_userGet the authenticated HeyGen user's profile, remaining credits or balance, and billing details.Read-onlyGet Current User
Get the authenticated HeyGen user's profile, remaining credits or balance, and billing details. Returns username, email, first_name, last_name, billing_type, wallet, subscription, usage_based. Use to verify the connection or check credits before starting a paid generation.
Inputs
This tool takes no inputs.
heygen_get_filler_word_removalGet a filler word removal job's status, progress, and the cleaned video URL when complete.Read-onlyGet Filler Word Removal
Get a filler word removal job's status, progress, and the cleaned video URL when complete. Returns id, title, status, progress, video_url, thumbnail_url, original_duration, output_duration, num_cuts, reduction_pct. Use to poll a removal job. Needs a filler_word_removal_id from create_filler_word_removal.
Inputs
filler_word_removal_idstringrequired- Unique filler word removal job identifier
heygen_get_folderGet one folder, including one in the trash.Read-onlyGet Folder
Get one folder, including one in the trash. Returns folder_id, name, parent_id, type, is_trash, created_at, updated_at, creator_username. Use to validate a stored folder_id. Needs a folder_id from create_folder.
Inputs
folder_idstringrequired- Unique folder identifier
heygen_get_heygen_imageGet a HeyGen Image generation's status and ordered image URLs when complete.Read-onlyGet Heygen Image
Get a HeyGen Image generation's status and ordered image URLs when complete. Returns generation_id, status, model, num_images, created_at, images, failure_code, failure_message. Use to poll create_heygen_image. Needs a generation_id from create_heygen_image.
Inputs
generation_idstringrequired- Generation job identifier returned by create image generation.
heygen_get_heygen_videoGet a HeyGen Video generation's status and output when complete.Read-onlyGet Heygen Video
Get a HeyGen Video generation's status and output when complete. Returns video_id, status, model, created_at, video_url, duration, input_video_duration, aspect_ratio, width, height. Use to poll create_heygen_video. Needs a video_id from create_heygen_video.
Inputs
video_idstringrequired- Unique video identifier
heygen_get_imageGet an image generation's status and download URLs when complete.Read-onlyGet Image
Get an image generation's status and download URLs when complete. Returns id, status, model, created_at, images, failure_code, failure_message. Use to poll create_image. Needs a generation_id from create_image.
Inputs
generation_idstringrequired- The `id` returned by create image.
heygen_get_lipsyncGet a lipsync job's status, video_url, caption_url, and failure details.Read-onlyGet Lipsync
Get a lipsync job's status, video_url, caption_url, and failure details. Returns id, title, status, duration, video_url, caption_url, callback_id, created_at, failure_message. Use to poll a lipsync job after creating it. Needs a lipsync_id from create_lipsync.
Inputs
lipsync_idstringrequired- Unique lipsync identifier
heygen_get_musicGet a music generation job's status and a fresh audio URL when complete.Read-onlyGet Music
Get a music generation job's status and a fresh audio URL when complete. Returns id, status, model, created_at, requested_duration_seconds, duration_seconds, audio_url, format, failure_code, failure_message. Use to retrieve a track created with create_music. Needs a music_id from create_music.
Inputs
music_idstringrequired- The `id` returned by Create Music.
heygen_get_podcastGet a podcast's status and, when complete, its video_url, thumbnail_url, and duration.Read-onlyGet Podcast
Get a podcast's status and, when complete, its video_url, thumbnail_url, and duration. Returns podcast_id, status, title, video_url, thumbnail_url, duration, failure_message, created_at. Use to poll a podcast. Needs a podcast_id from create_podcast.
Inputs
podcast_idstringrequired- Unique podcast identifier
heygen_get_proofread_sessionGet the status and details of a proofread session.Read-onlyGet Proofread Session
Get the status and details of a proofread session. Returns id, title, status, output_language, input_language, submitted_for_review, created_at, failure_message. Use to poll a session after creating it. Needs a proofread_id from create_proofread_session.
Inputs
proofread_idstringrequired- Unique proofread identifier
heygen_get_templateGet a template's variable schema (with current defaults) and its scenes.Read-onlyGet Template
Get a template's variable schema (with current defaults) and its scenes. Returns id, name, thumbnail_url, aspect_ratio, created_at, updated_at, variables, source_video_id, edit_version, scene_ids. Use before generate_video_from_template to learn which variables to fill. Needs a template_id from list_templates.
Inputs
template_idstringrequired- Unique template identifier
heygen_get_transcriptionGet a transcription's transcript, or its failure details.Read-onlyGet Transcription
Get a transcription's transcript, or its failure details. Returns id, status, model, created_at, language, duration_seconds, text, segments, failure_code, failure_message. Use to retrieve a transcription created with create_transcription. Needs a transcription_id from create_transcription.
Inputs
transcription_idstringrequired- The `id` returned by Create Transcription.
heygen_get_videoGet one video's status, video_url, thumbnail_url, duration, and failure details.Read-onlyGet Video
Get one video's status, video_url, thumbnail_url, duration, and failure details. Returns id, title, status, created_at, completed_at, video_url, thumbnail_url, gif_url, captioned_video_url, subtitle_url. Use to poll a video after creation or to fetch its download URL. Use list_videos to browse. Needs a video_id from a create_*_video call or list_videos.
Inputs
video_idstringrequired- Unique video identifier
heygen_get_video_agent_resourceGet one session resource (image, video, draft, avatar, voice, and similar) by resource id.Read-onlyGet Video Agent Resource
Get one session resource (image, video, draft, avatar, voice, and similar) by resource id. Returns resource_id, resource_type, source_type, url, thumbnail_url, preview_url, created_at, metadata, blueprint. Use to inspect an artifact the agent referenced in a session. Needs a session_id and a resource_id from get_video_agent_session.
Inputs
resource_idstringrequired- Resource ID
session_idstringrequired- Session ID
heygen_get_video_agent_sessionGet a Video Agent session's status, progress, video_id, and recent chat messages.Read-onlyGet Video Agent Session
Get a Video Agent session's status, progress, video_id, and recent chat messages. Returns session_id, status, progress, title, video_id, created_at, messages, error. Use to poll a session after creating it or sending a message. Needs a session_id from create_video_agent_session.
Inputs
session_idstringrequired- Session ID
heygen_get_video_generationGet a video generation's status and output when complete.Read-onlyGet Video Generation
Get a video generation's status and output when complete. Returns id, status, model, created_at, duration, resolution, aspect_ratio, video_url, duration_seconds, failure_code. Use to poll create_video_generation. Needs a generation_id from create_video_generation.
Inputs
generation_idstringrequired- The `id` returned by create video generation.
heygen_get_video_scenesGet a video's current scenes and the edit_version required to edit it.Read-onlyGet Video Scenes
Get a video's current scenes and the edit_version required to edit it. Returns video_id, edit_version, video, scenes. Use before edit_video. Needs a video_id from list_videos.
Inputs
video_idstringrequired- Unique video identifier
heygen_get_video_translationGet a translation job's status, output language, video_url, and failure details.Read-onlyGet Video Translation
Get a translation job's status, output language, video_url, and failure details. Returns id, title, status, output_language, input_language, duration, translate_audio_only, video_url, audio_url, srt_caption_url. Use to poll a translation after creating it. Needs a video_translation_id from create_video_translation.
Inputs
video_translation_idstringrequired- Unique video translation identifier
heygen_get_voiceGet one voice's details, including clone workflow status when available.Read-onlyGet Voice
Get one voice's details, including clone workflow status when available. Returns voice_id, name, language, gender, preview_audio_url, status, failure_message, support_pause, support_interactive_avatar, created_at. Use to poll a voice clone until it is ready. Needs a voice_id from list_voices or clone_voice.
Inputs
voice_idstringrequired- Unique voice identifier
heygen_list_ai_clippingsList AI clipping jobs, newest first.Read-onlyList Ai Clippings
List AI clipping jobs, newest first. Returns a page of items (id, title, status, input_language, source_duration, output_settings, clips, progress) with has_more and next_token. Use to find a job id.
Inputs
limitinteger- Maximum number of items per page. Defaults to 10 (lower than other v3 lists) because each item embeds its full clips array.
tokenstring- Opaque cursor token for the next page.
heygen_list_assetsList uploaded assets in the workspace, newest first.Read-onlyList Assets
List uploaded assets in the workspace, newest first. Returns a page of items (id, name, type, owner, space_id, folder_id, uploaded_at, url) with has_more and next_token. Use to find an asset_id. Use search_assets for public stock images.
Inputs
usernamestringrequired- Username of the workspace member whose assets to list — the same value as asset items' 'owner' field. Required while this endpoint is in beta; it will become an optional filter in a future release.
folder_idstring- Optional folder filter. Omit to list ALL workspace assets across folders. Pass a folder id to list that folder only, or an empty value (folder_id=) for root-level assets (assets not filed into any folder).
limitinteger- Maximum number of assets to return per page (1-100).
tokenstring- Opaque cursor from a previous response's next_token. Omit for the first page.
heygen_list_avatar_groupsList avatar groups (characters), each containing one or more looks.Read-onlyList Avatar Groups
List avatar groups (characters), each containing one or more looks. Returns a page of items (id, name, preview_image_url, preview_video_url, gender, created_at, looks_count, default_voice_id) with has_more and next_token. Use to browse characters. Use list_avatar_looks to find a look id for video creation.
Inputs
limitinteger- Maximum number of items to return per page (1-50).
ownershipstring- Filter by ownership: 'public' for preset avatars, or 'private' for your own. Omit for all.one of
publicprivate tokenstring- Opaque cursor token for the next page.
heygen_list_avatar_looksList avatar looks (outfits, poses, styles), filterable by group, type, and ownership.Read-onlyList Avatar Looks
List avatar looks (outfits, poses, styles), filterable by group, type, and ownership. Returns a page of items (id, name, avatar_type, group_id, preview_image_url, preview_video_url, gender, tags) with has_more and next_token. Use to find the avatar_id to pass to video creation tools. Use list_avatar_groups to browse characters.
Inputs
avatar_typestring- Filter by avatar type: 'studio_avatar', 'digital_twin', or 'photo_avatar'.one of
studio_avatardigital_twinphoto_avatar group_idstring- Filter looks to a specific avatar group. Returns only looks belonging to this group.
limitinteger- Maximum number of items to return per page (1-50).
ownershipstring- Filter by ownership: 'public' for preset avatars, or 'private' for your own. Omit for all.one of
publicprivate tokenstring- Opaque cursor token for the next page.
heygen_list_background_removalsList background removal jobs, newest first.Read-onlyList Background Removals
List background removal jobs, newest first. Returns a page of items (id, status, layers, duration, created_at, completed_at, error) with has_more and next_token. Use to find a job id.
Inputs
limitinteger- Maximum number of jobs to return (1-100).
tokenstring- Opaque pagination cursor from a previous response's next_token.
heygen_list_brand_glossariesList the brand glossaries in the workspace with names and timestamps.Read-onlyList Brand Glossaries
List the brand glossaries in the workspace with names and timestamps. Returns a page of items (brand_glossary_id, name, created_at, updated_at) with has_more and next_token. Use to find a brand_glossary_id.
Inputs
limitinteger- Maximum number of brand glossaries to return (1-100). Default 10.
tokenstring- Opaque pagination cursor from a previous response's `next_token`. Omit for the first page.
heygen_list_brand_kitsList the brand kits in the workspace with their colors and logo URL.Read-onlyList Brand Kits
List the brand kits in the workspace with their colors and logo URL. Returns a page of items (brand_kit_id, name, logo_url, colors) with has_more and next_token. Use to find a brand_kit_id.
Inputs
limitinteger- Results per page (1-100).
tokenstring- Opaque cursor token for the next page. Obtained from next_token in a previous response.
heygen_list_lipsyncsList lipsync jobs in the account.Read-onlyList Lipsyncs
List lipsync jobs in the account. Returns a page of items (id, title, status, duration, video_url, caption_url, callback_id, created_at) with has_more and next_token. Use to find a lipsync id.
Inputs
limitinteger- Maximum number of items per page
tokenstring- Opaque cursor token for the next page
heygen_list_look_templatesList the look templates and Look Packs your workspace can apply to an avatar.Read-onlyList Look Templates
List the look templates and Look Packs your workspace can apply to an avatar. Returns a page of items (id, type, name, gender, preview_image_url, looks_count) with has_more and next_token. Use before create_avatar_looks.
Inputs
genderstring- Filter to templates built for 'male' or 'female'. Templates with no gender of their own are returned for either value. Omit for all.one of
malefemale limitinteger- Maximum number of items to return per page (1-50).
tokenstring- Opaque cursor token for the next page.
typestring- Filter by generation method: 'look_pack' for Look Packs, 'template' for single look templates. Omit for both.one of
look_packtemplate
heygen_list_podcastsList podcasts in the workspace, newest first.Read-onlyList Podcasts
List podcasts in the workspace, newest first. Returns a page of items (podcast_id, status, title, video_url, thumbnail_url, duration, failure_message, created_at) with has_more and next_token. Use to find a podcast id.
Inputs
limitinteger- Results per page (1-100).
tokenstring- Opaque cursor token for the next page.
heygen_list_proofread_sessionsList proofread sessions in the workspace, newest first.Read-onlyList Proofread Sessions
List proofread sessions in the workspace, newest first. Returns a page of items (id, title, status, output_language, input_language, submitted_for_review, created_at, failure_message) with has_more and next_token. Use to find a proofread_id.
Inputs
limitinteger- Maximum number of items per page
tokenstring- Opaque cursor token for the next page
heygen_list_templatesList API-ready templates in the workspace.Read-onlyList Templates
List API-ready templates in the workspace. Returns a page of items (id, name, thumbnail_url, aspect_ratio, created_at, updated_at) with has_more and next_token. Use to find a template_id. Use get_template for a template's variables.
Inputs
limitinteger- Maximum number of templates to return per page
tokenstring- Opaque pagination token from a previous response's next_token
heygen_list_translation_languagesList all supported target language names for video translation.Read-onlyList Translation Languages
List all supported target language names for video translation. Returns languages. Use before create_video_translation to validate language names.
Inputs
This tool takes no inputs.
heygen_list_video_agent_session_videosList all videos produced within a Video Agent session, newest first.Read-onlyList Video Agent Session Videos
List all videos produced within a Video Agent session, newest first. Returns a page of items (id, title, status, created_at, completed_at, video_url, thumbnail_url, gif_url) with has_more and next_token. Use to retrieve the outputs of a session. Needs a session_id from list_video_agent_sessions.
Inputs
session_idstringrequired- Session ID
heygen_list_video_agent_sessionsList Video Agent sessions for the authenticated user, newest first.Read-onlyList Video Agent Sessions
List Video Agent sessions for the authenticated user, newest first. Returns a page of items (session_id, title, created_at) with has_more and next_token. Use to find a session id. Use get_video_agent_session for one session's detail.
Inputs
limitinteger- Results per page (1-100).
tokenstring- Opaque cursor token for the next page. Obtained from next_token in a previous response.
heygen_list_video_agent_stylesList the curated visual styles available for Video Agent sessions.Read-onlyList Video Agent Styles
List the curated visual styles available for Video Agent sessions. Returns a page of items (style_id, name, thumbnail_url, preview_video_url, tags, aspect_ratio) with has_more and next_token. Use to find a style_id to pass to create_video_agent_session.
Inputs
limitinteger- Results per page (1-100).
tagstring- Filter by tag (e.g., 'cinematic', 'retro-tech', 'iconic-artist', 'pop-culture', 'handmade', 'print').
tokenstring- Opaque cursor token for the next page. Obtained from next_token in a previous response.
heygen_list_video_translationsList video translation jobs in the account.Read-onlyList Video Translations
List video translation jobs in the account. Returns a page of items (id, title, status, output_language, input_language, duration, translate_audio_only, video_url) with has_more and next_token. Use to find a translation id.
Inputs
limitinteger- Maximum number of items per page
tokenstring- Opaque cursor token for the next page
heygen_list_videosList videos in the account, optionally filtered by folder or title substring.Read-onlyList Videos
List videos in the account, optionally filtered by folder or title substring. Returns a page of items (id, title, status, created_at, completed_at, video_url, thumbnail_url, gif_url) with has_more and next_token. Use to browse or find a video id. Use get_video for one video's full details.
Inputs
folder_idstring- Filter videos by folder ID
limitinteger- Maximum number of items to return per page
titlestring- Filter videos by title substring
tokenstring- Opaque pagination cursor from a previous response
heygen_list_voicesList voices, filterable by type, engine, language, and gender.Read-onlyList Voices
List voices, filterable by type, engine, language, and gender. Returns a page of items (voice_id, name, language, gender, preview_audio_url, support_pause, support_locale, type) with has_more and next_token. Use to find a voice_id for video creation or speech generation. Use get_voice for one voice.
Inputs
enginestring- Filter by stored engine mapping. Use 'heygen_voice' for HeyGen Voice; 'orca' remains accepted as its legacy alias. Also accepts 'starfish', 'elevenlabs' or internal engine names. Response engine values retain 'orca' for compatibility. The deprecated elevenlabs_v3 input alias is also accepted. Available engines may also include engines prepared on first use.
genderstring- Filter by gender ('male' or 'female').
languagestring- Filter by language (e.g. 'English').
limitinteger- Results per page (1-100).
tokenstring- Opaque cursor token for the next page.
typestring- Voice type: 'public' for the shared library or 'private' for your cloned voices.one of
publicprivate
heygen_search_assetsSemantically search re-hosted public images and icons by natural-language description.Read-onlySearch Assets
Semantically search re-hosted public images and icons by natural-language description. Returns a page of items (id, url, width, height, orientation, is_transparent, type) with has_more and next_token. Use to find stock imagery for videos. Use list_assets for your own uploads.
Inputs
querystringrequired- Natural-language description of the image or icon you want, e.g. 'pepperoni pizza on a wooden table' or 'minimalist rocket icon'. Results are ranked by semantic similarity.
typestringrequired- Asset type to search (image or icon).one of
imageicon limitinteger- Maximum number of results to return (1-50).
scopestring- Which assets to search: 'public' (the shared catalog, default) or 'personal' (your own space's assets).one of
publicpersonal tokenstring- Opaque cursor token for the next page, taken from 'next_token' in a prior response.
heygen_search_audioSearch the music or sound-effects catalog by natural-language description.Read-onlySearch Audio
Search the music or sound-effects catalog by natural-language description. Returns a page of items (id, name, description, audio_url, duration, peak_offset, placement, score) with has_more and next_token. Use to find background music or sound effects. Use create_music to generate a new track.
Inputs
querystringrequired- Natural-language description of the audio you want, e.g. 'upbeat lofi hip-hop' or 'tense cinematic riser'. Results are ranked by semantic similarity to this text.
limitinteger- Maximum number of results to return (1-50).
min_scorenumber- Minimum semantic similarity score (0-1). Tracks scoring below this are omitted.
tokenstring- Opaque cursor token for the next page, taken from 'next_token' in a prior response.
typestring- Audio content type to search: 'music' (background-music catalog) or 'sound_effects' (SFX catalog). Defaults to 'music'.one of
musicsound_effects
heygen_clone_voiceCreate a voice clone from an audio file.WriteClone Voice
Create a voice clone from an audio file. Returns voice_clone_id. Use to add a custom voice to the workspace. Provide the audio as a URL or an uploaded asset id. Poll get_voice until the clone is ready.
Inputs
audioobjectrequired- Audio file for voice cloning. Provide as {type: 'url', url: '...'}, {type: 'asset_id', asset_id: '...'}, or {type: 'base64', media_type: '...', data: '...'}.
voice_namestringrequired- Display name for the cloned voice. Up to 100 characters; names longer than 64 characters are stored truncated to 64.
languagestring- Language hint for the voice (e.g., 'en', 'es'). Auto-detected if omitted.
remove_background_noiseboolean- Remove background noise from the audio before cloning.
heygen_create_ai_clippingTurn a long video into short highlight clips with virality scores.WriteCreate Ai Clipping
Turn a long video into short highlight clips with virality scores. Returns ai_clipping_id. Use to cut social clips from long-form video. Poll get_ai_clipping for completion.
Inputs
videoobjectrequired- Source video. Either a URL or an asset_id from POST /v1/asset.
callback_idstring- Opaque client identifier echoed verbatim in webhook payloads. Mirrors /v3/video-translations callback_id.
callback_urlstring- HTTPS URL to receive per-job webhook callbacks. Mirrors /v3/video-translations callback_url. Per-job callback_url deliveries are NOT HMAC-signed: authenticate them by verifying TLS and matching the echoed callback_id, and do not trust an unverified body. To receive a signed payload, register a webhook endpoint with a secret (the signature header is sent only to registered endpoints).
input_languagestring- ISO-639-1 source language code (e.g. 'en', 'es'). Omit for auto-detect.
output_settingsobject- Configuration for the clips the job will produce.
titlestring- Title for the job. Defaults to the source video's title if omitted.
heygen_create_avatar_consentStart the consent flow for an avatar group and return a URL where the subject approves in a browser.WriteCreate Avatar Consent
Start the consent flow for an avatar group and return a URL where the subject approves in a browser. Returns avatar_group, url. Use after creating a digital twin avatar. Needs a group_id from create_digital_twin_avatar or list_avatar_groups.
Inputs
group_idstringrequired- Unique avatar group identifier
consent_textstring- Custom consent text rendered on the consent page in place of the default HeyGen text. Available as a premium option for select Enterprise customers — e.g. to display co-branded language like "I, (Name), hereby allow HeyGen and {Company} to use footage of me...". Plain text only; rendered as text (not HTML). The characters `<` and `>` are rejected to prevent stored-HTML injection. To request access, please contact our support team.
consent_videoobject- Asset input via publicly accessible HTTPS URL.
reroute_urlstring- Callback URL where the user is redirected after completing consent. Defaults to HeyGen's consent completion page.
heygen_create_avatar_looksGenerate new looks for an existing avatar from a reference look, using a Look Pack or a look template.WriteCreate Avatar Looks
Generate new looks for an existing avatar from a reference look, using a Look Pack or a look template. Returns group_id, looks. Use to expand an avatar with new outfits or styles. Find reference_look_id with list_avatar_looks and template ids with list_look_templates.
Inputs
reference_look_idstringrequired- An existing avatar look used as the identity reference. The new looks are added to its avatar.
template_idstringrequired- The Look Pack template to apply: a public template, or an enterprise custom pack assigned to your workspace.
typestringrequired- Generation method. 'look_pack' applies a Look Pack template.one of
look_packtemplate aspect_ratiostring- Output aspect ratio, '16:9' by default. Generation is always 16:9; '9:16' center-crops the delivered frames to portrait as the final step.one of
16:99:16
heygen_create_avatar_videoCreate a video where a HeyGen avatar speaks a script or audio file with lip-sync.WriteCreate Avatar Video
Create a video where a HeyGen avatar speaks a script or audio file with lip-sync. Returns video_id, status, output_format. Use for presenter-style videos with a chosen avatar. Use create_image_video to animate a still image, create_studio_video for multi-scene compositions, and create_video_agent_session to generate from a prompt alone. Find avatar_id with list_avatar_looks and voice_id with list_voices. Poll get_video for completion.
Inputs
avatar_idstringrequired- HeyGen avatar ID (video avatar or photo avatar look ID).
aspect_ratiostring- Output video aspect ratio. - ``16:9`` / ``9:16``: classic landscape / portrait. - ``4:5`` / ``5:4`` / ``1:1``: social-media-friendly ratios. Output is short-edge anchored to the requested resolution (e.g. ``1080p`` 1:1 → 1080x1080, ``1080p`` 4:5 → 1080x1350). - ``auto``: preserve the source's aspect ratio. The dimensions are derived from the avatar's source frames (``avatar_id``) or the uploaded image (``image_url`` / ``image_asset_id``), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to ``16:9`` when source dimensions can't be read.one of
16:99:164:55:41:1auto audio_asset_idstring- HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.
audio_urlstring- Public URL of an audio file to lip-sync. Mutually exclusive with script.
backgroundobject- Background configuration for the generated video.
brand_glossary_idstring- Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.
callback_idstring- Caller-defined identifier echoed back in the webhook payload.
callback_urlstring- Webhook URL to receive a POST notification when the video is ready.
captionobject- Caption generation settings for video creation. A sidecar subtitle file is always generated and returned via ``subtitle_url`` in the chosen ``file_format``. When ``style`` is also set, captions are additionally burned into the rendered video — the sidecar is still delivered.
engineobject- Avatar V engine configuration with cross-reference-driven animation.
expressivenessstring- Avatar expressiveness level for photo avatars.one of
highmediumlow fitstring- How the avatar is scaled to the output canvas.one of
containcover folder_idstring- Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. Supported only for single-video creation; batch video items cannot set their own destination folder.
motion_promptstring- Natural-language prompt controlling avatar body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars when engine.type is 'avatar_v'. Rejected for video avatars on the default Avatar IV engine, and for photo avatars on 'avatar_v' when the avatar's group has no animation reference (no digital twin or curated reference look).
output_formatstring- Output container for the generated video.one of
mp4webm remove_backgroundboolean- Remove the avatar background. Video avatars must be trained with matting enabled.
resolutionstring- Output video resolution. `4k` is available for Avatar III digital twins and studio avatars.one of
4k1080p720p scriptstring- Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id.
titlestring- Display title for the video in the HeyGen dashboard.
voice_idstring- Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).
voice_settingsobject- Voice tuning parameters for text-to-speech. Applies only when 'script' + 'voice_id' are provided — not when audio_url/audio_asset_id is used (uploaded audio bypasses TTS).
watermarkobject- Watermark configuration for video creation.
heygen_create_background_removalSubmit a video for background removal.WriteCreate Background Removal
Submit a video for background removal. Returns id, status, layers, duration, created_at, completed_at, error. Use to produce a transparent or keyed version of a video. Poll get_background_removal for completion.
Inputs
videoobjectrequired- Input video to remove the background from (url, asset_id, or base64).
layersarray- Output layers to return. Any of: 'foreground' (subject on a transparent background), 'mask' (grayscale alpha matte), 'background' (the scene with the subject removed). Defaults to all three.
request_idstring- Client-provided idempotency key — *the* idempotency mechanism for this endpoint. Re-sending the same `request_id` returns the *original* job (same `id`, same `status`, same charge) instead of creating a new one — the dedup is over (`space_id`, `request_id`), not over the response body, so a duplicate `request_id` with different content still collides on the original job. The HTTP `Idempotency-Key` header is *not* honored here; pick a per-content `request_id` if you need per-content dedup.
titlestring- Optional human-readable title for the job.
heygen_create_brand_glossaryCreate a brand glossary of pronunciations, do-not-translate terms, and forced translations.WriteCreate Brand Glossary
Create a brand glossary of pronunciations, do-not-translate terms, and forced translations. Returns brand_glossary_id, name, created_at, updated_at, terms, do_not_translate_terms, forced_translations. Use to control how terms are spoken and translated in videos.
Inputs
namestringrequired- Display name for the glossary. Surrounding whitespace is removed, and the trimmed name must be 1-64 characters and unique within your workspace, compared without regard to case.
do_not_translate_termsarray- Terms to keep untranslated when this glossary is used by a translation feature. Omit it, or pass an empty array, to add none.
forced_translationsarray- Force Translate rules: terms translated into an exact replacement when this glossary is used by a translation feature. Omit it, or pass an empty array, to add none. A term should not appear in both this list and `do_not_translate_terms`; behavior is undefined if it does.
termsarray- Term-to-pronunciation mappings. Omit it, or pass an empty array, to create a glossary you fill in later.
heygen_create_brand_kitCreate a brand kit by importing logos, colors, and fonts from a public website URL.WriteCreate Brand Kit
Create a brand kit by importing logos, colors, and fonts from a public website URL. Returns brand_kit_id, status. Use to capture a company's brand for videos. Poll get_brand_kit while status is loading.
Inputs
urlstringrequired- Public website URL to build the brand kit from. HeyGen visits the site and imports the brand assets it finds there, including logos, colors and font files. By calling this endpoint you confirm you have the rights and licenses necessary to upload, store and use those assets in HeyGen.
namestring- Name for the brand kit, up to 256 characters. Defaults to the brand name detected on the site, or its domain.
heygen_create_cinematic_avatar_videoCreate a cinematic video of an avatar from a motion prompt.WriteCreate Cinematic Avatar Video
Create a cinematic video of an avatar from a motion prompt. Returns video_id, status, output_format. Use for prompt-driven cinematic avatar clips. Use create_avatar_video for scripted presenter videos. Find avatar_id with list_avatar_looks. Poll get_video for completion.
Inputs
avatar_idarrayrequired- Avatar look ID(s) used as visual references. Provide 1 to 3 look IDs.
promptstringrequired- Natural-language prompt describing the video to generate.
aspect_ratiostring- Output aspect ratio. Supported for cinematic_avatar: '16:9', '9:16', '1:1'. Defaults to '16:9'.one of
16:99:161:1 auto_durationboolean- Let the model choose the video length. When true, omit duration.
durationinteger- Video length in seconds (4–15). Defaults to 10. Omit when auto_duration is true.
enhance_promptboolean- Enable server-side prompt enhancement.
folder_idstring- Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. Supported only for single-video creation; batch video items cannot set their own destination folder.
referencesarray- Reference assets (images, videos, or audio) guiding the generation. Each accepts a URL, an asset_id, or inline base64. Combined limits: at most 3 videos and 9 images across avatars and references.
resolutionstring- Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.one of
720p1080p titlestring- Display title for the video in the HeyGen dashboard.
heygen_create_digital_twin_avatarTrain a digital twin avatar from footage of a person.WriteCreate Digital Twin Avatar
Train a digital twin avatar from footage of a person. Returns avatar_item, avatar_group. Use for a realistic clone of a real person from video. Consent from the person is required. Call create_avatar_consent for the resulting group before the twin can be used. Poll get_avatar_group for status.
Inputs
fileobjectrequired- Footage of the avatar — provide as {"type": "url", "url": "https://..."} or {"type": "asset_id", "asset_id": "..."}
namestringrequired- Name of the avatar.
avatar_group_idstring- Optional identity you would like to attach the digital twin to. By default it will create a new identity.
heygen_create_filler_word_removalRemove filler words and long silences from a finished video.WriteCreate Filler Word Removal
Remove filler words and long silences from a finished video. Returns filler_word_removal_id. Use to tighten a recorded video. Poll get_filler_word_removal for completion.
Inputs
videoobjectrequired- Source video to clean. Either a URL or an asset_id from POST /v1/asset.
callback_idstring- Opaque client identifier echoed verbatim in webhook payloads.
callback_urlstring- HTTPS URL to receive per-job webhook callbacks (filler_word_removal.success / filler_word_removal.fail). Delivery is best-effort with limited retries — poll GET /v3/filler-word-removals/{id} as the source of truth (a terminal GET may precede its webhook). Per-job callback_url deliveries are NOT HMAC-signed: authenticate them by verifying TLS and matching the echoed callback_id, and do not trust an unverified body. To receive a signed payload, register a webhook endpoint with a secret via /v3/webhooks/endpoints.
titlestring- Display title for the job. Defaults to 'Filler Removal' if omitted.
heygen_create_folderCreate a folder at the root or inside a parent folder.WriteCreate Folder
Create a folder at the root or inside a parent folder. Returns folder_id, name, parent_id, type, is_trash, created_at, updated_at, creator_username. Use to organize videos; pass the folder_id when creating videos.
Inputs
namestringrequired- Folder name, 1-256 characters. Sibling folders may share a name.
parent_idstring- ID of the folder to create this one in. Omit, pass null, or pass an empty string to create it at the workspace root. The parent must be a folder in the caller's workspace, of a kind this endpoint creates, that is not in the trash. Assets library folders are flat and cannot hold folders.
typestring- The kinds POST /v3/folders creates, and the kinds a parent_id may name. Assets library folders ('asset') are created in the HeyGen app; existing ones are accepted as a folder_id destination and returned by GET /v3/folders/{folder_id}.one of
mixedvideovideo_translate
heygen_create_heygen_imageGenerate one to five identity-preserving portraits from reference images.WriteCreate Heygen Image
Generate one to five identity-preserving portraits from reference images. Returns generation_id, status. Use to put one identity into new scenes. Use create_image for general imagery. Poll get_heygen_image for completion.
Inputs
identity_imagesarrayrequired- One to five images of the identity to preserve.
modelstringrequired- Required identity-focused image model. Only heygen-image-1 is supported.one of
heygen-image-1 reference_imagesarrayrequired- Supply exactly one image whose clothing, pose, composition, and background should guide the result.
aspect_ratiostring- Output aspect ratio. Omit to match the reference image after EXIF orientation. Explicit presets are exact; inferred ratios round to the nearest pixel. Output resolution follows the model's canvas policy; read width and height from each result.one of
1:12:33:23:44:34:55:49:1616:9 modestring- Generation operation. Only identity_remix is supported. Defaults to identity_remix when omitted.one of
identity_remix num_imagesinteger- Number of images to generate in this job. Supports one to five.
seedinteger- Seed for the first image. Each subsequent image increments the seed by one. A random seed is chosen when omitted.
heygen_create_heygen_videoGenerate a short clip with its own audio from text, an image, or references using HeyGen Video.WriteCreate Heygen Video
Generate a short clip with its own audio from text, an image, or references using HeyGen Video. Returns video_id, status, input_video_duration. Use for 5 to 15 second prompt-driven clips. Poll get_heygen_video for completion.
Inputs
modestringrequired- Generate from the prompt alone.one of
image_to_videoreference_to_videotext_to_video modelstringrequired- Required video generation model. Only heygen-video-1 is supported.one of
heygen-video-1 promptstringrequired- Instructions for the video to generate. At most 16,000 Unicode characters.
aspect_ratiostring- Output aspect ratio for text-to-video. Defaults to 16:9.one of
21:916:94:31:13:49:16 callback_idstring- Client tracking ID echoed in the terminal webhook event.
callback_urlstring- HTTPS webhook URL for the terminal generation event.
durationinteger- Requested video duration: whole seconds from 5 through 15, or auto. Defaults to 5 when omitted. Auto selects a duration based on the prompt. Generation and billing use the resolved duration.
imageobject- First-frame image.
prompt_enhancementstring- Prompt enhancement mode: turbo, quality, ultraquality, or disabled. Defaults to quality; default is an alias for turbo.one of
turboqualitydefaultdisabledultraquality reference_audioarray- Reference audio recordings. At most three.
reference_imagesarray- Reference images. At most nine.
reference_videosarray- Reference videos. At most three.
resolutionstring- Output resolution: 480p, 768p, 1080p, or 2k. Defaults to 768p. At 1080p and 2k, text-to-video and reference-to-video require aspect_ratio 16:9 or 9:16; image-to-video follows the image proportions.one of
480p768p1080p2k seedinteger- Generation seed. A random seed is chosen when omitted.
heygen_create_imageGenerate images from a prompt, or edit reference images, with a selected image model.WriteCreate Image
Generate images from a prompt, or edit reference images, with a selected image model. Returns id, status, model, created_at, images, failure_code, failure_message. Use for general image generation. Use create_heygen_image for identity-preserving portraits. Poll get_image for completion.
Inputs
modelstringrequired- Which model to use.one of
gpt-image-2.5nano-banana-2nano-banana-2.1 promptstringrequired- What to generate, or how to edit the reference images.
aspect_ratiostring- Output aspect ratio. 16:9 when omitted.one of
1:116:99:164:33:4 num_imagesinteger- Number of images to generate, from 1 to 4.
reference_imagesarray- Reference images. When non-empty the request is an edit.
heygen_create_image_videoCreate a video where an arbitrary image speaks a script or audio file with lip-sync.WriteCreate Image Video
Create a video where an arbitrary image speaks a script or audio file with lip-sync. Returns video_id, status, output_format. Use to animate a still image or photo. Use create_avatar_video when you have a HeyGen avatar. Provide the image as a URL or an uploaded asset id. Poll get_video for completion.
Inputs
imageobjectrequired- Image to animate. Accepts URL, asset ID, or base64-encoded data.
aspect_ratiostring- Output video aspect ratio. - ``16:9`` / ``9:16``: classic landscape / portrait. - ``4:5`` / ``5:4`` / ``1:1``: social-media-friendly ratios. Output is short-edge anchored to the requested resolution (e.g. ``1080p`` 1:1 → 1080x1080, ``1080p`` 4:5 → 1080x1350). - ``auto``: preserve the source's aspect ratio. The dimensions are derived from the avatar's source frames (``avatar_id``) or the uploaded image (``image_url`` / ``image_asset_id``), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to ``16:9`` when source dimensions can't be read.one of
16:99:164:55:41:1auto audio_asset_idstring- HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.
audio_urlstring- Public URL of an audio file to lip-sync. Mutually exclusive with script.
backgroundobject- Background configuration for the generated video.
brand_glossary_idstring- Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.
callback_idstring- Caller-defined identifier echoed back in the webhook payload.
callback_urlstring- Webhook URL to receive a POST notification when the video is ready.
captionobject- Caption generation settings for video creation. A sidecar subtitle file is always generated and returned via ``subtitle_url`` in the chosen ``file_format``. When ``style`` is also set, captions are additionally burned into the rendered video — the sidecar is still delivered.
expressivenessstring- Avatar expressiveness level for photo avatars.one of
highmediumlow fitstring- How the avatar is scaled to the output canvas.one of
containcover folder_idstring- Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. Supported only for single-video creation; batch video items cannot set their own destination folder.
motion_promptstring- Natural-language prompt controlling avatar body motion. Photo avatars only.
output_formatstring- Output container for the generated video.one of
mp4webm remove_backgroundboolean- Remove the avatar background. Video avatars must be trained with matting enabled.
resolutionstring- Output video resolution. `4k` is available for Avatar III digital twins and studio avatars.one of
4k1080p720p scriptstring- Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id.
titlestring- Display title for the video in the HeyGen dashboard.
voice_idstring- Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).
voice_settingsobject- Voice tuning parameters for text-to-speech. Applies only when 'script' + 'voice_id' are provided — not when audio_url/audio_asset_id is used (uploaded audio bypasses TTS).
watermarkobject- Watermark configuration for video creation.
heygen_create_lipsyncReplace the audio on an existing video and re-animate the speaker's lips to match.WriteCreate Lipsync
Replace the audio on an existing video and re-animate the speaker's lips to match. Returns lipsync_id. Use to dub a video with new audio. Use create_video_translation to translate speech. Poll get_lipsync for completion.
Inputs
audioobjectrequired- Replacement audio — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}
videoobjectrequired- Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}
callback_idstring- ID included in webhook payload
callback_urlstring- Webhook URL for completion notifications
disable_music_trackboolean- Remove background music
enable_captionboolean- Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.
enable_dynamic_durationboolean- Allow dynamic duration adjustment
enable_speech_enhancementboolean- Enhance speech quality
enable_watermarkboolean- Add watermark to output
end_timenumber- End time in seconds for partial lipsync
folder_idstring- Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.
fps_modestring- Frame rate mode: 'vfr', 'cfr', or 'passthrough'.
keep_the_same_formatboolean- Preserve the source video's encoding specs (resolution, bitrate).
modestring- The mode.one of
speedprecision start_timenumber- Start time in seconds for partial lipsync
titlestring- Title for the lipsync job
heygen_create_musicGenerate a music track from a text prompt.WriteCreate Music
Generate a music track from a text prompt. Returns id, status, model, created_at, requested_duration_seconds, duration_seconds, audio_url, format, failure_code, failure_message. Use for custom background music. Use search_audio to pick from the catalog. The track may still be processing; poll get_music if needed.
Inputs
duration_secondsintegerrequired- Target length: 30, 60, 120 or 180. A longer render is cut to this length with a fade-out; a shorter one is kept as is.
modelstringrequired- Music model. Each model accepts its own options.one of
lyria-3-pro promptstringrequired- What the track should sound like: genre, mood, instruments, use.
bpminteger- Target tempo in beats per minute.
instrumentalboolean- No vocals. Cannot be combined with `lyrics`.
intensityinteger- Energy from 1 (ambient) to 5 (peak).
lyricsstring- Lyrics to sing verbatim. Untagged text is split into verses on blank lines. Written by the model when omitted.
heygen_create_photo_avatarCreate an avatar from a single still image.WriteCreate Photo Avatar
Create an avatar from a single still image. Returns avatar_item, avatar_group. Use to turn one photo into a reusable avatar. Use create_prompt_avatar for a synthetic character from text, and create_digital_twin_avatar for footage of a real person. Poll get_avatar_group for training status.
Inputs
fileobjectrequired- Photo asset of the avatar — provide as {"type": "url", "url": "https://..."} or {"type": "asset_id", "asset_id": "..."}
namestringrequired- Name of the avatar.
avatar_group_idstring- Optional identity you would like to attach the photo avatar to. By default it will create a new identity.
heygen_create_podcastGenerate a two-avatar conversational podcast video from a topic or source files.WriteCreate Podcast
Generate a two-avatar conversational podcast video from a topic or source files. Returns podcast_id, status. Use for dialogue-style videos. Poll get_podcast for completion.
Inputs
guest_avatar_idstringrequired- Avatar id for the guest.
guest_voice_idstringrequired- Voice id for the guest. List voices via GET /v3/voices.
host_avatar_idstringrequired- Avatar id for the host.
host_voice_idstringrequired- Voice id for the host. List voices via GET /v3/voices.
callback_idstring- Caller-defined identifier echoed back in the webhook payload so you can correlate the callback with this request.
callback_urlstring- Optional webhook URL. When set, HeyGen POSTs a notification here when the podcast reaches a terminal state (completed or failed), so you don't have to poll GET /v3/podcasts/{podcast_id}.
durationstring- Target spoken length. 'auto' lets the generator pick the length.one of
auto1min2min3min5min instructionsstring- Free-form scene/studio instructions (e.g. setting, tone). Used verbatim to describe the studio when set.
layoutstring- Output aspect ratio: 'landscape' (16:9) or 'portrait' (9:16).one of
landscapeportrait source_filesarray- Grounding documents (PDF/image/video) the script is built from. Provide each as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}. Provide `topic`, `source_files`, or both.
topicstring- Free-text topic / angle / instructions for the conversation. Provide `topic`, `source_files`, or both.
heygen_create_prompt_avatarGenerate a synthetic avatar character from a text prompt.WriteCreate Prompt Avatar
Generate a synthetic avatar character from a text prompt. Returns avatar_item, avatar_group. Use when no photo or footage exists. Use create_photo_avatar when you have an image. Poll get_avatar_group for status.
Inputs
namestringrequired- Name of the avatar.
promptstringrequired- Prompt for avatar generation.
aspect_ratiostring- Aspect ratios supported by prompt-avatar generation.one of
auto16:99:161:14:55:4 avatar_group_idstring- Optional identity (group) to save the generated avatar to. By default a new identity is created. If avatar_id is also provided, it must belong to this group.
avatar_idstring- Optional avatar id to use as the visual reference for the generation. When provided without avatar_group_id, the new avatar is saved to the referenced avatar's group; when provided with avatar_group_id, the avatar must belong to that group and the result is saved there. The referenced avatar must exist and have a usable image, otherwise the request is rejected.
reference_imagesarray- Reference images — each as {"type": "url", "url": "https://..."} or {"type": "asset_id", "asset_id": "..."}. Max 3.
heygen_create_proofread_sessionCreate a proofread session that extracts editable subtitles from a video before final rendering.WriteCreate Proofread Session
Create a proofread session that extracts editable subtitles from a video before final rendering. Returns proofread_ids, status. Use when a human should review translated subtitles before the video is rendered. Poll get_proofread_session until subtitles are ready.
Inputs
output_languagesarrayrequired- Target language codes. Use one for single proofread, multiple for batch.
titlestringrequired- Title for the proofread job
videoobjectrequired- Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}
brand_glossary_idstring- Brand glossary ID for custom term translations (e.g. translate 'Reformer' as 'Pilates equipment', not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries.
brand_voice_idstring- Brand glossary ID for custom term translations. Legacy field name for `brand_glossary_id` — both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries.
disable_music_trackboolean- Remove background music
enable_speech_enhancementboolean- Enhance speech quality
enable_video_stretchingboolean- Allow dynamic duration adjustment
folder_idstring- Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.
keep_the_same_formatboolean- Preserve the source video's encoding specs (resolution, bitrate)
modestring- The mode.one of
speedprecision speaker_numinteger- Number of speakers (improves speaker separation)
srtobject- Asset input via publicly accessible HTTPS URL.
heygen_create_studio_videoCompose avatar clips, images, and video footage into one rendered video from a list of scenes.WriteCreate Studio Video
Compose avatar clips, images, and video footage into one rendered video from a list of scenes. Returns video_id, status, output_format. Use for multi-scene compositions with global settings. Use create_avatar_video for a single avatar scene. Poll get_video for completion.
Inputs
scenesarrayrequired- Ordered list of whole-frame scenes to concatenate. Each scene is one of 'avatar_video', 'image', or 'video'. Must contain 1 to 50 scenes.
aspect_ratiostring- Output video aspect ratio. - ``16:9`` / ``9:16``: classic landscape / portrait. - ``4:5`` / ``5:4`` / ``1:1``: social-media-friendly ratios. Output is short-edge anchored to the requested resolution (e.g. ``1080p`` 1:1 → 1080x1080, ``1080p`` 4:5 → 1080x1350). - ``auto``: preserve the source's aspect ratio. The dimensions are derived from the avatar's source frames (``avatar_id``) or the uploaded image (``image_url`` / ``image_asset_id``), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to ``16:9`` when source dimensions can't be read.one of
16:99:164:55:41:1auto brand_glossary_idstring- Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies to every scene whose audio is synthesized from a script; scenes that supply their own audio URL or audio asset are unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.
callback_idstring- Caller-defined identifier echoed back in the webhook payload.
callback_urlstring- Webhook URL to receive a POST notification when the video is ready.
captionobject- Caption generation settings for video creation. A sidecar subtitle file is always generated and returned via ``subtitle_url`` in the chosen ``file_format``. When ``style`` is also set, captions are additionally burned into the rendered video — the sidecar is still delivered.
folder_idstring- Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. Supported only for single-video creation; batch video items cannot set their own destination folder.
resolutionstring- Output video resolution. `4k` is available for Avatar III digital twins and studio avatars.one of
4k1080p720p titlestring- Display title for the video in the HeyGen dashboard.
watermarkobject- Watermark configuration for video creation.
heygen_create_template_from_videoCreate a private template from one of your videos, copying its scenes, avatars, script, and media.WriteCreate Template From Video
Create a private template from one of your videos, copying its scenes, avatars, script, and media. Returns id, name, thumbnail_url, aspect_ratio, created_at, updated_at, variables, source_video_id, edit_version, scene_ids. Use to turn a finished video into a reusable template. Needs a video_id from list_videos.
Inputs
video_idstringrequired- ID of a video in your workspace to turn into a template. The video must have been generated with POST /v3/videos or saved in the HeyGen editor; its draft becomes the template's starting point.
namestring- Template name. Defaults to the source video's title.
heygen_create_transcriptionTranscribe an audio or video file.WriteCreate Transcription
Transcribe an audio or video file. Returns id, status, model, created_at, language, duration_seconds, text, segments, failure_code, failure_message. Use to get a transcript of media. Provide the media as a URL or an uploaded asset id.
Inputs
audioobjectrequired- The audio or video file to transcribe, as a url, an asset_id or inline base64.
modelstringrequired- Transcription model.one of
scribe-v2 diarizeboolean- Label speakers. Audio is limited to 10 minutes with this on and 30 minutes with it off.
languagestring- Spoken language as a lowercase ISO 639 code, such as `en`. Detected from the audio when omitted.
num_speakersinteger- Expected number of speakers; only valid with `diarize` true.
word_timestampsboolean- Return per-word timings in each segment.
heygen_create_video_agent_sessionStart a Video Agent session that writes the script, picks avatar and scenes, and renders a video from a text prompt.WriteCreate Video Agent Session
Start a Video Agent session that writes the script, picks avatar and scenes, and renders a video from a text prompt. Returns session_id, status, video_id, created_at. Use for one-shot prompt-to-video generation. Use create_avatar_video when you need explicit control of avatar, voice, and script. Poll get_video_agent_session until it completes.
Inputs
promptstringrequired- The message/prompt for video generation (1-10000 characters)
avatar_idstring- Specific avatar ID to use
brand_glossary_idstring- Brand glossary ID controlling how custom terms are pronounced in the generated video's narration (for example, saying 'HeyGen' as 'hey-jen'). Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.
brand_kit_idstring- Brand kit ID to apply brand colors, fonts, and logos to the generated video. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted; omit this field to apply the workspace default automatically.
callback_idstring- Optional callback ID included in webhook payload
callback_urlstring- Webhook URL for completion/failure notifications
filesarray- Optional file attachments (max 20 files)
incognito_modeboolean- When enabled, disables memory injection and extraction for this session
membersarray- Email addresses to grant access to. Valid only with `visibility: selected`, and every address must belong to a member of the caller's workspace (max 100). May be omitted or empty, leaving the session owner-only until members are added.
modestring- The mode.one of
generatechat orientationstring- Video orientation. If not provided, auto-detected from content.one of
landscapeportrait style_idstring- Style ID from GET /v3/video-agents/styles. Applies a curated visual template to the generated video.
visibilitystring- Who can open the session. `private`: the owner only. `space`: everyone in the workspace can open and drive the session. `selected`: the owner plus the workspace members listed in `members`. Defaults to `space`. Applies to the session and its conversation; does not change existing sessions.one of
privatespaceselected voice_idstring- Specific voice ID to use for narration
heygen_create_video_generationGenerate a video from a text prompt with a selected video model.WriteCreate Video Generation
Generate a video from a text prompt with a selected video model. Returns id, status, model, created_at, duration, resolution, aspect_ratio, video_url, duration_seconds, failure_code. Use for prompt-to-video clips without avatars. Use create_avatar_video for avatar presenters. Poll get_video_generation for completion.
Inputs
modelstringrequired- Video model. Each model accepts its own options.one of
minimax-h3-maxseedance-2.5 promptstringrequired- What the video should show.
aspect_ratiostring- Output aspect ratio.one of
16:91:19:16 callback_idstring- Caller-defined identifier echoed back in the webhook payload.
callback_urlstring- Webhook URL to receive a POST notification (`video_generation.success` or `video_generation.fail`) when the generation finishes, in addition to the workspace's configured webhook endpoints.
durationinteger- Output length in whole seconds, 4 to 30.
end_frameobject- Asset input via publicly accessible HTTPS URL.
first_frameobject- Asset input via publicly accessible HTTPS URL.
generate_audioboolean- Generate a soundtrack with the video. It does not change the price.
middle_frameobject- Asset input via publicly accessible HTTPS URL.
middle_frame_timenumber- Seconds from the start at which `middle_frame` guides the video, required with it. It is rounded to the nearest frame at 24 fps and must fall strictly between the first and last frames of `duration`.
prompt_expansion_modestring- How much the prompt is rewritten before generation: `disabled` sends it as written, `balanced` takes about a second, `quality` up to about 30 seconds for a richer prompt. It does not change the price.one of
disabledbalancedquality reference_audioarray- Reference audio clips, at most 3, each 2 to 15 seconds and 15 seconds in total. Each adds about 80 tokens a second to the references' total. Reference images, videos and audio clips together are at least 1 and at most 12 files, and their tokens past the first 4,096 add to the price.
reference_imagesarray- Reference images, at most 30.
reference_videosarray- Reference videos, at most 10, each 2 to 10 seconds and 30 seconds in total. Their length adds to the price.
resolutionstring- Output resolution.one of
480p720p1080p seedinteger- Generation seed. A random seed is chosen when omitted.
heygen_create_video_translationTranslate a video into one or more target languages with voice cloning and lip-sync.WriteCreate Video Translation
Translate a video into one or more target languages with voice cloning and lip-sync. Returns video_translation_ids. Use to localize a video. Use create_lipsync to replace audio without translating. Find language names with list_translation_languages. Poll get_video_translation for completion.
Inputs
output_languagesarrayrequired- Target language names (e.g. 'Chinese (Cantonese, Traditional)', 'Spanish (Spain)', 'English'). Use GET /v3/video-translations/languages for valid values. Use one for single translation, multiple for batch.
videoobjectrequired- Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}
audioobject- Asset input via publicly accessible HTTPS URL.
brand_glossary_idstring- Brand glossary ID for custom term translations (e.g. translate 'Reformer' as the Pilates equipment, not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries.
brand_voice_idstring- Brand glossary ID for custom term translations. Legacy field name for `brand_glossary_id` — both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries.
callback_idstring- ID included in webhook payload
callback_urlstring- Webhook URL for completion notifications
disable_music_trackboolean- Remove background music
enable_captionboolean- Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.
enable_dynamic_durationboolean- Allow dynamic duration adjustment
enable_speech_enhancementboolean- Enhance speech quality
enable_watermarkboolean- Add watermark to output
end_timenumber- End time in seconds for partial translation
folder_idstring- Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.
fps_modestring- Frame rate mode for the output video. 'vfr' = variable frame rate, 'cfr' = constant frame rate, 'passthrough' = match the source. Only takes effect when a custom 'audio' track is provided.one of
vfrcfrpassthrough input_languagestring- Source language code (auto-detected if omitted)
keep_the_same_formatboolean- Preserve the source video's encoding specs (resolution, bitrate).
modestring- The mode.one of
speedprecision speaker_numinteger- Number of speakers (improves speaker separation)
srtobject- Asset input via publicly accessible HTTPS URL.
srt_rolestring- Which video the subtitle applies to: 'input' (source) or 'output' (translated).one of
inputoutput start_timenumber- Start time in seconds for partial translation
stock_voice_configobject- Stock-voice options for a video translation request. Use a preset HeyGen voice for the translation instead of recreating the original speaker's voice. Enterprise feature, available for selected accounts and languages by request. See the ``stock_voice_config`` request field for usage.
titlestring- Title for the translation job
translate_audio_onlyboolean- Only translate audio, keep original video
heygen_design_voiceFind up to three voices that match a natural-language description.WriteDesign Voice
Find up to three voices that match a natural-language description. Returns voices, seed. Use to discover a voice by style (for example, warm and confident narrator). Use list_voices to filter by attributes.
Inputs
promptstringrequired- Natural language description of the desired voice (e.g., 'warm, confident female narrator').
genderstring- Filter by gender: 'male' or 'female'.
localestring- BCP-47 locale tag to filter by (e.g., 'en-US', 'pt-BR').
seedinteger- Controls which batch of results to return. seed=0 returns the top matches, seed=1 the next batch, etc. Same prompt + seed always returns the same voices.
heygen_edit_videoEdit a video's scenes and render it again under the same video id.WriteEdit Video
Edit a video's scenes and render it again under the same video id. Returns video_id, status, version_id, inserted_scenes. Use to revise an existing video. Use create_avatar_video for a new one. Call get_video_scenes first to read scene ids and the current edit_version.
Inputs
edit_versionstringrequired- The edit_version from the scenes read you are editing from. The edit is refused if the video changed since. The video refuses edits while it renders, and the render updates its document, so after the render finishes, read the scenes again for the next edit.
video_idstringrequired- Unique video identifier
actionsarray- Scene inserts, deletions and reordering, applied in order after the field edits in 'scenes' and before the render, at most 1000 actions and 50 inserts, whose image scenes' set durations total at most 1800s. The video must keep at least one scene, and an edit cannot grow it past 50 scenes: a video that already has more can be edited, but not grown. Anything the scenes read shows as a field is changed through 'scenes', never here.
callback_idstring- Caller-defined identifier echoed back in the webhook payload.
callback_urlstring- Webhook URL to receive a POST notification when the video is ready.
scenesarray- Field edits to existing scenes, one entry per scene that changes, at most 1000, and at most 10000 script entries and elements in total. Scenes not listed are unchanged. Applied before any action in 'actions'.
heygen_generate_speechSynthesize speech audio from text with a catalog voice.WriteGenerate Speech
Synthesize speech audio from text with a catalog voice. Returns audio_url, duration, request_id, word_timestamps, engine. Use for audio-only output. Use create_avatar_video when you need a video. Find voice_id with list_voices.
Inputs
textstringrequired- Text to synthesize (1-5000 characters). Break tags must express time in seconds (for example, <break time="0.35s"/>); millisecond values are not supported.
voice_idstringrequired- Voice ID from the voice catalog. Professional voice clones use model speech generation instead.
enginestring- Speech engine override for this request only. Omit to use the voice's saved default, including your saved preference. Voices without a concrete saved default retain Starfish. Unsupported defaults or overrides return an error; engines are never silently substituted. Use 'heygen_voice' for HeyGen Voice; 'orca' remains accepted as its legacy alias. Responses retain 'orca' for compatibility. ElevenLabs model variants are selected through settings.model_id. The deprecated elevenlabs_v3 engine retains its existing behavior while callers and saved defaults migrate.one of
heygen_voicestarfishorcaelevenlabselevenlabs_v3 force_regenerateboolean- Bypass HeyGen's speech cache and request fresh synthesis. Normal speech quota applies. Defaults to false.
input_typestring- Type of the input: 'text' for plain text, 'ssml' for SSML markup. Defaults to 'text'.
languagestring- Base language code (e.g. 'en', 'pt', 'zh'). Optional — auto-detected from text when omitted.
localestring- Locale tag for Starfish (e.g. 'zh-HK'). ElevenLabs does not support locale selection; use language instead.
settingsobject- Request-only ElevenLabs model settings. Applied after saved preferences; valid for elevenlabs or the deprecated elevenlabs_v3 compatibility engine.
speednumber- Speed multiplier (0.5-2.0).
heygen_generate_video_from_proofreadStart final video generation using the approved subtitles of a proofread session.WriteGenerate Video From Proofread
Start final video generation using the approved subtitles of a proofread session. Returns video_translation_id, status. Use as the last step of the proofread flow. Needs a proofread_id with approved subtitles.
Inputs
proofread_idstringrequired- Unique proofread identifier
callback_idstring- ID included in webhook payload
callback_urlstring- Webhook URL for completion notifications
captionsboolean- Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.
translate_audio_onlyboolean- Only translate audio, keep original video
heygen_generate_video_from_templateGenerate a video from a template by filling its variables.WriteGenerate Video From Template
Generate a video from a template by filling its variables. Returns id, title, status, created_at, completed_at, video_url, thumbnail_url, gif_url, captioned_video_url, subtitle_url. Use for repeatable, branded videos. Use create_avatar_video for one-off videos. Call get_template for the variable names. Poll get_video for completion.
Inputs
template_idstringrequired- Unique template identifier
variablesobjectrequired- Template variable replacements, keyed by the variable name defined in the template. Supply every text variable you want filled: an omitted text variable is not substituted, so its literal `{{variable_name}}` placeholder remains in the text it is bound to, whether that is a spoken script or an on-screen text element. Omitting an image, video, audio, character or voice variable is safe and keeps the value the template already holds. The defaults returned by `GET /v3/templates/{template_id}` are the template's current values, not fallbacks applied at generation time.
brand_glossary_idstring- Brand glossary controlling how custom terms are pronounced in generated speech. Discover IDs via GET /v3/brand-glossaries.
brand_voice_idstring- Legacy field name for `brand_glossary_id`. Both are accepted and resolve to the same workspace record. Prefer `brand_glossary_id`.
callback_idstring- Opaque ID echoed back in webhook events for this video
callback_urlstring- URL called with the video result in addition to registered webhook endpoints
captionboolean- Whether to burn captions into the video
dimensionobject- Output resolution override. Must keep the template's aspect ratio.
enable_sharingboolean- Whether the generated video's share page is publicly accessible
folder_idstring- Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. Supported only for single-video creation; batch video items cannot set their own destination folder.
fpsnumber- Output frame rate. One of 25, 30, or 60.
include_gifboolean- Whether to include a GIF preview in the webhook payload
keep_text_vertically_centeredboolean- When true, replaced text elements are vertically re-centered based on their rendered height
reorder_musicboolean- When true (default), background audio tracks move with their scenes. When false, tracks stay pinned to layout positions.
scene_idsarray- Scene IDs to render, in order (repeats allowed). Scenes must already exist in the template; the API can select, reorder, and repeat scenes but cannot create new ones. Omit to render all scenes in template order.
subtitlesobject- Output subtitle style settings (mirrors the /v3/videos subtitles input).
titlestring- Title for the generated video
heygen_send_video_agent_messageSend a follow-up message or revision request to an existing Video Agent session.WriteSend Video Agent Message
Send a follow-up message or revision request to an existing Video Agent session. Returns session_id, run_id, title, video_id. Use to answer the agent's questions or request changes. Provide a message, an edit_plan of scene edits, or both. Use stop_video_agent_session to halt a run. Needs a session_id from create_video_agent_session.
Inputs
session_idstringrequired- Session ID
avatar_idstring- Override avatar for this message
brand_kit_idstring- Brand kit ID to apply for this message. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted.
edit_planarray- Scene-scoped natural-language edits to validate and submit atomically. Required when message is omitted or empty.
filesarray- Optional file attachments (max 20 files)
messagestring- Text message to the agent. Required when edit_plan is omitted; may be omitted or empty when edit_plan is provided.
voice_idstring- Override voice for this message
heygen_set_template_variablesReplace a template's full set of variables; omitted variables are removed.WriteSet Template Variables
Replace a template's full set of variables; omitted variables are removed. Returns id, name, thumbnail_url, aspect_ratio, created_at, updated_at, variables, source_video_id, edit_version, scene_ids. Use to redefine which parts of a template are fillable. Call get_template first and resend every variable you want to keep.
- Idempotent
Inputs
template_idstringrequired- Unique template identifier
variablesobjectrequired- The complete variable set, keyed by variable name (letters, digits, underscores; must start with a letter or underscore; at most 64 characters). An empty object removes every variable.
expected_edit_versionstring- The template's edit_version from your last GET. When given, the update is rejected with 409 stale_edit_version if the template changed since. Omit to overwrite unconditionally.
heygen_stop_video_agent_sessionHalt an active Video Agent run at its next checkpoint, keeping partial results.WriteStop Video Agent Session
Halt an active Video Agent run at its next checkpoint, keeping partial results. Returns session_id. Use to cancel a run that is going the wrong way. Needs a session_id from create_video_agent_session.
Inputs
session_idstringrequired- Session ID
heygen_update_avatar_groupUpdate an avatar group you own, such as its default voice.WriteUpdate Avatar Group
Update an avatar group you own, such as its default voice. Returns id, name, preview_image_url, preview_video_url, gender, created_at, looks_count, default_voice_id, consent_status, status. Use to set the voice an avatar speaks with by default. Needs a group_id from list_avatar_groups and a voice id from list_voices.
Inputs
group_idstringrequired- Unique avatar group identifier
default_voice_idstring- Voice ID to set as the avatar's default voice, replacing the current one. The voice is also linked to the avatar group if it was not already. Accepts any voice available to your workspace, including imported voice clones. Only supported for avatars you own.
heygen_update_avatar_lookRename an avatar look.WriteUpdate Avatar Look
Rename an avatar look. Only photo avatar and digital twin looks are supported. Returns id, name, avatar_type, group_id, preview_image_url, preview_video_url, gender, tags, default_voice_id, supported_api_engines. Use to change a look's display name. Needs a look_id from list_avatar_looks.
Inputs
look_idstringrequired- Unique avatar look identifier. This is the value to pass as avatar_id to POST /v3/videos.
namestring- New display name for the look.
heygen_update_brand_glossaryUpdate a brand glossary; an omitted field is left untouched and a list you send replaces the existing list.WriteUpdate Brand Glossary
Update a brand glossary; an omitted field is left untouched and a list you send replaces the existing list. Returns brand_glossary_id, name, created_at, updated_at, terms, do_not_translate_terms, forced_translations. Use to change glossary terms. Needs a brand_glossary_id from list_brand_glossaries.
Inputs
brand_glossary_idstringrequired- Unique brand glossary identifier
do_not_translate_termsarray- Replacement Don't Translate list. Omit to leave the existing entries untouched, or pass an empty array to remove them all.
forced_translationsarray- Replacement Force Translate list. Omit to leave the existing entries untouched, or pass an empty array to remove them all. A term should not appear in both this list and `do_not_translate_terms`; behavior is undefined if it does.
namestring- New display name. Surrounding whitespace is removed, and the trimmed name must be 1-64 characters and unique within your workspace, compared without regard to case. Omit to keep the current name.
termsarray- Replacement term list. Omit to leave the existing terms untouched, or pass an empty array to remove them all.
heygen_update_brand_kitRename a brand kit or reassign which color, logo, and font play which role.WriteUpdate Brand Kit
Rename a brand kit or reassign which color, logo, and font play which role. Returns brand_kit_id, name, status, colors, color_roles, logos, logo_roles, fonts, font_roles. Use to adjust an imported brand kit. Needs a brand_kit_id from list_brand_kits.
Inputs
brand_kit_idstringrequired- Unique brand kit identifier
color_rolesobject- Color role assignment to write. Unknown keys are rejected.
font_rolesobject- Typographic role assignment to write. Unknown keys are rejected.
logo_rolesobject- Logo role assignment to write. Unknown keys are rejected.
namestring- New display name for the brand kit, 1-256 characters. Leading and trailing whitespace is trimmed.
heygen_update_lipsyncUpdate the display title of a lipsync job.WriteUpdate Lipsync
Update the display title of a lipsync job. Returns id, title, status, duration, video_url, caption_url, callback_id, created_at, failure_message. Use to rename a lipsync job. Needs a lipsync_id from list_lipsyncs.
Inputs
lipsync_idstringrequired- Unique lipsync identifier
titlestringrequired- New title for the lipsync
heygen_update_templateRename a template.WriteUpdate Template
Rename a template. Returns id, name, thumbnail_url, aspect_ratio, created_at, updated_at, variables, source_video_id, edit_version, scene_ids. Use to change a template's title. Use set_template_variables to change its variables. Needs a template_id from list_templates.
Inputs
namestringrequired- New template name
template_idstringrequired- Unique template identifier
heygen_update_video_translationUpdate the display title of a video translation job.WriteUpdate Video Translation
Update the display title of a video translation job. Returns id, title, status, output_language, input_language, duration, translate_audio_only, video_url, audio_url, srt_caption_url. Use to rename a translation. Needs a video_translation_id from list_video_translations.
Inputs
titlestringrequired- New title for the video translation
video_translation_idstringrequired- Unique video translation identifier
heygen_upload_proofread_srtReplace a proofread session's subtitles with an edited SRT file.WriteUpload Proofread Srt
Replace a proofread session's subtitles with an edited SRT file. Returns id, title, status, output_language, input_language, submitted_for_review, created_at, failure_message. Use after editing the subtitles from download_proofread_srt. Needs a proofread_id for a completed session.
- Idempotent
Inputs
proofread_idstringrequired- Unique proofread identifier
srtobjectrequired- SRT file — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}
heygen_delete_ai_clippingSoft-delete an AI clipping job and its clips.DestructiveDelete Ai Clipping
Soft-delete an AI clipping job and its clips. Returns id. Use only when the clips are no longer needed. Needs a job_id from list_ai_clippings.
- Idempotent
Inputs
job_idstringrequired- Unique AI clip job identifier
heygen_delete_assetPermanently delete an asset in the workspace.DestructiveDelete Asset
Permanently delete an asset in the workspace. Returns id. Use only when the asset is no longer needed. Needs an asset_id from list_assets.
- Idempotent
Inputs
asset_idstringrequired- Unique asset identifier
heygen_delete_avatar_groupPermanently delete an avatar group and all of its looks.DestructiveDelete Avatar Group
Permanently delete an avatar group and all of its looks. Returns id. Use only when the whole character is no longer needed. Use delete_avatar_look to remove one look. Public and community groups cannot be deleted.
- Idempotent
Inputs
group_idstringrequired- Unique avatar group identifier
heygen_delete_avatar_lookDelete an avatar look.DestructiveDelete Avatar Look
Delete an avatar look. Studio avatars cannot be deleted. Returns id. Use to remove one look. Use delete_avatar_group to remove the whole character. Needs a look_id from list_avatar_looks.
- Idempotent
Inputs
look_idstringrequired- Unique avatar look identifier. This is the value to pass as avatar_id to POST /v3/videos.
heygen_delete_background_removalSoft-delete a background removal job.DestructiveDelete Background Removal
Soft-delete a background removal job. Returns id, deleted. Use only when the output is no longer needed. Needs a job_id from list_background_removals.
- Idempotent
Inputs
job_idstringrequired- Background removal job id
heygen_delete_brand_glossaryDelete a brand glossary so its rules stop applying.DestructiveDelete Brand Glossary
Delete a brand glossary so its rules stop applying. Returns brand_glossary_id. Use only when the glossary is no longer needed. Needs a brand_glossary_id from list_brand_glossaries.
- Idempotent
Inputs
brand_glossary_idstringrequired- Unique brand glossary identifier
heygen_delete_brand_kitPermanently delete a brand kit with its colors, logos, and fonts.DestructiveDelete Brand Kit
Permanently delete a brand kit with its colors, logos, and fonts. Returns brand_kit_id. Use only when the kit is no longer needed. Needs a brand_kit_id from list_brand_kits.
- Idempotent
Inputs
brand_kit_idstringrequired- Unique brand kit identifier
heygen_delete_lipsyncPermanently delete a lipsync job and its associated files.DestructiveDelete Lipsync
Permanently delete a lipsync job and its associated files. Returns id. Use only when the job is no longer needed. Needs a lipsync_id from list_lipsyncs.
- Idempotent
Inputs
lipsync_idstringrequired- Unique lipsync identifier
heygen_delete_podcastSoft-delete a podcast so it no longer appears in get or list.DestructiveDelete Podcast
Soft-delete a podcast so it no longer appears in get or list. Returns data. Use only when the podcast is no longer needed. It does not cancel in-flight generation. Needs a podcast_id from list_podcasts.
- Idempotent
Inputs
podcast_idstringrequired- Unique podcast identifier
heygen_delete_proofread_sessionDelete a proofread session, removing it from listings.DestructiveDelete Proofread Session
Delete a proofread session, removing it from listings. Returns id. Use to discard an abandoned session. Needs a proofread_id from list_proofread_sessions.
- Idempotent
Inputs
proofread_idstringrequired- Unique proofread identifier
heygen_delete_templateSoft-delete a template so it can no longer generate videos.DestructiveDelete Template
Soft-delete a template so it can no longer generate videos. Returns id, deleted. Use when a template is retired. Videos already generated remain. Needs a template_id from list_templates.
- Idempotent
Inputs
template_idstringrequired- Unique template identifier
heygen_delete_videoPermanently delete a video and its associated files.DestructiveDelete Video
Permanently delete a video and its associated files. Returns id, deleted. Use only when the video is no longer needed; it cannot be undone. Needs a video_id from list_videos.
- Idempotent
Inputs
video_idstringrequired- Unique video identifier
heygen_delete_video_translationPermanently delete a video translation and its associated files.DestructiveDelete Video Translation
Permanently delete a video translation and its associated files. Returns id. Use only when the translation is no longer needed. Needs a video_translation_id from list_video_translations.
- Idempotent
Inputs
video_translation_idstringrequired- Unique video translation identifier
heygen_delete_voiceDelete a voice clone you own, freeing a slot against your clone limit.DestructiveDelete Voice
Delete a voice clone you own, freeing a slot against your clone limit. Returns voice_id. Use to remove an unused clone. A voice used by a template cannot be deleted. Needs a voice_id from list_voices.
- Idempotent
Inputs
voice_idstringrequired- Unique voice identifier
No tools match.
