Models

Overview

HeyGen avatar videos are defined by two independent concepts: avatar type (what the avatar looks like) and rendering engine (how it animates). Understanding both helps you pick the right combination for your use case.

Avatar types

Type	Description
digital_twin	A lifelike avatar trained from real video footage of a person
photo_avatar	An avatar generated from a single photo
studio_avatar	A pre-built HeyGen avatar from the public library
image	Animate any arbitrary image directly — no registered avatar needed
prompt	An AI-generated avatar created from a text description

Rendering engines

Each generation of HeyGen’s rendering engine improves on motion quality, expressiveness, and API capabilities. The engine is set via the engine field in POST /v3/videos.

Generation	Engine key
Avatar III	N/A (legacy)
Avatar IV	avatar_iv
Avatar V	avatar_v

Avatar III is only available to existing users on legacy endpoints. New integrations should use Avatar IV or Avatar V via POST /v3/videos.

---

Avatar IV

Avatar IV is the default rendering engine on the v3 API. When you call POST /v3/videos without specifying an engine, Avatar IV is used automatically.

Key capabilities

• Default engine — no configuration needed. Omitting the engine field selects Avatar IV.
• motion_prompt — a natural-language string that controls avatar body motion (e.g., "walk towards the camera slowly"). Photo avatars and arbitrary images only.
• expressiveness — controls the energy and range of facial/body movement (high, medium, low). Photo avatars and arbitrary images only. Defaults to low.
• Arbitrary image support — animate any image by setting type: "image" in the request body instead of using a registered avatar look.
• Full v3 feature set — supports fit, remove_background, background, watermark, caption, and output_format: "webm".

Supported avatar types

Avatar type	Supported	motion_prompt	expressiveness
studio_avatar	✓	✗	✗
digital_twin	✓	✗	✗
photo_avatar	✓	✓	✓
image (arbitrary)	✓	✓	✓
prompt	✓	✗	✗

Example request

{
  "type": "avatar",
  "avatar_id": "YOUR_LOOK_ID",
  "script": "Hello from Avatar IV.",
  "voice_id": "YOUR_VOICE_ID",
  "resolution": "1080p"
}

engine is omitted — Avatar IV is the default.

Avatar V

Avatar V is HeyGen’s latest rendering engine. It uses cross-reference-driven animation, analyzing the avatar and audio together to produce more natural motion and lip-sync than Avatar IV. It must be explicitly requested and is only available for avatar looks that have been trained or certified to support it.

Key capabilities

• Cross-reference-driven animation — produces more natural, coherent motion than Avatar IV, particularly for complex expressions and longer scripts.
• Explicit opt-in — pass engine: {"type": "avatar_v"} to use it.
• v3 only — Avatar V is not available through legacy v1/v2 endpoints.
• Full v3 feature set — supports fit, remove_background, background, watermark, caption, and output_format: "webm".

Checking eligibility

Not every avatar look supports Avatar V. Inspect the supported_api_engines array on the look before requesting it:

curl -X GET "https://api.heygen.com/v3/avatars/looks/YOUR_LOOK_ID" \
  -H "x-api-key: YOUR_API_KEY"

{
  "id": "lk_abc123",
  "name": "My Digital Twin",
  "avatar_type": "digital_twin",
  "supported_api_engines": ["avatar_iv", "avatar_v"]
}

Avatar V is available only if "avatar_v" appears in supported_api_engines.

If you pass engine: {"type": "avatar_v"} for a look that does not list avatar_v in supported_api_engines, the API returns a 400 error.

Parameters not supported in Avatar V

Parameter	Avatar IV	Avatar V
motion_prompt	✓	✗
expressiveness	✓	✗

Do not include these parameters when engine.type is avatar_v.

Supported avatar types

Avatar type	Supported	Notes
studio_avatar	✓ (if eligible)	Check supported_api_engines
digital_twin	✓ (if eligible)	Check supported_api_engines
photo_avatar	✓ (if eligible)	Check supported_api_engines
image (arbitrary)	✗	Avatar V requires a registered look
prompt	✓ (if eligible)	Check supported_api_engines

Example request

{
  "type": "avatar",
  "avatar_id": "YOUR_LOOK_ID",
  "script": "Hello from Avatar V.",
  "voice_id": "YOUR_VOICE_ID",
  "resolution": "1080p",
  "engine": { "type": "avatar_v" }
}

Avatar III (legacy)

Avatar III is HeyGen’s original rendering engine, available only to existing users through the v1 and v2 legacy endpoints. It is not offered to new users.