Avatar Groups enable consistent AI avatar generation with multiple looks and styles. This guide walks you through the process of creating and training photo avatar groups, enabling you to achieve high-quality results tailored to your needs.

1. Create Photo Avatar Group

See detailed API reference
This API enables the creation of a photo avatar group. The photo avatars can either be AI generated or uploaded by the user.

For AI Generated Photo Avatars: Pass the generation_id and the image_key of the generated avatar. To generate AI Avatar photos see the guide.
For User-Uploaded Photos: First, upload the image via the Upload Assets API. Use the returned image_key when creating the photo avatar group. To upload an image to the HeyGen platform use the Upload Asset endpoint and get the image_key.

curl --location 'https://api.heygen.com/v2/photo_avatar/avatar_group/create' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <your-api-key>' \
--data '{
    "name": "Sylvia",
    "image_key": "image/47b2367366d94ee79894ed1f692b33ae/original"
}'

{
    "error": null,
    "data": {
        "id": "0b1b8dabd16f40a2b2ae6599790bba05",
        "image_url": "https://files2.heygen.ai/image/47b2367366d94ee79894ed1f692b33ae/original?Expires=1738267155&Signature=eD-97Qbr8s~xX1kueBjtHiGbbSlvEcOLz4V8hN1gokvXCF4Ij0WU-obDbMnKiDOrMBxdrvSIWBWHd9ae0o3RdIQ5XtZGbT0i2IDcT9s99kVo~8X0ZUu3~yIjGy3SxOnOMM0xKBrgtMSpw2e~xK7jM6BSpwQSNz-G9lp0IUqH5j2sYMRkhCzFk8ow7I0FqU0mjzJzEe6BvwCVu9cWRmTuFbhHz7BX9hcPG4S~UyRnWnCqLi2RCeKuBRdWrIa-2UWDAKA~dPM29Q5eOXPEfpVqK88EgyEGbqgBv7DPtSQhoLLYlALoUHXunZrcye5~WN9OyPSglzGFhulyXU7jWNmggw__&Key-Pair-Id=K38HBHX5LX3X2H",
        "created_at": 1737662355.643309,
        "name": "Sylvia",
        "status": "pending",
        "group_id": "0b1b8dabd16f40a2b2ae6599790bba05",
        "is_motion": false,
        "motion_preview_url": null,
        "business_type": "user_upload",
        "upscale_availability": {
            "available": false,
            "reason": "Photo avatar look upload not completed"
        },
        "upscaled": false,
        "background_sound_effect": null
    }
}

2. Add Looks to Avatar Group

See detailed API reference
You can enhance the avatar group by adding more looks using the Add Looks API. Pass an array of image_keys to add multiple photos.

curl --request POST \
     --url https://api.heygen.com/v2/photo_avatar/avatar_group/add \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <your_api_key>' \
     --data '
{
  "image_keys": [
    "image/9b3dc45f59b949499bc827d5fc0b4f33/original",
    "image/94a0aeef2cf840a0b6da6bdc420aa7a1/original",
    "image/7fe20c8e3e5e43e39795141b746227b2/original"
  ],
  "group_id": "0b1b8dabd16f40a2b2ae6599790bba05",
  "name": "name"
}
'

{
    "error": null,
    "data": {
        "photo_avatar_list": [
            {
                "id": "afc22a9aeb7a478a886a1d31a02646f6",
                "image_url": "https://files2.heygen.ai/image/9b3dc45f59b949499bc827d5fc0b4f33/original?Expires=1738267605&Signature=BkbKz6FQVO8H0iJAtAmSmsy4i-OGwyAbyJoobFvIyKmXcrq9-9nT2kL8Nqe~cjZNb9FChXzaEqhvdJl86ujyDWypvzRNBCrdun3M0gQwnsk-NpSIecwLbA7Oz~EuEYNwFVTXRSJaM1BtFkJ9iucvaiQp-HKmPe-DOYqBhVdKhiY22kOjp9hb87b0GsZ424n-~gQXAzwFKSEYfxEE8caNz0r6VHLN4RwFzDegePqMJbA2yX90GImFSGMtvq9qR7rXCZpf5E0~HhG6E6B2I5xHz7yrPS7GebqYMT19P0Hq4SEdvd9rb6MXGm8-NfViXN-oEl0XOKwmNDVZG56Ff1nqBA__&Key-Pair-Id=K38HBHX5LX3X2H",
                "created_at": 1737662805.738763,
                "name": "name",
                "status": "pending",
                "group_id": "0b1b8dabd16f40a2b2ae6599790bba05",
                "is_motion": false,
                "motion_preview_url": null,
                "business_type": "generated",
                "upscale_availability": {
                    "available": false,
                    "reason": "Photo avatar look upload not completed"
                },
                "upscaled": false,
                "background_sound_effect": null
            },
            {
                "id": "ad1346b011834df1a583a32c7061ca1f",
                "image_url": "https://files2.heygen.ai/image/94a0aeef2cf840a0b6da6bdc420aa7a1/original?Expires=1738267605&Signature=kHSh1WPZ-V8norsF5pUfKmra6r6Wgx~MTmW74DXAl8WB2bpek4jCNs00dHVZn1xmLpDCJN16FAh61x3W980sIfRBSoOAJSjP8ykvR5iSE5P42YZs0z0X3iOiuae5yZ2PshTBh1mTl7ioUZok~vQ0tOcSE2XfftYHF7FaThu-1FcWnRJr-ciY5-r2eS2aVKSJgRFVh~lJPD3h~dwGwaC7JIUT8kTCi-dPc6ojRWx9Cpxq1O73Vzfqf3qvhrgxCP0hAewSDzvdNkaxZYZ0qxkH~nZKhBypxFBgphuTnm279hG0-F0PbG9UCogKmoJCqcTESSQ~Ui7ibEzWqYk7v1zcHg__&Key-Pair-Id=K38HBHX5LX3X2H",
                "created_at": 1737662805.862844,
                "name": "name",
                "status": "pending",
                "group_id": "0b1b8dabd16f40a2b2ae6599790bba05",
                "is_motion": false,
                "motion_preview_url": null,
                "business_type": "generated",
                "upscale_availability": {
                    "available": false,
                    "reason": "Photo avatar look upload not completed"
                },
                "upscaled": false,
                "background_sound_effect": null
            },
            {
                "id": "62d4489300634c3f99c0ec994c31fa76",
                "image_url": "https://files2.heygen.ai/image/7fe20c8e3e5e43e39795141b746227b2/original?Expires=1738267606&Signature=bipVwvAvwr0H6FaS4ONBRzwuZMqWK-Be7VsUb6zac0CIuNh~3vXc1HvcWiKsq1~m12hIpV~KPtjl-emgSQEu63xBaQvhX9FnNPYOD3INF8vjqF0nMEeyNz2zTGy1IDYtM8BlXPisdB2-uHu34z~DQ~ZKxHeZIRPLkJ2nM7nalpN45ZbeguhZqilub2X1kDaDmzAXaH4EeDeapXaUFJ~OKkEn25E4U9VwNYvD1BtyXnuhdLy6GVhX2JKOJe8u2U5atbTBQs7iXyv0KTPpT3zdqwr4aSOM82KeKfEO1kai3VQ0o5TVNucwC~MYj~on-zuE1J2moTLHRln-~j7MRh7lOg__&Key-Pair-Id=K38HBHX5LX3X2H",
                "created_at": 1737662805.989199,
                "name": "name",
                "status": "pending",
                "group_id": "0b1b8dabd16f40a2b2ae6599790bba05",
                "is_motion": false,
                "motion_preview_url": null,
                "business_type": "generated",
                "upscale_availability": {
                    "available": false,
                    "reason": "Photo avatar look upload not completed"
                },
                "upscaled": false,
                "background_sound_effect": null
            }
        ]
    }
}

Ideal Photo Selection: Choose recent, high-resolution images that authentically represent the subject. Capture a diverse range of angles, expressions (smiling, neutral, serious), and outfit styles. Aim for a mix of close-up and full-body shots that reflect the individual's current appearance. Consistent lighting, clear facial features, and minimal background distractions will enhance avatar group training quality and consistency.

3. Train the Photo Avatar Group

See detailed API reference
Once the avatar group is created and looks are added, you can train the photo avatar group for better consistency across looks.

curl --request POST \
     --url https://api.heygen.com/v2/photo_avatar/train \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <your_api_key>' \
     --data '
{
  "group_id": "0b1b8dabd16f40a2b2ae6599790bba05"
}
'

{
  "error": null,
  "data": {
    "code": 100,
    "data": null,
    "msg": null,
    "message": null
  }
}

You can check the status of the training job for the avatar group using the following API:
See detailed API reference

curl --request GET \
     --url https://api.heygen.com/v2/photo_avatar/train/status/0711b7c97f844dda9fa8acab475beda0 \
     --header 'accept: application/json' \
     --header 'x-api-key: <your_api_key>'

{
    "error": null,
    "data": {
        "status": "pending",
        "error_msg": null,
        "created_at": 1737663091.0,
        "updated_at": null
    }
}

{
    "error": null,
    "data": {
        "status": "training",
        "error_msg": null,
        "created_at": 1737663091.0,
        "updated_at": 1737663206.0
    }
}

{
    "error": null,
    "data": {
        "status": "ready",
        "error_msg": null,
        "created_at": 1737663091.0,
        "updated_at": 1737663421.0
    }
}

4. Generate Photo Avatar Looks

See detailed API reference
To generate looks for the photo avatar, you can use the Generate Photo Avatar Look API. Provide a description in the prompt field, as well as the orientation, pose, and style.

curl --request POST \
     --url https://api.heygen.com/v2/photo_avatar/look/generate \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <your_api_key>' \
     --data '
{
  "group_id": "0711b7c97f844dda9fa8acab475beda0",
  "prompt": "White shirt front-facing",
  "orientation": "square",
  "pose": "half_body",
  "style": "Realistic"
}
'

{
    "error": null,
    "data": {
        "generation_id": "c37388c94f614948ad96b8cf75c7a09f"
    }
}

You can check the status of the look generation using the generation_id.
See detailed API reference

curl --request GET \
     --url https://api.heygen.com/v2/photo_avatar/generation/c37388c94f614948ad96b8cf75c7a09f \
     --header 'accept: application/json' \
     --header 'x-api-key: <your_api_key>'

{
    "error": null,
    "data": {
        "id": "def3076d2c8b4929acf269d8ea6b562e",
        "status": "in_progress",
        "msg": null,
        "image_url_list": null,
        "image_key_list": null
    }
}

{
    "error": null,
    "data": {
        "id": "c37388c94f614948ad96b8cf75c7a09f",
        "status": "success",
        "msg": null,
        "image_url_list": [
            "https://resource2.heygen.ai/image/c5ca4f593b2f4e73a7bf2af2e2b7550d/original",
            "https://resource2.heygen.ai/image/ab46c34c8c3746d18a68cce31882eeca/original",
            "https://resource2.heygen.ai/image/a34a3111b0424ad498616dc821c96bda/original",
            "https://resource2.heygen.ai/image/52bd5394774c42a5be2a7da05a3294b3/original"
        ],
        "image_key_list": [
            "image/c5ca4f593b2f4e73a7bf2af2e2b7550d/original",
            "image/ab46c34c8c3746d18a68cce31882eeca/original",
            "image/a34a3111b0424ad498616dc821c96bda/original",
            "image/52bd5394774c42a5be2a7da05a3294b3/original"
        ]
    }
}

Conclusion

In conclusion, creating and managing photo avatar groups enables users to design highly customized and consistent AI avatar experiences. By leveraging tools like the Create Photo Avatar Group and Add Looks APIs, users can upload, organize, and enhance avatars with ease.