`heygen_speaker`

Generates avatar talking-head video clips using the HeyGen API to fill timeline gaps with a synthetic presenter.

Tip: The media processor's heygen preset generates the same avatar presenter, and its heygen-audio preset lip-syncs to audio you supply. With source: gaps and gap_audio: true, it can fill timeline gaps with the avatar. See media and Filling gaps and generating per segment.

When to use

Use when you need an on-camera presenter but don't have source footage. Common in the auto-assembly pipeline after write_script and transcript_aiprep. Requires a HeyGen avatar ID and voice ID.

In the editor

Add it from the Library (Avatar group), or with + add step and a search for heygen_speaker, after the step that produced the words to be spoken.

Under Inputs, add transcript as a step input pointing at your script or prepped-script step. avatar_id is required, and the Inspector marks it with a red asterisk; voice_id goes with it unless you are feeding in audio you generated elsewhere, in which case add an audio step input and the presenter lip-syncs to that instead. avatar_style, speed, pitch and emotion shape the delivery. Leave use_iv_model and matting on: they are what make the presenter look right and sit cleanly over your background.

This step needs your own HeyGen key. Add it in the workspace's Variables & Service API Keys, from the editor's Settings. A run that needs a key you have not set is refused before it starts rather than failing partway.

Tick Review gate. Generated takes cost money, and the gate lets you watch one before the rest of the video is assembled around it.

The presenter appears as a clip on the level you chose, and behaves like any other footage from then on. Takes already generated in a run group are reused, so an unchanged line is not paid for twice.

YAML Example

- id: avatar
  processor: heygen_speaker
  input:
    - id: transcript
      step: prep_script
  params:
    avatar_id: "your-avatar-id"
    voice_id: "your-voice-id"
    use_iv_model: true
    matting: true
  output:
    timeline: main
  review: true
  cache: true

Required secrets

HEYGEN_API_KEY: set in workspace or template secrets. A run whose pipeline includes this processor is refused before it starts if the key is missing; the web UI prompts for it.

Inputs

ID	Source	Description
`transcript`	step	Text to speak (from `write_script`, `transcript_aiprep`, etc.) Required in TTS mode.
`audio`	step (optional)	Pre-generated audio from `elevenlabs_tts`. When provided, TTS is skipped; HeyGen lip-syncs to this audio.
`segment_plan`	step (optional)	A `SegmentPlan` (e.g. from `video_director`) constraining which segments the speaker fills.

Params

Param	Type	Default	Description
`avatar_id`	string	none	HeyGen avatar ID
`voice_id`	string	none	HeyGen voice ID. Not required when `audio` input is provided.
`avatar_style`	select: `normal`, `circle`, `closeUp`	`"normal"`	Avatar pose style
`speed`	number	`1`	Voice speed (0.5–2.0). 0 = API default.
`pitch`	number	`0`	Voice pitch (-50–50). 0 = omit.
`emotion`	select: `Excited`, `Friendly`, `Serious`, `Soothing`, `Broadcaster`	none	`Excited`, `Friendly`, `Serious`, `Soothing`, or `Broadcaster`
`scale`	number	`0`	Character scale multiplier (0 = API default)
`background_color`	color	`"#00FF00"`	Green screen background color when `matting: false`
`background_image`	string	none	Path to a local image file to use as background. Overrides `background_color`.
`use_iv_model`	bool	`false`	Use HeyGen interactive video model. Always set to `true`.
`matting`	bool	`false`	Enable background removal (transparent output). Always set to `true`.
`elevenlabs_model`	string	none	ElevenLabs model ID for voice synthesis (e.g. `eleven_v3`)
`elevenlabs_stability`	number	none	ElevenLabs stability (0–1)
`elevenlabs_similarity_boost`	number	none	ElevenLabs similarity boost (0–1)
`elevenlabs_style`	number	none	ElevenLabs style (0–1)
`elevenlabs_speaker_boost`	bool	none	ElevenLabs speaker boost
`fill_gaps`	bool	`false`	Generate one clip per gap instead of one full video. Requires `audio` input and `gap_level`.
`gap_level`	level	none	Timeline level to find gaps in (required when `fill_gaps: true`)
`overflow_start`	duration (s)	`0`	Extend each gap start backward by this many seconds
`overflow_end`	duration (s)	`0`	Extend each gap end forward by this many seconds
`force_reuse`	bool	`false`	Never generate new clips: only reuse clips already generated
`output_dir`	string	`"heygen"`	Folder in your workspace where generated clips are kept

Output

EditDecisions on the output timeline level.

Notes

Requires a HEYGEN_API_KEY set in your workspace's Service API Keys.
Never set use_iv_model: false or matting: false. These are critical to output quality. If HeyGen fails due to insufficient credits, top up credits rather than disabling these options.
Avatar takes already generated for a run are reused when you re-run the step, so an unchanged line is not paid for twice.