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.
Quick Example
curl -X GET "https://api.heygen.com/v3/avatars/looks?avatar_type=photo_avatar&ownership=public&limit=5" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|
group_id | string | No | — | Filter looks to a specific avatar group. Returns only looks belonging to this character. |
avatar_type | string | No | all | "studio_avatar", "digital_twin", or "photo_avatar". |
ownership | string | No | all | "public" for HeyGen presets or "private" for your own. Omit for both. |
limit | integer | No | 20 | Results per page (1–50). |
token | string | No | — | Opaque cursor token for the next page. |
Response Fields
Each look in the data array contains:
| Field | Type | Description |
|---|
id | string | Unique look identifier. This is the value to pass as avatar_id to POST /v3/videos or POST /v3/video-agents. |
name | string | Display name of the look. |
avatar_type | string | One of "studio_avatar", "digital_twin", or "photo_avatar". Determines engine and parameter compatibility. |
group_id | string or null | ID of the avatar group (character) this look belongs to. |
gender | string or null | Gender of the avatar. |
preview_image_url | string or null | URL to a preview image. |
preview_video_url | string or null | URL to a preview video. |
default_voice_id | string or null | Default voice ID for this look. |
tags | array | Tags associated with the look (e.g. ["business", "casual"]). |
supported_api_engines | array | Engine values this look supports for video creation (e.g. ["avatar_4_quality", "avatar_4_turbo"]). |
status | string or null | Training status: "processing", "completed", or "failed". Only present for private avatars. |
Avatar Types
The avatar_type field determines what features and parameters are available when creating a video:
| Type | Description |
|---|
studio_avatar | Pre-built HeyGen studio avatars with fixed poses and backgrounds. |
digital_twin | Avatars created from video footage. Support background removal if trained with matting. |
photo_avatar | Avatars generated from a single photo. Support motion_prompt and expressiveness in video creation. |
Get a Single Look
curl -X GET "https://api.heygen.com/v3/avatars/looks/look_def456" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Filtering by Group
To see all outfits and styles for a specific character, pass its group_id:
curl -X GET "https://api.heygen.com/v3/avatars/looks?group_id=group_abc123" \
-H "X-Api-Key: $HEYGEN_API_KEY"
has_more is true, pass the next_token value as the token query parameter to fetch the next page.
curl -X GET "https://api.heygen.com/v3/avatars/looks?token=eyJsYXN0X2lkIjoiNDU2In0" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Using a Look in Video Creation
Once you have a look id, pass it as avatar_id:
curl -X POST "https://api.heygen.com/v3/video-agents" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A product demo for our new app",
"avatar_id": "look_def456"
}'
