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
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 thedata 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}.
Pagination
Ifhas_more is true, pass the next_token value as the token query parameter to fetch the next page.
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 theavatar_id. See Avatar Looks for how to browse and select looks.