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

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

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`](https://heygen-1fa696a7.mintlify.site/reference/list-avatar-groups) and [`GET /v3/avatars/{group_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-avatar-group). To pick a specific look to render with, see [Avatar Looks](https://heygen-1fa696a7.mintlify.site/docs/avatar-looks.md). To train your own avatar, see [Create Avatar](https://heygen-1fa696a7.mintlify.site/docs/create-avatar.md).

## List avatar groups

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

Pass `ownership` as `public` for HeyGen's preset avatars or `private` for your own, and omit it for both. 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-groups.md) lists every query parameter and response field. Fields worth knowing:

* **`id`**: pass it to [`GET /v3/avatars/{group_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-avatar-group), or as `group_id` to filter [`GET /v3/avatars/looks`](https://heygen-1fa696a7.mintlify.site/reference/list-avatar-looks).
* **`default_voice_id`**: the character's default voice, from [`GET /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/list-audio-voices).
* **`consent_status`**: `pending`, `accepted` or `rejected`, and `null` for photo and prompt groups, which have no consent step.
* **`status`**: present for private avatars only, driven by consent and review: `pending_consent`, `completed`, or `failed` (consent rejected, reason in `error.message`). Training progress is on each look's `status`, see [Avatar Looks](https://heygen-1fa696a7.mintlify.site/docs/avatar-looks.md).

## Get a Single Avatar Group

Full schema: [`GET /v3/avatars/{group_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-avatar-group). To change the default voice of an avatar you own, send `default_voice_id` to [`PATCH /v3/avatars/{group_id}`](https://heygen-1fa696a7.mintlify.site/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}`](https://heygen-1fa696a7.mintlify.site/reference/delete-avatar-group). Source assets and any cloned voice are kept; see [Delete an avatar](https://heygen-1fa696a7.mintlify.site/docs/create-avatar.md#delete-an-avatar).

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

When creating a video, you pass a **look ID** (not a group ID) as the `avatar_id`.


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