Digital Twin

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 an engine, check the supported_api_engines array on the avatar look via GET /v3/avatars/looks/{look_id} — it lists which of avatar_iii, avatar_iv, and avatar_v the look accepts, and requesting an engine that isn’t listed will be rejected. 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 everything you need to download and display the result:

Field	What it is
`video_url`	The rendered video. Captions are burned in only when you request a caption `style` — otherwise this is always the clean render.
`captioned_video_url`	The video with captions burned in, when caption burn-in was requested.
`subtitle_url`	The SRT subtitle sidecar file, when captions were requested.
`thumbnail_url`	Still thumbnail image.
`gif_url`	Animated GIF preview.
`duration`	Video length in seconds.

These are presigned URLs with a limited expiry window — download promptly, or call GET /v3/videos/{video_id} again to get fresh URLs. When status is failed, the response includes a machine-readable failure_code alongside the human-readable failure_message.

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)
`caption`	object	Both	Caption settings — see Captions and subtitles
`callback_url`	string	Both	Webhook URL — receive a POST when the video is ready

Captions and subtitles

Captions are off by default — omit caption and video_url is a clean render with no subtitles. To generate captions, pass a caption object:

{
  "caption": { "file_format": "srt" }
}

This returns a sidecar subtitle file via subtitle_url in the status response, while the video itself stays clean — you control how subtitles display in your own player. To additionally burn captions into the rendered video, set a style:

{
  "caption": { "file_format": "srt", "style": "default" }
}

caption is an object on /v3/videos. Boolean-style fields like caption: true or enable_caption (used by the v2 API and by the template endpoint) fail /v3/videos validation with invalid_parameter (“Extra inputs are not permitted”). Use the object form above.

If a downloaded video shows captions you didn’t ask for, you most likely grabbed captioned_video_url (or the url from a webhook payload that points at the captioned render). Fetch GET /v3/videos/{video_id} and download video_url for the caption-free file.

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.

Auth

User Info

Models

Video Generation

Video Composition

Realtime Video

Video Translation

Video Agent

Lipsync

Tools

Avatar Management

Voice Management

Asset Management

Batches

Webhook

Limits

Pricing

Socials

For Agents

Integrations

Prerequisites

Step 1 — Find your Digital Twin

Step 2 — Choose a rendering engine

Step 3 — Create the video

Using Avatar IV (default)

Using Avatar V (higher quality)

Step 4 — Poll for completion

Status values

Full example

Optional parameters

Captions and subtitles

Using webhooks instead of polling

​Prerequisites

​Step 1 — Find your Digital Twin

​Step 2 — Choose a rendering engine

​Step 3 — Create the video

​Using Avatar IV (default)

​Using Avatar V (higher quality)

​Step 4 — Poll for completion

​Status values

​Full example

​Optional parameters

​Captions and subtitles

​Using webhooks instead of polling

Prerequisites

Step 1 — Find your Digital Twin

Step 2 — Choose a rendering engine

Step 3 — Create the video

Using Avatar IV (default)

Using Avatar V (higher quality)

Step 4 — Poll for completion

Status values

Full example

Optional parameters

Captions and subtitles

Using webhooks instead of polling