> ## 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.

# Cinematic Avatar

> Generate cinematic avatar video from a single prompt with the HeyGen API. Combine up to three avatar looks with reference videos and images — no script or voice required.

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

Cinematic Avatar is a prompt-driven variant of [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video). Instead of a script and a voice, you describe the shot you want in natural language and hand HeyGen up to three avatar looks (plus optional reference media). HeyGen composes the scene, motion, framing, and sound, rendered by [HeyGen Video](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md), our own video model, with `model: "heygen_video_1"`.

## Prerequisites

> [!TIP]
>
> One to three avatar look IDs. Use `GET /v3/avatars/looks` to browse your looks and copy the `id` field for each one you want in the shot.

> [!TIP]
>
> A prompt describing the scene, action, and framing. This replaces the `script` + `voice_id` you'd use for a [Digital Twin video](https://heygen-1fa696a7.mintlify.site/generate-avatar-video.md).

## Step 1 — Write your prompt

The `prompt` (1–10,000 characters) is the creative brief for the shot. Describe the setting, the camera and lens, the light, what the avatar does in order, any line they say in quotes, and the sound. For example: *"The avatar walks through a sunlit startup office, stops at a whiteboard, turns to camera and says: 'We built this for the people who ship.' Handheld, 35mm at f/2.8. Soft room tone, no music."* See [How to prompt HeyGen Video](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md#how-to-prompt-it) for the rules that change the output.

## Step 2 — Pick your avatar looks

Pass `avatar_id` as an **array** of 1–3 look IDs from `GET /v3/avatars/looks?ownership=private`. Multiple looks let HeyGen feature more than one avatar in the same shot, and each look's linked voice comes along as that character's voice.

## Step 3 — Create the video

Send a `POST` to `/v3/videos` with `type: "cinematic_avatar"` and `model: "heygen_video_1"`:

```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": "cinematic_avatar",
    "model": "heygen_video_1",
    "prompt": "The avatar walks through a sunlit startup office, stops at a whiteboard, turns to camera and says: \"We built this for the people who ship.\" Handheld, 35mm at f/2.8. Soft room tone, no music.",
    "avatar_id": ["YOUR_LOOK_ID"],
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 10,
    "title": "Founder office walkthrough"
  }'
```

The response is the same `video_id` shape as any other `/v3/videos` job. Defaults are `16:9`, `720p`, and 10 seconds; omit `duration` when `auto_duration` is `true`, and set `enhance_prompt: true` to expand a short prompt into a richer description. The [Create Video reference](https://heygen-1fa696a7.mintlify.site/reference/create-video.md) has the full schema.

### Choose a model

| | HeyGen Video | Seedance 2 |
| - | - | - |
| `model` | `"heygen_video_1"` | `"seedance_2"`, or omit `model` |
| `aspect_ratio` | `16:9`, `9:16` | `16:9`, `9:16`, `1:1` |
| `resolution` | `720p` | `720p`, `1080p` |
| `duration` | 5–15 seconds | 4–15 seconds |
| `auto_duration: true` | Renders 10 seconds | Renders 10 seconds |
| References | Up to 3 videos, 9 images, and 3 audio clips; 12 in total, avatars and their voices included | Up to 3 videos and 9 images, avatars included, plus any number of audio clips |

The response, polling, and webhooks are the same for both models.

### Adding reference media

Use `references` to steer style, motion, composition, or sound with your own videos, images, and audio. Each reference is a `url`, `asset_id`, or `base64` asset input:

```json theme={null}
{
  "type": "cinematic_avatar",
  "model": "heygen_video_1",
  "prompt": "Match the lighting and camera movement of the reference clip.",
  "avatar_id": ["YOUR_LOOK_ID"],
  "references": [
    { "type": "url", "url": "https://your-cdn.com/reference-clip.mp4" },
    { "type": "asset_id", "asset_id": "YOUR_UPLOADED_ASSET_ID" }
  ]
}
```

> [!NOTE]
>
> Avatar looks and references share a combined media budget across `avatar_id` and `references`. With HeyGen Video that is **3 videos, 9 images, and 3 audio clips, 12 in total**; reference videos share a 15-second budget, each avatar look with a video counts 3 seconds of it, and each `asset_id` goes in once. See [References and prompt labels](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md#references-and-prompt-labels). Upload your own files first with [Assets](https://heygen-1fa696a7.mintlify.site/assets.md) to get an `asset_id`.

> [!TIP]
>
> With more than one look, refer to each avatar by its look name and set `enhance_prompt: true` so HeyGen ties every name to the right reference.

## Step 4 — 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`.

## Using webhooks instead of polling

Cinematic Avatar does not accept `callback_url` (the request returns `400`). To be notified when the job finishes, register an endpoint via `POST /v3/webhooks/endpoints` and subscribe to `avatar_video.success` and `avatar_video.fail` as covered in [Webhooks](https://heygen-1fa696a7.mintlify.site/docs/webhooks.md).


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