Create Avatar - HeyGen Documentation

Three creation modes all go through POST /v3/avatars — 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 and 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"`
A photo of a person	An avatar from that photo, fast	`type: "photo"`
Just a text description	A fully synthetic AI character	`type: "prompt"`
An existing HeyGen avatar	A new look for it (new outfit, setting, style)	`type: "prompt"` + `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.

Creation Methods

Digital Twin
Photo Avatar
Prompt-to-Avatar

Digital Twin (`type: "digital_twin"`)

Create an avatar from video footage. The speaker in the video becomes a reusable digital twin.

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`), 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.

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

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.
`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`), 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.

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:

Create the photo avatar once:

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

Generate as many additional looks as you need, each conditioned on Sarah’s identity:

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=... — 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:

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:

{
  "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` or 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`.
`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.

Before you can generate video with a digital twin, the person depicted must consent to being cloned. Photo avatars and prompt-to-avatar characters do not require consent (their consent_status is null). HeyGen offers three increasing levels of consent access — recording via webcam (all customers), uploading a consent video (enterprise), and skipping consent entirely (strategic accounts, by agreement). The API flow, the full breakdown of the three levels, and how to request higher levels all live on the dedicated page.

Avatar Consent — levels of access & the API flow

How consent works, who each level is for, and the POST /v3/avatars/{group_id}/consent flow.

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 to browse looks (see Avatar Looks), or pass avatar_group_id when creating a new avatar to add a look to an existing character.

​Pick your flow

​Creation Methods

​Digital Twin (type: "digital_twin")

​Photo Avatar (type: "photo")

​Prompt-to-Avatar (type: "prompt") — Tokyo Pipeline

​Parameters

​How avatar_id and avatar_group_id combine

​Generate new looks for an existing avatar

​With reference images

​Errors

​Response

​Avatar Consent

Avatar Consent — levels of access & the API flow

​Avatars vs. Looks

Pick your flow

Creation Methods

Digital Twin (`type: "digital_twin"`)

Photo Avatar (`type: "photo"`)

Prompt-to-Avatar (`type: "prompt"`) — Tokyo Pipeline

Parameters

How `avatar_id` and `avatar_group_id` combine

Generate new looks for an existing avatar

With reference images

Errors

Response

Avatar Consent

Avatars vs. Looks