> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Video 1 > HeyGen Video 1 generates a whole scene from a prompt: subject, setting and sound together, in one call. See what it makes, and how to prompt it. **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](/models). 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. export const HERO = [{ "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0da80-3a9f-76b1-ac56-97dba6afb043.mp4", "poster": "https://resource2.heygen.ai/image/8e021180172a41c6b6e6f71b84791d5d/original.jpg", "label": "Asking for texture, then forbidding the fix", "teaches": "Skin reads as skin only if you rule out the correction", "prompt": "A 74-year-old fisherman looks into the lens on a cold morning. Skin shows real texture: deep pores, broken capillaries, sun damage, white stubble, a wet sheen from the spray. No retouching, no beauty filter, no glamour lighting. Overcast daylight, 50mm at f/2.0, ISO 800 grain. He says nothing." }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0da80-36bc-7e6d-95cb-4857a5c86351.mp4", "poster": "https://resource2.heygen.ai/image/b20d2240f6e645ba9077a9097b6aba41/original.jpg", "label": "Naming the lens does the work", "teaches": "Camera language beats adjectives", "prompt": "A 61-year-old luthier holds a half-finished violin up to a workshop window, turning it slowly to read the grain. Shot on an ARRI Alexa Mini, 85mm at T2.0, one north-facing window as the only light, fine film grain, 24 fps. Shallow focus falls off behind his hands. Muted true-to-life colour, no teal-orange grade." }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0da80-4264-728a-8131-6529759ecd9a.mp4", "poster": "https://resource2.heygen.ai/image/c04ff9e0d77a40beb9dd32f782f2023f/original.jpg", "label": "Dialogue is written, not implied", "teaches": "Around 2.5 words per second fits the duration", "prompt": "A night-shift radio operator at a remote weather station speaks one line into a desk microphone, then waits. She says: \"Station four, we have you. Give us your position and hold there.\" Static camera, 40mm at f/2.0, green instrument light and one desk lamp. Audio: tape hiss, a carrier tone, wind on the mast outside." }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0da80-3ea0-78b7-885d-f9656eb059f4.mp4", "poster": "https://resource2.heygen.ai/image/0474610c50f448db8e2ec8219d03b3e4/original.jpg", "label": "Stillness reads as production value", "teaches": "A locked camera and one small movement", "prompt": "A pastry chef pipes a single line of cream along a tart shell, then stops. Static camera on a tripod, 60mm macro at f/4, overhead softbox, stainless bench. Her hands are the only thing that moves. Muted colour, no beauty filter." }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0da80-3ad6-73e3-8ccb-d1e945d3b1d6.mp4", "poster": "https://resource2.heygen.ai/image/d7277267c62f442abcdb5135dfdcff6e/original.jpg", "label": "The audio comes from the same prompt", "teaches": "Name the room, the effects and the distance", "prompt": "A thunderstorm reaches a suburban porch at night. Audio: heavy rain on a tin awning, water running in a gutter, distant rolling thunder, one close crack with a sharp slap and a long tail, crickets stopping after it. No music. Static camera, 35mm at f/2.0, practical porch light only." }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0da80-3ed7-78ff-b6b3-929e579ebe8b.mp4", "poster": "https://resource2.heygen.ai/image/fcfbe7cdf9ca472ca34dbcfa243052ac/original.jpg", "label": "Naming a real medium, not a vibe", "teaches": "Say what makes the image, and what it must not do", "prompt": "A cyanotype blueprint of a pocket watch, animated. Deep Prussian blue ground, the drawing in exposed white line only, uneven hand coating with brush marks at the edges, small bleached patches where the wash pooled. The movement exploded outward, then rotating a quarter turn. No photography, no gradients, no lettering." }]; export const STYLES = [{ "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca25-b82a-72e1-abe4-552f4539a063.mp4", "poster": "https://resource2.heygen.ai/image/3046245e9c324d72ab2358be6f6d8c32/original.jpg", "label": "Risograph two-colour print", "note": "Internal comms and culture films that should not look corporate" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca25-bc4c-760c-8c7f-39a3bb7171ea.mp4", "poster": "https://resource2.heygen.ai/image/7abec2b0c31b427f92ada1c722bcb8d0/original.jpg", "label": "Sumi-e ink wash on washi", "note": "Spa, ryokan and wellness brands where stillness is the product" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca25-c3e3-7854-8127-8f9375df1eff.mp4", "poster": "https://resource2.heygen.ai/image/16ff838ea68648da84a17d5d9ab755aa/original.jpg", "label": "Scratchboard engraving", "note": "Firms whose whole brand is sobriety and permanence" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-7659-7c46-8e34-e6d6ef3da331.mp4", "poster": "https://resource2.heygen.ai/image/6dab3b8ec02746b7b1097a70cb459934/original.jpg", "label": "Plasticine stop-motion", "note": "Explaining a procedure to a frightened child or their parent" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-7659-72d7-8b94-d29dcf7de1bb.mp4", "poster": "https://resource2.heygen.ai/image/fa8f90227cf946acbc35eb1c096d5a28/original.jpg", "label": "Cyanotype blueprint", "note": "Machine explainers where the drawing is more honest than a photo" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-79bf-7066-b7fb-d5424ba3334d.mp4", "poster": "https://resource2.heygen.ai/image/5b013895fb2e487dae3a82e4b4a0ddac/original.jpg", "label": "Anatomical plate illustration", "note": "Mechanism of action, where there is nothing to point a camera at" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-7d9f-79dd-a46b-f0b63681418e.mp4", "poster": "https://resource2.heygen.ai/image/9b866c95348945babba15ec6d0677712/original.jpg", "label": "Mid-century screen-printed public information film", "note": "Safety messaging that borrows civic authority instead of brand polish" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-7db8-7193-92c0-298f45ab9557.mp4", "poster": "https://resource2.heygen.ai/image/ff129b0cc1884b74a9b19f4d21a46f4b/original.jpg", "label": "Isometric technical cutaway", "note": "Showing how a building works when the building does not exist yet" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-81af-7f23-86c7-de6cd50a6fcf.mp4", "poster": "https://resource2.heygen.ai/image/f1b46aa186324e8fb005638255499b02/original.jpg", "label": "16-bit console pixel art", "note": "Safety and onboarding modules that new hires will actually finish" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-818f-7864-a57f-0be91242427c.mp4", "poster": "https://resource2.heygen.ai/image/6ff85b5bc3874414a7b3de5fcb2bff39/original.jpg", "label": "1980s institutional VHS training film", "note": "Compliance content that admits what it is and is watched because of it" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-818f-7f36-8b52-8bb48aab93fe.mp4", "poster": "https://resource2.heygen.ai/image/3b38e76a9b47463386b64ac58053d889/original.jpg", "label": "Ukiyo-e woodblock print", "note": "Travel and heritage brands that want craft rather than filters" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-81c3-7cea-b608-f60c96d55564.mp4", "poster": "https://resource2.heygen.ai/image/839e3b7dd97045258f80fea708c5ab31/original.jpg", "label": "Rotoscoped ink over live action", "note": "Claims and legal stories where a real person must stay unidentifiable" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-817b-7688-abfb-c018396f3d48.mp4", "poster": "https://resource2.heygen.ai/image/8b4bbea33ed74d119d401049f35a6339/original.jpg", "label": "Cut-paper silhouette animation", "note": "Paediatric storytelling and consent explained to a child" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-85a0-7cde-a402-5e3df671f1f4.mp4", "poster": "https://resource2.heygen.ai/image/4d3061b28b79405ca4b28790bcecd4dd/original.jpg", "label": "Thermal infrared imaging", "note": "Energy, maintenance and building-survey findings that a photo cannot show" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-8592-7787-a071-c78ea19d73a1.mp4", "poster": "https://resource2.heygen.ai/image/6e3ad595f48947f8a8db1181eaa1b577/original.jpg", "label": "Wet-plate collodion tintype", "note": "Heritage, estates and institutions selling permanence" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-8959-75d1-919c-74a4a1f81fca.mp4", "poster": "https://resource2.heygen.ai/image/f6fa59dc6de84a3aa27ad8a633e3e978/original.jpg", "label": "Photocopy degradation zine", "note": "Recruitment and culture pieces aimed at people who distrust polish" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-9580-7404-8b7d-a635a870f48c.mp4", "poster": "https://resource2.heygen.ai/image/4bd2c07466de43bc840778cebf16614f/original.jpg", "label": "1970s Kodachrome documentary", "note": "Heritage and archive-flavoured brand films" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-9542-7746-90d6-c74b32516fea.mp4", "poster": "https://resource2.heygen.ai/image/3b1e51e6a11a4ae6bf390cdb20f95392/original.jpg", "label": "Oscilloscope vector phosphor", "note": "Security, telemetry and systems stories that should feel instrumented" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-98ed-7692-88aa-49dcc7463143.mp4", "poster": "https://resource2.heygen.ai/image/f6fffc69cdf24836aab6934fc3ec2dcc/original.jpg", "label": "Chalk on blackboard", "note": "Teaching content where the drawing should appear as it is explained" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca27-9cea-72b8-aaab-ed034145a10e.mp4", "poster": "https://resource2.heygen.ai/image/13956b09c59f4f8ea80ae356bc0a77d6/original.jpg", "label": "Embroidered textile stitch", "note": "Craft, artisan and interiors brands where texture is the product" }]; export const BRANDS = [{ "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca86-0e59-70bc-b16e-d2329a606ea9.mp4", "poster": "https://resource2.heygen.ai/image/c73b1a4afaa94330b4dcc28c707a1313/original.jpg", "label": "KELVA", "note": "Cold-chain logistics" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca86-1a16-7cdd-8d52-fe103a959bde.mp4", "poster": "https://resource2.heygen.ai/image/880cca76b04e47548fed507b037da650/original.jpg", "label": "ORRIN", "note": "Legal" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca86-21f7-7692-a6f9-d782fdab93b9.mp4", "poster": "https://resource2.heygen.ai/image/936e393252f94cfd9dd863d9593e5c37/original.jpg", "label": "NUVEX", "note": "Pharma" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca86-25c9-77cd-9831-d4c454a637a9.mp4", "poster": "https://resource2.heygen.ai/image/c5e9d8565d7f4cb58ff139fa5050e6d5/original.jpg", "label": "VESTRA", "note": "Insurance" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca86-2da5-79aa-9cf8-24e17406fccc.mp4", "poster": "https://resource2.heygen.ai/image/32dd8d743dd04c448f1891f957dae1ee/original.jpg", "label": "QUELL", "note": "Medical devices" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca86-356b-7801-8205-55eef310c645.mp4", "poster": "https://resource2.heygen.ai/image/aac92471742f47c5a65fc96354172215/original.jpg", "label": "ALTIRA", "note": "Hospitality" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca86-3d46-73e6-a1e0-d090e92b1edd.mp4", "poster": "https://resource2.heygen.ai/image/d5fa46419eb64bf8b6c08249b87b043d/original.jpg", "label": "SABLE", "note": "Private wealth" }, { "src": "https://resource2.heygen.ai/videos/66c20e44a62c40a58cf8c51210dab761/66c20e44a62c40a58cf8c51210dab761/01a0ca86-4516-7b44-8de7-0630c4913e2b.mp4", "poster": "https://resource2.heygen.ai/image/23fa1c5fa1de4a3ebff63aca0dc1a046/original.jpg", "label": "FARROW", "note": "Industrial manufacturing" }]; export const Grid = ({items, cols = 3, showPrompt = false}) =>
{items.map(v =>
{v.label} {v.note && {v.note}} {showPrompt && v.prompt && {v.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. Objects stay the same size and shape, stay where they were put, and obey physics. Things do not duplicate, vanish or reappear mid-shot. It follows a brief literally rather than improvising. If you did not ask for dialogue, you do not get dialogue. Room tone, effects and speech are generated with the image from the same prompt, so they match the space you described. 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 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. 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`. Plain clothing and equipment will otherwise pick up invented branding. Add `no logos, brand names, printed words or badges anywhere in 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. 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. 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. 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. 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](https://app.heygen.com/developers/api) | | Scopes | `videos:write` to create, `videos:read` to retrieve, `assets:write` to upload references | ### Generate a video ```bash theme={null} 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`: ```json theme={null} { "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`. ```bash theme={null} curl https://api.heygen.com/v3/models/videos/VIDEO_ID \ -H "x-api-key: $HEYGEN_API_KEY" ``` ```json theme={null} { "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. ```json theme={null} { "model": "heygen-video-1", "mode": "reference_to_video", "prompt": "A supervisor wearing the harness in 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 ``, the second is ``, the first entry of `reference_videos` is `