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

## HTTP Response Codes

- **200**: Success
- **400**: Bad Request
- **401**: Unauthorized
- **429**: Too Many Requests

## Example Successful Response

```json
{
  "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, required

  HeyGen API key. Obtain from your HeyGen dashboard.

Request Body

• CreatePromptAvatarRequest
• CreateDigitalTwinRequest
• CreatePhotoAvatarRequest

Fields

• type: string, required
  • Must be 'prompt' for AI-generated avatars. Allowed value: "prompt"
• name: string, required
• prompt: string, required, max length: 1000
• reference_images: array of objects, optional
  • Each object can have type as url or asset_id, max 3 items.
• avatar_group_id: string, optional

Example Error Response

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}