Skip to main content

Documentation Index

Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt

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

​
HeyGen Avatar Rendering Engines

HeyGen has three generations of rendering engines. New integrations should use Avatar IV or Avatar V via POST /v3/videos.

​
Avatar III (Legacy)

Only available to existing users through the v1/v2 legacy endpoints. Not offered to new users and not accessible via POST /v3/videos.

​
Avatar IV

The default engine on the v3 API. Omitting the engine field automatically uses Avatar IV. Supported avatar types: studio_avatar, digital_twin, photo_avatar, image (arbitrary), prompt Exclusive features:
  • motion_prompt — natural-language string to control body motion (e.g. "walk towards the camera slowly"). Photo avatars and arbitrary images only.
  • expressiveness — controls energy and range of movement: high, medium, or low. Photo avatars and arbitrary images only. Defaults to low.
  • Arbitrary image support — animate any image by setting type: "image" without a registered avatar.
Example: 
{
  "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 selected automatically.

​
Avatar V

The latest engine, offering more natural motion and lip-sync through cross-reference-driven animation. Must be explicitly opted into and is only available for avatar looks that support it. Supported avatar types: studio_avatar, digital_twin, photo_avatar, prompt (all subject to eligibility) Not supported: arbitrary image input (type: "image") Not supported parameters (Avatar IV only):
  • motion_prompt
  • expressiveness

​
Checking Eligibility

Not every avatar look supports Avatar V. Before using it, fetch the look and check supported_api_engines: 
GET /v3/avatars/looks/{look_id}

{
  "id": "lk_abc123",
  "name": "My Digital Twin",
  "avatar_type": "digital_twin",
  "supported_api_engines": ["avatar_iv", "avatar_v"]
}
Avatar V is only available if "avatar_v" appears in supported_api_engines. Requesting it for an ineligible look returns a 400 error. Example: 
{
  "type": "avatar",
  "avatar_id": "YOUR_LOOK_ID",
  "script": "Hello from Avatar V.",
  "voice_id": "YOUR_VOICE_ID",
  "resolution": "1080p",
  "engine": { "type": "avatar_v" }
}

​
Comparison

FeatureAvatar IIIAvatar IVAvatar V
API versionv1/v2 (legacy)v3v3
Available to new users✗✓✓
Default engine✗✓✗ (explicit opt-in)
Arbitrary image input✗✓✗
motion_prompt✗✓✗
expressiveness✗✓✗
Cross-reference animation✗✗✓
Better motion & lip-sync quality✗✗✓
Eligibility check required✗✗✓