Skip to main content
  • Endpoint: GET https://api.heygen.com/v3/avatars/looks
  • Purpose: List avatar looks (outfits/styles) with cursor-based pagination and filtering. Each look has a unique ID that you pass as avatar_id to POST /v3/videos or POST /v3/video-agents.

​
Authentication

HeaderValue
X-Api-KeyYour HeyGen API key
AuthorizationBearer YOUR_ACCESS_TOKEN (OAuth)

​
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

ParameterTypeRequiredDefaultDescription
group_idstringNo—Filter looks to a specific avatar group. Returns only looks belonging to this character.
avatar_typestringNoall"studio_avatar", "video_avatar", or "photo_avatar".
ownershipstringNoall"public" for HeyGen presets or "private" for your own. Omit for both.
limitintegerNo20Results per page (1–50).
tokenstringNo—Opaque cursor token for the next page.

​
Response Fields

Each look in the data array contains:
FieldTypeDescription
idstringUnique look identifier. This is the value to pass as avatar_id to POST /v3/videos or POST /v3/video-agents.
namestringDisplay name of the look.
avatar_typestringOne of "studio_avatar", "video_avatar", or "photo_avatar". Determines engine and parameter compatibility.
group_idstring or nullID of the avatar group (character) this look belongs to.
genderstring or nullGender of the avatar.
preview_image_urlstring or nullURL to a preview image.
preview_video_urlstring or nullURL to a preview video.
default_voice_idstring or nullDefault voice ID for this look.
tagsarrayTags associated with the look (e.g. ["business", "casual"]).
supported_api_enginesarrayEngine values this look supports for video creation.

​
Avatar Types

The avatar_type field determines what features and parameters are available when creating a video:
TypeDescription
studio_avatarPre-built HeyGen studio avatars with fixed poses and backgrounds.
video_avatarDigital twins created from video footage. Support background removal if trained with matting.
photo_avatarAvatars generated from a single photo. Support motion_prompt and expressiveness parameters in video creation.

​
Get a Single Look

Fetch details for a specific look by ID: 
curl -X GET "https://api.heygen.com/v3/avatars/looks/look_def456" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

​
Filtering Looks by Group

To see all outfits/styles for a specific character, pass the group_id: 
curl -X GET "https://api.heygen.com/v3/avatars/looks?group_id=group_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

​
Pagination

The endpoint uses cursor-based 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"
  }'