Scene quickstart

Three short jobs, each a fixed chain of tools. Every tool takes media by URL. None reads a local path, a file:// URI or inlined file bytes, and such a source is refused before anything renders. For a file the user has only on their device, call picsart_drive_upload_ask: it opens a drag-and-drop upload. The call itself returns no URL; the file's URL arrives on the user's next turn, as widget context (or in their message), so read it there before going on. Pass detected_files when you can see the file name, and known_urls to offer URLs already made in this conversation.

Merge several videos into one

The montage template plays its clips one after another and renders one file.

1. Probe each clip. Call picsart_media_probe once per clip URL for its width, height and duration. Skip a clip whose exact size and duration an earlier tool result already gave. A missing durationSeconds means the duration is unknown, not zero: follow the probe's own note on that field.

2. Build the parameters. Write the clips as JSON, one object per clip with uri, width, height, duration from the probe, and optionally in and out (the trim, in seconds), fit (cover, contain or fill) and align (one of nine positions such as top left or center, the default). Then run scripts/montage_params.py:

   python3 scripts/montage_params.py --transition crossfade --transition-duration 0.4 clips.json

   It prints the complete picsart_scene_apply_template arguments: uri: "scene://montage", mode: "bootstrap", and parameters with transition, transitionDuration and clips. Omit --width and --height: the canvas matches the largest clip and the frame rate follows the clips. Pass both only to deliberately change the aspect or size. For a smaller output file, use picsart_scene_export's resolution. Pass --transition "" for a hard cut. Use fit and align when a clip's shape differs from the output's, as with portrait and landscape clips in one montage.

   Without a shell, write the script's output yourself. The template's clips do not take the input shape above. Each clip becomes duration (out minus in) plus a content object that carries the probed asset, the trim, fit and align. A hard cut is transition: "" with transitionDuration: 0. Here clip 1 is trimmed to 0–4 s of a 12 s clip, then a hard cut to all 8 s of clip 2:

   {"uri": "scene://montage", "mode": "bootstrap", "parameters": {
     "transition": "", "transitionDuration": 0,
     "clips": [
       {"duration": 4, "content": {"kind": "media",
         "asset": {"type": "video", "uri": "https://…/a.mp4", "width": 1080, "height": 1920, "duration": 12},
         "trim": {"in": 0, "out": 4}, "fit": "cover", "align": "center"}},
       {"duration": 8, "content": {"kind": "media",
         "asset": {"type": "video", "uri": "https://…/b.mp4", "width": 1080, "height": 1920, "duration": 8},
         "trim": {"in": 0, "out": 8}, "fit": "cover", "align": "center"}}]}}

3. Bootstrap the scene. Call picsart_scene_apply_template with those arguments, unchanged. These arguments are complete, so this job needs no schema or template lookup. The composition's duration is the sum of the clip durations: never set it by hand.
4. Validate. Call picsart_scene_validate on the returned scene.
5. Render. Call picsart_scene_export with the scene and mediaType: "mp4". It replies with a job receipt: follow it as picsart-video-rules says until it reports urls, one merged file.

The montage is sequential: each clip starts where the one before it ends. For layers that play at the same time, as in picture-in-picture, write overlapping layers with picsart_scene_patch instead.

The rendered length is not snapped to the frame grid, so a montage of exact decimal trims can land a frame or two short of the target. That is expected, not an error.

Sample frames from a scene

1. Have a valid scene: one a template returned, or one written with picsart_scene_patch.
2. Call picsart_scene_validate on it.
3. Call picsart_scene_contact_sheet with either times (exact timestamps) or frames (that many evenly spaced), never both, and optionally resolution. It returns frames, each a time and a url: low-resolution previews, not the deliverable.

Render a scene to a file

1. Have a valid scene, as above. A scene this skill's merge job built needs no other check. Otherwise confirm its shape with picsart_scene_capabilities, sections ["schemaSummary"] then ["schema:<Name>"], or ["template:<uri>"] for a template.
2. Call picsart_scene_validate on it.
3. Call picsart_scene_export with mediaType (mp4, png and the others it lists), and optionally resolution, fps, duration and startTime. Pass fileName, a short name from the scene's subject, so a file saved to Drive gets a real name. It replies with a job receipt by default; follow it as picsart-video-rules says until it reports urls.

Export renders on a server and needs a signed-in user. Follow picsart-video-rules's rule on cost before you call it.