Render Composition
clipform_render_compositionRender a specialised video composition to MP4 or PNG - custom animated visuals that clipform_generate_video can't provide, such as geography animations or designed motion graphics. Available composition names and their required input props schemas come from clipform_list_compositions.
Output formats: mp4 (H.264, best for social media) or png (single frame). Returns a public URL when complete.
For multi-render builds (e.g. one clip per quiz question), pass everything in ONE call via items (max 10): all renders fire in parallel and you get one job ID each - then collect the URLs in a single clipform_check_render call with job_ids. Single render: pass compositionId/inputProps at the top level (wait: true blocks and returns the URL; wait: false returns a job ID).
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. 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. In batch mode, set node_id per item (see items) and form_id once at the top level.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Single render only: true (default) blocks until the render is ready and returns its URL; false returns a job ID for clipform_check_render. Batch items always run fire-and-poll. | |
| items | No | Batch mode: multiple renders in one call. All fire in parallel; returns one job ID per item - collect with clipform_check_render (job_ids). Use this whenever rendering more than one clip. | |
| context | Yes | Describe the user's underlying goal in one sentence - not the tool you're calling. | |
| form_id | No | The form UUID - required when node_id is set (single render) or any item sets node_id (batch). | |
| node_id | No | Single render only: form node to attach this render to automatically once it completes. Requires form_id. For batch mode, set node_id per item instead. | |
| captions | No | Single render only: word-level captions from clipform_generate_tts, carried onto the attached media asset. Only used when node_id is set. For batch mode, set captions per item instead. | |
| inputProps | No | Single render: props object matching the composition's schema from clipform_list_compositions. Validated STRICTLY - unknown or missing props fail with the schema in the error, nothing renders silently with defaults. For map compositions (Map), wide shots (camera.zoom < 9) may round lat/lng to 1 decimal place to improve cache hit rates; close shots and pin drops should keep full precision — the pin lands exactly on `target`. | |
| caption_ref | No | Single render only: caption_ref from clipform_generate_tts - an opaque handle that attaches that TTS run's word-level captions to the media asset, resolved server-side. Preferred over captions. Only used when node_id is set. For batch mode, set caption_ref per item instead. | |
| outputFormat | No | Single render: output format (default: mp4) | mp4 |
| compositionId | No | Single render: the composition ID. Call clipform_list_compositions to see available options (e.g. 'Slideshow', 'Map', 'Grid'). Use items instead for multiple renders. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| jobs | Yes | One entry per render (single or batch) |