Avatar Looks - HeyGen Documentation

A look is one outfit/pose/style for a character (avatar group). It’s the value you pass as avatar_id to video creation. List via GET /v3/avatars/looks, fetch one via GET /v3/avatars/looks/{look_id}, or Update / Delete your own. To create a new look, see Create Avatar.

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 — see Browse Voices.
`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 by default on new twins.
`photo_avatar`	Avatars generated from a single photo. Support `motion_prompt` and `expressiveness` in video creation.

Get a Single Look

Full schema: GET /v3/avatars/looks/{look_id}. To rename or retag, use PATCH /v3/avatars/looks/{look_id}; to remove, DELETE.

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"

Pagination

If 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"
  }'

​Quick Example

​Query Parameters

​Response Fields

​Avatar Types

​Get a Single Look

​Filtering by Group

​Pagination

​Using a Look in Video Creation