Create an avatar

Create an avatar from multiple file sources. Returns an avatar_id for tracking purposes via GET /v3/avatars/looks/ . Also returns an avatar_group_id for tracking purposes via GET /v3/avatars/ . Files can be provided as asset_id (from POST /v3/assets), HTTPS URL, or base64-encoded content. Supported types: image (png, jpeg), video (mp4, webm), audio (mp3, wav), and pdf.

POST /v3/avatars

Create an avatar

cURL

curl --request POST \
  --url https://api.heygen.com/v3/avatars \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "type": "<string>",
  "name": "<string>",
  "prompt": "<string>",
  "reference_images": [
    {
      "type": "<string>",
      "url": "<string>"
    }
  ],
  "avatar_group_id": "<string>"
}
'

200

{
  "data": {
    "avatar_item": {
      "id": "<string>",
      "name": "<string>",
      "avatar_type": "studio_avatar",
      "group_id": "ag_abc123",
      "preview_image_url": "https://files.heygen.ai/look/business_preview.jpg",
      "preview_video_url": "https://files.heygen.ai/look/business_preview.mp4",
      "gender": "female",
      "tags": [
        "<string>"
      ],
      "default_voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
      "supported_api_engines": [
        "<string>"
      ],
      "image_width": 1920,
      "image_height": 1080,
      "preferred_orientation": "<string>"
    },
    "avatar_group": {
      "id": "<string>",
      "name": "<string>",
      "created_at": 123,
      "looks_count": 123,
      "preview_image_url": "https://files.heygen.ai/avatar/anna_preview.jpg",
      "preview_video_url": "https://files.heygen.ai/avatar/anna_preview.mp4",
      "gender": "female",
      "default_voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
      "consent_status": "approved"
    }
  }
}

Authorizations

ApiKeyAuthBearerAuth

x-api-key · string · header · required

HeyGen API key. Obtain from your HeyGen dashboard.

Body

application/json

CreatePromptAvatarRequest

CreateVideoAvatarRequest

CreatePhotoAvatarRequest

Discriminated union for POST /v3/avatars request body.

type · string · required

Must be 'prompt' for AI-generated avatars.

Allowed value: "prompt"

name · string · required

Name of the avatar.

prompt · string · required

Prompt for avatar generation.

Maximum string length: 200

reference_images · (AssetUrl · object | AssetId · object | AssetBase64 · object)[] | null

Reference images you want to be included in the avatar. Max 3. Will only work with an avatar_group_id.

Maximum array length: 3

Asset input via publicly accessible HTTPS URL.

AssetUrl

AssetId

AssetBase64

Show child attributes

avatar_group_id · string | null

Optional identity you would like to attach the prompted avatar to. By default it will create a new identity.

Response

200

application/json

Successful response

data · CreateAvatarResponse · object

Show child attributes