Photo to Avatar

Turn one still image into a HeyGen avatar with POST /v3/avatars. The fastest creation path: no footage, no consent step, and the photo becomes the reference for every later look.

A photo avatar is built from a single still image. It is the fastest way into the API: no recording session, and no consent step, since a group created from a photo reports consent_status of null. The image is still of a real person, so have their permission before you use it, as Avatar Consent explains.

1. Create the avatar

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

   file also takes { "type": "asset_id", "asset_id": "..." } from POST /v3/assets, or base64 content. Add avatar_group_id to add this photo as another look on a character you already have; consent_status is a property of the group, so the response reports whatever that group already carries.

   Save avatar_item.id from the response. That is the avatar_id for video creation.

2. Wait for processing

   Poll GET /v3/avatars/looks/{look_id} until status leaves processing.

   curl -X GET "https://api.heygen.com/v3/avatars/looks/$LOOK_ID" \
     -H "X-Api-Key: $HEYGEN_API_KEY"
   

   A completed look returns preview_image_url and the supported_api_engines it renders on. A failed one carries error.code of training_failed or moderation_failed, with the reason in error.message.

3. Render

   Photo avatars accept motion_prompt and expressiveness on POST /v3/videos, which direct how much the subject moves while speaking.

   curl -X POST "https://api.heygen.com/v3/videos" \
     -H "X-Api-Key: $HEYGEN_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "type": "avatar",
       "avatar_id": "look_abc123",
       "voice_id": "voice_xyz789",
       "script": "Here is what changed in this release."
     }'
   

   Pick a voice with GET /v3/voices, or set one as the character default through PATCH /v3/avatars/{group_id} and leave voice_id out. The Photo Avatar recipe covers the render end to end.

A clear, front-facing portrait in even lighting works best: whole head in frame, one person, as much resolution as you have. The image becomes the visual reference the character is remembered by, so choose the shot you want every later look to resemble.

Give the character more looks

The photo is the identity reference for everything that follows. Pass its look id as avatar_id to Prompt to Avatar to put the same person in a new outfit or setting, or apply a Look Pack for a coordinated set in one call.

New looks join the same character, and GET /v3/avatars/looks?group_id=... lists them all.