Create Avatar

The four ways to create a HeyGen avatar over the API: from video footage, from one photo, from a text prompt, or by applying a Look Pack to an avatar you already own.

Every avatar you create is a look on a character. The look id is what you pass as avatar_id when you create a video. The character, called an avatar group, is the identity that holds all of that person’s looks together. Browse them with Avatar Groups and Avatar Looks.

Pick a starting point

You have	You get	Guide
Video footage of a person	A digital twin of that person, plus a voice cloned from the same recording	Video to Avatar
One photo of a person	An avatar from that image, ready in minutes	Photo to Avatar
A text description	A synthetic character, no real person depicted	Prompt to Avatar
An avatar you already own	A new outfit, setting, or style for that same character	Prompt to Avatar or Look Packs

The first three go through POST /v3/avatars, distinguished by the type field. The fourth generates looks for an existing character: one at a time in your own words through the same endpoint, or a curated set in one call through POST /v3/avatars/looks.

What creation returns

POST /v3/avatars answers the same shape for all three types: the new look in avatar_item, the character it belongs to in avatar_group.

{
  "data": {
    "avatar_item": {
      "id": "look_abc123",
      "name": "Sarah",
      "avatar_type": "digital_twin",
      "group_id": "group_xyz789",
      "preview_image_url": "https://files.heygen.ai/...",
      "supported_api_engines": ["avatar_iv", "avatar_v"],
      "default_voice_id": "voice_cloned123",
      "status": "processing"
    },
    "avatar_group": {
      "id": "group_xyz789",
      "name": "Sarah",
      "looks_count": 1,
      "default_voice_id": "voice_cloned123",
      "status": "pending_consent",
      "consent_status": "pending",
      "created_at": 1717000000
    }
  }
}

Creation is asynchronous, so a new look starts at status: "processing". Poll GET /v3/avatars/looks/{look_id} until it reports completed. For digital twins you can also subscribe to the instant_avatar.success and instant_avatar.fail webhook events, then read the look to confirm its status. Before requesting a specific engine, check the look’s supported_api_engines against Models.

The character carries a status of its own, covering consent and moderation rather than training, so avatar_group.status and avatar_item.status move independently. avatar_group.status follows consent_status: pending_consent while consent is outstanding, failed if it was rejected, and completed otherwise. A photo or prompt avatar renders as soon as its look reports completed. A digital twin renders once the look is completed and its group has cleared consent, so wait for both.

Consent

A digital twin generates video once the person depicted has agreed to be cloned, which is what consent_status tracks. A group created from a photo or a prompt has no consent step, so it reports consent_status of null. A photo still shows a real person: you are responsible for having their permission, as Photo to Avatar explains. The field belongs to the group, so a photo or prompt look added to an existing twin’s group carries that group’s status. Avatar Consent covers the POST /v3/avatars/{group_id}/consent flow and the three levels of access to it.

One character, many looks

Adding looks to a character you already have keeps one identity across every video: pass avatar_group_id when you create, hand an existing look to a prompt, or apply a Look Pack. List everything a character owns with GET /v3/avatars/looks?group_id=..., rename a look with PATCH /v3/avatars/looks/{look_id}, and remove one with DELETE. Deleting the last look in a character deletes the character with it.

Delete an avatar

DELETE /v3/avatars/{group_id} deletes the character and every look in it. To remove a single look instead, use DELETE /v3/avatars/looks/{look_id} as above. Neither can be undone through the API.

Deleting an avatar does not delete the files you created it from, or anything else made with it:

Resource	Removed with the avatar?	How to remove it
Training footage, consent video, or photo you supplied	No, each is a separate asset	DELETE /v3/assets/{asset_id}
Voice cloned from twin footage	No, it stays in your voice library	DELETE /v3/voices/{voice_id}
Videos already generated	No	DELETE /v3/videos/{video_id}

A file or consent_video passed as a url or base64 is also saved as an asset in your workspace. To keep the asset_id of every source file so you can delete it later, upload with POST /v3/assets first and pass asset_id. To remove an avatar and everything you supplied for it, delete the avatar group, then each source asset and the cloned voice. Delete source assets only after the look reports completed or failed and consent has been accepted or rejected.