HeyGen Image to Video is HeyGen's image-to-video model on Versely. This page is its structured prompting reference: the 7 parameters its schema actually exposes, the i2v technique that applies to it, copy-ready templates.
Everything here is grounded in the same sources Versely's agent reads — the model's input schema. Where a line is general craft advice rather than a documented fact about HeyGen Image to Video, the page says so.
What HeyGen Image to Video wants
The exact input surface, from the same schema the Versely agent fetches with get_model_input_schema before every generation.
| Parameter | What it does | Values |
|---|---|---|
image_urlreq | Avatar source image (REQUIRED) | string |
prompt | Text to speak (optional per docs) | string |
voice | Name of voice to use (fal field is `voice` not `voice_id`) | string |
audio_url | When provided, overrides prompt and voice | string |
talking_style | Talking style | stable · expressivedefault: stable |
aspect_ratio | Aspect ratio | 16:9 · 9:16 · 1:1default: 16:9 |
resolution | Resolution (5 tiers per docs) | 360p · 480p · 540p · 720p · 1080pdefault: 720p |
- — Verified against fal.ai/models/fal-ai/heygen/avatar4/image-to-video — only `image_url` is required; field is `voice` not `voice_id`; `output_language` not in docs
Technique that applies here
Image-to-video: animating a start frame; motion description relative to the input image; UGC hook pool applies
- Aspect ratio usually isn't a settable parameter in image-to-video mode — it's inherited from your source image. Vidu Q3's runpod schema note is explicit: 'No style/aspect_ratio fields in I2V — aspect ratio is inferred from the input image.' Pixverse 5.6 I2V's note says the same thing: 'I2V infers aspect_ratio from image (no aspect_ratio field).' Wan's i2v schemas (2.7, and the folded Wan 2.5 variants) all omit an aspect_ratio param entirely; two of its provider variants confirm this directly in their own schema notes — kie's says 'inferred from image', replicate's says 'aspect is derived from the input image.' Crop or compose your source image to the aspect you want before you upload it; asking for '16:9 widescreen' in the prompt text does nothing on these schemas.
- The prompt describes motion relative to what the image already shows, not the scene itself. Vidu's own param description for its i2v prompt field is literally 'Text description of the desired motion and action' — contrast a text-to-video prompt, which has to establish the whole scene from nothing. General craft, not a schema fact: name what changes — a hand reaches, a head turns, hair moves in wind — rather than re-describing the subject or setting the photo has already fixed, which just competes with the image for the model's attention instead of directing it.
- Not every 'image-to-video' model takes the same kind of prompt. HeyGen's i2v schema is a talking-avatar generator — voice, audio_url and a talking_style enum ('stable'/'expressive') carry the performance, and prompt itself isn't even required (only image_url is). Hailuo 2.3's i2v is the opposite: motion-description-only, no audio output at all, and no text-to-video sibling to fall back on ('NO T2V variant exists on KIE for Hailuo 2.3', per its own schema note). Check which flavor of 'i2v' you're actually on before assuming a generic motion prompt applies.
Copy-ready templates
Replace the bracketed slots; each template says when it's the right shape.
[WHAT MOVES — e.g. 'she turns her head toward camera and smiles'], [SECONDARY MOTION DETAIL — e.g. 'hair drifts in a light breeze']. Camera: [static / slow push-in / slight handheld].
Use when: i2v models whose schema infers aspect ratio from the source image (Vidu, Pixverse, Wan) — crop the source image to your target aspect first, then spend the whole prompt on motion, not framing.
Voice: [VOICE NAME/ID]. Talking style: [stable / expressive]. Prompt (optional): [background or action direction beyond the talking delivery].
Use when: HeyGen-style avatar i2v models, where voice and talking_style carry the performance and the free-text prompt is optional rather than the primary control.
How the Versely agent does this automatically
You can use this page by hand, or let the agent apply the same knowledge. Four real mechanisms — no more, no less:
get_model_input_schema— before generating, the agent looks up HeyGen Image to Video's exact input fields, required fields, allowed values, defaults, and min/max bounds. The parameter table above is that same surface.- The prompt enhancer's family rules — 12 per-family rewrite rules (this model's family isn't one of the 12, so only general enhancement applies) shape how a rough prompt gets rewritten.
- The per-provider speech guide — for TTS scripts, the agent follows a provider-specific tag scheme — not relevant to this model, but it's why voiceover scripts come out marked up correctly.
expand_movie_scene— in movie flows, brief scene ideas are rewritten into detailed cinematic descriptions before generation.
Mistakes that waste generations
- Asking for a specific aspect ratio in the prompt when the schema doesn't expose an aspect_ratio param — it's silently ignored; on Vidu, Pixverse, and Wan's i2v variants the frame shape comes entirely from the source image you upload.
- Re-describing the subject or scene the source image already shows instead of focusing on the motion — wastes prompt budget and can conflict with the photo (a different outfit or background than what's actually in frame).
- Treating every 'image-to-video' model as the same shape: sending a HeyGen-style voice/talking_style prompt to Vidu, or a plain motion-description prompt to HeyGen, targets a control surface that model doesn't expose.
Frequently asked questions
Does HeyGen Image to Video support negative prompts?+
No — HeyGen Image to Video's published schema has no negative_prompt parameter. Exclusions have to be phrased positively inside the main prompt, or dropped.
Which aspect ratios does HeyGen Image to Video support?+
The aspect_ratio parameter is an enum: 16:9, 9:16, 1:1. Set the parameter — describing the frame shape in prose does nothing on its own.
How does the Versely agent know HeyGen Image to Video's parameters?+
Before generating, the agent calls its get_model_input_schema tool, which looks up the exact input fields, required fields, allowed values, defaults, and min/max bounds for the model. Nothing on this page is guessed — it is the same schema surface those tools read.
Related prompting guides
Generate with HeyGen Image to Video
HeyGen Image to Video is live in Versely — paste a template above, or just describe what you want and let the agent map it onto the schema for you.