> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Avatar Looks

> Browse and select avatar looks (outfits, poses, hair styles) for any HeyGen avatar group via the Avatar Looks API.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-8.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=d16cda8ab7835eed66c6a205d16e631f)

A **look** is one outfit/pose/style for a character ([avatar group](https://heygen-1fa696a7.mintlify.site/docs/avatars.md)). It's the value you pass as `avatar_id` to video creation. List via [`GET /v3/avatars/looks`](https://heygen-1fa696a7.mintlify.site/reference/list-avatar-looks), fetch one via [`GET /v3/avatars/looks/{look_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-avatar-look), or [Update](https://heygen-1fa696a7.mintlify.site/reference/update-avatar-look.md) / [Delete](https://heygen-1fa696a7.mintlify.site/reference/delete-avatar-look.md) your own. To create a new look, see [Create Avatar](https://heygen-1fa696a7.mintlify.site/docs/create-avatar.md).

## List looks

```bash curl theme={null}
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"
```

```json Response theme={null}
{
  "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": ["heygen-avatar-6", "heygen-avatar-6-turbo", "avatar_iv", "avatar_v"],
      "status": "completed"
    }
  ],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoiNDU2In0"
}
```

Filter with `group_id` (one character's looks), `avatar_type` and `ownership` (`public` for HeyGen presets, `private` for your own). Results are paginated: when `has_more` is `true`, pass `next_token` as `token` for the next page. The [reference](https://heygen-1fa696a7.mintlify.site/reference/list-avatar-looks.md) lists every parameter and field. Fields worth knowing:

* **`id`**: the value to pass as `avatar_id` to [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) or [`POST /v3/video-agents`](https://heygen-1fa696a7.mintlify.site/reference/create-video-agent-session).
* **`supported_api_engines`**: the engine values this look accepts for [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video), from `"heygen-avatar-6"`, `"heygen-avatar-6-turbo"`, `"avatar_iii"`, `"avatar_iv"` and `"avatar_v"`. Requesting an engine that isn't listed returns `invalid_parameter`.
* **`status`**: training status, `processing`, `completed` or `failed`. Present for private avatars only.

## 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}`](https://heygen-1fa696a7.mintlify.site/reference/get-avatar-look). To rename a look, use [`PATCH /v3/avatars/looks/{look_id}`](https://heygen-1fa696a7.mintlify.site/reference/update-avatar-look); to remove, [`DELETE`](https://heygen-1fa696a7.mintlify.site/reference/delete-avatar-look).

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/avatars/looks/look_def456" \
  -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": "heygen-avatar-6"}` for [Avatar 6](https://heygen-1fa696a7.mintlify.site/docs/models/avatar-6.md) when the array includes `"heygen-avatar-6"`. Omitting `engine` uses Avatar IV. See [Models](https://heygen-1fa696a7.mintlify.site/models) for how the engines compare.

```bash "Video Agent" theme={null}
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"
  }'
```

```bash "Avatar Video" theme={null}
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",
    "engine": { "type": "heygen-avatar-6" },
    "voice_id": "voice_xyz789",
    "script": "Welcome to our product walkthrough."
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.