GET
/v1/schemas/fal/video/fal-ai%2Fheygen%2Favatar4%2Fimage-to-video
Accept:
Request body
10 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. | |
| 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" |
| audio_url | string | URL of an audio file for the avatar to lip-sync to. When provided, overrides prompt and voice. | nullable |
| talking_style | enum | Talking style - 'stable' for minimal movement, 'expressive' for more animation | stable | expressive · default: "stable" |
| background | AvatarIVBackground | Background configuration | |
| resolution | enum | Video resolution preset. Options: 360p, 480p, 540p, 720p, 1080p | 360p | 480p | 540p | 720p | 1080p · default: "720p" |
| voice | enum | Name of the voice to use for the avatar | Warm Pro Narrator | Chill Brian | Ivy | John Doe | Monika Sogam | Hope · +96 more |
| expression | const | Facial expression | "happy" · nullable |
| prompt | string | The text the avatar will speak | nullable |
| caption | boolean | Whether to add captions to the video | default: false |
Validate a payload
before you spend tokensshell
$ 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", …}]}