Generate Video
clipform_generate_videoGenerate a video from images, video clips, or both, synced to an audio track. Use this for narrated question backgrounds, topic visualisations, or any form node that benefits from video. Combine with clipform_generate_tts for narrated audio and clipform_search_media for royalty-free images. Creates 9:16 (720x1280) with Ken Burns pan/zoom effects and transitions. Returns a public URL when complete.
Items: type "image" (Ken Burns motion) or "video" (cover-cropped, muted by default). Duration matches audio_url or set duration_seconds explicitly.
For multi-question builds, pass wait: false on every render: each call returns a job ID immediately, so all renders run in parallel - then collect URLs with clipform_check_render. Sequential waiting renders take 15-120 seconds EACH.
Choosing a render tool: for a recognisable form/quiz beat (guess-the-city, this-or-that, mystery reveal, multiple choice, photo montage...) reach for a video template first (clipform_list_video_templates + clipform_render_video_template) - it is a one-call recipe. Use clipform_generate_video for a narrated or audio-synced media montage (images/clips timed to a voice track). Use clipform_render_composition only when neither fits and you need a custom layer stack. Montage disambiguation: choose clipform_generate_video when the montage is narrated or synced to an audio track; choose the slideshow video template when it is silent (motion + transitions only, no voice-over). A render for a form node is not done until it is attached to that node. Pass node_id (and form_id) so the completed render attaches itself automatically - do not poll clipform_check_render to completion or manually chain clipform_upload_media_asset + clipform_attach_node_media; fire the render and move on.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | true (default) blocks until the video is ready and returns its URL. false returns a job ID immediately - fire all renders first, then poll clipform_check_render. Use false whenever rendering more than one video. | |
| items | Yes | Media items (images, video clips, or a mix) | |
| preset | No | Named look driving transition + motion + colour treatment together (default: 'clean'). One of: clean, editorial, punchy, bold-poster. The advanced fields below (transition, style_preset, texture, duotone, background_color, per-item effect) override individual pieces of the chosen look when set. | clean |
| context | Yes | Describe the user's underlying goal in one sentence - not the tool you're calling. | |
| duotone | No | Advanced override: two-tone editorial recolour on image items, overriding the preset look's own duotone - desaturates then maps to a shadow->highlight palette. Pair with a halftone texture for a screen-print poster look. | |
| form_id | No | The form UUID (required when node_id is set). | |
| node_id | No | Form node to attach this render to automatically once it completes - skips the manual clipform_upload_media_asset + clipform_attach_node_media steps and republishes the form if it's currently live. Requires form_id. | |
| texture | No | Advanced override: print-style pattern overlay on image items, overriding the preset look's own texture - makes stock imagery read as designed (screen-print dither look) | |
| captions | No | Word-level captions from clipform_generate_tts - carried onto the attached media asset. Only used when node_id is set. | |
| audio_url | No | Audio track URL. Video duration matches audio duration. | |
| transition | No | Advanced: overrides the preset look's transition | |
| style_preset | No | Advanced override: a raw Ken Burns motion preset, overriding the preset look's own motion. | |
| random_effects | No | Shuffle Ken Burns effects across image items (default: true) | |
| background_color | No | Advanced override: background color, overriding the preset look's own background (default '#000') | |
| duration_seconds | No | Video duration in seconds (required if no audio_url) | |
| background_audio_url | No | Ambience/music bed under the narration (crowd noise, room tone). Loops to fill the video. Find tracks with clipform_search_music. | |
| background_audio_volume | No | Background bed volume 0-1 (default 0.15 - sits under speech) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | Present when status is 'rendering' - pass to check_render | |
| status | Yes | 'rendering' when wait:false (poll check_render); 'complete' with a public_url when wait:true | |
| attached | No | True when node_id was provided and the render was attached to the node automatically (present once the attach outcome is known). | |
| public_url | No | Present when status is 'complete' - attach via upload_media_asset then attach_node_media (fit_media: true), unless node_id was set (auto-attached) | |
| republished | No | True when the form was live and was republished to include this media. | |
| attach_error | No | Present when node_id was provided but auto-attach failed - the render itself still succeeded. | |
| media_asset_id | No | The workspace media asset created from this render, when attached. | |
| duration_seconds | No |