Discussions

I’m using the HeyGen API endpoint:

GET https://api.heygen.com/v2/avatar_group/{group_id}/avatars

According to the documentation, each avatar object in the avatar_list should include a group_id field. However, in my response payload, I don’t see this field at all—only avatar_id, avatar_name, preview_image_url, preview_video_url, tags, premium, and default_voice_id.

Could you please help clarify:

It looks to me like a bug - just not working like it should be...

But,

1. Should group_id indeed be included in each avatar object per your spec?
2. If yes, is there any scenario (e.g., specific plan tiers or avatar types) where this field might be omitted?
3. Could this omission be due to an API response inconsistency or a bug?

Here is some additional information:

Response
Field Type Description
avatar_list
List of avatars in the group.
avatar_list[].id string Unique identifier for the avatar.
avatar_list[].image_url string URL of the avatar image.
avatar_list[].created_at float Timestamp (in seconds) when the avatar was created.
avatar_list[].name string Name of the avatar look.
avatar_list[].status string Status of the avatar. Example: completed.
avatar_list[].group_id string Identifier of the group this avatar belongs to.
avatar_list[].is_motion boolean Whether the avatar is a motion avatar.
avatar_list[].motion_preview_url string | null URL for the motion avatar preview. null if not available.
avatar_list[].business_type string Business type of the avatar. Example: generated.
avatar_list[].upscale_availability
Upscale availability information.
avatar_list[].upscale_availability.available boolean Whether the avatar is available for upscaling.
avatar_list[].upscale_availability.reason string Reason why upscaling is not available (if applicable).
avatar_list[].upscaled boolean Whether the avatar has been upscaled.
avatar_list[].background_sound_effect string | null Background sound effect applied to the avatar. null if none.
avatar_list[].default_voice_id string Default voice ID assigned to this avatar.
PATH PARAMS
group_id
string
required
Avatar group id

curl --request GET
--url https://api.heygen.com/v2/avatar_group/1727698066/avatars
--header 'accept: application/json'
--header 'x-api-key: (hidden here)

Response I keep getting:

{
"error": null,
"data": {
"avatar_list": [
{
"avatar_id": "Raul_sitting_casualsofawithipad_front",
"avatar_name": "Raul Casual Sofa with iPad Front",
"gender": "male",
"preview_image_url": "https://files2.heygen.ai/avatar/v3/5b7ccb338dc4477d89db916950207884_38810/preview_target.webp",
"preview_video_url": "https://files2.heygen.ai/avatar/v3/5b7ccb338dc4477d89db916950207884_38810/preview_video_target.mp4",
"premium": false,
"type": "LIFELIKE",
"tags": [
"Hyper Realistic",
"4K",
"Matting",
"Horizontal",
"Free",
"man",
"white",
"technology",
"young adult",
"sitting",
"indoor",
"home",
"casual"
],
"default_voice_id": null
},