Skip to main content

​
Supported avatar types

digital_twin — for eligible looks.

​
Supported parameters

  • motion_prompt — natural-language control of body motion and hand gestures.
  • reference_look_id (optional) — an instant_avatar look to use as the animation reference. Must belong to the same avatar group as avatar_id. When omitted, the digital twin self-references.
For expressiveness control, use Avatar IV.

​
Checking eligibility

Avatar V is opt-in per look. 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 available when "avatar_v" appears in supported_api_engines.

​
Example request

Select Avatar V by passing "engine": { "type": "avatar_v" } in your POST /v3/videos request: 
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_LOOK_ID",
    "script": "Hello from Avatar V.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p",
    "engine": { "type": "avatar_v" }
  }'
Video generation is asynchronous — the response returns a video_id you poll with GET /v3/videos/{video_id}. See the Digital Twin guide for the end-to-end request and polling flow, Models for an engine comparison, or Avatar IV for the default engine.