`media`

Generates or retrieves media from an external service you describe in configuration, then places the result on the timeline.

When to use

Use media when you want to call a media service (text to speech, image or video generation, stock search) and have the result land on a timeline level. You describe the service once, in YAML, either by naming a built in preset or by writing the request yourself. Changing which service you use is a configuration change, not a code change.

In the editor

Add it from the Library, or with + add step and a search for media. Under Inputs, add source as a step or file input with the text the request needs. Choose a preset to start from, or provide a spec with the request details. Set any values the request needs (such as a voice id) under vars.

Services you call with your own account need your key. Add it in the workspace's Variables & Service API Keys. A run that needs a key you have not set is refused before it starts.

Required secrets

Depends on the service you configure. When the request reads a key by name, that key must be set in workspace or template secrets, and the run is refused before it starts if the key is missing.

Inputs

ID	Source	Description
`source`	step or file	Text the request uses (for example the script to speak).
`transcript`	step (optional)	A transcript, used by source strategies that need it.
`footage_analysis`	step (optional)	Footage analysis, used to guide what and where to generate.
`segment_plan`	step (optional)	A segment plan (from a director-style step), used by the `plan` source strategy.

Params

Param	Type	Default	Description
`preset`	select: `elevenlabs`, `imagen`, `veo`, `heygen`, `heygen-audio`	none	Name of a shipped service preset to start from (e.g. elevenlabs). Override any field with the spec param.
`spec`	text	none	Inline declarative service spec (transport, auth, request, response), written as YAML. Overrides the preset field by field.
`source`	select: `single`, `gaps`, `plan`	`"single"`	How generation requests are produced. single = one asset from the input text; gaps = one asset per uncovered span of the `gap_level` timeline; plan = one asset per matching `segment_plan` segment.
`place`	select: `at_position`, `chain`, `gaps`	`"at_position"`	How generated assets land on the timeline. at_position = at position 0; chain = end to end by duration; gaps = at each asset's target position, clamped to fit its target span.
`vars`	text	none	Extra key/value pairs merged into the request template data (e.g. VoiceID, Model, OutputFormat), written as YAML.
`judge_enable`	bool	`false`	Ask the assistant to review each generated asset and drop ones that fail. Requires the app assistant.
`judge_prompt`	text	none	What makes a good result (e.g. must be a wide landscape, no text, no faces). Guides the quality judge.
`prompt_judge`	bool	`false`	Before generating, ask the assistant to approve, rewrite, or reject the request prompt against your judge criteria. Saves paid calls on bad prompts.
`gap_level`	level	none	When source is gaps: the timeline level whose empty spans to fill.
`gap_audio`	bool	`false`	When source is gaps: treat the source input as a narration audio track instead of text. Slice the matching span per gap and drive generation from it (e.g. HeyGen audio-sync avatar fill-gaps).
`plan_content_type`	string	none	When source is plan: only generate for segments of this content type (blank = any segment with a prompt).

Available presets

Preset	Service produces
`elevenlabs`	Text to speech
`imagen`	A still image, animated into a moving clip
`veo`	Video
`heygen`	An avatar speaking your text (text to speech)
`heygen-audio`	An avatar lip-synced to audio you supply

Set preset to one of these to start from a ready-made spec; override any field with spec. See Bring your own media service for worked examples of each.

Output

EditDecisions placed on output.timeline.

Notes

Start from a preset and override only what you need.
Use cache: true: generation is deterministic for the same request and inputs.