Update groups
update_groupsTransform, keyframe, rename, nest or lock GROUPS. A group moves, scales, rotates and fades as ONE unit, without touching any child's stored position — which is how you get a camera push instead of building the target layout twice and crossfading it.
Address by group_id, never by name. Ids come from get_clip, or from the group_id that add_elements/update_elements hands back when you pass group. An unknown id is an error, never a silent create.
There is no add_groups: a group is CREATED by putting elements in one — add_elements(group: "hero-card") — which also returns its id. That is not a shortcut; a group's pivot comes from its children's bounding box, so an empty group has no geometry to transform.
The shortest path, in one script:
const clip = get_clip({ project_id, clip_index: 2, select: ["groups"] }); const byName = new Map(clip.groups.map(g => [g.name, g.id])); update_groups({ project_id, items: [{ clip_index: 2, group_id: byName.get("hero-card"), anchor_px: [960, 540], keyframes: [ { timestamp: 0, scaleX: 1, scaleY: 1 }, { timestamp: 1.2, scaleX: 2.4, scaleY: 2.4, offsetX: -400, offsetY: -120, interpolation: "easeOut" }, ], }]});
Units are canvas pixels, as everywhere else: offset_px, blur_px and anchor_px are pixels; scale is a multiplier; rotation/rotate are degrees; opacity is 0-100.
anchor_px is the pivot everything rotates and scales about. Give it as a point on the canvas — the server converts it to a fraction of the group's child bounding box and reports back both that fraction and the box, so you can check it. Default is the box's centre. Set it when you want a push that favours one corner. Because it is stored as a fraction of the members' box, adding or removing members moves the pivot on the canvas; set anchor_px again after changing a transformed group's membership.
Only fields you pass are changed. keyframes: [] CLEARS every track; omitting keyframes leaves them alone; a non-empty list replaces the WHOLE track of each property it names and leaves the other properties alone, so to change one keyframe send every keyframe of that property (read them from get_clip's groups). parent_group_id: "" moves a group to the clip root; omitting it leaves the parent alone.
Keyframable: offsetX, offsetY, scaleX, scaleY, rotation, rotateX, rotateY, opacity, blur. Position, size and colour belong to elements, not groups.
Concurrency: clip-scoped (a group edit can add or re-parent nodes in its clip). Serialize against other mutations on the SAME clip; different clips and different projects run in parallel freely.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | One entry per group to update | |
| returning | No | What comes back, the way get_clip's `select` shapes a read. Omitted: ids, the measured layout and the clip audit in compact form. 'ids': element_id per result. 'layout': the measured text fit (font_size_px, text_width_px, natural_width_px, line_count, fits_width/fits_height/fits — widen a box to natural_width_px, not text_width_px; an `adjusted` entry when the measured line box replaced your height) plus `placement` {y_anchor, top, center, bottom}: compare placement.center with a container's centre line to verify centring. 'qa.codes': the clip audit with severity/code/element_ids per finding; 'qa': with the message and fix on each. Errors always come back: in full under ['ids'], as {clip_index, errors: [{code, element_ids}]} under []; bleed under a keyframed group is a warning marked camera_move. A failed item and font_warnings always come back. [] is the leanest write: {total, succeeded, failed} plus errors. | |
| project_id | Yes | The project ID |