Skip to main content

​
Prerequisites

A Digital Twin avatar_id (type: video_avatar). Use GET /v3/avatars/looks?avatar_type=video_avatar 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=video_avatar&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 — Create the video

Send a POST request to /v3/videos with your Digital Twin ID, a script, and a voice: 
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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": "16:9"
  }'

​
Step 3 — 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

StatusMeaning
pendingQueued for processing
processingVideo is being generated
completedReady — video_url is available
failedSomething went wrong
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
resp = requests.post(f"{BASE}/v3/videos", headers=HEADERS, json={
    "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": "16:9"
})
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

ParameterTypeDescription
titlestringDisplay name in the HeyGen dashboard
resolutionstring1080p or 720p
aspect_ratiostring16:9 or 9:16
remove_backgroundbooleanRemoves the avatar background (twin must be trained with matting enabled)
backgroundobjectSet a solid color or image background
voice_settingsobjectAdjust speed (0.5–1.5), pitch (-50 to +50), and locale
callback_urlstringWebhook 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. 
{
  "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.