Skip to main content
​
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.
​
Updated Response Schemas
VideosAvatarsVoicesVideo AgentVideo TranslationWebhooksUser
Changed - April 2026
Consistency updates for API response structuresWe have updated the response schemas for various endpoints to provide more accurate and up-to-date data structures. Key areas affected include:
  • Videos (/v2/videos, /v3/videos): Updated property definitions for generated media and failure metadata.
  • Avatars (/v3/avatars): Refined schema definitions for avatar groups, looks, and consent statuses.
  • Voices (/v1/audio/voices, /v3/voices): Standardized properties for voice metadata and locale support.
  • User (/v1/user/me, /v3/user/me): Updated user profile, billing, and subscription credit models.
  • Workflows: Refined execution data and workflow definitions.
  • Webhooks: Updated webhook endpoint configurations and event data schemas.
​
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/user/me).
The v1/v2 endpoints continue to work, but we recommend migrating to v3 for all new integrations.
​
Digital Twin Creation & Overdub
AvatarsOverdub
Added - April 2026
Create Digital Twins and Photo Avatars via APIYou can now create custom avatars programmatically with POST /v3/avatars. Two creation modes are supported:
  • Digital Twin (type: "video") — upload training footage and HeyGen builds a reusable avatar from the speaker in the video.
  • Photo Avatar (type: "photo") — upload a single headshot for a quick avatar with no video recording needed.
Both return an avatar_item with a look ID you can pass directly to POST /v3/videos for video generation. A consent flow (POST /v3/avatars/{group_id}/consent) is available to collect approval from the avatar subject before use.Overdub — Replace Audio with Lip-SyncThe new Overdub API (POST /v3/overdubs) lets you swap a video’s audio track and re-sync the speaker’s lip movements to match. Provide a source video and replacement audio — HeyGen handles the rest.
  • Choose "speed" mode for fast turnaround or "precision" for higher quality lip-sync using avatar inference.
  • Supports partial overdub via start_time / end_time, background music removal, caption generation, and webhook notifications.
  • Poll status via GET /v3/overdubs/{overdub_id} until "completed".
  • Overdub Guide