Developer Guide
Start typing to search…

Create and Train Photo Avatar Groups

Create and train photo avatar groups for personalized AI avatar

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.

1. Create Photo Avatar Group

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

📘

Note:

Each uploaded or generated photo automatically creates an Avatar Group in HeyGen's interface. Additional looks or avatars can later be added to this group.

  • For AI Generated Photo Avatars: Pass the name , generation_id, and the image_key of the generated avatar. The generation_id parameter is optional . Refer to the Generate AI Avatar Photos guide for detailed steps.
  • For User-Uploaded Photos: First, upload the image via the Upload Asset API. Use the returned image_key when creating the photo avatar group.
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
    }
}

For a complete list of supported parameters and example responses, see detailed API Reference: Create Photo Avatar Group

📘

The image URL you get will expire in 7 days. 📆

You can observe this expiration in the URL parameters. To retain access, you should either download and store the image locally before it Expires or regenerate a new URL by calling the same endpoint again with the same parameters..

2. Add Looks to Avatar Group

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

📘

Note:

For AI avatars, the generation_id parameter is optional. For uploaded photos, no generation_id is required.

📘

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

Once the avatar group is created and looks are added, you can train the photo avatar group by providing group_id to the Train Photo Avatar Group API. This helps maintain better consistency across looks.

You can check the status of the training job for the avatar group using the Get Training Job Status API.

4. Generate Photo Avatar Looks

To generate looks for the photo avatar, you can use the Generate Photo Avatar Looks API. In this example, we are providing a concise 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 in the Check Photo/Look Generation Status API. The response will include a status field that indicates the current state of the generation process.You can view complete status response examples on the right-side Response panel of the API Reference page - open the Examples dropdown to view responses for different video statuses. You can select any example to preview the corresponding response body.

Status Descriptions

in_progress
The look is still being generated.

success
The look has been successfully generated and includes the generated image URLs.

failed
The generation process did not complete successfully.

📘

Note:

These image_keys can then be used in the Add Looks to Photo Avatar Group API to attach the new AI-generated looks to an existing avatar group.

Conclusion

In conclusion, creating and managing photo avatar groups enables users to design highly customized and consistent AI avatar experiences.

Updated 11 days ago