> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Avatar
> Create a HeyGen avatar from video footage, a single photo, or a text prompt. Covers all three creation types, generating new looks for an existing avatar, the consent flow, and how to render videos with your trained avatar.
Three creation modes all go through [`POST /v3/avatars`](/reference/create-avatar) — distinguished by the `type` field. The result is a new **look** that you pass as `avatar_id` to video creation endpoints. To browse existing avatars and looks instead, see [Avatars](/docs/avatars) and [Avatar Looks](/docs/avatar-looks).
## Pick your flow
| You have... | You want... | Use |
| ------------------------- | -------------------------------------------------- | ------------------------------------------------------- |
| Video footage of a person | A reusable digital twin of that person | [`type: "digital_twin"`](#digital-twin) |
| A photo of a person | An avatar from that photo, fast | [`type: "photo"`](#photo-avatar) |
| Just a text description | A fully synthetic AI character | [`type: "prompt"`](#prompt-to-avatar) |
| An existing HeyGen avatar | A **new look** for it (new outfit, setting, style) | [`type: "prompt"`](#prompt-to-avatar) **+** `avatar_id` |
The last row is the most-overlooked path: once you have any HeyGen avatar (digital twin, photo, or prompt), you can use the prompt endpoint to generate additional looks for that same character — see [Generate new looks for an existing avatar](#generate-new-looks-for-an-existing-avatar).
## Creation Methods
### Digital Twin (`type: "digital_twin"`)
Create an avatar from video footage. The speaker in the video becomes a reusable digital twin.
```bash theme={null}
curl -X POST "https://api.heygen.com/v3/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "digital_twin",
"name": "My Digital Twin",
"file": { "type": "url", "url": "https://example.com/training-footage.mp4" }
}'
```
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` | string | Yes | Must be `"digital_twin"`. |
| `name` | string | Yes | Display name for the avatar. |
| `file` | object | Yes | Training video. `{ "type": "url", "url": "..." }`, `{ "type": "asset_id", "asset_id": "..." }` (from [`POST /v3/assets`](/reference/upload-asset)), or `{ "type": "base64", "media_type": "video/mp4", "data": "..." }`. |
| `avatar_group_id` | string | No | Attach to an existing character identity. Omit to create a new one. |
### Photo Avatar (`type: "photo"`)
Create an avatar from a single photo. Quick to set up — no video recording needed.
```bash theme={null}
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": "My Photo Avatar",
"file": { "type": "url", "url": "https://example.com/headshot.png" }
}'
```
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | ------------------------------------------------------------------- |
| `type` | string | Yes | Must be `"photo"`. |
| `name` | string | Yes | Display name for the avatar. |
| `file` | object | Yes | Photo image. Same format options as digital twin `file`. |
| `avatar_group_id` | string | No | Attach to an existing character identity. Omit to create a new one. |
**Want to generate new outfits or settings from a photo using a prompt?** Create the photo avatar first, then call `type: "prompt"` with the returned `avatar_item.id` as `avatar_id` — see [Generate new looks for an existing avatar](#generate-new-looks-for-an-existing-avatar). The image you upload here becomes the visual reference that prompt-driven variations are conditioned on.
### Prompt-to-Avatar (`type: "prompt"`) — Tokyo Pipeline
Generate an entirely new AI avatar from a text description. No photo or video needed — describe the character you want and the Tokyo pipeline creates it.
Prompt-to-Avatar uses HeyGen's Tokyo pipeline to generate a unique AI character from your text description. The avatar is fully synthetic — no real person is depicted.
```bash theme={null}
curl -X POST "https://api.heygen.com/v3/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "prompt",
"name": "Space Commander",
"prompt": "Young woman, early 30s, confident expression, short silver hair, warm brown eyes, wearing a dark blue space suit with mission patches, standing in a modern spacecraft bridge with holographic displays"
}'
```
#### Parameters
| Parameter | Type | Required | Description |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` | string | Yes | Must be `"prompt"`. |
| `name` | string | Yes | Display name for the avatar. |
| `prompt` | string | Yes | Text description of the avatar's appearance, clothing, setting, and style. Max 1000 chars. Be specific for best results. |
| `avatar_id` | string | No | An existing look ID to use as the **visual reference** for the generation. The new look is saved to the referenced avatar's group; if `avatar_group_id` is also provided, the avatar must belong to that group and the result is saved there. The referenced avatar must exist and have a usable image, otherwise the request is rejected. Use this to create new looks (outfits, settings, styles) for an avatar you already created — see [Generate new looks for an existing avatar](#generate-new-looks-for-an-existing-avatar). |
| `avatar_group_id` | string | No | The identity (group) to **save** the generated avatar to. By default a new identity is created. If `avatar_id` is also provided, it must belong to this group. This field only controls where the result is saved — it does not drive the visual reference; use `avatar_id` for that. |
| `reference_images` | array | No | Up to **3** reference images for additional style/setting guidance. Each entry is `{ "type": "url", "url": "..." }`, `{ "type": "asset_id", "asset_id": "..." }` (from [`POST /v3/assets`](/reference/upload-asset)), or `{ "type": "base64", "media_type": "image/png", "data": "..." }`. Can be used on their own or layered on top of an `avatar_id` reference. |
#### How `avatar_id` and `avatar_group_id` combine
| `avatar_id` | `avatar_group_id` | Visual reference | Saved to |
| ----------- | ----------------- | --------------------------------------- | ---------------------------------------------------- |
| ✗ | ✗ | none — generated purely from the prompt | a new group |
| ✗ | ✓ | none — generated purely from the prompt | that group |
| ✓ | ✗ | the referenced avatar's image | the referenced avatar's group |
| ✓ | ✓ | the referenced avatar's image | `avatar_group_id` (the avatar **must** belong to it) |
`reference_images` layer additional guidance on top of any of these combinations; with no `avatar_id` they are used on their own.
**Changed behavior (June 2026):** `avatar_group_id` previously conditioned the generation on one of the group's looks. It now only controls where the result is saved. If you relied on it for character consistency, pass the base look's ID as `avatar_id` instead — see the [changelog](/changelog).
**Prompting tips for best results:**
* Be specific about age, gender, expression, and clothing
* Describe the setting/background
* Mention lighting or mood (e.g., `"warm studio lighting"`, `"cinematic"`)
* Reference images help with style consistency but are optional
#### Generate new looks for an existing avatar
If you already have a HeyGen avatar — from any creation type — you can generate additional looks for that same character by calling `type: "prompt"` with the existing look's ID as `avatar_id`. The referenced look's image is used as the visual reference that conditions the new generation, so the character's identity stays consistent across the new outfit, setting, or style described in your prompt. The new look is saved to the referenced avatar's group automatically — no `avatar_group_id` needed.
Typical sequence — say you have a photo of a person and want several prompt-driven variations:
1. Create the photo avatar once:
```bash theme={null}
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" }
}'
```
Save the returned `avatar_item.id` (e.g. `look_abc123`).
2. Generate as many additional looks as you need, each conditioned on Sarah's identity:
```bash theme={null}
curl -X POST "https://api.heygen.com/v3/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "prompt",
"name": "Sarah — Navy Blazer Office",
"prompt": "Wearing a navy blazer, modern office background with plants, warm natural light",
"avatar_id": "look_abc123"
}'
```
Each call returns a new `avatar_item.id` (a new look) attached to the same `avatar_group.id`. Browse all looks for an avatar via [`GET /v3/avatars/looks?group_id=...`](/reference/list-avatar-looks) — and pass any look's ID as `avatar_id` to use it as the reference for the next variation.
Passing only `avatar_group_id` (without `avatar_id`) saves the new look to that group but does **not** use any of the group's images as a visual reference — the result is generated purely from the prompt. To keep a character's identity consistent, pass the base look's ID as `avatar_id`.
#### With reference images
`reference_images` (up to 3) add style or setting guidance to the generation. They can be used on their own — to guide a brand-new identity — or layered on top of an `avatar_id` reference for extra control over the new look:
```bash theme={null}
curl -X POST "https://api.heygen.com/v3/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "prompt",
"name": "Brand Ambassador — Plant Studio",
"prompt": "Professional woman in her 40s, warm smile, wearing a navy blazer, modern office background with plants",
"avatar_id": "look_abc123",
"reference_images": [
{ "type": "url", "url": "https://example.com/style-reference.png" },
{ "type": "url", "url": "https://example.com/setting-reference.jpg" }
]
}'
```
#### Errors
| Condition | HTTP status | Error code |
| --------------------------------------------------------------------------------------- | ----------- | ------------------- |
| `avatar_id` not found | 404 | `AVATAR_NOT_FOUND` |
| `avatar_id` exists but has no usable image (e.g. generation not completed, or rejected) | 400 | `INVALID_PARAMETER` |
| `avatar_id` does not belong to the provided `avatar_group_id` | 400 | `INVALID_PARAMETER` |
## Response
All three creation types return the same response shape:
```json theme={null}
{
"data": {
"avatar_item": {
"id": "look_abc123",
"name": "Space Commander",
"avatar_type": "studio_avatar",
"group_id": "group_xyz789",
"preview_image_url": "https://files.heygen.ai/...",
"supported_api_engines": ["avatar_4_quality", "avatar_4_turbo"],
"tags": []
},
"avatar_group": {
"id": "group_xyz789",
"name": "Space Commander",
"looks_count": 1,
"consent_status": null,
"created_at": 1717000000
}
}
}
```
| Field | Type | Description |
| ----------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `avatar_item.id` | string | The look ID — pass this as `avatar_id` to [`POST /v3/videos`](/reference/create-video) or [Create Video Agent Session](/reference/create-video-agent-session). |
| `avatar_item.avatar_type` | string | `"digital_twin"`, `"photo_avatar"`, or `"studio_avatar"`. |
| `avatar_item.supported_api_engines` | array | Engine values compatible with this look for [`POST /v3/videos`](/reference/create-video). |
| `avatar_item.group_id` | string | The character identity this look belongs to. |
| `avatar_group.id` | string | Group ID. Use to add more looks or initiate consent. |
| `avatar_group.consent_status` | string or null | `null` for photo and prompt avatars. Digital twins may require consent — see below. |
## Avatar Consent
Initiate a consent flow for an avatar group. Returns a URL the avatar subject must visit to approve usage. Full schema: [`POST /v3/avatars/{group_id}/consent`](/reference/create-avatar-consent).
Consent is only required for **digital twin** avatars (`type: "digital_twin"`). Photo avatars and prompt-to-avatar characters do not require consent.
### Request
```bash theme={null}
curl -X POST "https://api.heygen.com/v3/avatars/group_xyz789/consent" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reroute_url": "https://heygen.com/consent-done"
}'
```
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------- |
| `reroute_url` | string | No | Redirect URL after the subject completes consent. Defaults to HeyGen's own completion page. |
### Response
```json theme={null}
{
"data": {
"avatar_group": {
"id": "group_xyz789",
"name": "My Digital Twin",
"consent_status": "pending",
"looks_count": 1,
"created_at": 1717000000
},
"url": "https://heygen.com/consent/abc123..."
}
}
```
| Field | Type | Description |
| ----------------------------- | ------ | ----------------------------------------------------------------------- |
| `url` | string | Consent page URL. Send this to the avatar subject to complete approval. |
| `avatar_group.consent_status` | string | Current consent status (e.g. `"pending"`). |
Check `consent_status` on the avatar group via [`GET /v3/avatars/{group_id}`](/reference/get-avatar-group) to know when consent is complete.
## Avatars vs. Looks
An **avatar group** is a character identity (e.g. "Sarah"). Each group can have multiple **looks** — different outfits, poses, or styles. When creating a video, you pass a look ID (not a group ID) as the `avatar_id`. Use [`GET /v3/avatars/looks`](/reference/list-avatar-looks) to browse looks (see [Avatar Looks](/docs/avatar-looks)), or pass `avatar_group_id` when creating a new avatar to add a look to an existing character.