HeyGen 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. Clips run 5 to 30 seconds in all three modes with turbo or quality enhancement. Each clip has 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 behind POST /v3/videos. 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. To cast your own avatar looks in a HeyGen Video shot, use Cinematic Avatar with model: "heygen_video_1".

Build with it


Model identifier	`heygen-video-1`
Create	`POST /v3/models/videos`
Retrieve	`GET /v3/models/videos/{video_id}`
Examples	The launch films clip by clip, with the prompt behind every shot
Auth	`x-api-key` header, from the API keys page
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 with a video_id and status pending. 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} until the status reaches completed, failed or cancelled; jobs run to completion once submitted. The completed record carries video_url plus the resolved duration, width, height, aspect_ratio and seed. 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 an identical file, 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; the completed job reports the seed it used. Treat a seed as reproducible within a deployment rather than as a permanent handle on one render.

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 an HTTPS callback_url on the create request to be notified when a job finishes, and callback_id (up to 256 characters) to correlate the delivery. The job fires avatar_video.success or avatar_video.fail, with the payloads described in webhook events. 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). reference_to_video is the default and needs at least one reference image or video in reference_images or reference_videos (reference_audio is optional). image_to_video needs image. 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	15

Reference videos share a 15-second input budget across the request. When their combined duration fits, the model uses all the footage. Otherwise, each video keeps up to its first five seconds, and the remaining budget is shared equally among videos with footage left. Clips are trimmed from the start to their allocated length before generation.

Uploaded video lengths	Footage used from each video
15 seconds	15 seconds
10 + 10 seconds	7.5 + 7.5 seconds
3 + 10 + 10 seconds	3 + 6 + 6 seconds
2 + 4 + 20 seconds	2 + 4 + 9 seconds

Trim a clip before uploading if you want a later section used. Images and standalone audio do not consume this video budget. The output duration is separate from the reference-video budget. Submission and polling responses report the total reference-video seconds allocated for billing as input_video_duration; it is 0 when there are no video references. For example, two 10-second videos report 15, while videos of 3, 4, and 6 seconds report 13. 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 trades speed for quality: turbo is fastest, quality (default) balances the two, ultraquality is slowest and best. Use disabled when you have already written a long, fully specified prompt and want it followed word for word.

Parameters

The full field list is in the API reference. The schema is strict: unknown fields are rejected rather than ignored. prompt takes up to 32,000 characters, resolution defaults to 768p (1080p and 2k bill at 3× the 768p rate), and seed is an unsigned 32-bit integer.

Duration limits

Use the same heygen-video-1 model and POST /v3/models/videos endpoint for short and long clips. Set duration to a whole number of seconds; no extra mode or flag is required. Omitting duration still selects 5 seconds.

Request settings	Explicit duration	`auto` range
`text_to_video` or `image_to_video`, with `turbo` or `quality`	5–30 seconds	8–30 seconds
`reference_to_video`, with `turbo` or `quality`	5–30 seconds	8–15 seconds
`ultraquality` or `disabled` enhancement, any mode	5–15 seconds	8–15 seconds
HeyGen Video through MCP, on any plan	5–30 seconds, with `turbo` or `quality`	8–15 seconds

Long clips support 480p, 768p, 1080p, and 2k, with the existing aspect-ratio rules. Omitted prompt_enhancement selects quality. An explicit duration above the limit for your settings is rejected rather than shortened. A 30-second clip is still one job and one final video through the same polling or webhook flow.

Auto duration

Set duration to auto to estimate the clip length from quoted dialogue. The API counts words inside straight or curly double quotes, estimates 2.5 words per second, adds one second of lead-in, and rounds up to a whole second. It then applies an 8-second minimum and the maximum in the table above. For example, 60 quoted words select 25 seconds for a compatible text-to-video or image-to-video request. The same dialogue selects at most 15 seconds for reference_to_video, ultraquality or disabled enhancement, or MCP. A prompt without quoted dialogue selects 8 seconds. Auto duration is an estimate; use an explicit duration when you need to choose the length yourself. The completed job reports the length it picked as duration, and billing uses that length.

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`	`2k`	`1080p`	`768p`	`480p`
`21:9`			1536 × 672	960 × 416
`16:9`	2688 × 1536	1890 × 1080	1344 × 768	832 × 480
`4:3`			1024 × 768	640 × 480
`1:1`			768 × 768	480 × 480
`3:4`			768 × 1024	480 × 640
`9:16`	1536 × 2688	1080 × 1890	768 × 1344	480 × 832

1080p and 2k render in 16:9 or 9:16. Set aspect_ratio to one of them for text_to_video and reference_to_video, since adaptive resolves at 480p and 768p only. image_to_video follows the first frame at every resolution.

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.

Errors

Validation errors use code invalid_parameter and set param to the field; see error codes. Insufficient credits return 400. This route runs on 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.

Get started

Video

Avatar

Voice

Audio

Image

Decision

Video editing

Brand

Platform

Build with it

Generate a video

Retrieve the result

What it is good at

Scenes that hold together

Doing what you asked

Picture and sound together

Holding an object you supply

How to prompt it

The rules worth knowing

Twelve styles

Lettering in the shot

Callbacks

Modes

References and prompt labels

Prompt enhancement

Parameters

Duration limits

Auto duration

Output

Default aspect ratio

Errors

Get an API key

HeyGen Avatar