clone_voice
ChatGPTCreates a voice clone from an audio file. Returns a voice_clone_id that can be polled via GET /v3/voices/{voice_clone_id} until the status is 'complete'. The resulting voice can be used with POST /v3/voices/speech and POST /v3/videos.
create_avatar_consent
ChatGPTInitiates the consent flow for an avatar group and returns a URL for the user to complete approval in their browser. Required before a private avatar can be used for video generation.
create_digital_twin
ChatGPTCreates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous. (type: digital_twin)
create_lipsync
ChatGPTReplaces the audio on an existing video and re-animates the speaker's lip movements to match the new audio. Use mode: 'speed' for fast output or 'precision' for high-quality lip-sync.
create_photo_avatar
ChatGPTCreates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous. (type: photo)
create_prompt_avatar
ChatGPTCreates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous. (type: prompt)
create_speech
ChatGPTSynthesize speech audio from text using a specified voice. The voice must support the starfish engine — use GET /v3/voices?engine=starfish to find compatible voices. Supports plain text and SSML. Speed range: 0.5–2.0x. Returns a URL to the generated audio file along with duration and optional word-level timestamps.
create_video_from_avatar
ChatGPTCreate a video from a HeyGen avatar (video or photo avatar). Provide an avatar_id to use a previously created avatar. The server automatically selects the appropriate engine based on the avatar type (video avatar or photo avatar).
create_video_from_image
ChatGPTCreate a video by animating an arbitrary image. Provide an image via URL, asset ID. The image will be animated with lip-sync to the provided audio or generated speech.
create_video_translation
ChatGPTTranslates a video into one or more target languages with voice cloning and lip-sync. Returns one video_translation_id per language. Use mode: 'speed' (default) for fast turnaround or 'precision' for higher lip-sync quality.
delete_lipsync
ChatGPTPermanently deletes a lipsync job and its associated files. This action cannot be undone.
delete_video
ChatGPTPermanently deletes a video and its associated files. This action cannot be undone.
delete_video_translation
ChatGPTPermanently deletes a video translation and its associated files. This action cannot be undone.
design_voice
ChatGPTReturns up to 3 voices matching a natural language description (e.g. 'warm, confident female narrator'). Use the seed parameter to get different batches of results.
get_avatar_group
ChatGPTReturns details for a specific avatar group including name, gender, preview URLs, looks count, and training status.
get_avatar_look
ChatGPTReturns details for a specific avatar look including supported engines, preferred orientation, preview URLs, and training status.
get_current_user
ChatGPTReturns the authenticated user's profile, remaining credits or balance, and billing details.
get_lipsync
ChatGPTReturns details for a lipsync job including status, video_url, caption_url, and failure info if applicable.
get_video
ChatGPTReturns details for a video including status, video_url, thumbnail_url, duration, and failure info if applicable.
get_video_agent_resource
ChatGPTReturns a single session resource (image, video, draft, avatar, voice, etc.) by its resource_id.
get_video_agent_session
ChatGPTReturns the current status, progress, video_id, and recent chat messages for a session.
get_video_translation
ChatGPTReturns details for a translation job including status, output language, video_url, and failure info if applicable.
get_voice
ChatGPTReturns details for a specific voice, including clone workflow status when available. Use this to poll a voice clone until its status is 'complete'.
list_avatar_groups
ChatGPTReturns a paginated list of avatar groups (characters). Each group contains one or more looks. Filterable by ownership.
list_avatar_looks
ChatGPTReturns a paginated list of avatar looks (outfits, poses, styles). Filterable by group_id, avatar_type, and ownership. The look id is the avatar_id to pass when creating a video.
list_lipsyncs
ChatGPTReturns a paginated list of all lipsync jobs in the account.
list_video_agent_session_videos
ChatGPTReturns all videos produced within a Video Agent session, sorted newest-first.
list_video_agent_sessions
ChatGPTReturns a paginated list of video agent sessions for the authenticated user, sorted newest-first.
list_video_agent_styles
ChatGPTReturns curated visual style templates available for Video Agent sessions. Each style controls scene composition, pacing, and aesthetics. Supports tag filtering (e.g. 'cinematic', 'retro-tech').
list_video_translation_languages
ChatGPTReturns all supported target language names for video translation.
list_video_translations
ChatGPTReturns a paginated list of all video translation jobs in the account.
list_videos
ChatGPTReturns a paginated list of all videos in the account. Filterable by folder_id or title substring.
list_voices
ChatGPTReturns a paginated list of voices, filterable by type, engine, language, and gender. Use engine=starfish for voices compatible with the TTS endpoint.
stop_video_agent_session
ChatGPTHalts an active agent run at its next checkpoint. Partial results are preserved.
update_avatar_look
ChatGPTUpdates the display name of an avatar look. Only supported for photo avatar and digital twin look types.
update_lipsync
ChatGPTUpdates the display title of a lipsync job.
update_video_translation
ChatGPTUpdates the display title of a video translation job.
video_agent.generate
ChatGPTThe primary tool for video creation using HeyGen's Video Agent. Use this tool to generate videos on behalf of the user. WHEN TO CALL: - If the user explicitly requests this tool or mentions "HeyGen Video Agent", invoke it. - User provides a SPECIFIC topic AND narrative details, script, or style instructions (e.g., "Make a 30-second product demo for our AI scheduling app with a professional tone" or "Create a video explaining basketball rules with an energetic narrator"). - High-intent users: Specific topic + content/narrative/script provided. NEVER CALL WHEN: - The request is vague or lacks a specific topic (e.g., "Make me a video" or "Help me with a video about coding"). Instead, stay in chat and help the user define their topic, narrative, and style before calling this tool. SESSION MANAGEMENT: - First call: Leave session_id empty. A new session will be created automatically. - Subsequent calls (continuing a conversation): Pass the session_id returned from the previous tool call. This continues the conversation and keeps the agent in the loop. - New video request: If the user explicitly asks to start a completely new video, leave session_id empty to create a fresh session. INPUTS: - prompt: (Required) The user's direct request for the video. - conversation_context: (Optional) All relevant context from the conversation that informs this request. IMPORTANT: Always include the actual content being referenced—never use vague references like "the script above", "as mentioned", or "that idea". Expand all pronouns and references into the actual material. - session_id: (Optional) Session ID from a previous tool call to continue the conversation.
