> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/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.

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_4_quality", "avatar_4_turbo"],
        "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 supports for video creation (e.g. `["avatar_4_quality", "avatar_4_turbo"]`).                                                                                      |
| `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 if trained with matting.                |
| `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_4_quality", "avatar_4_turbo"],
      "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`:

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