# Create Avatar

## cURL

```bash
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

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