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

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

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: `"pending"`, `"accepted"`, or `"rejected"`. `null` means consent is not required, as for photo and prompt groups, which have no consent step. |
| `status` | string or null | Group status, driven by consent and review: `"pending_consent"`, `"completed"`, or `"failed"` (consent rejected, reason in `error.message`). Training progress is reported on each look's `status`, see [Avatar Looks](/docs/avatar-looks). 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). To change the default voice of an avatar you own, send `default_voice_id` to [`PATCH /v3/avatars/{group_id}`](/reference/update-avatar-group); any voice available to your workspace works, including imported clones. Public avatars cannot be updated.

To remove a character you own and every look in it, call [`DELETE /v3/avatars/{group_id}`](/reference/delete-avatar-group). Source assets and any cloned voice are kept; see [Delete an avatar](/docs/create-avatar#delete-an-avatar).

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


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