Avatar Looks

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"

{
  "data": [
    {
      "id": "look_def456",
      "name": "Monica - Business Casual",
      "avatar_type": "photo_avatar",
      "group_id": "group_abc123",
      "gender": "female",
      "preview_image_url": "https://files.heygen.ai/look/preview_def456.jpg",
      "preview_video_url": "https://files.heygen.ai/look/preview_def456.mp4",
      "default_voice_id": "voice_xyz789",
      "tags": ["business", "casual", "female"],
      "supported_api_engines": ["avatar_iv", "avatar_v"],
      "status": "completed"
    }
  ],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoiNDU2In0"
}

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 accepts for `POST /v3/videos`: `"avatar_iii"`, `"avatar_iv"`, and/or `"avatar_v"`. Check this array before requesting a specific `engine` — requesting an engine that isn’t listed returns `invalid_parameter`.
`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"

{
  "data": {
    "id": "look_def456",
    "name": "Monica - Business Casual",
    "avatar_type": "photo_avatar",
    "group_id": "group_abc123",
    "gender": "female",
    "preview_image_url": "https://files.heygen.ai/look/preview_def456.jpg",
    "preview_video_url": "https://files.heygen.ai/look/preview_def456.mp4",
    "default_voice_id": "voice_xyz789",
    "tags": ["business", "casual", "female"],
    "supported_api_engines": ["avatar_iv", "avatar_v"],
    "status": "completed"
  }
}

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. When you request a specific rendering engine, pick one from the look’s supported_api_engines array — for example, pass "engine": {"type": "avatar_v"} when the array includes "avatar_v". Omitting engine uses Avatar IV. See Models for how the engines compare.

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

curl -X POST "https://api.heygen.com/v3/videos" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "look_def456",
    "voice_id": "voice_xyz789",
    "script": "Welcome to our product walkthrough."
  }'

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Video Translation

Lipsync

Tools

Avatar Management

Voice Management

Asset Management

Batches

Webhook

Limits

Pricing

Socials

For Agents

Integrations

Quick Example

Query Parameters

Response Fields

Avatar Types

Get a Single Look

Filtering by Group

Using a Look in Video Creation

​Quick Example

​Query Parameters

​Response Fields

​Avatar Types

​Get a Single Look

​Filtering by Group

​Pagination

​Using a Look in Video Creation

Quick Example

Query Parameters

Response Fields

Avatar Types

Get a Single Look

Filtering by Group

Pagination

Using a Look in Video Creation