Digital Twin

Generate AI avatar video from a script with the HeyGen API. Pick an avatar, voice, and background; HeyGen handles rendering, captions, and final export.

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

Prerequisites

A Digital Twin avatar_id (type: digital_twin). Use GET /v3/avatars/looks?avatar_type=digital_twin to find yours.

A voice_id for the voice you want. Use GET /v3/voices to browse available voices.

Step 1 — Find your Digital Twin

List your private Digital Twin looks to get the avatar_id:

curl -X GET "https://api.heygen.com/v3/avatars/looks?avatar_type=digital_twin&ownership=private" \
  -H "x-api-key: YOUR_API_KEY"

From the response, copy the id field of the look you want. This is your avatar_id.

Step 2 — Choose a rendering engine

HeyGen v3 supports three rendering engines for Digital Twins. You select the engine via the engine object in your video creation request.

Engine	Key	Default?	Quality
Avatar IV	avatar_iv	Yes — used when engine is omitted	Standard, widely supported
Avatar V	avatar_v	No — must be explicitly requested	Higher quality, cross-reference-driven animation
Avatar III	avatar_iii	No — must be explicitly requested	Dedicated photo-to-video pipeline

Before requesting Avatar V, check the supported_api_engines array on the avatar look via GET /v3/avatars/looks/{look_id} — if avatar_v is not listed, the request will be rejected. Avatar III does not appear in supported_api_engines and accepts any avatar look. See Models for full details on each engine.

Step 3 — Create the video

Send a POST request to /v3/videos with type: "avatar", your Digital Twin ID, a script, and a voice.

Using Avatar IV (default)

Omit the engine field or pass {"type": "avatar_iv"} — Avatar IV is the default:

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_DIGITAL_TWIN_LOOK_ID",
    "script": "Hello! I am your Digital Twin. This video was generated entirely through the HeyGen API.",
    "voice_id": "YOUR_VOICE_ID",
    "title": "My First Digital Twin Video",
    "resolution": "1080p",
    "aspect_ratio": "auto"
  }'

Using Avatar V (higher quality)

Pass {"type": "avatar_v"} in the engine field to request cross-reference-driven animation:

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_DIGITAL_TWIN_LOOK_ID",
    "script": "Hello! I am your Digital Twin.",
    "voice_id": "YOUR_VOICE_ID",
    "title": "My Digital Twin — Avatar V",
    "resolution": "1080p",
    "aspect_ratio": "auto",
    "engine": { "type": "avatar_v" }
  }'

motion_prompt is supported on both Avatar IV and Avatar V — pass a natural-language prompt to control body motion and hand gestures.

expressiveness remains an Avatar IV-only parameter. Do not include it when using Avatar V — it will cause a validation error.

Step 4 — Poll for completion

Video generation is asynchronous. Poll GET /v3/videos/{video_id} until status is completed:

curl -X GET "https://api.heygen.com/v3/videos/YOUR_VIDEO_ID" \
  -H "x-api-key: YOUR_API_KEY"

Status values

Status	Meaning
pending	Queued for processing
processing	Video is being generated
completed	Ready — video_url is available
failed	Something went wrong — check failure_message

Once completed, the response includes a video_url with a presigned download link.

Full example

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# 1. Create the video (Avatar V — swap engine for {"type": "avatar_iv"} or omit for default)
resp = requests.post(f"{BASE}/v3/videos", headers=HEADERS, json={
    "type": "avatar",
    "avatar_id": "YOUR_DIGITAL_TWIN_LOOK_ID",
    "script": "Welcome to our product demo. Let me walk you through the new features.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p",
    "aspect_ratio": "auto",
    "engine": {"type": "avatar_v"}  # omit entirely to use Avatar IV (default)
})
video_id = resp.json()["data"]["video_id"]
print(f"Video created: {video_id}")

# 2. Poll until done
while True:
    status_resp = requests.get(f"{BASE}/v3/videos/{video_id}", headers=HEADERS)
    data = status_resp.json()["data"]
    print(f"Status: {data['status']}")
    if data["status"] == "completed":
        print(f"Download: {data['video_url']}")
        break
    elif data["status"] == "failed":
        print(f"Error: {data.get('failure_message')}")
        break
    time.sleep(10)

Optional parameters

Parameter	Type	Engine	Description
title	string	Both	Display name in the HeyGen dashboard
resolution	string	Both	4k, 1080p (recommended), or 720p
aspect_ratio	string	Both	auto (recommended — matches the source, falling back to 16:9), 16:9, 9:16, 4:5, 5:4, or 1:1
engine	object	—	{"type": "avatar_iv"}, {"type": "avatar_v"}, or {"type": "avatar_iii"}. Defaults to Avatar IV when omitted
remove_background	boolean	Both	Removes the avatar background (supported by default on new digital twins)
background	object	Both	Set a solid color or image background
voice_settings	object	Both	Adjust speed (0.5–1.5), pitch (-50 to +50), and locale
motion_prompt	string	Both	Natural-language prompt controlling avatar body motion and hand gestures
expressiveness	string	IV only	high, medium, or low. Defaults to low
output_format	string	Both	mp4 (default) or webm (transparent background / alpha channel)
callback_url	string	Both	Webhook URL — receive a POST when the video is ready

Using webhooks instead of polling

Instead of polling, pass a callback_url when creating the video. HeyGen will send a POST request to that URL when the video completes or fails.

{
  "type": "avatar",
  "avatar_id": "YOUR_DIGITAL_TWIN_LOOK_ID",
  "script": "This video uses a webhook callback.",
  "voice_id": "YOUR_VOICE_ID",
  "callback_url": "https://your-server.com/webhooks/heygen"
}

Register a webhook endpoint via POST /v3/webhooks/endpoints and subscribe to avatar_video.success and avatar_video.fail events for production use.