v1

latestOpenAPI 3.1.02026-07-2665164286.3 KB

Avatars

List Avatar Looks

Returns a paginated list of avatar looks (outfits, poses, styles). Filterable by group_id, avatar_type, and ownership. The look id is the avatar_id to pass when creating a video.

get/v3/avatars/looks

Query parameters

group_idstring

Filter looks to a specific avatar group. Returns only looks belonging to this group.

avatar_type'studio_avatar' | 'digital_twin' | 'photo_avatar'

Filter by avatar type: 'studio_avatar', 'digital_twin', or 'photo_avatar'.

ownership'public' | 'private'

Filter by ownership: 'public' for preset avatars, or 'private' for your own. Omit for all.

limitinteger

Maximum number of items to return per page (1-50).

tokenstring

Opaque cursor token for the next page.

Response

Successful response

has_moreboolean

Whether more pages are available

next_tokenstring nullable

Opaque cursor for the next page

Example response

{
  "data": [
    {
      "id": "lk_abc123",
      "name": "Business Suit",
      "group_id": "ag_abc123",
      "preview_image_url": "https://files.heygen.ai/look/business_preview.jpg",
      "preview_video_url": "https://files.heygen.ai/look/business_preview.mp4",
      "gender": "female",
      "tags": [
        "business",
        "formal"
      ],
      "default_voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
      "supported_api_engines": [
        "avatar_v",
        "avatar_iv",
        "avatar_iii"
      ],
      "image_width": 1920,
      "image_height": 1080,
      "error": {
        "code": "training_failed",
        "message": "Footage duration must be between 15s and 600s"
      }
    }
  ]
}