GET

/v1/schemas/fal/video/fal-ai/heygen/avatar4/image-to-video

Accept:

kind inputactivity videohash 0d379020…extracted Oct 9, 2026version currentsource upstream spec ↗

field	recorded source
schema	Source linked above. upstream-spec Source trace `c996528d83d44955130019d0f9452376ac86444c71a064d71eee3a80520d75fd` { "fetchedAt": 1791522002, "extractorVersion": "1", "verifiedAt": null }

Request body

11 properties · 1 required · 1 $defs

property	type	description	constraints
image_url*	string	URL of the image to animate. The image should contain a clear face.
expression	const	Facial expression	"happy" · nullable
prompt	string	The text the avatar will speak	nullable
enable_safety_checker	boolean	Authorized callers may set false to request relaxed screening.	default: true
talking_style	enum	Talking style - 'stable' for minimal movement, 'expressive' for more animation	stable \| expressive · default: "stable"
aspect_ratio	enum	Aspect ratio of the output video. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', and 'auto'. 'auto' preserves the source aspect ratio when HeyGen can read it, falling back to '16:9' otherwise.	16:9 \| 9:16 \| 4:5 \| 5:4 \| 1:1 \| auto · default: "16:9"
voice	enum	Name of the voice to use for the avatar	Warm Pro Narrator \| Chill Brian \| Ivy \| John Doe \| Monika Sogam \| Hope · +96 more
audio_url	string	URL of an audio file for the avatar to lip-sync to. When provided, overrides prompt and voice.	nullable
background	AvatarIVBackground	Background configuration
resolution	enum	Video resolution preset. Options: 360p, 480p, 540p, 720p, 1080p	360p \| 480p \| 540p \| 720p \| 1080p · default: "720p"
caption	boolean	Whether to add captions to the video	default: false

Types

1 $defs

AvatarIVBackgroundobject

type	enum	Type of background	color \| image \| video · default: "color"
value	string	Background value - hex color for 'color' type, URL for 'image' or 'video' type	default: "#FFFFFF"

Validate a payload

before you spend tokens

shell

$ curl -X POST https://modelschemas.com/v1/validate \
    -d '{"provider":"fal","endpointId":"fal-ai/heygen/avatar4/image-to-video","payload":{…}}'
→ {"valid": false, "errors": [{"path": "#", "keyword": "required", …}]}