Create Avatar

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.

Creating a digital twin automatically clones one voice from the training footage. The response returns its ID immediately as avatar_item.default_voice_id while both the avatar and voice continue processing. There is no separate voice-cloning request or opt-in step.

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. Voice and status metadata belong to the nested look and group resources rather than the response wrapper.

{
  "data": {
    "avatar_item": {
      "id": "look_abc123",
      "name": "My Digital Twin",
      "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",
      "tags": []
    },
    "avatar_group": {
      "id": "group_xyz789",
      "name": "My Digital Twin",
      "looks_count": 1,
      "default_voice_id": "voice_cloned123",
      "status": "completed",
      "consent_status": "pending",
      "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_item.default_voice_id`	string or null	For a digital twin, the exact voice cloned from this request’s footage. The ID is available immediately, although the voice may still be processing.
`avatar_item.status`	string	Training status of the look. Avatar creation is asynchronous, so a new digital twin begins as `"processing"`.
`avatar_group.id`	string	Group ID. Use to add more looks or initiate consent.
`avatar_group.default_voice_id`	string or null	The effective group-first default voice. For a new group this is the cloned voice; for an existing group its current default can differ from the new look’s voice.
`avatar_group.status`	string	Status of the group resource. This is independent from look training status.
`avatar_group.consent_status`	string or null	`null` for photo and prompt avatars. Digital twins may require consent — see below.

Digital Twin Voice

A digital twin and its cloned voice train asynchronously. Poll GET /v3/avatars/looks/{look_id} until the look’s status is "completed" before using it to create a video. The creation response exposes the voice through two related nested fields:

Field	Meaning
`avatar_item.default_voice_id`	The exact voice cloned from this request’s footage. It is returned immediately for `type: "digital_twin"`.
`avatar_group.default_voice_id`	The effective voice for the character identity. The group voice takes precedence when one is linked; otherwise this falls back to the new look’s cloned voice.

When creating a narrated avatar scene with POST /v3/videos, provide script and avatar_id and omit voice_id to use the linked default automatically. The group voice is used when present, with the look voice as the fallback. Pass voice_id only when you want to override that default. 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 through the same API endpoint, and skipping consent entirely. The two higher levels are enterprise-only — reach out to sales or your account team for access. The API flows, the full breakdown of the three levels, and how to request them 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.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Video Translation

Lipsync

Tools

Avatar Management

Voice Management

Asset Management

Batches

Webhook

Limits

Pricing

Socials

For Agents

Integrations

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

Digital Twin Voice

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

​Digital Twin Voice

​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

Digital Twin Voice

Avatar Consent

Avatars vs. Looks