Skip to main content
POST
/
v3
/
avatars
Create Avatar
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>"
}
'
{
  "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": "portrait",
      "status": "completed",
      "error": {
        "code": "<string>",
        "message": "<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",
      "status": "completed",
      "error": {
        "code": "<string>",
        "message": "<string>"
      }
    }
  }
}

Authorizations

​
x-api-key
string
header
required

HeyGen API key. Obtain from your HeyGen dashboard.

Body

application/json

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: 1000
​
reference_images
(AssetUrl · object | AssetId · object | AssetBase64 · object)[] | null

Reference images — each as {"type": "url", "url": "https://..."} or {"type": "asset_id", "asset_id": "..."}. Max 3. Will only work with an avatar_group_id.

Maximum array length: 3

Asset input via publicly accessible HTTPS URL.

​
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

Successful response

​
data
CreateAvatarResponse · object