Skip to main content
POST
Create Avatar 6 Video

Authorizations

x-api-key
string
header
required

HeyGen API key. Obtain from your HeyGen dashboard.

Headers

Idempotency-Key
string

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Required string length: 1 - 255
Pattern: ^[A-Za-z0-9_\-:.]{1,255}$

Body

application/json
model
enum<string>
required

Avatar generation model.

Available options:
heygen-avatar-6,
heygen-avatar-6-turbo
audio
AssetUrl · object
required

Asset input via publicly accessible HTTPS URL.

reference_images
(AssetUrl · object | AssetId · object | AssetBase64 · object)[]

Up to one reference image.

Maximum array length: 1

Asset input via publicly accessible HTTPS URL.

reference_videos
(AssetUrl · object | AssetId · object | AssetBase64 · object)[]

Up to one reference video, at least 2 seconds long. A shorter video returns HTTP 400 (invalid_parameter) before a job is created.

Maximum array length: 1

Asset input via publicly accessible HTTPS URL.

resolution
enum<string>
default:1080p

Inference resolution. Defaults to 1080p.

Available options:
1080p,
2k
motion_prompt
string | null

Optional instructions for gestures, expression, posture, and camera behavior. Overrides motion_expressiveness where specified.

Required string length: 1 - 1200
motion_expressiveness
enum<string>
default:default

Use default for the model's usual motion, or less for fewer and smaller gestures and calmer facial expressions. Does not disable motion.

Available options:
default,
less
output_width
integer | null

Output width in pixels; supply with output_height, or omit both to use the native size.

Required range: x > 0Must be a multiple of 2
output_height
integer | null

Output height in pixels; supply with output_width, or omit both to use the native size.

Required range: x > 0Must be a multiple of 2
callback_url
string | null

HTTPS URL for terminal generation notifications.

callback_id
string | null

Client identifier echoed in terminal notifications.

Maximum string length: 256

Response

Accepted — submission acknowledged; poll for completion.

data
CreateModelAvatarResponse · object