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

# Avatar 6

> Generate Avatar 6 videos through the Model API on POST /v3/models/avatars or the Application API on POST /v3/videos.

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

Avatar 6 is available two ways:

| | [Model API](#model-api) | [Application API](#application-api) |
| - | - | - |
| Endpoint | `POST /v3/models/avatars` | `POST /v3/videos` |
| You send | A reference image or video plus speech audio | A HeyGen avatar look plus a script and voice, or audio |
| Models | `heygen-avatar-6`, `heygen-avatar-6-turbo` | `heygen-avatar-6`, `heygen-avatar-6-turbo` |
| Resolution | `1080p` (default) or `2k` | `1080p` (default) or `2k` |
| Output size | Follows the reference's shape ([sizes](#output-size)) | Set by `aspect_ratio` ([sizes](#application-api)) |
| Motion controls | `motion_prompt` and `motion_expressiveness` | `motion_prompt` and `engine.motion_expressiveness` |

## Model API

The Avatar 6 model animates your reference media with the speech audio you supply. There is no avatar or voice to set up first.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/models/avatars" \
  -H "x-api-key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-6",
    "reference_images": [{ "type": "asset_id", "asset_id": "IMAGE_ASSET_ID" }],
    "audio": { "type": "url", "url": "https://example.com/speech.wav" },
    "resolution": "2k",
    "motion_prompt": "Face the camera with a warm expression and use small, natural hand gestures."
  }'
```

Submission returns `202`:

```json theme={null}
{ "data": { "video_id": "VIDEO_ID", "status": "pending" } }
```

Each media input accepts an HTTPS URL, an [uploaded asset](https://developers.heygen.com/docs/upload-assets.md) ID, or inline base64:

```json theme={null}
{ "type": "url",      "url": "https://example.com/photo.jpg" }
{ "type": "asset_id", "asset_id": "ASSET_ID" }
{ "type": "base64",   "media_type": "image/jpeg", "data": "<base64>" }
```

| Field | Type | Default | Notes |
| - | - | - | - |
| `model` | string | required | `heygen-avatar-6` or `heygen-avatar-6-turbo`. Both take the same inputs. |
| `reference_images` | array | | One image. Send `reference_images`, `reference_videos`, or both: at least one is required. |
| `reference_videos` | array | | One video. See [reference media](#reference-media). |
| `audio` | asset | required | The speech the avatar performs. The video runs the length of the audio. |
| `resolution` | enum | `1080p` | `1080p` or `2k` |
| `motion_prompt` | string | | Up to 1,200 characters on gestures, expression, posture and camera. Takes precedence over `motion_expressiveness` where they overlap. |
| `motion_expressiveness` | enum | `default` | `default`, or `less` for fewer, smaller gestures and calmer expressions |
| `output_width`, `output_height` | integer | | Resize the finished video to an exact size. Even pixel values, set together. Omit both for the [output size](#output-size) below. |
| `callback_url` | string | | HTTPS URL notified when the job finishes |
| `callback_id` | string | | Up to 256 characters, returned with the callback |

### Output size

Without `output_width` and `output_height`, the video keeps the reference's aspect ratio, sized by `resolution`:

| `resolution` | Short edge | 16:9 reference | 9:16 reference |
| - | - | - | - |
| `1080p` | 1080 px | 1920 × 1080 | 1080 × 1920 |
| `2k` | 1620 px | 2880 × 1620 | 1620 × 2880 |

### Retrieve the result

```bash theme={null}
curl "https://api.heygen.com/v3/models/videos/VIDEO_ID" \
  -H "x-api-key: $HEYGEN_API_KEY"
```

```json theme={null}
{
  "data": {
    "video_id": "VIDEO_ID",
    "status": "completed",
    "model": "heygen-avatar-6",
    "created_at": 1793750400,
    "video_url": "https://resource2.heygen.ai/videos/.../VIDEO.mp4",
    "duration": 12.6,
    "width": 2880,
    "height": 1620,
    "aspect_ratio": "16:9"
  }
}
```

`pending` and `processing` mean the job is running; it ends as `completed`, `failed` or `cancelled`. `video_url` is a signed link: poll again to refresh it. `duration` can be about a tenth of a second shorter than the audio. Failed and cancelled jobs carry `failure_code` and `failure_message`:

| `failure_code` | Meaning |
| - | - |
| `generation_failed` | The render did not complete. Retry the request. |
| `generation_cancelled` | The job was cancelled. |
| `moderation_rejected` | The speech or reference media does not meet HeyGen's content policy. Send different input. |

### Reference media

Three ways to render a real person, based on your source material and your agreement with HeyGen:

| Approach | Available to | Consent | Avatar slot |
| - | - | - | - |
| **HeyGen avatar**: a public avatar, or a digital twin made through HeyGen's [consent flow](https://developers.heygen.com/docs/avatar-consent.md), on the [Application API](#application-api) | All workspaces | Handled by HeyGen's consent flow | Required for digital twins |
| **Photo reference**: a photo of the person, used with their permission. The model generates the motion. | All workspaces | No agreement needed | Not required |
| **Video reference**: the person's own gestures and mannerisms, for the highest likeness. Add a matching photo for best results. | Enterprise customers | The person verifies consent with HeyGen before their video is submitted. Some contracts run without a consent step, reviewed case by case. | Not required |

Videos of animated or illustrated characters work as references in every workspace.

A realistic reference video from a workspace without video-reference access returns `422` with `realistic_human_reference_not_allowed`. Use a photo reference or a HeyGen avatar instead, or [contact sales](https://www.heygen.com/contact-us/sales) for access.

Reference URLs and base64 inputs take videos up to 50 MB and images up to 32 MB. For a larger reference video, up to 200 MB, upload it with [direct upload](https://developers.heygen.com/docs/direct-upload.md) and pass its `asset_id`.

## Application API

Render a HeyGen avatar look with Avatar 6 on [`POST /v3/videos`](https://developers.heygen.com/reference/create-video) by setting `engine.type` to `heygen-avatar-6` or `heygen-avatar-6-turbo`. To animate a realistic person, use a [digital twin](https://developers.heygen.com/docs/avatar-from-video.md) created with HeyGen's [consent flow](https://developers.heygen.com/docs/avatar-consent.md).

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_LOOK_ID",
    "script": "Welcome. This clip was rendered with Avatar 6.",
    "voice_id": "YOUR_VOICE_ID",
    "engine": { "type": "heygen-avatar-6", "motion_expressiveness": "less" },
    "resolution": "2k",
    "aspect_ratio": "16:9",
    "motion_prompt": "Smile warmly and use small, open-handed gestures while speaking."
  }'
```

The response returns `data.video_id`.

This endpoint supports Avatar 6 for single-avatar requests (`type: "avatar"`). Avatar 6 is not supported for raw-image requests, studio scenes, batch creation, or scene editing. Omitting `engine` continues to select Avatar IV.

Use a compatible photo or video look. Check `supported_api_engines` on [`GET /v3/avatars/looks/{look_id}`](https://developers.heygen.com/reference/get-avatar-look): eligible looks list `heygen-avatar-6` and `heygen-avatar-6-turbo`. The look and reference must also satisfy the consent requirements.

| Field | Notes |
| - | - |
| `type` | `avatar` |
| `avatar_id` | A look ID, from the public library or your workspace ([`GET /v3/avatars/looks`](https://developers.heygen.com/docs/avatar-looks)) |
| `script` + `voice_id`, `audio_url` or `audio_asset_id` | One speech source: a script with a [voice](https://developers.heygen.com/docs/voices/overview.md), a public audio URL, or an [uploaded audio asset](https://developers.heygen.com/docs/upload-assets.md) |
| `engine.type` | `heygen-avatar-6` or `heygen-avatar-6-turbo` |
| `engine.reference_look_id` | Optional. A digital-twin look in the same avatar group whose recorded footage drives the motion. It must be accessible to your workspace, have completed [consent](https://developers.heygen.com/docs/avatar-consent.md), and be eligible for Avatar 6. |
| `engine.motion_expressiveness` | `default` (also the omission default), or `less` for fewer, smaller gestures and calmer facial expressions. Does not disable motion. |
| `resolution` | `1080p` or `2k`. Omitted or `null` defaults to `1080p`; `720p` and `4k` are not supported. |
| `aspect_ratio` | `16:9` (default), `9:16`, `1:1`, `4:5`, `5:4`, or `auto`. Output sizes are below. |
| `motion_prompt` | Optional. Plain-language direction for gestures, expression and posture. Overrides `engine.motion_expressiveness` where specified. |
| `title` | Optional. Name of the video in your library |

The legacy top-level `expressiveness` field is not accepted for Avatar 6. Set `motion_expressiveness` inside `engine`.

When `engine.reference_look_id` is omitted, a video look uses its own footage and a photo look renders without a video reference. `aspect_ratio: "auto"` derives the output shape from the source; use an explicit aspect ratio below for predictable dimensions.

| `aspect_ratio` | `1080p` | `2k` |
| - | - | - |
| `16:9` | 1920 × 1080 | 2560 × 1440 |
| `9:16` | 1080 × 1920 | 1440 × 2560 |
| `1:1` | 1080 × 1080 | 1440 × 1440 |
| `4:5` | 1080 × 1350 | 1440 × 1800 |
| `5:4` | 1350 × 1080 | 1800 × 1440 |

### Check status

```bash theme={null}
curl "https://api.heygen.com/v3/videos/VIDEO_ID" \
  -H "x-api-key: $HEYGEN_API_KEY"
```

When `data.status` is `completed`, download the file from `data.video_url`. The link is signed, so poll again for a fresh one. A failed video carries `data.failure_code` and `data.failure_message`.


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