Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.heygen.com/llms.txt

Use this file to discover all available pages before exploring further.

​
New `download_failed` Error Code
Errors
Added - May 18, 2026
Clearer signal when a user-supplied URL can’t be fetchedRequests that include a URL for video, image, audio, or any other resource can now return a dedicated download_failed error (HTTP 400) when the URL can’t be downloaded. The message field tells you which URL failed and why.Common causes:
  • URL isn’t publicly accessible (auth required, private video, restricted sharing).
  • URL is malformed or points to a page rather than a direct file.
  • Remote server refused the connection or returned an error.
  • Google Drive links must be shared with Anyone with the link.
  • YouTube/Vimeo videos must be public — unlisted or private videos aren’t supported.
The resource_limit_exceeded error message also now covers instant-avatar redo attempts and verified avatar group slots, with guidance to wait for limits to reset where applicable.See the error codes reference for the full list.
​
Avatar V Pricing Parity with Avatar IV
Pricing
Changed - May 12, 2026
Avatar V is billed at the same rates as Avatar IVPer-second video generation rates for Avatar V now match Avatar IV across both self-serve and enterprise plans. No action required — pricing tables have been updated to reflect the combined Avatar IV & V rates.
​
API Updates
VideosAssetsAvatarsVideo TranslationLipsyncWebhooks
Added - May 2026
Added Idempotency support and expanded API capabilitiesWe have introduced support for the Idempotency-Key header across key endpoints to ensure safe retries for POST requests. Additionally, several endpoints now return a 409 Conflict status to handle concurrent requests or state conflicts.
  • Idempotency-Key Support: Added to POST /v3/assets, POST /v3/avatars, POST /v3/avatars/{group_id}/consent, POST /v3/lipsyncs, POST /v3/video-translations, POST /v3/video-translations/proofreads, POST /v3/video-translations/proofreads/{proofread_id}/generate, POST /v3/videos, POST /v3/webhooks/endpoints, and POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret.
  • New Endpoints: Added DELETE /v3/assets/{asset_id}, DELETE /v3/avatars/looks/{look_id}, and DELETE /v3/avatars/{group_id}.
  • Default Values: The aspect_ratio parameter now defaults to 16:9 in POST /v2/videos and POST /v3/videos.
​
Video Translation Improvements
Video TranslationBreaking Change
Changed - May 2026
Strict schema validation for frame rate modesThe fps_mode property in POST /v3/video-translations has been updated to use a strict enum, ensuring more predictable behavior for video output.
  • Breaking Change: The fps_mode property is now restricted to an enum. Supported values are now explicitly defined as vfr, cfr, and passthrough.
  • Migration: Ensure your integration passes one of these three strings. Previously provided custom values may now be rejected.
​
Corrected `avatar_video.success` Webhook Payload Fields
WebhooksVideos
Fixed - May 11, 2026
Webhook payload field names now match what’s actually deliveredThe documented payload for the avatar_video.success webhook event has been corrected. If you wired up handlers from the previous documentation, double-check the field names you’re reading — the live payload uses these keys:
  • video_id, url, gif_download_url, video_page_url, video_share_page_url, folder_id, callback_id
No change to the webhook delivery itself — this aligns the webhook events reference with the payload the API has been sending.
​
Video Engine Updates & Brand Kit Support
VideosVideo AgentBreaking Change
Changed - May 2026
Video engine updates and new brand kit integrationWe have updated the video generation workflow and introduced support for Brand Kits across Video Agents. Note that the engine parameter structure for POST /v3/videos has changed, which is a breaking change for existing integrations.
  • Breaking Change: The engine property in POST /v3/videos now requires an object structure (e.g., {"type": "avatar_v"}) instead of a string. ApiAvatarEngine has been removed.
  • Video Scaling: Added a new optional fit parameter to POST /v3/videos for both CreateVideoFromAvatar and CreateVideoFromImage request types.
  • Brand Kits: Added brand_kit_id as an optional parameter to POST /v3/video-agents and POST /v3/video-agents/{session_id}.
  • New Endpoint: Added GET /v3/brand-kits to retrieve available brand kit resources.
  • Parameter Constraints: Note that expressiveness and motion_prompt in POST /v3/videos are now strictly for Avatar IV and are not supported when engine.type is set to avatar_v.
​
Support for Stock TTS and Engine Selection
Video TranslationVideos
Added - May 2026
New configuration options for Video Translation and Video GenerationWe have introduced support for Stock TTS in video translations and added explicit engine selection for avatar-based video generation.
  • Video Translation: Added stock_voice_config to POST /v2/video_translate and POST /v3/video-translations. This allows users to opt into Stock TTS instead of using Voice Cloning.
  • Video Generation: Added an optional engine field to POST /v3/videos (for CreateVideoFromAvatar requests). You can now explicitly select between Avatar IV and Avatar V engines. If omitted, the system defaults to Avatar IV.
​
Avatar Engine Metadata Updates
Avatars
Changed - May 2026
Updated schema definitions for Avatar engine supportMetadata for supported API engines has been updated across the avatar look endpoints to ensure consistency when retrieving avatar configurations.
  • Updated supported_api_engines fields in:
    • POST /v3/avatars
    • GET /v3/avatars/looks
    • GET /v3/avatars/looks/{look_id}
    • PATCH /v3/avatars/looks/{look_id}
​
Custom Watermark Controls
Videos
Added - April 30, 2026
Fine-tune watermark size, transparency, and positionThe watermark object on POST /v3/videos now accepts three new optional fields for finer control over how your watermark renders:
  • scale (number, 0–2, default 1.0) — adjust the watermark size relative to its native resolution.
  • opacity (number, 0–1, default 1.0) — control transparency.
  • placement — choose an anchor corner (top_left, top_right, bottom_left, bottom_right) and apply fractional offset_x / offset_y values for precise positioning.
All fields are optional and backward-compatible. Omitting them preserves the existing bottom-right default behavior.
​
Voice Cloning API
Voices
Added - April 27, 2026
Programmatic voice cloning is now availableYou can now create and manage voice clones directly from the API, no dashboard step required.
  • POST /v3/voices/clone initiates a clone from a reference audio sample.
  • GET /v3/voices/{voice_id} returns clone status and details so you can poll until processing completes.
  • Use the resulting voice_id anywhere a voice is accepted (POST /v3/videos, POST /v3/voices/speech, etc.).
See the voices overview for details.
​
Burned-in Captions
Videos
Added - April 27, 2026
Render captions directly into your videosPOST /v2/videos and POST /v3/videos now accept a caption.style field. Set it to burn captions into the rendered video instead of (or in addition to) consuming the sidecar subtitle file at subtitle_url.Useful for social platforms where viewers watch with sound off and you want captions baked into the asset.
​
Custom Watermarks
Videos
Added - April 27, 2026
Apply your own watermark to generated videosPOST /v3/videos accepts a new optional watermark property on both CreateVideoFromAvatar and CreateVideoFromImage requests. Pass a PNG or JPEG image to overlay it onto the rendered output — handy for branding, attribution, or moderation marks.Available as a premium option for select Enterprise customers — contact support to request access.
​
Watermark Schema Refactor
VideosBreaking Change
Changed - April 27, 2026
watermark now uses the WatermarkInput schemaThe inline schema previously used for the watermark field on video generation requests has been replaced with the dedicated WatermarkInput type. The shape of the property has changed — update existing payloads to match the new schema before upgrading.
​
Video Title Search Requires a Value
VideosBreaking Change
Changed - April 27, 2026
Empty title queries are no longer acceptedGET /v2/videos and GET /v3/videos now require at least one character for the title query parameter (minLength increased from 0 to 1). Omit the parameter entirely if you don’t want to filter by title — sending an empty string will return a validation error.
​
Clearer Voice Clone Quota Errors
Voices
Fixed - April 27, 2026
Better error feedback when the voice clone limit is reachedPOST /v3/voices/clone now returns the resource_limit_reached error code (HTTP 400) when your account has hit its voice clone quota, instead of a generic validation error. The response message tells you to delete unused clones or contact support to raise the limit. See the error codes reference for handling guidance.
​
MCP Server Updates
MCPPlatform
Added - April 2026
Expanded tool coverage for the HeyGen MCP serverThe HeyGen Remote MCP server now includes tools for managing avatars, videos, lipsync, and video translation — making more of the API accessible to AI agents like Claude, Cursor, Gemini CLI, and Manus.
  • Added avatar management tools: create_digital_twin, create_photo_avatar, create_prompt_avatar, create_avatar_consent, list_avatar_looks, get_avatar_look, update_avatar_look, and more.
  • Added full video CRUD: create_video_from_avatar, create_video_from_image, list_videos, get_video, delete_video.
  • Added lipsync and video translation management tools.
  • Added design_voice for finding voices from a natural-language description.
  • See the MCP overview for the full tool list.
​
HeyGen CLI v0.0.4
CLIPlatform
Added - April 2026
CLI command surface synced with v3 APIThe HeyGen CLI now covers all v3 endpoints, including Video Agent, Lipsync, Video Translation (with Proofreads), Webhooks, and Assets.
  • Added --wait flag for blocking until async operations complete, with configurable --timeout.
  • Added --request-schema and --response-schema flags to inspect API schemas without authentication.
  • Added --force flag for non-interactive destructive operations in CI.
  • See the CLI commands and features pages for usage details.
​
v1/v2 API Deprecation Timeline
Platform
Changed - April 2026
v1 and v2 endpoints sunset on October 31, 2026A formal deprecation timeline is now in place for the v1 and v2 API. Both versions remain fully operational through October 31, 2026, after which they will be retired.
  • Studio API (multi-scene) and Template API will continue to be supported on v2 until a v3 equivalent is available.
  • See the endpoint version comparison for a full migration checklist and feature comparison.
​
New API Error Codes
Platform
Added - April 2026
More granular error responses across the APINew error codes provide clearer feedback when requests fail, making it easier to handle edge cases in your integration.
  • ai_vendor_access_restricted — workspace AI vendor policy blocks the request.
  • unlimited_mode_disabled — avatar doesn’t support unlimited mode.
  • voice_unavailable — cloned voice failed processing or expired.
  • ephemeral_upload_disabled — eager upload temporarily disabled for the account.
  • gateway_timeout — external resource could not be fetched in time.
  • See the full error codes reference for details and troubleshooting.
​
Starfish Engine Integration
VoicesPlatform
Changed - April 2026
New requirement for Starfish engine compatibilityText-to-speech generation endpoints now require the use of voices that support the Starfish engine.
  • Updated POST /v1/audio/text_to_speech and POST /v3/voices/speech documentation.
  • Developers should filter for compatible voices by passing engine=starfish when calling the voice listing endpoints.
​
Asset ID Documentation Update
VideosAvatarsVideo TranslationLipsyncVideo Agent
Changed - April 2026
Standardized Asset ID descriptionsDocumentation across multiple endpoints has been clarified to consistently refer to asset IDs originating from the HeyGen asset upload endpoint. No functional changes were made to the API behavior.
  • Applies to request bodies for:
    • POST /v3/avatars
    • POST /v3/lipsyncs
    • POST /v3/video-agents and POST /v3/video-agents/{session_id}
    • POST /v3/video-translations, POST /v3/video-translations/proofreads, and PUT /v3/video-translations/proofreads/{proofread_id}/srt
    • POST /v3/videos
​
New Video Agents Endpoint
Video AgentPlatform
Added - April 2026
New endpoint for listing Video AgentsWe have introduced a new endpoint to allow developers to retrieve a list of all existing video agents associated with their account.
  • Added GET /v3/video-agents: Use this endpoint to fetch your video agents, enabling easier integration and management of your agent instances.
​
Avatar Error Code Update
Avatars
Changed - April 2026
Updated error codes for Avatar endpointsWe have updated the error response codes for avatar-related endpoints to provide more specific feedback when a group cannot be located.
  • GET /v3/avatars/{group_id}: The 404 response error code has been updated from not_found to avatar_group_not_found.
  • POST /v3/avatars/{group_id}/consent: The 404 response error code has been updated from not_found to avatar_group_not_found.
​
Enhanced Video Generation Controls
VideosVoices
Added - April 2026
Advanced voice customization and output formattingWe have introduced new parameters to provide finer control over generated audio and video output quality.
  • Added volume and engine_settings to voice_settings for POST /v2/videos and POST /v3/videos. These settings apply when using text-to-speech (script + voice_id).
  • Added output_format to POST /v3/videos for both CreateVideoFromAvatar and CreateVideoFromImage request schemas.
​
Webhook API Updates
Webhooks
Added - April 2026
Improved error handling for webhook managementWe have updated our webhook endpoints to provide more consistent and descriptive error responses.
  • Added a 409 conflict response to POST /v3/webhooks/endpoints to better handle registration errors.
  • Standardized error codes for 404 responses across DELETE, PATCH, and POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret by updating the error code to webhook_not_found.
​
New Output Format Support
Videos
Added - April 2026
Support for custom output formats in video generationYou can now specify a preferred output format when creating videos. The API response now includes the output_format field to confirm the format used for your generated video.
  • Added optional output_format request property to POST /v2/videos.
  • Added output_format to the response body of POST /v2/videos (200 OK).
  • Added output_format to the response body of POST /v3/videos (200 OK).
​
API Documentation Overhaul
PlatformVideosAvatarsVideo AgentVoicesVideo TranslationLipsyncWebhooks
Changed - April 2026
Comprehensive API Documentation UpdatesWe have updated the endpoint descriptions across our entire V3 API to provide clearer guidance, better parameter context, and more precise functionality definitions. While the underlying API logic remains consistent, the improved documentation clarifies how to integrate with our latest engine versions and features.
  • Video Generation: POST /v3/videos now officially documents support for the Avatar IV engine and upcoming Avatar V.
  • Avatars: Clarified workflows for POST /v3/avatars (asynchronous training) and added guidance on the mandatory consent flow for private avatars via POST /v3/avatars/{group_id}/consent.
  • Video Agent: Streamlined descriptions for session-based interactions, clearly distinguishing between generate (one-shot) and chat (multi-turn) modes.
  • Lipsync & Translation: Updated documentation for POST /v3/lipsyncs and POST /v3/video-translations to emphasize the speed vs. precision mode selection for output quality.
  • Webhooks: Clarified that PATCH /v3/webhooks/endpoints/{endpoint_id} performs a full replacement of the event types array.
  • Assets: Updated supported MIME types for POST /v3/assets to include refined file type lists.
​
Caption URL Support
LipsyncVideo Translation
Added - April 2026
Added caption_url to Lipsync and Video Translation responsesYou can now retrieve the caption_url for generated lipsyncs and video translations, providing direct access to the generated caption files.
  • GET /v3/lipsyncs and GET /v3/lipsyncs/{lipsync_id}
  • PATCH /v3/lipsyncs/{lipsync_id}
  • GET /v3/video-translations and GET /v3/video-translations/{video_translation_id}
  • PATCH /v3/video-translations/{video_translation_id}
​
Default Avatar Voices
VideosAvatars
Changed - April 2026
Support for avatar-default voicesYou can now generate videos using an avatar’s default voice without explicitly specifying a voice_id. When creating a video, if voice_id is omitted while avatar_id is present, the system will automatically use the avatar’s default voice.
  • Updated POST /v3/videos: The voice_id requirement has been relaxed for both CreateVideoFromAvatar and CreateVideoFromImage schemas, allowing the system to fall back to the avatar’s default voice.
​
Video Agent Interaction Updates
Video Agent
Changed - April 2026
Enhanced capabilities for Video Agent interactionsWe have updated the description and scope of the POST /v3/video-agents/{session_id} endpoint to better reflect its versatility in managing agent-led workflows.
  • Updated the endpoint description to clarify support for answering agent-posed questions and requesting specific edits or revisions.
  • The request body schema has been updated to better align with these extended conversational and editing capabilities.
​
Video Agent Status Update
Video AgentPlatform
Added - April 2026
New ‘thinking’ status for Video AgentsWe have introduced a new thinking state to the Video Agent response object to provide better visibility into agent processing workflows.
  • Updated POST /v3/video-agents
  • The status field in the response now includes the thinking enum value.
  • Integration note: Ensure your client-side parsers are prepared to handle this new status value in the response body.
​
Video Agent Enhancements
Video AgentBreaking Change
Changed - April 2026
Updated Video Agent session retrieval and new video listingWe have refactored how resource data is handled in Video Agent sessions to improve performance. Additionally, we have introduced a new endpoint to fetch videos associated with a session.
  • Breaking Change: The resources property has been removed from the response body of GET /v3/video-agents/{session_id}.
  • Migration: To access resource details previously found in the session object, please use the new GET /v3/video-agents/{session_id}/resources/{resource_id} endpoint.
  • New Endpoint: Added GET /v3/video-agents/{session_id}/videos to retrieve a list of videos generated within a specific agent session.
​
Video Agent Session Refactor
Video AgentBreaking Change
Changed - April 2026
Breaking change: Restructured Video Agent session managementWe have updated the Video Agent API to simplify session handling. Please note that the previous /v3/video-agents/sessions path structure is deprecated and removed.
  • Removed endpoints: POST /v3/video-agents/sessions, GET /v3/video-agents/sessions/{session_id}, POST /v3/video-agents/sessions/{session_id}/messages, GET /v3/video-agents/sessions/{session_id}/resources, and POST /v3/video-agents/sessions/{session_id}/stop have been removed.
  • Migration: Replace existing calls with the new flattened endpoints under /v3/video-agents/{session_id}.
  • New endpoints added:
    • GET /v3/video-agents/{session_id}
    • POST /v3/video-agents/{session_id}
    • GET /v3/video-agents/{session_id}/resources/{resource_id}
    • POST /v3/video-agents/{session_id}/stop
​
Video Agent Enhancements
Video Agent
Added - April 2026
New configuration options for Video Agent sessionsThe POST /v3/video-agents endpoint now supports advanced control over session flow.
  • Added mode: Supports generate (default, one-shot) and chat (multi-turn, allows revisions and follow-ups).
  • Added auto_proceed: Enables automated progression through storyboards.
  • Added skip_agentic_stop: Provides granular control over agent stopping behavior.
​
Platform Updates
PlatformUser
Changed - April 2026
API Operation ID updateThe operation ID for GET /v3/users/me has been updated from getUserMeV3 to getCurrentUserV3 to maintain consistency across our SDKs.
​
New Voice Creation Endpoint
Voices
Added - April 2026
Added support for custom voice creationWe have introduced a new endpoint to allow developers to programmatically create and add new voices to their HeyGen account.
  • Added POST /v3/voices to the API.
​
New Video Creation Schema
VideosBreaking Change
Changed - April 2026
Refactored POST /v3/videos request bodyWe have updated the POST /v3/videos endpoint to use a discriminated union for improved type safety and flexibility. This change replaces the legacy flat request structure with dedicated schemas for creating videos from avatars versus images.
  • Breaking Change: The request body structure has been completely overhauled. You must now specify a type discriminator: use CreateVideoFromAvatar for digital twins/avatars or CreateVideoFromImage for custom image animation.
  • Migration: All properties previously passed at the top level of the request (e.g., avatar_id, image_url, voice_id, script) must now be nested within the appropriate schema based on the video source.
  • The operation ID for this endpoint has been updated from createAvatarVideoV3 to createVideo.
​
Improved API Error Handling
Platform
Changed - April 2026
Enhanced error messaging across all endpointsWe have updated the error response schemas and examples across the entire API suite. Developers can now expect more consistent and detailed error responses for common issues, including:
  • Improved 400 Bad Request messages with clearer parameter validation feedback.
  • Standardized 401 Unauthorized responses when API keys are missing or expired.
  • Consistent 429 Rate Limited responses that align with standard retry headers.
  • Better descriptive error messages for resource-specific failures (e.g., 404 Not Found for specific IDs).
These updates ensure that your integrations can better handle exceptions and debugging.
​
New v3 API endpoints
Platform
Added - April 2026
HeyGen for Developers — New v3 API SurfaceWe’ve launched a new set of v3 endpoints across the HeyGen API, bringing a consistent interface, cursor-based pagination, and a unified asset input model to all major resources.What’s new:
  • All v3 endpoints share a standard error format, cursor-based pagination (has_more / next_token), and consistent authentication via X-Api-Key or OAuth bearer token.
  • Asset inputs now use a type-discriminated union — pass files as { "type": "url", "url": "..." }, { "type": "asset_id", "asset_id": "..." }, or { "type": "base64", "media_type": "...", "data": "..." } across all endpoints.
  • New and updated endpoints include: Video Agent (POST /v3/video-agents), Videos (POST /v3/videos), Voices (GET /v3/voices, POST /v3/voices/speech), Video Translations (POST /v3/video-translations), Overdub (POST /v3/overdubs), Avatars (POST /v3/avatars), Assets (POST /v3/assets), Webhooks (/v3/webhooks/*), and User (GET /v3/users/me).
The v1/v2 endpoints continue to work, but we recommend migrating to v3 for all new integrations.