Skip to main content
HeyGen logo
  • Category: media generation
  • Auth: API_KEY
  • Composio-managed OAuth available? N/A
  • Tools: 78
  • Triggers: 0
  • Slug: HEYGEN
  • Version: 20261101_00

Tools

Slug: HEYGEN_ADD_LOOKS_TO_PHOTO_AVATAR_GROUPTool to add additional looks (images) to an existing photo avatar group. Use when you need to expand an avatar group with new image variations. Maximum 4 image keys can be added per request.

Input Parameters

string
required
The name identifier for the avatar looks being added
string
required
The unique identifier of the avatar group to which looks will be added
array
required
Array of image key strings to add to the group. Maximum 4 image keys can be added at a time. Image keys are string identifiers (e.g., ‘photo_generation/xxx/yyy.jpg’ or ‘image/xxx/original’) obtained from photo generation or upload responses. If you have objects with ‘id’ fields, extract the ‘id’ value as the image key string.
string
The unique identifier of the generation request for the images. Required for AI-generated avatars, optional for uploaded photos
boolean
Indicates whether the image keys were normalized.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_ADD_MOTIONTool to add natural motion or animation to an existing photo avatar, turning a still image into a moving, lifelike one. Use when you need to animate an avatar or add motion effects to a static photo avatar. The endpoint returns a new ID for the motion-enabled avatar.

Input Parameters

string
required
The unique identifier of the photo avatar to which motion should be applied. This ID can be obtained from photo avatar creation or listing endpoints.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_CHECK_PHOTO_LOOK_GENERATION_STATUSRetrieve the status and available image details of a photo avatar or look generation by ID. Use it to monitor progress and check whether generation is complete.

Input Parameters

string
required
The unique identifier for the photo avatar or look generation job. This ID is obtained from the response of the Generate Photo Avatar Photos endpoint.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_CREATE_FOLDERTool to create a new folder under your HeyGen account. Use when you need to organize content by creating a new folder. Once created, you can place videos in the folder by providing the folder_id parameter when generating videos.

Input Parameters

string
required
The name of the folder to be created
string
The ID of the parent folder if creating a nested folder structure. Omit this to create a folder at the root level

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_CREATE_KNOWLEDGE_BASETool to create a new knowledge base with a specified name, opening line, and custom prompt for Interactive Avatar streaming sessions. Use when you need to set up a new knowledge base with custom AI behavior.

Input Parameters

string
required
The name/identifier for the knowledge base. Must be a non-empty string
string
required
Custom instructions/system prompt for AI behavior that influences how the avatar responds when using the TALK task type with GPT-4o mini
string
required
Initial greeting or opening line that the Interactive Avatar uses when starting a conversation

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_CREATE_PHOTO_AVATAR_GROUPTool to create an avatar group which can include both AI-generated and user-uploaded photos of the avatar. Use when you need to create a new avatar group for training or managing avatar photos.

Input Parameters

string
required
The name identifier for the avatar group being created
string
required
Reference key for the associated image asset obtained from either uploading an image or generating an AI avatar. Example format: ‘image/0be8fa31f9b4406eaab861238f140e3d/original’
string
ID of the generated photo, used only for AI-generated avatars. Optional parameter that should be provided when creating avatar group from AI-generated photos.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_CREATE_WEBM_VIDEOTool to create a WebM format video with transparent background featuring an avatar speaking text or audio. Use when you need to generate WebM videos with transparent backgrounds for overlaying on other content. Note that this API endpoint does not support custom avatars - only HeyGen’s studio avatars are supported. The output format will be WebM instead of MP4 to preserve transparency.

Input Parameters

integer
Video width in pixels. If not specified, default dimensions will be used
integer
Video height in pixels. If not specified, default dimensions will be used
string
Voice ID from List All Voices (V2) API. Required when using input_text
string
Text to be spoken by the avatar. Required if input_audio is not provided
string
Asset ID of uploaded audio file. Alternative to input_text and voice_id. Obtain this ID from the Upload Asset API response
string
Avatar style for the video. Common values are ‘normal’ or ‘happy’
string
required
Avatar pose ID from List All Avatars (V2) API. This is the avatar_id value that identifies a specific avatar pose. Must be an avatar that supports WebM format

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_DELETE_AN_AVATAR_VIDEODelete a generated avatar video or translated video by ID from a HeyGen account. Use this to remove a video that is no longer needed.

Input Parameters

string
required
The unique identifier of the video to delete. Supports both generated (avatar) videos and translated videos

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_DELETE_ASSETTool to delete a specific asset by its unique asset ID from HeyGen account. Use when you need to remove an asset (image, video, or audio) that is no longer required.

Input Parameters

string
required
The unique identifier of the asset to be deleted

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_DELETE_KNOWLEDGE_BASETool to delete a specific knowledge base by its ID. Use when you need to permanently remove a knowledge base from the HeyGen streaming platform.

Input Parameters

string
required
The unique identifier of the knowledge base to be deleted

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_DELETE_PHOTO_AVATARTool to delete a photo avatar by its ID from HeyGen account. Use when you need to remove a photo avatar that is no longer required.

Input Parameters

string
required
The unique identifier of the photo avatar to be deleted

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_DELETE_PHOTO_AVATAR_GROUPTool to delete a photo avatar group by its ID from HeyGen account. Use when you need to remove a photo avatar group that is no longer required.

Input Parameters

string
required
The unique identifier of the photo avatar group to be deleted

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_DELETE_WEBHOOK_ENDPOINTTool to permanently delete a webhook endpoint from HeyGen. Use when you no longer need to receive webhook notifications for a specific endpoint.

Input Parameters

string
required
The unique identifier of the webhook endpoint to delete

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_GENERATE_PHOTO_AVATAR_PHOTOSTool to generate a personalized AI avatar based on text prompts and attribute inputs. Use when you need to create custom AI-generated avatar photos with specific characteristics like age, gender, ethnicity, pose, and appearance details.

Input Parameters

string ("Young Adult" | "Early Middle Age" | "Late Middle Age" | "Senior" | "Unspecified")
required
Age group classification for the avatar. Must be one of: ‘Young Adult’ (18-35), ‘Early Middle Age’ (35-50), ‘Late Middle Age’ (50-65), ‘Senior’ (65+), or ‘Unspecified’.
string
required
Name identifier for the avatar. This is used to identify and track the generated avatar.
string
required
Body position type for the avatar. Defines how much of the avatar’s body is visible in the frame. Valid values: ‘half_body’, ‘close_up’, ‘full_body’
string
required
Visual aesthetic style for rendering. Determines the artistic style of the generated avatar. Valid values: ‘Realistic’, ‘Pixar’, ‘Cinematic’, ‘Vintage’, ‘Noir’, ‘Cyberpunk’, ‘Unspecified’
string
required
Gender specification for the avatar. Defines the gender presentation of the generated avatar.
string
required
Ethnic background for the avatar. Specifies the ethnic characteristics to be reflected in the avatar.
string
required
Detailed description of the avatar’s look, attire, and setting. This text prompt guides the AI generation to create specific visual characteristics, clothing, and environmental context.
string
required
Layout direction/orientation of the image. Determines the aspect ratio and framing of the generated photo.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_GENERATE_TEXT_TO_SPEECHTool to generate a speech audio file from any text input using a specified voice, powered by HeyGen’s Starfish model. Use when you need to convert text to speech audio with high-quality voice synthesis.

Input Parameters

string
required
The text content to convert to speech
string
required
The ID of the voice to use for speech generation. Can be obtained from the List All Voices (V2) endpoint

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_GENERATE_VOICE_AUDIO_PREVIEWTool to generate a short audio preview with the specified voice and text. Use when you need to synthesize short audio clips using selected voices before creating full videos. This is an Enterprise-only feature that consumes API credits and is currently in Beta.

Input Parameters

string
required
Sample text to synthesize into audio
string
required
Identifier for the voice to use in the preview. Can be retrieved from the List All Voices (V2) endpoint
string ("text" | "ssml")
Specifies input format. Accepted values: ‘text’ or ‘ssml’. Defaults to ‘text’ if not specified

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_GET_ASSETRetrieve metadata and the public URL for one HeyGen workspace asset.

Input Parameters

string
required
Unique HeyGen asset identifier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_GET_AVATAR_GROUPRetrieve one HeyGen v3 avatar group by its identifier.

Input Parameters

string
required
Unique v3 avatar group identifier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_GET_AVATAR_LOOKRetrieve a HeyGen v3 avatar look and its rendering compatibility.

Input Parameters

string
required
Unique v3 avatar look identifier used as avatar_id for video generation.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_GET_CURRENT_USER_INFORMATIONTool to retrieve the profile information of the currently authenticated user. Use when you need to fetch user details including username, email, full name, subscription status, and quotas.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_GET_TRAINING_JOB_STATUSTool to retrieve the current training status and details of a photo avatar training job by group ID. Use when you need to check training progress, monitor job completion, or verify if training has finished successfully.

Input Parameters

string
required
The unique identifier of the avatar group whose training status is being queried. This ID is obtained when creating a training job.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_GET_VOICERetrieve one HeyGen v3 voice and its clone workflow status by ID.

Input Parameters

string
required
Unique v3 voice identifier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_KEEP_ALIVE_STREAMING_SESSIONTool to reset the idle timeout counter for an active streaming session. Use when you need to prevent a streaming session from timing out during periods of inactivity.

Input Parameters

string
required
A unique identifier for the streaming session to keep alive

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_LIST_ALL_AVATAR_GROUPSTool to retrieve a list of all available avatar groups in your HeyGen account. Use when you need to fetch all avatar groups for content management or selection purposes.

Input Parameters

boolean
Whether to include all public avatar groups

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_LIST_ALL_LOCALES_FOR_VOICESTool to retrieve available locales for multilingual voices. Use when you need to access locale identifiers that can be used with multilingual voices for video generation.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_LIST_ASSETSTool to retrieve a paginated list of all assets (images, audios, videos) created under your account. Use when you need to fetch assets for content management or track uploaded resources. Supports filtering by file type and folder, as well as cursor-based pagination.

Input Parameters

integer
Maximum number of assets to return per page (controls page size for pagination)
string
Cursor token for pagination. Use the token returned from previous response to fetch next page of results
string
Filter assets by type. Possible values: ‘image’, ‘video’, ‘audio’
string
Filter assets by parent folder ID to retrieve assets from specific folder

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_LIST_AVATAR_GROUPSBrowse HeyGen v3 avatar groups by ownership with cursor pagination.

Input Parameters

integer
Maximum number of avatar groups to return per page (1-50).
string
Opaque next_token returned by the previous page.
string ("public" | "private")
Filter to public preset avatars or private avatars owned by the account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_LIST_AVATAR_LOOKSBrowse avatar looks and their engine compatibility, with optional group, type and ownership filters and cursor pagination. Results may include looks still processing, awaiting consent or failed.

Input Parameters

integer
Maximum number of avatar looks to return on this page (1-50).
string
Opaque next_token returned by the previous page.
string
Return only looks belonging to this avatar group.
string ("public" | "private")
Filter to public preset looks or private account-owned looks.
string ("studio_avatar" | "digital_twin" | "photo_avatar")
Filter by avatar look type.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_LIST_BRAND_VOICESTool to retrieve a list of brand glossaries created under your account. Use when you need to access brand voice definitions that maintain consistent terminology and pronunciation across videos.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_LIST_FOLDERSTool to retrieve a paginated list of folders created under your account. Use when you need to organize or browse folder structures in HeyGen. Supports cursor-based pagination using the token parameter.

Input Parameters

string
Cursor token for pagination. For the first request, omit this parameter. For subsequent requests, use the token value returned in the previous response to get the next page of results. When the token is empty or null in the response, it indicates there are no more pages

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_LIST_GROUP_AVATARSTool to retrieve all avatars that belong to a specific avatar group. Use when you need to fetch all avatars within a particular group for content management or selection purposes.

Input Parameters

string
required
The unique identifier for the specific avatar group from which to retrieve avatars. This ID can be obtained from the HeyGen dashboard or from other group-related endpoints.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_LIST_KNOWLEDGE_BASESTool to retrieve a list of all existing knowledge bases associated with your account. Use when you need to view available knowledge bases for streaming interactions.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_LIST_SESSION_HISTORYTool to retrieve a paginated history of all streaming sessions with metadata including session duration, timestamps, and other details. Use when you need to view historical streaming session data for reporting or analysis purposes.

Input Parameters

integer
Page number to retrieve (default 1)
string
Token for retrieving the next page of results, obtained from the previous response’s next_page_token field
integer
Number of records per page (default 10)

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_LIST_STREAMING_AVATARSTool to retrieve a list of public and custom interactive avatars for streaming. Use when you need to fetch available avatars for interactive streaming sessions.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_LIST_TTS_VOICESTool to retrieve a list of public and custom voices compatible with HeyGen’s Starfish TTS model. Use when you need to access available voices for text-to-speech audio generation in videos.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_LIST_V3_VOICESBrowse HeyGen v3 voices using catalog, engine, language, and gender filters.

Input Parameters

string ("public" | "private")
Voice catalog to browse: public shared voices or private cloned voices.
integer
Number of voices to return per page, from 1 to 100.
string
Opaque next_token from the previous page. Omit for the first page.
string
Speech engine mapping to filter by, such as starfish, orca, or elevenlabs.
string
Voice gender to filter by, such as male or female.
string
Language name to filter by, such as English or Spanish.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_NEW_SESSIONTool to initiate a new streaming session with an Interactive Avatar for real-time interactions. Use when starting a new avatar streaming session to get WebSocket connection details including session_id, URL, and access_token.

Input Parameters

object
Avatar voice configuration settings
string ("high" | "medium" | "low")
required
Data quality level - ‘high’ (2000kbps/720p), ‘medium’ (1000kbps/480p), or ‘low’ (500kbps/360p). Required parameter.
string
API version. Valid value is ‘v2’ (beta). Use this to access v2-specific features.
string
Interactive Avatar ID. Defaults to ‘default’ if omitted. Use to specify which avatar to use for the streaming session.
object
Speech-to-text conversion settings (beta)
string
Knowledge Base prompt for chat tasks. Provides context for avatar responses.
string ("H264" | "VP8")
Video format encoding - ‘H264’ or ‘VP8’. Defaults to VP8 if not specified.
object
Custom LiveKit instance configuration (beta)
string
Knowledge base ID for avatar responses. Requires version=‘v2’ to be set.
boolean
Disables the default 2-minute idle timeout when set to true. Useful for long-running sessions.
integer
Maximum idle seconds after last activity. Range: 30-3600 seconds. Default: 120 seconds.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_PERSONALIZED_VIDEO_ADD_CONTACTThis endpoint allows you to add one or more contacts to a specific personalized video project in the Heygen platform. It is used when you need to associate individual contact information with a project, likely for the purpose of creating tailored video content for each contact. The endpoint accepts a project identifier and a list of contacts, each with a first name and email address. This tool is essential for populating your project with recipient data, enabling the creation of personalized videos at scale. Note that this endpoint only adds contacts to a project; it does not initiate video creation or sending. Ensure that your project_id is valid and that all contact information is accurate to avoid errors in video personalization or delivery.

Input Parameters

string
required
Project identifier
array
required
Variables List

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_PERSONALIZED_VIDEO_PROJECT_DETAILRetrieves detailed information about a specific personalized video project in HeyGen, including status, settings, and metadata. Use this to check project progress or review configuration. Read-only endpoint. The project ID must be obtained from the HeyGen web interface - there is no API to list projects. Go to Personalized Video section, select a project, and copy the Project ID from the API setup page. May require Enterprise subscription.

Input Parameters

string
required
The unique identifier of the personalized video project. This ID must be obtained from the HeyGen web interface when creating a personalized video project. Go to HeyGen’s Personalized Video section, create or select a project, and copy the Project ID from the API setup page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_PHOTO_AVATAR_DETAILSTool to retrieve detailed information about a photo avatar or look using its unique ID. Use when you need to get comprehensive information about a specific photo avatar including status, metadata, and configuration details.

Input Parameters

string
required
The unique identifier of the photo avatar or look whose details need to be retrieved. This ID can be obtained from photo avatar creation or listing endpoints.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_POST_TALKING_PHOTO_BINARY_IMAGEUploads a JPEG or PNG image to create a talking photo asset for subsequent video generation. The response can include the talking photo ID and URL.

Input Parameters

object
Image file to upload for talking photo creation. Accepts JPEG and PNG formats.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_RESTORE_FOLDERTool to restore a previously deleted folder from trash by its unique folder ID. Use when you need to recover a folder that was moved to trash.

Input Parameters

string
required
The unique identifier of the folder to be restored from trash

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_RETRIEVE_AVATAR_DETAILSTool to retrieve detailed information about a specific avatar by its ID. Use when you need to get comprehensive information about an avatar including identification details, display properties, and preview media URLs.

Input Parameters

string
required
The unique identifier of the avatar whose details need to be fetched. This ID can be obtained from the List All Avatars endpoint or from the HeyGen dashboard.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_RETRIEVE_SHARABLE_VIDEO_URLTool to generate a public, shareable URL for a specific video by ID. Use when you need to create a public link that allows anyone to view the video without authentication. The generated URL can be shared with anyone and does not require HeyGen account access. Generated URLs may be time-limited; call this tool again to refresh the link if it expires.

Input Parameters

string
required
The unique identifier of the video for which to generate a shareable URL. This ID is returned when a video is created via the video generation API.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_RETRIEVE_TEMPLATE_DETAILS_V3Tool to retrieve comprehensive details about a specific template including all available variables for replacement and scene mappings for templates built in the New AI Studio. Use when you need to understand the structure, available customization options, variables, and scene configurations of a template before generating videos from it.

Input Parameters

string
required
The unique identifier of the template to retrieve details for. This ID can be obtained from the List Templates endpoint or from the HeyGen dashboard.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_RETRIEVE_VIDEO_STATUS_DETAILSTool to retrieve the current processing status and metadata for a specific video by ID. Use when you need to check video processing progress, get time-limited URLs for video downloads, or monitor video generation completion. Video rendering is asynchronous and typically takes 30–180+ seconds; poll at moderate intervals rather than tight loops. Verify returned URLs are accessible before surfacing to users. Note that returned URLs expire after 7 days but can be regenerated by calling this endpoint again.

Input Parameters

string
required
The unique identifier of the video to retrieve status for. This ID is returned when a video is created via the video generation API.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_SEARCH_PUBLIC_AVATAR_GROUPSTool to search and retrieve public avatar groups with optional filters and pagination. Use when you need to find specific avatar groups by tags, name, or browse available public avatars.

Input Parameters

integer
Current page number for pagination (default: 1). Must be a positive integer.
string
Search query to filter by avatar name or other attributes, for example: ‘Ann’ or ‘Business Executive’. Use to search for specific avatar names or descriptions.
integer
Number of avatar groups per page (default: 20). Must be between 1 and 100.
array
Search tags to filter avatar groups, for example: [‘Middle Aged’, ‘Professional’]. Use tags that describe avatar characteristics like age, style, or profession.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_STREAMING_CREATE_TOKENCreates a new streaming token for use with HeyGen’s real-time avatar and voice chat services. This endpoint generates a unique, time-limited token that authenticates and authorizes access to HeyGen’s streaming capabilities. Use this endpoint when initiating a new streaming session or when the previous token has expired. The generated token is typically for one-time use and should be obtained shortly before starting a streaming interaction. Note that this endpoint does not initiate the streaming itself; it only provides the necessary credentials for subsequent streaming API calls.

Input Parameters

integer
Token expiry time in seconds

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_STREAMING_ICEThis endpoint is used to submit ICE (Interactive Connectivity Establishment) candidate information for a specific streaming session in the Heygen platform. It plays a crucial role in establishing and managing peer-to-peer connections for real-time communication and streaming of avatar content. The endpoint should be called when new ICE candidates are discovered during the connection setup process, typically as part of the WebRTC negotiation. It’s essential for ensuring optimal connectivity between clients, especially in scenarios involving NAT traversal or complex network environments. This endpoint does not return the status of the connection or initiate the streaming itself; it only submits candidate information to be used in the connection process.

Input Parameters

string
required
Streaming session ID
string
Media stream identifier
string
ICE candidate string
integer
Index of the media line
string
ICE username fragment

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_STREAMING_INTERRUPTInterrupts an ongoing streaming session with an interactive avatar. This endpoint allows immediate termination of the avatar’s current action or speech, providing control over the flow of interaction. Use this when you need to abruptly stop the avatar’s current behavior, such as when changing topics or responding to user input that requires a different response. The interruption is immediate and irreversible, so use it judiciously to maintain a smooth user experience. This endpoint is particularly useful in scenarios where real-time responsiveness is crucial, like in customer service applications or interactive presentations.

Input Parameters

string
required
ID of the streaming session to interrupt

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_STREAMING_LISTRetrieves a list of active or available streaming sessions or content within the HeyGen platform. This endpoint allows users to get an overview of ongoing streams, which may include live avatar interactions, real-time video generations, or other streaming content created using HeyGen’s AI-driven tools. It’s particularly useful for monitoring current streaming activities or checking the availability of streams for integration into applications. The endpoint returns basic information about each stream, such as stream IDs, status, and possibly metadata, but does not provide the actual stream content. Use this when you need to track or display a list of active streams in your application’s interface or for administrative purposes.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_STREAMING_NEWInitiates a new streaming session with HeyGen, allowing users to start an avatar-based stream with specified quality settings. This endpoint should be used when starting a new interactive content session or when creating a personalized digital avatar stream. It sets up the initial configuration for the streaming quality, which affects the overall user experience and bandwidth usage. The endpoint does not handle the actual streaming content or avatar creation; it only establishes the session parameters.

Input Parameters

string ("high" | "low" | "medium")
Streaming quality

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_STREAMING_STARTStarts an existing HeyGen streaming session using its session ID and an SDP answer for WebRTC connection setup.

Input Parameters

object
required
The SDP answer object containing the WebRTC session description from the client’s peer connection.
string
required
The ID of the streaming session to start. Obtained from the streaming.new endpoint.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_STREAMING_STOPThe streaming.stop endpoint is used to terminate an active streaming session in the Heygen API. This endpoint should be called when you want to end a real-time data transfer session, such as when closing an interactive avatar conversation or stopping a live content stream. It’s particularly useful for freeing up server resources and ensuring proper closure of streaming connections. The endpoint requires the unique session_id to identify which specific session to stop, allowing for precise control over multiple concurrent sessions. Note that once a session is stopped, it cannot be resumed; a new session must be started if streaming is needed again.

Input Parameters

string
required
Session to stop

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_STREAMING_TASKThe StreamingTask endpoint initiates a real-time speaking task for an AI-driven avatar within an active streaming session. It enables developers to make avatars vocalize specified text, creating interactive and dynamic user experiences. This endpoint should be used when you want to generate speech from an avatar in response to user input or as part of a scripted interaction. It’s particularly useful for applications requiring real-time avatar interactions, such as virtual assistants, interactive presentations, or educational content. Note that this endpoint requires an active streaming session, and the avatar’s voice and appearance are determined by the session configuration.

Input Parameters

string
required
Text for avatar to speak
string ("sync" | "async")
Task execution mode.
string ("repeat" | "chat")
Specifies behavior: ‘repeat’ - avatar simply repeats the input text; ‘chat’ - avatar responds according to knowledge base set in streaming.new API.
string
required
Session identifier obtained from streaming.new endpoint

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_TRASH_FOLDERTool to move a specific folder to trash by its unique folder ID. Use when you need to delete a folder from HeyGen (soft delete - can be recovered later).

Input Parameters

string
required
The unique identifier of the folder to be moved to trash

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_UPDATE_FOLDERTool to update (rename) an existing folder by its unique folder ID. Use when you need to change the name of a folder in HeyGen.

Input Parameters

string
required
The new name for the folder
string
required
The unique identifier of the folder to be updated

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_UPDATE_KNOWLEDGE_BASEUpdate an existing knowledge base by ID for Interactive Avatar streaming sessions. The name and opening line are required on every request; a custom prompt can also be supplied.

Input Parameters

string
required
The name/identifier for the knowledge base. This field is required by the API.
string
Custom instructions/system prompt for AI behavior that influences how the avatar responds when using the TALK task type with GPT-4o mini
string
required
Initial greeting or opening line that the Interactive Avatar uses when starting a conversation. This field is required by the API.
string
required
The unique identifier of the knowledge base to update

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_UPDATE_WEBHOOK_ENDPOINTTool to modify an existing webhook endpoint configuration including URL and subscribed event types. Use when you need to update webhook settings or change event subscriptions for an existing endpoint.

Input Parameters

string
required
The webhook URL where HeyGen will send event notifications. Must respond to OPTIONS requests within 1-second timeout during validation
array
List of event types to subscribe to. Common events include ‘avatar_video.success’, ‘avatar_video.fail’, ‘video_translate.success’, ‘photo_avatar_train.fail’, ‘instant_avatar.success’
string
Security key for validating webhook authenticity
string
required
Unique identifier for the webhook endpoint to update

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_UPLOAD_ASSETTool to upload a file asset (image, video, or audio) to HeyGen platform. Use when you need to upload media files for use in video generation or other HeyGen services.

Input Parameters

object
required
File to upload as an asset. Supported types: image (png, jpeg), video (mp4, webm), or audio (mpeg).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_UPSCALE_AN_AVATARTool to enhance the resolution and visual quality of a motion avatar. Use when you need to improve avatar quality for higher resolution output. Important: Upscaling can ONLY be performed on motion avatars/looks - the avatar must first have motion added using the Add Motion endpoint.

Input Parameters

string
required
The unique identifier of the motion avatar or look to upscale. This must be a motion avatar created using the Add Motion endpoint. Upscaling can ONLY be performed on motion avatars, not regular photo avatars.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V1_AVATAR_LISTRetrieves available HeyGen avatars and talking photos for selection or inventory management. Results may include identifiers, names, types, and preview URLs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V1_TALKING_PHOTO_LISTRetrieves a list of talking photos created using the HeyGen platform. This endpoint allows users to fetch information about their existing talking photo projects, which are interactive images capable of speaking and engaging users. It’s useful for managing and reviewing your talking photo content, or for integrating talking photo information into your application. The endpoint returns details about each talking photo, potentially including identifiers, creation dates, and associated metadata. Note that this endpoint likely returns all talking photos by default, so for users with a large number of projects, implementing client-side filtering or pagination may be necessary.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V1_VIDEO_LISTLists videos associated with the HeyGen account, with pagination via a limit and cursor token. Results can include titles, creation dates, durations, statuses, and video download URLs.

Input Parameters

integer
Maximum number of videos to return per page (0-100). Defaults to 10 if not specified.
string
Pagination cursor token from a previous response to retrieve the next page of results.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V1_VOICE_LISTRetrieves available HeyGen voices for avatar and text-to-speech use, including voice IDs, names, languages, and audio preview URLs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V1_WEBHOOK_ENDPOINT_ADDAdds a new webhook endpoint to receive real-time notifications for specified Heygen events. This endpoint allows you to configure where and for which events you want to receive updates, enabling seamless integration of Heygen’s capabilities into your application. Use this when you need to set up automated responses to specific events in the Heygen platform, such as avatar creation or video completion. The webhook will send POST requests to the specified URL whenever the subscribed events occur. Note that you may need to implement proper security measures on your receiving endpoint to validate incoming webhook requests.

Input Parameters

string
required
Webhook URL
array
required
Event types to subscribe to

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V1_WEBHOOK_ENDPOINT_LISTRetrieves a list of all webhook endpoints configured for your HeyGen account. This endpoint allows you to view and manage the webhook configurations that receive notifications about various events in your HeyGen integration. Use this endpoint to monitor your existing webhook setups, verify their status, or gather information for updating or removing webhooks. The response will likely include details such as the endpoint URLs, associated event types, and current status of each webhook. This tool is particularly useful for developers managing multiple webhook integrations or troubleshooting notification issues within their HeyGen-powered applications.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V1_WEBHOOK_WEBHOOK_LISTRetrieves a list of all available webhook event types that can be subscribed to in your HeyGen account. This endpoint returns the complete list of event types that HeyGen supports for webhook notifications, such as avatar video success/failure events, video translation events, personalized video events, instant avatar events, photo avatar events, and more. Use this endpoint when you need to discover which webhook events are available for subscription before configuring your webhook endpoints. Note that this endpoint only lists the available event types - to manage actual webhook endpoint configurations, use the webhook endpoint.list, endpoint.add, and endpoint.delete endpoints.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V2_TALKING_PHOTO_ID_DELETEDeletes a specific talking photo from the HeyGen platform using its unique identifier. This endpoint should be used when you need to permanently remove a talking photo resource, such as when it’s no longer needed or to manage storage. Once deleted, the talking photo cannot be recovered, so use this endpoint with caution. It’s important to note that this operation does not affect any videos or content that may have already been generated using this talking photo.

Input Parameters

string
required
id

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V2_TEMPLATE_GENERATEGenerates a customized video from a pre-existing template using HeyGen’s AI platform. Accepts a video title and template variables to personalize content. Ideal for creating tailored videos at scale like personalized marketing, educational content, or custom presentations. Supports test mode, captions, and custom dimensions. IMPORTANT: First retrieve template variable definitions using ‘Get template by id’ (GET /v2/template/{id}). Variable names must exactly match those from that endpoint, or the API will reject with ‘Invalid variable name’ error.

Input Parameters

string
required
Template ID
boolean
Test mode flag
string
required
Video title
boolean
Enable captions
object
Video dimension configuration.
object
required
Dictionary of template variables keyed by variable name. Variable names MUST exactly match those defined in the template (retrieve them first using the ‘Get template by id’ action with endpoint GET /v2/template/{id}). Each variable has a type (text, image, video, character, voice, audio) and type-specific properties corresponding to its type.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V2_TEMPLATE_IDRetrieves the customizable variables of a specific HeyGen template by its ID, including their types and available properties.

Input Parameters

string
required
Template ID

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V2_TEMPLATESRetrieves a list of HeyGen video templates, including template IDs, names, and preview images, for selecting a template for video generation.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V2_USER_REMAINING_QUOTARetrieves the authenticated user’s remaining HeyGen quota and category breakdown. The v2 remaining-quota endpoint is deprecated and scheduled for removal on October 31, 2026.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V2_VIDEO_GENERATEGenerates a customized video using Heygen’s AI-driven platform. This endpoint allows you to create videos featuring digital avatars with specified voices, enabling dynamic content creation. It’s ideal for producing personalized video content, such as explainer videos, product demonstrations, or interactive presentations. The endpoint supports multiple input configurations, allowing for complex video scenarios with different characters and voices. Use this when you need to programmatically create AI-generated videos with specific avatar and voice combinations. Note that while the endpoint offers extensive customization, real-time video generation is not supported, and processing times may vary based on complexity and system load.

Input Parameters

boolean
Test mode flag
string
The title of the video
string
Optional callback ID
string
Video aspect ratio
array
required
Array of video input configurations
integer
Video width in pixels
integer
Video height in pixels

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V2_VIDEO_TRANSLATEThe TranslateVideo endpoint enables the translation of video content from one language to another. It offers flexible options for translating either the entire video or just the audio track, accommodating various use cases. This tool is ideal for creating multilingual versions of video content, making it accessible to a global audience. The endpoint requires specifying the source video URL and the desired output language, with additional options to customize the translation process, such as handling multiple speakers and setting a title for the translated video. Use this endpoint when you need to quickly and efficiently translate video content while maintaining the integrity of the original presentation.

Input Parameters

string
Title for translated video
string
required
Source video URL
integer
Number of speakers
string
required
Target language
boolean
Translate only audio

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V2_VIDEO_TRANSLATE_ID_STATUSRetrieves the current status of a video translation job in the HeyGen platform. This endpoint allows users to check the progress of their requested video translations, providing information such as whether the translation is in progress, completed, or if any errors have occurred. It should be used when tracking the state of an ongoing translation task or to confirm if a translation has finished processing. The endpoint does not modify the translation job or initiate new translations; it’s purely for status checking purposes.

Input Parameters

string
required
Video ID

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V2_VIDEO_TRANSLATE_TARGET_LANGUAGESRetrieves a list of all available target languages supported by HeyGen’s video translation feature. This endpoint should be used when you need to know which languages are available for translating your video content. It provides an up-to-date array of supported languages, including various dialects and locales, allowing you to make informed decisions about your video translation projects. The endpoint does not require any parameters and will return the complete list of supported languages, which currently includes over 77 options. This tool is particularly useful for planning multilingual content strategies or when preparing to use HeyGen’s video translation services.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: HEYGEN_V2_VOICESRetrieves a list of available voice models and options that can be used with HeyGen’s AI-driven video creation platform. This endpoint provides information about the various voice options, including different languages and voice characteristics, which can be applied to avatars in generated videos. Use this endpoint when you need to present users with voice choices for their video projects or when implementing voice customization features in your application. The returned data likely includes details such as voice ID, language, gender, and other relevant attributes for each available voice model. This endpoint is essential for applications that want to offer a range of voice options to enhance the personalization of AI-generated video content.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not