Skip to main content
  • Endpoint: POST https://api.heygen.com/v3/avatars
  • Purpose: Create a new avatar from a video (digital twin), a photo, or an AI prompt. Returns an avatar_item (the look) and an avatar_group (the character identity). The look ID is what you pass as avatar_id when creating videos.

​
Authentication

HeaderValue
X-Api-KeyYour HeyGen API key
AuthorizationBearer YOUR_ACCESS_TOKEN (OAuth)

​
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": "video",
    "name": "My Digital Twin",
    "file": { "type": "url", "url": "https://example.com/training-footage.mp4" }
  }'
ParameterTypeRequiredDescription
typestringYesMust be "video".
namestringYesDisplay name for the avatar.
fileobjectYesTraining video. { "type": "url", "url": "..." }, { "type": "asset_id", "asset_id": "..." }, or { "type": "base64", "media_type": "video/mp4", "data": "..." }.
avatar_group_idstringNoAttach to an existing character identity. Omit to create a new one.

​
Photo Avatar

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" }
  }'
ParameterTypeRequiredDescription
typestringYesMust be "photo".
namestringYesDisplay name for the avatar.
fileobjectYesPhoto image. Same format options as digital twin file.
avatar_group_idstringNoAttach to an existing character identity. Omit to create a new one.

​
Response

Both types return the same shape: 
{
  "data": {
    "avatar_item": {
      "id": "look_abc123",
      "name": "My Digital Twin",
      "avatar_type": "video_avatar",
      "group_id": "group_xyz789",
      "preview_image_url": "https://files.heygen.ai/...",
      "supported_api_engines": ["v3"]
    },
    "avatar_group": {
      "id": "group_xyz789",
      "name": "My Digital Twin",
      "looks_count": 1,
      "consent_status": null,
      "created_at": 1717000000
    }
  }
}
FieldTypeDescription
avatar_item.idstringThe look ID — pass this as avatar_id to POST /v3/videos.
avatar_item.avatar_typestring"video_avatar" (digital twin) or "photo_avatar".
avatar_item.group_idstringThe character identity this look belongs to.
avatar_group.idstringGroup ID. Use to add more looks or initiate consent.
avatar_group.consent_statusstring or nullnull means consent is not required. Otherwise check the consent flow below.
  • Endpoint: POST https://api.heygen.com/v3/avatars/{group_id}/consent
  • Purpose: Initiate a consent flow for an avatar group. Returns a URL the avatar subject must visit to approve usage. Required for digital twins before the avatar can be used in video generation.

​
Quick Example

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"
  }'

​
Request Body

ParameterTypeRequiredDescription
reroute_urlstringNoRedirect URL after the subject completes consent. Defaults to HeyGen’s own completion page.

​
Response

{
  "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..."
  }
}
FieldTypeDescription
urlstringConsent page URL. Send this to the avatar subject to complete approval.
avatar_group.consent_statusstringCurrent consent status (e.g. "pending").
Check consent_status on the avatar group (via GET /v3/avatars/{group_id}) 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 to browse looks, or pass avatar_group_id when creating a new avatar to add a look to an existing character.