Skip to main content
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.

List avatar groups

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 lists every query parameter and response field. Fields worth knowing:
  • id: pass it to GET /v3/avatars/{group_id}, or as group_id to filter GET /v3/avatars/looks.
  • default_voice_id: the character’s default voice, from GET /v3/models/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.

Get a Single Avatar Group

Full schema: GET /v3/avatars/{group_id}. To change the default voice of an avatar you own, send default_voice_id to PATCH /v3/avatars/{group_id}; 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}. Source assets and any cloned voice are kept; see Delete an avatar.
When creating a video, you pass a look ID (not a group ID) as the avatar_id.