Skip to main content
Free usage: Avatar IV videos created through CLI OAuth (heygen auth login --oauth) draw from your free monthly avatar-video quota — no pay-as-you-go charge. See Free usage for agents.

​
Supported avatar types

studio_avatar, digital_twin, photo_avatar, image (arbitrary), prompt

​
Exclusive features

  • motion_prompt — a natural-language string controlling body motion and hand gestures (e.g. "walk towards the camera slowly"). Available for photo avatars and arbitrary images.
  • expressiveness — controls energy and range of movement: high, medium, or low. Available for photo avatars and arbitrary images. Defaults to low.
  • Arbitrary image support — animate any image by setting type: "image", with no registered avatar required.

​
Example request

Avatar IV is the default engine, so you can omit engine entirely 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 IV.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p"
  }'
To request it explicitly — or to be unambiguous in code that switches engines — pass "engine": { "type": "avatar_iv" }: 
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 IV.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p",
    "engine": { "type": "avatar_iv" }
  }'
Video generation is asynchronous — the response returns a video_id you poll with GET /v3/videos/{video_id}. For a full walkthrough of creating a Digital Twin video and polling for completion, see the Digital Twin guide. To compare engines, see Models; for the highest-fidelity motion, see Avatar V.