Create Video
Creates an avatar video: a HeyGen avatar or an image speaks your script or audio with lip-sync. Choose Avatar III, IV, V or Avatar 6 (heygen-avatar-6, or heygen-avatar-6-turbo for faster renders) with engine (Avatar IV by default); a look’s supported_api_engines lists the engines it supports. To generate a whole scene from a prompt instead, use POST /v3/models/videos.
Headers
Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.
1 - 255^[A-Za-z0-9_\-:.]{1,255}$Body
- CreateVideoFromAvatar
- CreateVideoFromImage
- CreateVideoFromCinematicAvatar
- CreateVideoFromStudio
Create a video from a HeyGen avatar (video or photo avatar).
Provide an avatar_id to use a previously created avatar. Supports all
avatar types: studio_avatar, digital_twin, and photo_avatar. Optionally
set engine to select Avatar V for eligible avatars; when omitted, the
server defaults to Avatar IV.
Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. Supported only for single-video creation; batch video items cannot set their own destination folder.
Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.
16:9, 9:16, 4:5, 5:4, 1:1, auto How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations.
contain, cover Upload the finished files straight into your own storage. Give a presigned PUT URL per file, for Amazon S3, Google Cloud Storage or Azure Blob Storage; HeyGen uploads each file when the video finishes. The outcome is reported by the video_delivery.success and video_delivery.fail webhooks. Available to enabled workspaces.
Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically — the caller does not need to set 'remove_background'.
mp4, webm Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from script; a caller-supplied audio_url or audio_asset_id is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.
1Natural-language prompt controlling avatar body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars when engine.type is 'avatar_v'. Rejected for video avatars on the default Avatar IV engine, and for photo avatars on 'avatar_v' when the avatar's group has no animation reference (no digital twin or curated reference look).

