- Endpoint:
GET https://api.heygen.com/v3/avatars - Purpose: List avatar groups (characters) with cursor-based pagination. Each group contains one or more looks (outfits/styles) — use the Avatar Looks endpoint to browse them.
Authentication
| Header | Value |
|---|---|
X-Api-Key | Your HeyGen API key |
Authorization | Bearer YOUR_ACCESS_TOKEN (OAuth) |
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 to get 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 this to GET /v3/avatars/{group_id} for details, or use it to filter looks. |
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. |
created_at | integer | Unix timestamp of creation. |
Get a Single Avatar Group
Fetch details for a specific avatar group by ID:Pagination
The endpoint uses cursor-based 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.