Video 1 - HeyGen Documentation

HeyGen Video 1 generates the whole frame. Give it a prompt and it returns a clip of 5 to 15 seconds with its own audio track: dialogue, ambience and sound effects, synthesized in the same call. No separate speech pass, no lip-sync step, no avatar to pick. 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.

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 legible 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 each show the prompt that produced them.

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, 85mm at T2.0, one north-facing window as the only light 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 out of frame

One short capitalized word renders reliably. Longer strings, multi-word titles and labelled diagrams come back as plausible-looking gibberish. Suppress lettering in the prompt and composite real type 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.

Twenty styles

Style is a prompt variable. The reliable way to get a real one is to name an actual production process and the physical marks it leaves, restrict the palette, and rule out the smooth digital default.

Brand moments

A five-second identity piece, rendered in a medium chosen for the sector rather than a generic logo spin. Short single-word marks render reliably, which is what makes these work. A full lockup with a tagline still needs type added afterwards.

The brands below are invented for this page. Any resemblance to a real company is coincidental.

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.

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.

​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

​Twenty styles

​Brand moments

​Build with it

​Generate a video

​Retrieve the result

​Callbacks

​Modes

​References and prompt labels

​Prompt enhancement

​Parameters

​Output

​Default aspect ratio

​Seeds

​Errors

​Specs at a glance

Get an API key

HeyGen Avatar

What it is good at

How to prompt it

The rules worth knowing

Twenty styles

Brand moments

Build with it

Generate a video

Retrieve the result

Callbacks

Modes

References and prompt labels

Prompt enhancement

Parameters

Output

Default aspect ratio

Seeds

Errors

Specs at a glance