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

> Generate AI avatar videos via the HeyGen API. Choose from 500+ stock avatars or train custom digital twins. Includes avatar looks, voices, and instant.

Avatars come in two layers: a **group** is a character (e.g. "Monica"); each group has one or more **looks** (outfits, poses, styles). This page is about listing and inspecting groups via [`GET /v3/avatars`](/reference/list-avatar-groups) and [`GET /v3/avatars/{group_id}`](/reference/get-avatar-group). To pick a specific look to render with, see [Avatar Looks](/docs/avatar-looks). To train your own avatar, see [Create Avatar](/docs/create-avatar).

## Quick Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/avatars?ownership=public&limit=5" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "data": [
      {
        "id": "group_abc123",
        "name": "Monica",
        "gender": "female",
        "preview_image_url": "https://files.heygen.ai/avatar/preview_abc123.jpg",
        "preview_video_url": "https://files.heygen.ai/avatar/preview_abc123.mp4",
        "looks_count": 3,
        "default_voice_id": "voice_xyz789",
        "consent_status": null,
        "status": "completed",
        "created_at": 1711382400
      }
    ],
    "has_more": true,
    "next_token": "eyJsYXN0X2lkIjoiMTIzIn0"
  }
  ```
</CodeGroup>

## Query Parameters

| Parameter   | Type    | Required | Default | Description                                                                        |
| ----------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------- |
| `ownership` | string  | No       | all     | `"public"` for HeyGen's preset avatars 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 avatar group in the `data` array contains:

| Field               | Type           | Description                                                                                                                                                                                          |
| ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                | string         | Unique group identifier. Pass to [`GET /v3/avatars/{group_id}`](/reference/get-avatar-group) for details, or use as `group_id` in [`GET /v3/avatars/looks`](/reference/list-avatar-looks) to filter. |
| `name`              | string         | Display name of the avatar character.                                                                                                                                                                |
| `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.                                                                                                                                                                              |
| `looks_count`       | integer        | Number of looks (outfits/styles) available for this character.                                                                                                                                       |
| `default_voice_id`  | string or null | Default voice ID for this avatar — pair with [Browse Voices](/docs/voices/search-voices) or [`GET /v3/voices`](/reference/list-voices).                                                              |
| `consent_status`    | string or null | Consent status for the group. `null` means consent is not required.                                                                                                                                  |
| `status`            | string or null | Training status: `"processing"`, `"pending_consent"`, `"completed"`, or `"failed"`. Only present for private avatars.                                                                                |
| `created_at`        | integer        | Unix timestamp of creation.                                                                                                                                                                          |

## Get a Single Avatar Group

Full schema: [`GET /v3/avatars/{group_id}`](/reference/get-avatar-group).

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

  ```json Response theme={null}
  {
    "data": {
      "id": "group_abc123",
      "name": "Monica",
      "gender": "female",
      "preview_image_url": "https://files.heygen.ai/avatar/preview_abc123.jpg",
      "preview_video_url": "https://files.heygen.ai/avatar/preview_abc123.mp4",
      "looks_count": 3,
      "default_voice_id": "voice_xyz789",
      "consent_status": null,
      "status": "completed",
      "created_at": 1711382400
    }
  }
  ```
</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?token=eyJsYXN0X2lkIjoiMTIzIn0" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```
</CodeGroup>

## Avatars vs. Looks

Avatar **groups** represent characters (e.g. "Monica"). Each group has one or more **looks** — different outfits, poses, or styles for that character. When creating a video, you pass a **look ID** (not a group ID) as the `avatar_id`. See [Avatar Looks](/docs/avatar-looks) for how to browse and select looks.