v2 Photo Avatar Endpoints: Generation, Training, and Looks

Walkthrough for Using Photo Avatar Endpoints

This guide explains how to use the various endpoints for generating, customizing, and managing photo avatars using HeyGen's API.

At a high level, the steps for creating a motion-enabled photo avatar that can be used in HeyGen video generation is:

1. Upload existing photos or Generate new photos with prompts
2. Create an Avatar Group using a collection of photos of the same subject
3. Train the Avatar Group
4. Create new Looks for the avatar within the trained Avatar Group using prompts
5. Add motion and sound effects programmatically
6. Use the Avatars within the group to create whatever kinds of videos you can imagine!

1. Generate Photo Avatar Photos

• Endpoint: POST https://api.heygen.com/v2/photo_avatar/photo/generate
• Description: This endpoint generates photos for creating a photo avatar.
• Required Body Parameters:
  • name: Name of the avatar.
  • age, gender, ethnicity, orientation, pose, style, appearance: Mandtory attributes to define the avatar's look.
• Response: Returns a generation_id to check the generation status later.
• Example:
  Bash

  curl --request POST \
       --url https://api.heygen.com/v2/photo_avatar/photo/generate \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'x-api-key: YOUR_API_KEY' \
       --data '{"name": "Sample Avatar", "style": "professional"}'
  

  Documentation Reference: https://docs.heygen.com/reference/generate-photo-avatar-photos

2. Check Photo/Look Generation Status

• Endpoint: GET https://api.heygen.com/v2/photo_avatar/generation/{generation_id}
• Description: Checks the status of a photo or look generation request.
• Required Path Parameter:
  • generation_id: The ID returned from the generate endpoint.
• Response: Provides the status and links to the generated images.
• Example:
  Bash

  curl --request GET \
       --url https://api.heygen.com/v2/photo_avatar/generation/GENERATION_ID \
       --header 'accept: application/json' \
       --header 'x-api-key: YOUR_API_KEY'
  

  Documentation Reference: https://docs.heygen.com/reference/check-photolook-generation-status

3. Create Photo Avatar Group

• Endpoint: POST https://api.heygen.com/v2/photo_avatar/avatar_group/create
• Description: Creates a new photo avatar group.
• Required Body Parameters:
  • name: Name of the group.
  • image_key: Key of the image used for the avatar.
  • generation_id: ID of the generated photo.
• Response: Returns the group_id for further actions.
• Example:
  Bash

  curl --request POST \
       --url 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": "Avatar Group 1", "image_key": "IMAGE_KEY", "generation_id": "GENERATION_ID"}'
  

  Documentation Reference: https://docs.heygen.com/reference/create-photo-avatar-group

4. Add Looks to Photo Avatar Group

• Endpoint: POST https://api.heygen.com/v2/photo_avatar/avatar_group/add
• Description: Adds more looks to an existing photo avatar group.
• Required Body Parameters:
  • group_id: ID of the avatar group.
  • image_keys: Array of image keys to add (max 4 at a time).
  • generation_id: ID of the generation request for the images.
• Response: Confirms the addition of looks to the group.
• Example:
  Bash

  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 '{"group_id": "GROUP_ID", "image_keys": ["IMAGE_KEY_1", "IMAGE_KEY_2"], "generation_id": "GENERATION_ID"}'
  

  Documentation Reference: https://docs.heygen.com/reference/add-looks-to-photo-avatar-group

5. Train Photo Avatar Group

• Endpoint: POST https://api.heygen.com/v2/photo_avatar/train
• Description: Trains a photo avatar group for further customization.
• Required Body Parameters:
  • group_id: ID of the group to train.
• Response: Confirms the training request.
• Example:
  Bash

  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": "GROUP_ID"}'
  

  Documentation Reference: https://docs.heygen.com/reference/train-photo-avatar-group

6. Get Training Job Status

• Endpoint: GET https://api.heygen.com/v2/photo_avatar/train/status/{group_id}
• Description: Checks the status of a group training job.
• Required Path Parameter:
  • group_id: ID of the trained group.
• Response: Provides the training progress and completion status.
• Example:
  Bash

  curl --request GET \
       --url https://api.heygen.com/v2/photo_avatar/train/status/GROUP_ID \
       --header 'accept: application/json' \
       --header 'x-api-key: YOUR_API_KEY'
  

  Documentation Reference: https://docs.heygen.com/reference/get-training-job-status

Generate Photo Avatar Looks

• Endpoint: POST https://api.heygen.com/v2/photo_avatar/look/generate
• Description: This endpoint generates additional looks for a trained photo avatar group. You must have a trained photo avatar group to use this endpoint.

Required Body Parameters:

• group_id (string): The ID of the trained photo avatar group.
• prompt (string): A description of the desired look - make sure to add 'avatar' (e.g., "Avatar in business attire, smiling").
• orientation (string): Specifies the orientation of the avatar.
• pose (string): Defines the pose for the avatar.
• style (string): Specifies the visual style.

Response:

Returns a generation_id which can be used to check the status of the generated look.

Example Request:

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": "GROUP_ID",
         "prompt": "Avatar in business attire, smiling",
         "orientation": "front",
         "pose": "hands on hips",
         "style": "realistic"
     }'

Example Response:

{
  "generation_id": "12345abcdef",
  "message": "Look generation started successfully."
}

Next Steps:

Once the request is submitted:

1. Use the generation_id to check the status via the Check Photo/Look Generation Status endpoint.
2. Add the generated look to the avatar group using the Add Looks to Photo Avatar Group endpoint if desired.

Error Handling:

• Ensure the group_id is valid and the group is already trained.
• Validate the prompt for syntax and descriptive clarity.

Documentation Reference: https://docs.heygen.com/reference/generate-photo-avatar-looks

7. Add Motion

• Endpoint: POST https://api.heygen.com/v2/photo_avatar/add_motion
• Description: Adds motion to a photo avatar.
• Required Body Parameters:
  • id: ID of the photo avatar.
• Response: Returns a new ID for the motion-added avatar.
• Example:
  Bash

  curl --request POST \
       --url https://api.heygen.com/v2/photo_avatar/add_motion \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'x-api-key: YOUR_API_KEY' \
       --data '{"id": "PHOTO_AVATAR_ID"}'
  

  Documentation Reference: https://docs.heygen.com/reference/add-motion

8. Add Sound Effect

• Endpoint: POST https://api.heygen.com/v2/photo_avatar/add_sound_effect
• Description: Adds sound effects to a photo avatar.
• Required Body Parameters:
  • id: ID of the photo avatar.
• Response: Confirms the addition of sound effects.
• Example:
  Bash

  curl --request POST \
       --url https://api.heygen.com/v2/photo_avatar/add_sound_effect \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'x-api-key: YOUR_API_KEY' \
       --data '{"id": "PHOTO_AVATAR_ID"}'
  

  Documentation Reference:

9. Get Photo Avatar Details

• Endpoint: GET https://api.heygen.com/v2/photo_avatar/{id}
• Description: Retrieves details of a specific photo avatar.
• Required Path Parameter:
  • id: ID of the photo avatar.
• Response: Returns detailed information about the avatar.
• Example:
  Bash

  curl --request GET \
       --url https://api.heygen.com/v2/photo_avatar/PHOTO_AVATAR_ID \
       --header 'accept: application/json' \
       --header 'x-api-key: YOUR_API_KEY'
  

  Documentation Reference: https://docs.heygen.com/reference/add-sound-effect

Notes:

• Replace placeholders like YOUR_API_KEY, GENERATION_ID, and GROUP_ID with actual values.
• Ensure your API key is valid and has sufficient permissions.
• Follow rate limits and error handling guidelines specified in the API documentation.

Let me know if you'd like additional assistance or code samples!