HeyGen Video

HeyGen Video, built on MiniMax H3 and post-trained by HeyGen, generates a whole scene from a prompt: subject, setting and sound together, in one call. Text to video, image to video and reference to video.

HeyGen Video is our general-purpose video model, built on MiniMax H3 and post-trained by HeyGen. Give it a prompt and it generates the whole scene: subject, setting, light and sound together, in one call. Each clip runs 5 to 15 seconds with its own audio track of dialogue, ambience and sound effects, so there is no separate speech pass, lip-sync step or avatar to pick.

One model, heygen-video-1, called in three ways:

Mode	You give it	You get
Text to video (text_to_video)	A prompt	A new scene with its sound
Image to video (image_to_video)	A prompt and one image	A clip that opens on your image as its first frame
Reference to video (reference_to_video)	A prompt and your images, videos or audio	A new scene that keeps the products, people or places you supplied

It is a different tool from the avatar rendering engines. Those animate a look you already own from a script you already wrote. This one invents the subject, the setting, the light and the sound at once, from a description. The rest of this page starts with the call itself, then what the model is good at and how to prompt it, then the full API reference.

Build with it

Model identifier	heygen-video-1
Create	POST /v3/models/videos
Retrieve	GET /v3/models/videos/{video_id}
Auth	x-api-key header, from your API settings
Scopes	videos:write to create, videos:read to retrieve, assets:write to upload references

Generate a video

curl -X POST https://api.heygen.com/v3/models/videos \
  -H "x-api-key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-video-1",
    "mode": "text_to_video",
    "prompt": "A plant supervisor in a plain grey coat stands beside a conveyor line and speaks to camera.",
    "duration": 5,
    "resolution": "768p",
    "aspect_ratio": "16:9",
    "seed": 42
  }'

Submission returns 202:

{ "data": { "status": "pending", "video_id": "VIDEO_ID" } }

Send an Idempotency-Key header to retry safely: a retry with the same key within 24 hours returns the original response, and a concurrent duplicate returns 409.

Retrieve the result

Poll GET /v3/models/videos/{video_id}. pending means queued and processing means running. The terminal states are completed, failed and cancelled.

curl https://api.heygen.com/v3/models/videos/VIDEO_ID \
  -H "x-api-key: $HEYGEN_API_KEY"

{
  "data": {
    "video_id": "VIDEO_ID",
    "status": "completed",
    "model": "heygen-video-1",
    "created_at": 1789689600,
    "video_url": "https://resource2.heygen.ai/videos/.../VIDEO.mp4",
    "duration": 5,
    "aspect_ratio": "16:9",
    "width": 1344,
    "height": 768,
    "seed": 42
  }
}

video_url is a signed link: poll again to refresh it. Failed and cancelled jobs carry failure_code (generation_failed or generation_cancelled) and failure_message. An unknown ID, or one from another workspace, returns 404.

The same job is also readable through GET /v3/videos/{video_id}, alongside your other videos, with video_page_url and a title taken from the first 64 characters of the prompt.

What it is good at

Sound on for everything below. Every clip on this page is raw model output, with the audio it generated.

Scenes that hold together

Objects stay the same size and shape, stay where they were put, and obey physics. Things do not duplicate, vanish or reappear mid-shot.

Doing what you asked

It follows a brief literally rather than improvising. If you did not ask for dialogue, you do not get dialogue.

Picture and sound together

Room tone, effects and speech are generated with the image from the same prompt, so they match the space you described.

Holding an object you supply

Give it a photograph in reference_to_video and the colour, form and markings of that object survive into the shot.

It is at its best on short, contained shots: one subject, one place, one action, a locked or barely moving camera. It is least reliable on long on-screen text, soft organic motion such as petals, paper and hair, and close hand work like assembling or operating equipment.

How to prompt it

Long prompts beat short ones. A few hundred to a few thousand characters gives materially better output, and there is no penalty for detail. The examples below are shots from the HeyGen Video launch film, each with the exact prompt that produced it. The last two use the sectioned layout the film was written in for its longer shots; it is plain text in the same prompt field.

The rules worth knowing

Name the camera, not the mood

A body, a lens and an aperture set depth of field, grain and motion together. “Cinematic” and “high quality” do almost nothing. Shot on an ARRI Alexa Mini LF, 50mm T2, locked off on a tripod changes the image.

Ask for texture, then forbid the correction

Describing pores and fine lines gets you part way. Adding no retouching, no beauty filter, no glamour lighting gets you the rest. Without the second clause, faces drift toward a retouched look. The same applies to colour: ask for muted colour, then rule out the default with no teal-orange grade.

Rule out marks you did not ask for

Plain clothing and equipment will otherwise pick up invented branding. Add no logos, brand names, printed words or badges anywhere in frame.

Keep lettering short and spelled out

A short capitalised phrase renders reliably when the prompt spells it exactly and names it as the only lettering in frame: The only lettering anywhere is the words NOT ANYMORE, spelled exactly NOT ANYMORE. Keep everything else free of text with the marks clause above. Paragraphs, small print and labelled diagrams read best as real type composited afterwards.

Prefer stillness to manipulation

A static camera with the subject wearing or holding an object is the most reliable composition available. Objects worn on the body render best of all. Close hand work degrades fastest: if a procedure needs explaining, let the speech carry the steps and keep the hands still.

Say where things touch

When an action involves one thing meeting another, name the contact point and say it holds. Without that, the gesture often lands near the target rather than on it.

Describe the sound

Audio comes from the same prompt, so direct it. Name the room tone, the specific effects and their distance. Say no music when you do not want a bed, because one may otherwise appear. Written dialogue fits at roughly 2.5 words per second.

Iterate with a fixed seed

Set seed yourself and the same prompt returns the same clip, so you can change one clause at a time. Omit it and the server picks a random one, so two identical requests give you different videos.

Twelve styles

Style is a prompt variable. The launch films shot the same driver close-up in four media, and took one drawing from pencil to oil paint to a clay model, each step an image_to_video shot that starts from the last frame of the one before. The reliable way to get a real style is to name an actual production process and the physical marks it leaves, restrict the palette, and rule out the smooth digital default.

Lettering in the shot

Every title in the launch films was generated inside the shot: painted on a wall, stamped in ink or pressed into paper. The painted track and the platform display under How to prompt it are two more. Short phrases, spelled out exactly, render reliably, which is what makes these work.

Each prompt spelled the phrase exactly and named it as the only lettering in frame. For longer copy, such as a full lockup with a tagline, add real type afterwards.

Callbacks

Pass callback_url on the create request to be notified when a job finishes, and callback_id to correlate the delivery.

callback_url	Must be an HTTPS URL
callback_id	At most 256 characters, returned with the delivery
Events	avatar_video.success and avatar_video.fail
Success payload	video_id, callback_id, url, video_page_url, video_share_page_url
Failure payload	video_id, callback_id, video_page_url, msg

Send callback_id alone to deliver to the webhook endpoints registered for your workspace. One event fires per job, at the terminal status, and a callback is attempted once. Treat it as a latency optimisation and keep polling as the fallback for anything you cannot afford to miss.

Modes

mode selects how the model is conditioned. Each mode has its own fields; a field from another mode returns 400 when it carries a value (an empty list or null passes).

Mode	Requires	Takes
text_to_video	prompt	the shared fields
image_to_video	prompt and image	image as the first frame
reference_to_video (default)	prompt and at least one reference image or video	reference_images, reference_videos, reference_audio

The short forms t2v, i2v and ref2va are accepted as aliases. New integrations should use the long names, which is what validation errors return.

image_to_video treats the supplied image as the literal first frame, so the clip opens exactly as that still looks. To place a product or piece of equipment into a scene of your own, use reference_to_video and describe the scene around it.

{
  "model": "heygen-video-1",
  "mode": "reference_to_video",
  "prompt": "A supervisor wearing the harness in <Picture 1> stands still and speaks to camera.",
  "reference_images": [{ "type": "asset_id", "asset_id": "ASSET_ID" }],
  "duration": 10
}

References and prompt labels

In reference_to_video, list order becomes the label you address in the prompt. The first entry of reference_images is <Picture 1>, the second is <Picture 2>, the first entry of reference_videos is <Video 1>, and so on. Images, videos and audio are numbered independently.

The API does not rewrite these labels. Prompt enhancement can reword the rest of the prompt; set it to disabled to keep your text as written.

List	Maximum
reference_images	9
reference_videos	3
reference_audio	3
Total across all three	12

Each reference accepts an HTTPS URL, an uploaded asset ID, or inline base64.

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

Input	Maximum size
Image by URL	16 MB
Video or audio by URL	32 MB
Image as base64	5 MB
Video or audio as base64	16 MB

URLs are fetched server side with SSRF checks and staged before dispatch. The fetcher does not follow redirects, so upload anything you do not control through POST /v3/assets and pass the returned asset_id.

curl -X POST https://api.heygen.com/v3/assets \
  -H "x-api-key: $HEYGEN_API_KEY" \
  -F "file=@harness.jpg"

Uploaded assets must belong to the calling workspace and are reusable across requests.

Prompt enhancement

Before generation, the prompt passes through an enhancement step that expands it for the model. prompt_enhancement picks how:

Value	Behaviour
turbo (default)	Fast enhancement pass
quality	More thorough enhancement pass
disabled	The prompt goes to the model exactly as you wrote it

{
  "model": "heygen-video-1",
  "mode": "text_to_video",
  "prompt": "A pastry chef pipes a single line of cream along a tart shell, then stops.",
  "prompt_enhancement": "quality"
}

Use disabled when you have already written a long, fully specified prompt and want it followed word for word.

Parameters

Field	Type	Default	Notes
model	string	required	heygen-video-1
mode	enum	reference_to_video	text_to_video, image_to_video, reference_to_video
prompt	string	required	1 to 32,000 characters
duration	integer	5	Any integer from 5 to 15 seconds
resolution	enum	768p	480p or 768p
prompt_enhancement	enum	turbo	turbo, quality or disabled
aspect_ratio	enum	see below	21:9, 16:9, 4:3, 1:1, 3:4 or 9:16, plus adaptive for reference_to_video. image_to_video follows the first frame.
seed	integer	random	Unsigned 32-bit. Random when omitted; set it yourself to iterate on a shot.
callback_url	string		HTTPS only
callback_id	string		At most 256 characters
image	asset		image_to_video only, required there
reference_images	array	[]	reference_to_video only
reference_videos	array	[]	reference_to_video only
reference_audio	array	[]	reference_to_video only

The schema is strict: unknown fields are rejected rather than ignored.

Output

Container	MP4, H.264
Frame rate	24 fps, rounded up to the next whole frame: a 7-second request encodes 175 frames
Audio	AAC, 32 kHz stereo, generated dialogue and effects
Delivery	HTTPS URL on the job record

resolution names a size class and aspect_ratio sets the shape. When you set aspect_ratio explicitly, the two resolve to a fixed pixel size:

aspect_ratio	768p	480p
21:9	1536 × 672	960 × 416
16:9	1344 × 768	832 × 480
4:3	1024 × 768	640 × 480
1:1	768 × 768	480 × 480
3:4	768 × 1024	480 × 640
9:16	768 × 1344	480 × 832

Default aspect ratio

text_to_video has nothing to take a shape from and defaults to 16:9.

reference_to_video defaults to adaptive: the aspect ratio of the first reference image, or the first reference video when there are no images. Pass one of the six ratios to override it.

image_to_video always follows the first frame, including its EXIF orientation. To change the output shape, crop the image before uploading it.

In both adaptive cases the output follows the source ratio, scaled to the short edge of the resolution with each side rounded to a multiple of 32. A 1280 × 852 reference at 480p returns 736 × 480. The completed job reports the actual width and height, and aspect_ratio as the reduced pixel ratio, for example 23:15.

Seeds

Set seed yourself to make a shot repeatable: the same prompt and the same seed, submitted in succession, return an identical file. Hold the seed and change one clause at a time to iterate.

When seed is omitted the server picks a random one, so two identical requests return different videos. The completed job reports the seed it used as seed.

Treat a seed as reproducible within a deployment rather than as a permanent handle on one render.

Errors

Errors return {"error": {"code", "message", "param", "doc_url"}}. Validation errors use code invalid_parameter and set param to the field.

Situation	param	Message
Wrong model identifier	model	Must be heygen-video-1
Unknown mode	mode	mode must be one of: text_to_video, image_to_video, reference_to_video.
No references in reference_to_video	reference_images	Provide at least one reference image or video.
Reference list outside reference_to_video	the field sent	reference_images is only accepted with mode reference_to_video.
image_to_video without image	image	Field required
Duration out of range	duration	Input should be greater than or equal to 5
Unsupported aspect ratio	aspect_ratio	Lists the ratios the mode accepts
Non-HTTPS callback	callback_url	Value error, callback_url must be an HTTPS URL
Unfetchable reference URL	absent	Invalid URL in reference_image[0]: Could not download the file. Ensure the URL is publicly accessible.
Oversized inline reference	absent	Base64 file in reference_image[0] is too large (N bytes).
Unknown field	the field	Extra inputs are not permitted
Insufficient credits	absent	Returned as 400

This route runs on paid API keys.

Specs at a glance

Duration	5 to 15 seconds
Resolution	480p or 768p
Aspect ratio	Six ratios, plus adaptive for reference_to_video; image_to_video follows the first frame
Jobs	Run to completion once submitted
Callbacks	Delivered once; poll as the fallback
API keys	Paid API keys

Get an API key

Create a key and check your usage.

HeyGen Avatar

Animate a look you own from a script, with Avatar V, IV and III.