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.
Only fields you pass are changed. keyframes: [] CLEARS every track; omitting keyframes leaves them alone; a non-empty list replaces only the properties it names. 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 | Declare what comes back, the way get_clip's `select` shapes a read. Omit it and you get ids, the measured layout, and the clip audit in compact form — which names every problem but drops the explanatory prose. Values: '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 — `fits` is the WIDTH check (the widest rendered line inside the box), `fits_height` is the separate height one — plus an `adjusted` entry whenever the measured line box replaced the height you sent; widen a box to natural_width_px, NOT text_width_px, which is the widest RENDERED line and so a lower bound on text that is already wrapping; plus `placement` {y_anchor, top, center, bottom} — where the box landed and what your `y` meant, emitted only when the origin was implicit or resolves to 'center'. Compare placement.center with a container's centre line to verify centring: a mis-anchored label is the one layout error nothing else reports), 'qa.codes' (audit counts and summary plus severity/code/element_ids per finding), 'qa' (the same audit with the full message and suggested fix on every finding — ask for this when a code alone isn't enough to act on). A text element measured on a fallback face is listed in top-level `font_warnings` whichever you choose. ERROR-severity findings always come back with their full message whichever you choose — including `returning:[]` and `['ids']`, which suppress WARNINGS only. A failed item always returns complete. Pass [] for just {total, succeeded, failed} plus any errors, the leanest write. | |
| project_id | Yes | The project ID |