Avatar 6

Avatar 6 is available two ways:

	Model API	Application API
Endpoint	`POST /v3/models/avatars`	`POST /v3/videos`
You send	A reference image or video plus speech audio	A HeyGen avatar look plus a script and voice, or audio
Models	`heygen-avatar-6`, `heygen-avatar-6-turbo`	`heygen-avatar-6`, `heygen-avatar-6-turbo`
Resolution	`1080p` (default) or `2k`	`1080p` (default) or `2k`
Output size	Follows the reference’s shape (sizes)	Set by `aspect_ratio` (sizes)
Motion controls	`motion_prompt` and `motion_expressiveness`	`motion_prompt` and `engine.motion_expressiveness`

Model API

The Avatar 6 model animates your reference media with the speech audio you supply. There is no avatar or voice to set up first.

curl -X POST "https://api.heygen.com/v3/models/avatars" \
  -H "x-api-key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-6",
    "reference_images": [{ "type": "asset_id", "asset_id": "IMAGE_ASSET_ID" }],
    "audio": { "type": "url", "url": "https://example.com/speech.wav" },
    "resolution": "2k",
    "motion_prompt": "Face the camera with a warm expression and use small, natural hand gestures."
  }'

Submission returns 202:

{ "data": { "video_id": "VIDEO_ID", "status": "pending" } }

Each media input accepts an HTTPS URL, an uploaded asset ID, or inline base64:

{ "type": "url",      "url": "https://example.com/photo.jpg" }
{ "type": "asset_id", "asset_id": "ASSET_ID" }
{ "type": "base64",   "media_type": "image/jpeg", "data": "<base64>" }

Field	Type	Default	Notes
`model`	string	required	`heygen-avatar-6` or `heygen-avatar-6-turbo`. Both take the same inputs.
`reference_images`	array		One image. Send `reference_images`, `reference_videos`, or both: at least one is required.
`reference_videos`	array		One video. See reference media.
`audio`	asset	required	The speech the avatar performs. The video runs the length of the audio.
`resolution`	enum	`1080p`	`1080p` or `2k`
`motion_prompt`	string		Up to 1,200 characters on gestures, expression, posture and camera. Takes precedence over `motion_expressiveness` where they overlap.
`motion_expressiveness`	enum	`default`	`default`, or `less` for fewer, smaller gestures and calmer expressions
`output_width`, `output_height`	integer		Resize the finished video to an exact size. Even pixel values, set together. Omit both for the output size below.
`callback_url`	string		HTTPS URL notified when the job finishes
`callback_id`	string		Up to 256 characters, returned with the callback

Output size

Without output_width and output_height, the video keeps the reference’s aspect ratio, sized by resolution:

`resolution`	Short edge	16:9 reference	9:16 reference
`1080p`	1080 px	1920 × 1080	1080 × 1920
`2k`	1620 px	2880 × 1620	1620 × 2880

Retrieve the result

curl "https://api.heygen.com/v3/models/videos/VIDEO_ID" \
  -H "x-api-key: $HEYGEN_API_KEY"

{
  "data": {
    "video_id": "VIDEO_ID",
    "status": "completed",
    "model": "heygen-avatar-6",
    "created_at": 1793750400,
    "video_url": "https://resource2.heygen.ai/videos/.../VIDEO.mp4",
    "duration": 12.6,
    "width": 2880,
    "height": 1620,
    "aspect_ratio": "16:9"
  }
}

pending and processing mean the job is running; it ends as completed, failed or cancelled. video_url is a signed link: poll again to refresh it. duration can be about a tenth of a second shorter than the audio. Failed and cancelled jobs carry failure_code and failure_message:

`failure_code`	Meaning
`generation_failed`	The render did not complete. Retry the request.
`generation_cancelled`	The job was cancelled.
`moderation_rejected`	The speech or reference media does not meet HeyGen’s content policy. Send different input.

Reference media

Three ways to render a real person, based on your source material and your agreement with HeyGen:

Approach	Available to	Consent	Avatar slot
HeyGen avatar: a public avatar, or a digital twin made through HeyGen’s consent flow, on the Application API	All workspaces	Handled by HeyGen’s consent flow	Required for digital twins
Photo reference: a photo of the person, used with their permission. The model generates the motion.	All workspaces	No agreement needed	Not required
Video reference: the person’s own gestures and mannerisms, for the highest likeness. Add a matching photo for best results.	Enterprise customers	The person verifies consent with HeyGen before their video is submitted. Some contracts run without a consent step, reviewed case by case.	Not required

Videos of animated or illustrated characters work as references in every workspace. A realistic reference video from a workspace without video-reference access returns 422 with realistic_human_reference_not_allowed. Use a photo reference or a HeyGen avatar instead, or contact sales for access. Reference URLs and base64 inputs take videos up to 50 MB and images up to 32 MB. For a larger reference video, up to 200 MB, upload it with direct upload and pass its asset_id.

Application API

Render a HeyGen avatar look with Avatar 6 on POST /v3/videos by setting engine.type to heygen-avatar-6 or heygen-avatar-6-turbo. To animate a realistic person, use a digital twin created with HeyGen’s consent flow.

curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_LOOK_ID",
    "script": "Welcome. This clip was rendered with Avatar 6.",
    "voice_id": "YOUR_VOICE_ID",
    "engine": { "type": "heygen-avatar-6", "motion_expressiveness": "less" },
    "resolution": "2k",
    "aspect_ratio": "16:9",
    "motion_prompt": "Smile warmly and use small, open-handed gestures while speaking."
  }'

The response returns data.video_id. This endpoint supports Avatar 6 for single-avatar requests (type: "avatar"). Avatar 6 is not supported for raw-image requests, studio scenes, batch creation, or scene editing. Omitting engine continues to select Avatar IV. Use a compatible photo or video look. Check supported_api_engines on GET /v3/avatars/looks/{look_id}: eligible looks list heygen-avatar-6 and heygen-avatar-6-turbo. The look and reference must also satisfy the consent requirements.

Field	Notes
`type`	`avatar`
`avatar_id`	A look ID, from the public library or your workspace (`GET /v3/avatars/looks`)
`script` + `voice_id`, `audio_url` or `audio_asset_id`	One speech source: a script with a voice, a public audio URL, or an uploaded audio asset
`engine.type`	`heygen-avatar-6` or `heygen-avatar-6-turbo`
`engine.reference_look_id`	Optional. A digital-twin look in the same avatar group whose recorded footage drives the motion. It must be accessible to your workspace, have completed consent, and be eligible for Avatar 6.
`engine.motion_expressiveness`	`default` (also the omission default), or `less` for fewer, smaller gestures and calmer facial expressions. Does not disable motion.
`resolution`	`1080p` or `2k`. Omitted or `null` defaults to `1080p`; `720p` and `4k` are not supported.
`aspect_ratio`	`16:9` (default), `9:16`, `1:1`, `4:5`, `5:4`, or `auto`. Output sizes are below.
`motion_prompt`	Optional. Plain-language direction for gestures, expression and posture. Overrides `engine.motion_expressiveness` where specified.
`title`	Optional. Name of the video in your library

The legacy top-level expressiveness field is not accepted for Avatar 6. Set motion_expressiveness inside engine. When engine.reference_look_id is omitted, a video look uses its own footage and a photo look renders without a video reference. aspect_ratio: "auto" derives the output shape from the source; use an explicit aspect ratio below for predictable dimensions.

`aspect_ratio`	`1080p`	`2k`
`16:9`	1920 × 1080	2560 × 1440
`9:16`	1080 × 1920	1440 × 2560
`1:1`	1080 × 1080	1440 × 1440
`4:5`	1080 × 1350	1440 × 1800
`5:4`	1350 × 1080	1800 × 1440

Check status

curl "https://api.heygen.com/v3/videos/VIDEO_ID" \
  -H "x-api-key: $HEYGEN_API_KEY"

When data.status is completed, download the file from data.video_url. The link is signed, so poll again for a fresh one. A failed video carries data.failure_code and data.failure_message.

Auth

User Info

Models

Applications

Platform

For Agents

Integrations

Model API

Output size

Retrieve the result

Reference media

Application API

Check status

​Model API

​Output size

​Retrieve the result

​Reference media

​Application API

​Check status

Model API

Output size

Retrieve the result

Reference media

Application API

Check status