HeyGen photo avatar API: create one from a photo

To create a HeyGen avatar from a photo through the API, call POST /v3/avatars with "type": "photo", a name and a file, save avatar_item.id, wait until that look leaves processing, and pass the id as avatar_id when you create a video. HeyGen says no recording session and no consent step is involved.

The HeyGen steps are from its Photo to Avatar page, read 2026-09-29. Sume's equivalent is described in Create new avatar and Generate avatar video.

What does the create request take?

The photo goes in file as a URL, an asset_id from HeyGen's asset upload, or base64 content. To add the photo as another look on a character you already have, pass avatar_group_id.

curl -X POST "https://api.heygen.com/v3/avatars" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "photo",
    "name": "Sarah",
    "file": { "type": "url", "url": "https://example.com/sarah-headshot.png" }
  }'

How do I know the avatar is ready?

Poll GET /v3/avatars/looks/{look_id} until status leaves processing. A completed look returns a preview_image_url and the supported_api_engines it can render on. A failed look carries an error.code of training_failed or moderation_failed, with the reason in error.message. Photo avatars also accept motion_prompt and expressiveness on POST /v3/videos, which direct how much the subject moves while speaking.

Which photo should I use, and can I add looks?

HeyGen recommends a clear, front-facing portrait in even lighting, whole head in frame, one person, at as high a resolution as you have. The image becomes the visual reference the character is remembered by. Later looks in a new outfit or setting join the same character through Prompt to Avatar or a Look Pack.

Why does my photo avatar fail?

Two failure codes are documented, training_failed and moderation_failed, and the reason is in error.message. Because a failed look still returns a response, check status every time instead of assuming the avatar is usable after the create call returns.

A working order of operations is: create the avatar, poll the look, read supported_api_engines to confirm which engine renders it, then submit the video with the saved avatar_id. Keep the avatar_id and the look_id in your own database next to the source photo URL, so a later look can be added with avatar_group_id instead of creating a second character.

How does the same job look on Sume?

Do I need permission to use the photo?

Yes in practice, whichever vendor you use. HeyGen notes that the image is still of a real person, so you should have their permission. Sume's avatar docs page checked has no consent step, so the same responsibility sits with you. For the consent side, see how HeyGen treats your avatar and voice.