> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-8.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=d16cda8ab7835eed66c6a205d16e631f)

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](https://heygen-1fa696a7.mintlify.site/docs/avatars.md) and [Avatar Looks](https://heygen-1fa696a7.mintlify.site/docs/avatar-looks.md).

## 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](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-video.md) |
| One photo of a person | An avatar from that image, ready in minutes | [Photo to Avatar](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-photo.md) |
| A text description | A synthetic character, no real person depicted | [Prompt to Avatar](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-prompt.md) |
| An avatar you already own | A new outfit, setting, or style for that same character | [Prompt to Avatar](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-prompt.md) or [Look Packs](https://heygen-1fa696a7.mintlify.site/docs/avatar-look-packs.md) |

The first three go through [`POST /v3/avatars`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar), 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`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar-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`.

```json theme={null}
{
  "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": ["heygen-avatar-6", "heygen-avatar-6-turbo", "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}`](https://heygen-1fa696a7.mintlify.site/reference/get-avatar-look) until it reports `completed`. For digital twins you can also subscribe to the `instant_avatar.success` and `instant_avatar.fail` [webhook events](https://heygen-1fa696a7.mintlify.site/docs/webhook-events.md), then read the look to confirm its status. Before requesting a specific engine, check the look's `supported_api_engines` against [Models](https://heygen-1fa696a7.mintlify.site/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](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-video.md) 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`. 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](https://heygen-1fa696a7.mintlify.site/docs/avatar-consent.md) covers permission for photo avatars, the [`POST /v3/avatars/{group_id}/consent`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar-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](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-prompt.md), or apply [a Look Pack](https://heygen-1fa696a7.mintlify.site/docs/avatar-look-packs.md). List everything a character owns with [`GET /v3/avatars/looks?group_id=...`](https://heygen-1fa696a7.mintlify.site/reference/list-avatar-looks), rename a look with [`PATCH /v3/avatars/looks/{look_id}`](https://heygen-1fa696a7.mintlify.site/reference/update-avatar-look), and remove one with [`DELETE`](https://heygen-1fa696a7.mintlify.site/reference/delete-avatar-look). Deleting the last look in a character deletes the character with it.

## Delete an avatar

[`DELETE /v3/avatars/{group_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-avatar-group) deletes the character and every look in it. To remove a single look instead, use [`DELETE /v3/avatars/looks/{look_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-avatar-look) 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}`](https://heygen-1fa696a7.mintlify.site/reference/delete-asset) |
| Voice cloned from twin footage | No, it stays in your voice library | [`DELETE /v3/models/audio/voices/{voice_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-an-audio-voice) |
| Videos already generated | No | [`DELETE /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-video) |

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`](https://heygen-1fa696a7.mintlify.site/docs/upload-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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.