## 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 — Create the video

Send a `POST` request to `/v3/videos` with `type: "avatar"`, 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 '{
    "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": "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

| Status     | Meaning                          |  |
|------------|---------------------------------|--|
| `pending`  | Queued for processing           |  |
| `processing` | Video is being generated       |  |
| `completed` | Ready — `video_url` is available |  |
| `failed`    | Something 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={
    "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": "16:9"
})
vide_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    | Description  |
|---------------------|---------|--------------|
| `title`             | string  | Display name in the HeyGen dashboard |
| `resolution`        | string  | `4k`, `1080p`, or `720p` |
| `aspect_ratio`      | string  | `16:9` or `9:16` |
| `remove_background` | boolean | Removes the avatar background (twin must be trained with matting enabled) |
| `background`        | object  | Set a solid color or image background |
| `voice_settings`    | object  | Adjust `speed` (0.5–1.5), `pitch` (-50 to +50), and `locale` |
| `callback_url`      | string  | 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.