GET

/v1/schemas/fal/video/fal-ai/heygen/avatar5/digital-twin

Accept:

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

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

Request body

13 properties · 0 required · 2 $defs

property	type	description	constraints
prompt	string	Text the avatar will speak. Required when ``audio_url`` is not provided.	nullable
watermark	AvatarVWatermark	Watermark configuration for Avatar V videos.	nullable
fit	enum	How the avatar fits within the output frame. 'contain' keeps the full avatar in view (may letterbox); 'cover' fills the frame (may crop).	contain \| cover · default: "cover"
enable_safety_checker	boolean	Authorized callers may set false to request relaxed screening.	default: true
remove_background	boolean	Remove the avatar's background. Requires a matting-enabled avatar.	default: false
background	AvatarVBackground	Background configuration for Avatar V videos.	nullable
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 text-to-speech voice to use for the avatar when ``audio_url`` is not provided.	Warm Pro Narrator \| Chill Brian \| Ivy \| John Doe \| Monika Sogam \| Hope · +96 more · default: "Warm Pro Narrator"
audio_url	string	HTTP(S) URL of an audio file for the avatar to lip-sync to. When provided, the avatar uses this audio instead of text-to-speech and ``prompt``/``voice`` are ignored.	nullable
avatar	string	Name of the Avatar V-eligible avatar to use.	nullable
resolution	enum	Output resolution preset.	720p \| 1080p \| 4k · default: "720p"
output_format	enum	Output container format. 'webm' produces a transparent video (automatically removes the background) and ignores the ``background`` field.	mp4 \| webm · default: "mp4"
caption	boolean	Generate a sidecar SRT caption file alongside the video.	default: false

Types

2 $defs

AvatarVBackgroundobject

Background configuration for Avatar V videos.

type	enum	Type of background. 'color' for a solid hex color, 'image' for an image URL.	color \| image · default: "color"
value	string	Background value — hex color for 'color' type, or HTTP(S) URL for 'image' type.	default: "#FFFFFF"

AvatarVWatermarkobject

Watermark configuration for Avatar V videos.

scale	number	Watermark scale relative to the video (0.0 exclusive–2.0).	0 < n ≤ 2 · nullable
placement	enum	Where to place the watermark on the video.	top-left \| top-right \| bottom-left \| bottom-right · nullable
image_url*	string	HTTP(S) URL of the watermark image to overlay on the video.
opacity	number	Watermark opacity (0.0 = transparent, 1.0 = opaque).	0 ≤ n ≤ 1 · nullable

Validate a payload

before you spend tokens

shell

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