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.

Cinematic Avatar is a prompt-driven variant of POST /v3/videos. 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, our own video model, with model: "heygen_video_1".

Prerequisites

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.

A prompt describing the scene, action, and framing. This replaces the script + voice_id you’d use for a Digital Twin video.

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 for the rules that change the output.

Step 2 — Pick your avatar looks

Pass avatar_id as an array of 1–3 look IDs. 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:

curl -X GET "https://api.heygen.com/v3/avatars/looks?ownership=private" \
  -H "x-api-key: YOUR_API_KEY"

Copy the id of each look you want into the array.

Step 3 — Create the video

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

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 shape as any other /v3/videos job:

{
  "data": {
    "video_id": "abc123",
    "status": "pending",
    "output_format": "mp4"
  }
}

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:

{
  "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" }
  ]
}

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. Upload your own files first with Assets to get an asset_id.

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} until status is completed:

curl -X GET "https://api.heygen.com/v3/videos/YOUR_VIDEO_ID" \
  -H "x-api-key: YOUR_API_KEY"

Status	Meaning
pending	Queued for processing
processing	Video is being generated
completed	Ready — video_url is available
failed	Something went wrong — check failure_message

Full example

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# 1. Create the Cinematic Avatar video
resp = requests.post(f"{BASE}/v3/videos", headers=HEADERS, json={
    "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,
})
video_id = resp.json()["data"]["video_id"]
print(f"Video created: {video_id}")

# 2. Poll until done
while True:
    status_resp = requests.get(f"{BASE}/v3/videos/{video_id}", headers=HEADERS)
    data = status_resp.json()["data"]
    print(f"Status: {data['status']}")
    if data["status"] == "completed":
        print(f"Download: {data['video_url']}")
        break
    elif data["status"] == "failed":
        print(f"Error: {data.get('failure_message')}")
        break
    time.sleep(10)

Parameters

Parameter	Type	Required	Description
type	string	Yes	Must be "cinematic_avatar"
prompt	string	Yes	1–10,000 characters describing the shot
avatar_id	array	Yes	1–3 avatar look IDs
model	string	No	heygen_video_1 for HeyGen Video, or seedance_2. Omitting model renders with seedance_2. See Choose a model
references	array	No	Videos, images, and audio as url, asset_id, or base64 inputs, sharing the budget with avatar_id
aspect_ratio	string	No	16:9 (default) or 9:16. seedance_2 also renders 1:1
resolution	string	No	720p (default). seedance_2 also renders 1080p
duration	integer	No	5–15 seconds (4–15 with seedance_2), default 10. Omit when auto_duration is true
auto_duration	boolean	No	Renders the 10-second default with either model. Default false
enhance_prompt	boolean	No	Auto-expand a short prompt into a richer description. Default false
title	string	No	Display name in the HeyGen dashboard

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.