Documentation Index
Fetch the complete documentation index at: https://developers.heygen.com/llms.txt
Use this file to discover all available pages before exploring further.
Creation Methods
Digital Twin
Photo Avatar
Prompt-to-Avatar
Digital Twin (type: "digital_twin")
Create an avatar from video footage. The speaker in the video becomes a reusable digital twin.curl -X POST "https://api.heygen.com/v3/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "digital_twin",
"name": "My Digital Twin",
"file": { "type": "url", "url": "https://example.com/training-footage.mp4" }
}'
| Parameter | Type | Required | Description |
|---|
type | string | Yes | Must be "digital_twin". |
name | string | Yes | Display name for the avatar. |
file | object | Yes | Training video. { "type": "url", "url": "..." }, { "type": "asset_id", "asset_id": "..." }, or { "type": "base64", "media_type": "video/mp4", "data": "..." }. |
avatar_group_id | string | No | Attach to an existing character identity. Omit to create a new one. |
Photo Avatar (type: "photo")
Create an avatar from a single photo. Quick to set up — no video recording needed.curl -X POST "https://api.heygen.com/v3/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "photo",
"name": "My Photo Avatar",
"file": { "type": "url", "url": "https://example.com/headshot.png" }
}'
| Parameter | Type | Required | Description |
|---|
type | string | Yes | Must be "photo". |
name | string | Yes | Display name for the avatar. |
file | object | Yes | Photo image. Same format options as digital twin file. |
avatar_group_id | string | No | Attach to an existing character identity. Omit to create a new one. |
Prompt-to-Avatar (type: "prompt") — Tokyo Pipeline
Generate an entirely new AI avatar from a text description. No photo or video needed — describe the character you want and the Tokyo pipeline creates it.Prompt-to-Avatar uses HeyGen’s Tokyo pipeline to generate a unique AI character from your text description. The avatar is fully synthetic — no real person is depicted.
curl -X POST "https://api.heygen.com/v3/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "prompt",
"name": "Space Commander",
"prompt": "Young woman, early 30s, confident expression, short silver hair, warm brown eyes, wearing a dark blue space suit with mission patches, standing in a modern spacecraft bridge with holographic displays"
}'
Parameters
| Parameter | Type | Required | Description |
|---|
type | string | Yes | Must be "prompt". |
name | string | Yes | Display name for the avatar. |
prompt | string | Yes | Text description of the avatar’s appearance, clothing, setting, and style. Be specific for best results. |
reference_images | array | No | Optional reference images to guide generation. Array of objects: [{ "type": "url", "url": "..." }]. |
avatar_group_id | string | No | Attach to an existing character identity. Omit to create a new one. |
With Reference Images
You can provide reference images to guide the avatar’s appearance — useful for matching a brand style or specific aesthetic:curl -X POST "https://api.heygen.com/v3/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "prompt",
"name": "Brand Ambassador",
"prompt": "Professional woman in her 40s, warm smile, wearing a navy blazer, modern office background with plants",
"reference_images": [
{ "type": "url", "url": "https://example.com/style-reference.png" },
{ "type": "url", "url": "https://example.com/setting-reference.jpg" }
]
}'
Prompting tips for best results:
- Be specific about age, gender, expression, and clothing
- Describe the setting/background
- Mention lighting or mood (e.g.,
"warm studio lighting", "cinematic")
- Reference images help with style consistency but are optional
Response
All three creation types return the same response shape:
{
"data": {
"avatar_item": {
"id": "look_abc123",
"name": "Space Commander",
"avatar_type": "studio_avatar",
"group_id": "group_xyz789",
"preview_image_url": "https://files.heygen.ai/...",
"supported_api_engines": ["avatar_4_quality", "avatar_4_turbo"],
"tags": []
},
"avatar_group": {
"id": "group_xyz789",
"name": "Space Commander",
"looks_count": 1,
"consent_status": null,
"created_at": 1717000000
}
}
}
| Field | Type | Description |
|---|
avatar_item.id | string | The look ID — pass this as avatar_id to POST /v3/videos. |
avatar_item.avatar_type | string | "digital_twin", "photo_avatar", or "studio_avatar". |
avatar_item.supported_api_engines | array | Engine values compatible with this look for POST /v3/videos. |
avatar_item.group_id | string | The character identity this look belongs to. |
avatar_group.id | string | Group ID. Use to add more looks or initiate consent. |
avatar_group.consent_status | string or null | null for photo and prompt avatars. Digital twins may require consent — see below. |
Avatar Consent
Initiate a consent flow for an avatar group. Returns a URL the avatar subject must visit to approve usage.
Endpoint: POST https://api.heygen.com/v3/avatars/{group_id}/consent
Consent is only required for digital twin avatars (type: "digital_twin"). Photo avatars and prompt-to-avatar characters do not require consent.
Request
curl -X POST "https://api.heygen.com/v3/avatars/group_xyz789/consent" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reroute_url": "https://heygen.com/consent-done"
}'
| Parameter | Type | Required | Description |
|---|
reroute_url | string | No | Redirect URL after the subject completes consent. Defaults to HeyGen’s own completion page. |
Response
{
"data": {
"avatar_group": {
"id": "group_xyz789",
"name": "My Digital Twin",
"consent_status": "pending",
"looks_count": 1,
"created_at": 1717000000
},
"url": "https://heygen.com/consent/abc123..."
}
}
| Field | Type | Description |
|---|
url | string | Consent page URL. Send this to the avatar subject to complete approval. |
avatar_group.consent_status | string | Current consent status (e.g. "pending"). |
Check consent_status on the avatar group via GET /v3/avatars/{group_id} to know when consent is complete.
Avatars vs. Looks
An avatar group is a character identity (e.g. “Sarah”). Each group can have multiple looks — different outfits, poses, or styles. When creating a video, you pass a look ID (not a group ID) as the avatar_id. Use GET /v3/avatars/looks to browse looks, or pass avatar_group_id when creating a new avatar to add a look to an existing character.
