Avatar Groups

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 and GET /v3/avatars/{group_id}. To pick a specific look to render with, see Avatar Looks. To train your own avatar, see Create Avatar.

Quick Example

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

{
  "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"
}

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}` for details, or use as `group_id` in `GET /v3/avatars/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 or `GET /v3/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}.

curl -X GET "https://api.heygen.com/v3/avatars/group_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

{
  "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
  }
}

Pagination

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

curl -X GET "https://api.heygen.com/v3/avatars?token=eyJsYXN0X2lkIjoiMTIzIn0" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

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 for how to browse and select looks.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Video Translation

Lipsync

Tools

Avatar Management

Voice Management

Asset Management

Batches

Webhook

Limits

Pricing

Socials

For Agents

Integrations

Quick Example

Query Parameters

Response Fields

Get a Single Avatar Group

Avatars vs. Looks

​Quick Example

​Query Parameters

​Response Fields

​Get a Single Avatar Group

​Pagination

​Avatars vs. Looks

Quick Example

Query Parameters

Response Fields

Get a Single Avatar Group

Pagination

Avatars vs. Looks