Skip to main content
Avatar Shots 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). The Seedance pipeline composes the scene, motion, and framing for you.

​
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 what the avatar is doing, the setting, the camera, and the mood — e.g. “A founder walks through a sunlit startup office, gesturing toward a whiteboard, shot handheld in a documentary style.” See Writing Effective Video Prompts for guidance.

​
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: 
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: "avatar_shots": 
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar_shots",
    "prompt": "A founder walks through a sunlit startup office, gesturing toward a whiteboard, shot handheld in a documentary style.",
    "avatar_id": ["YOUR_LOOK_ID"],
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "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"
  }
}

​
Adding reference media

Use references to steer style, motion, or composition with your own videos and images. Each reference is a url, asset_id, or base64 asset input: 
{
  "type": "avatar_shots",
  "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: at most 3 videos and 9 images total across avatar_id and references. Upload your own files first with Assets to get an asset_id.

​
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"
StatusMeaning
pendingQueued for processing
processingVideo is being generated
completedReady — video_url is available
failedSomething 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 Avatar Shots video
resp = requests.post(f"{BASE}/v3/videos", headers=HEADERS, json={
    "type": "avatar_shots",
    "prompt": "A founder walks through a sunlit startup office, gesturing toward a whiteboard, shot handheld in a documentary style.",
    "avatar_id": ["YOUR_LOOK_ID"],
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "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

ParameterTypeRequiredDescription
typestringYesMust be "avatar_shots"
promptstringYes1–10,000 characters describing the shot
avatar_idarrayYes1–3 avatar look IDs
referencesarrayNoUp to 3 videos / 9 images (shared with avatar_id) as url, asset_id, or base64 inputs
aspect_ratiostringNo16:9 (default), 9:16, or 1:1
resolutionstringNo720p (default) or 1080p
durationintegerNo4–15 seconds, default 10. Omit when auto_duration is true
auto_durationbooleanNoLet HeyGen pick the duration. Default false
enhance_promptbooleanNoAuto-expand a short prompt into a richer description. Default false
titlestringNoDisplay name in the HeyGen dashboard

​
Using webhooks instead of polling

Pass a callback_url when creating the video and HeyGen will POST to it 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.