> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Photo Avatar

> Turn a single photo into a talking AI avatar with the HeyGen Photo Avatar API. Upload an image, attach a script, render a lipsynced video starring that photo.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-8.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=d16cda8ab7835eed66c6a205d16e631f)

## Prerequisites

> [!TIP]
>
> A portrait photo (PNG or JPEG) — clear, front-facing, good lighting

> [!TIP]
>
> A `voice_id` for the voice you want. Use `GET /v3/models/audio/voices` to browse voices.

## Step 1 — Create a Photo Avatar

Upload your photo and create a Photo Avatar with `POST /v3/avatars`:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/avatars" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "photo",
    "name": "Sarah — Marketing",
    "file": {
      "type": "url",
      "url": "https://example.com/portrait.jpg"
    }
  }'
```

To use a local file, upload it first with `POST /v3/assets` and pass `"file": {"type": "asset_id", "asset_id": "RETURNED_ASSET_ID"}` instead.

The response includes an `avatar_item` with an `id` — this is your `avatar_id` for video creation.

## Step 2 — Generate the video

Use `POST /v3/videos` with `type: "avatar"` and the Photo Avatar ID:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_PHOTO_AVATAR_ID",
    "engine": { "type": "heygen-avatar-6" },
    "script": "Hi there! This video was created from a single photo using the HeyGen API.",
    "voice_id": "YOUR_VOICE_ID",
    "title": "Photo Avatar Demo",
    "resolution": "1080p",
    "aspect_ratio": "auto"
  }'
```

## Step 3 — Poll for completion

Generation is asynchronous. Poll [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) until `status` is `completed`, then download `video_url`.

## Motion and expressiveness

Photo avatars (`avatar_type: photo_avatar`) take a `motion_prompt` that directs body motion and hand gestures (e.g. "nodding gently"). On Avatar IV they also take `expressiveness`: `high`, `medium`, or `low` (default `low`). On Avatar 6, set `engine.motion_expressiveness` instead.

```json theme={null}
{
  "type": "avatar",
  "avatar_id": "YOUR_PHOTO_AVATAR_ID",
  "script": "Let me show you our quarterly results.",
  "voice_id": "YOUR_VOICE_ID",
  "motion_prompt": "gesturing with hands while presenting",
  "expressiveness": "high"
}
```

Every other field, such as `background`, `remove_background`, `voice_settings`, and `callback_url`, is in the [Create Video reference](https://heygen-1fa696a7.mintlify.site/reference/create-video.md).

> [!WARNING]
>
> Photo quality matters. Use a well-lit, front-facing portrait with a neutral expression for the best results. Avoid sunglasses, hats covering the forehead, or extreme angles.

## Using a preset Photo Avatar

You can skip avatar creation and use a public preset avatar instead:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/avatars/looks?avatar_type=photo_avatar&ownership=public" \
  -H "x-api-key: YOUR_API_KEY"
```

Pick any `id` from the response and use it directly as your `avatar_id` in `POST /v3/videos`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.