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.
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" 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 | ✓ | ✗ |
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.
