> ## 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.

<img className="w-full h-44 object-cover rounded-xl" src="https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-8.webp?fit=max&auto=format&n=hfMXXwJzjE7vBSYZ&q=85&s=d16cda8ab7835eed66c6a205d16e631f" alt="" noZoom width="1400" height="788" data-path="images/theme/research-8.webp" />

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

## Quick Example

<CodeGroup>
  ```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": ["avatar_iv", "avatar_v"],
        "status": "completed"
      }
    ],
    "has_more": true,
    "next_token": "eyJsYXN0X2lkIjoiNDU2In0"
  }
  ```
</CodeGroup>

## 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`](/reference/create-video) or [`POST /v3/video-agents`](/reference/create-video-agent-session). |
| `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](/docs/voices/search-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`](/reference/create-video): `"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}`](/reference/get-avatar-look). To rename or retag, use [`PATCH /v3/avatars/looks/{look_id}`](/reference/update-avatar-look); to remove, [`DELETE`](/reference/delete-avatar-look).

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/avatars/looks/look_def456" \
    -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": ["avatar_iv", "avatar_v"],
      "status": "completed"
    }
  }
  ```
</CodeGroup>

## Filtering by Group

To see all outfits and styles for a specific character, pass its `group_id`:

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/avatars/looks?group_id=group_abc123" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```
</CodeGroup>

## Pagination

If `has_more` is `true`, pass the `next_token` value as the `token` query parameter to fetch the next page.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/avatars/looks?token=eyJsYXN0X2lkIjoiNDU2In0" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```
</CodeGroup>

## 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](/models) for how the engines compare.

<CodeGroup>
  ```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",
      "voice_id": "voice_xyz789",
      "script": "Welcome to our product walkthrough."
    }'
  ```
</CodeGroup>


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