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.
-
Probe each clip. Call
picsart_media_probeonce per clip URL for its width, height and duration. Skip a clip whose exact size and duration an earlier tool result already gave. A missingdurationSecondsmeans the duration is unknown, not zero: follow the probe's own note on that field. -
Build the parameters. Write the clips as JSON, one object per clip with
uri,width,height,durationfrom the probe, and optionallyinandout(the trim, in seconds),fit(cover,containorfill) andalign(one of nine positions such astop leftorcenter, the default). Then runscripts/montage_params.py:python3 scripts/montage_params.py --transition crossfade --transition-duration 0.4 clips.jsonIt prints the complete
picsart_scene_apply_templatearguments:uri: "scene://montage",mode: "bootstrap", andparameterswithtransition,transitionDurationandclips. Omit--widthand--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, usepicsart_scene_export'sresolution. Pass--transition ""for a hard cut. Usefitandalignwhen 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(outminusin) plus acontentobject that carries the probed asset, the trim,fitandalign. A hard cut istransition: ""withtransitionDuration: 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"}}]}} -
Bootstrap the scene. Call
picsart_scene_apply_templatewith 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. -
Validate. Call
picsart_scene_validateon the returnedscene. -
Optional: the editable project.
picsart_scene_translatereturns the scene as a full engine project, with each transition wired at its seam. Skip it when only the file is wanted. -
Render. Call
picsart_scene_exportwith the scene andmediaType: "mp4". It replies with a job receipt: follow it as picsart-video-rules says until it reportsurls, 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
- Have a valid scene: one a template returned, or one written with
picsart_scene_patch. - Call
picsart_scene_validateon it. - Call
picsart_scene_contact_sheetwith eithertimes(exact timestamps) orframes(that many evenly spaced), never both, and optionallyresolution. It returnsframes, each atimeand aurl: low-resolution previews, not the deliverable.
Render a scene to a file
- 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. - Call
picsart_scene_validateon it. - Call
picsart_scene_exportwithmediaType(mp4,pngand the others it lists), and optionallyresolution,fps,durationandstartTime. PassfileName, 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 reportsurls.
Export renders on a server and needs a signed-in user. Follow picsart-video-rules's rule on cost before you call it.