--- title: "Update a layout" method: PATCH path: "/v1/videos/{id}/clips/{clipId}/layouts/{layoutId}" tags: ["Clips"] --- # Update a layout `PATCH /v1/videos/{id}/clips/{clipId}/layouts/{layoutId}` ## Request - Base URL: `https://api.tella.com` - URL: `https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts/{layoutId}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Update a layout's shape, timing, transition style, or media. `transitionStyle` and `media` are only valid on time-ranged layouts, not on the base (clip-spanning) layout. Updating the base layout also changes every layout that reports `followsBase: true`. ## Path parameters - `id` string, required: Video ID - `clipId` string, required: Clip ID - `layoutId` string, required: Layout (section) ID ## Request body - UpdateClipLayoutRequest: Update an existing layout on a clip - `cameraStyle` 'none' | 'circle' | 'square' | 'portrait' | 'cutout' | 'blob' | 'blob-outline', nullable: The camera's frame shape, as the editor's Camera style picker sets it, overriding the named layout's own: `circle`, `square`, `portrait`, `none` (a rectangle in the camera slot's aspect, rounded by the clip's `corners`, e.g. a squircle when corners are `squircle`), `cutout` (the presenter cut out of the camera feed with no frame or room, in the layout's camera position — e.g. `camera-bubble` with `style: full` and `position: bottom-left` for a full-screen recording with a cut-out presenter in the corner; it switches pop-out off), `blob` or `blob-outline`. It shapes the camera bubble and the pop-out frame. Null clears it so the layout's own shape applies; omitted leaves it as it is. Needs a camera recording and a named layout that frames the camera (not cut-out, screen-only or custom; on a custom layout set `presentation.shape`). On the base layout it is accepted without `layout`. - `crop` ClipLayoutCrop: A crop of the clip's screen recording, as pixels of the recording removed from each edge. The edges must leave a visible area. - `bottom` number, required: Pixels of the screen recording removed from its bottom edge - `left` number, required: Pixels of the screen recording removed from its left edge - `right` number, required: Pixels of the screen recording removed from its right edge - `top` number, required: Pixels of the screen recording removed from its top edge - `durationMs` integer - `layout` union: Structured layout description, discriminated by `kind`. Valid named kinds depend on the clip's `layoutSceneType` and the video's aspect ratio; the server validates the kind+fields and returns a 400 if they don't fit. `custom` carries explicit per-slot geometry and is valid on any clip. - object: Single-layer fullscreen. Takes an optional `style` (regular/stretch); basic-subject clips also take an optional `screenFit`. - `kind` 'fullscreen', required - `screenFit` 'cover' | 'letterbox': Only honoured for basic-subject clips (Tella renders the screen fullscreen). Defaults to cover. - `style` 'regular' | 'stretch': `regular` (default) is plain fullscreen; `stretch` punches in to 1.15x. On basic-subject clips `stretch` needs uploaded footage (not a screen recording). - object: Centered subject. Camera-subject clips take a `shape`; basic-subject clips take no fields. - `kind` 'middle', required - `shape` 'circle' | 'square' | 'landscape' | 'portrait': Required for camera-subject clips. Rejected on basic-subject clips, which have no camera. - object: Camera and screen side by side. Combi (all ratios). Landscape splits horizontally (`position: left/right`, style regular/even/overlap/perspective); portrait and square split vertically 50/50 (`position: top/bottom` for the camera half, `style: even` only). Note that `even` crops the screen recording to fill its half; see `style`. - `kind` 'side-by-side', required - `position` 'left' | 'right' | 'top' | 'bottom', required: Where the camera sits. `left`/`right` on landscape clips; `top`/`bottom` on portrait and square clips. - `size` 'S' | 'M' | 'L': Camera size. Required when `style: "overlap"`; ignored otherwise. - `style` 'regular' | 'even' | 'overlap' | 'perspective', required: `regular` weights camera and screen unevenly, `even` splits 50/50, `overlap` lets the camera bleed over the screen edge (and requires `size`), `perspective` angles the camera and screen toward each other (landscape only). Portrait and square clips support `even` only. `regular` and `overlap` scale the whole screen recording to fit its panel; `even` fills each half edge to edge and center-crops the screen to that half-canvas box (roughly half its width on a landscape canvas), with no `screenFit`/letterbox option. Avoid `even` for terminals, code, spreadsheets or other dense screen content unless you check the result with a clip frame. In the editor's layout picker these are 'Split Left/Right' (regular), 'Split Left/Right Overlap' (overlap, size M or L), 'Split Left/Right Small' (overlap, size S) and 'Split Left/Right 50/50' (even); users often call Overlap 'overlay'. - object: Today-show layout: presenter on one side, screen on the other. Combi (landscape) only. - `kind` 'tv-presenter', required - `position` 'left' | 'right', required - `style` 'regular' | 'full' | 'overlap', required: `regular` is the standard today-show framing, `full` puts the screen fullscreen behind the presenter, `overlap` tightens the camera-screen overlap. - object: The presenter is cut out of the footage (person matting). On combi clips they are blended over the screen recording; on camera-subject clips or basic-subject clips whose subject is an uploaded video, they cover the frame over the story background. Screen-only recordings are not supported: using cut-out on them returns 400. Use fullscreen or middle instead. - `kind` 'cut-out', required - `position` 'left' | 'right': Combi clips only (required there): which side the cut-out presenter sits on in landscape. Portrait and square stories stack the two instead — `right` puts the presenter at the top, `left` at the bottom. Ignored on camera-subject clips. - `style` 'regular' | 'perspective': Landscape combi clips only. `regular` (default) places the screen beside the presenter; `perspective` fills most of the canvas with the screen, angled away toward the presenter, who stands in front in the bottom corner on `position`'s side. - object: Floating camera bubble over the screen recording. Combi (all ratios). Position is 9-way. Set `style: full` to put the screen fullscreen behind the bubble. - `kind` 'camera-bubble', required - `position` 'left' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'middle', required - `screenFit` 'cover' | 'letterbox': Only honoured when `style: "full"`. Defaults to cover. - `shape` 'circle' | 'square' | 'landscape' | 'portrait': Defaults to `circle`, as in the editor's Camera Bubble picker. - `size` 'S' | 'M' | 'L', required - `style` 'regular' | 'full': `regular` (default) keeps the screen layered behind the bubble; `full` puts the screen fullscreen behind the bubble (and honours `screenFit`). - object: Camera fills the frame or sits centered; the screen is hidden. Combi (all ratios). - `kind` 'camera-only', required - `punchIn` boolean: Only allowed when `style: "fullscreen"`; `punchIn: true` with `style: "middle"` is rejected. Defaults to false. - `shape` 'circle' | 'square' | 'landscape' | 'portrait': Required when `style: "middle"`, rejected otherwise. Allowed shapes vary by ratio (no `portrait` in portrait clips, no `square` in square clips). - `style` 'fullscreen' | 'middle', required: `fullscreen` fills the frame with the camera (optional `punchIn`); `middle` centers a shaped camera (requires `shape`). - object: Screen fills the frame or sits centered; the camera is hidden. Combi (all ratios). - `kind` 'screen-only', required - `screenFit` 'cover' | 'letterbox': Only honoured when `style: "fullscreen"`. Defaults to cover. - `style` 'fullscreen' | 'middle', required: `fullscreen` fills the frame with the screen (optional `screenFit`); `middle` centers the screen. - object: Explicit geometry per slot in artboard pixels (the video's `dimensions`), like a layout arranged by hand in the editor. Valid on any scene type. Read the clip's layouts first: a section that is already custom merges the fields you pass over its current geometry; any other layout needs full `subject` geometry. Custom layouts can't carry `media` and aren't accepted in batch edits. - `kind` 'custom', required - `presentation` CustomLayoutSlot: Geometry of one slot. `point` and `dimensions` are required unless the layout being written is already custom, in which case omitted fields keep their current values. Responses report every field. - `corners` 'none' | 'regular' | 'squircle': Corner rounding of a rectangular frame. Defaults to `regular`. - `dimensions` CustomLayoutDimensions: Slot size in artboard pixels. - `height` number, required - `width` number, required - `hidden` boolean: Leave the layer out of the picture. Defaults to false. - `order` integer: Stacking order; the lower one draws on top: 0 is the front layer and 1 the layer behind it (use only 0 and 1). Defaults to 0 for the subject and 1 for the presentation. - `point` CustomLayoutPoint: Top-left corner of the slot in artboard pixels. - `x` number, required - `y` number, required - `shape` 'none' | 'circle' | 'square' | 'portrait' | 'cutout' | 'blob' | 'blob-outline': Frame the layer is drawn in: `none` (default) is the plain rectangle given by `dimensions`; `circle`, `square` and `portrait` are the camera-bubble frames; `cutout` cuts the presenter out of the camera feed; `blob` is a wobbling bubble that grows toward the presenter's hands, and `blob-outline` is the same with a white line around it. - `subject` CustomLayoutSlot: Geometry of one slot. `point` and `dimensions` are required unless the layout being written is already custom, in which case omitted fields keep their current values. Responses report every field. - `corners` 'none' | 'regular' | 'squircle': Corner rounding of a rectangular frame. Defaults to `regular`. - `dimensions` CustomLayoutDimensions: Slot size in artboard pixels. - `height` number, required - `width` number, required - `hidden` boolean: Leave the layer out of the picture. Defaults to false. - `order` integer: Stacking order; the lower one draws on top: 0 is the front layer and 1 the layer behind it (use only 0 and 1). Defaults to 0 for the subject and 1 for the presentation. - `point` CustomLayoutPoint: Top-left corner of the slot in artboard pixels. - `x` number, required - `y` number, required - `shape` 'none' | 'circle' | 'square' | 'portrait' | 'cutout' | 'blob' | 'blob-outline': Frame the layer is drawn in: `none` (default) is the plain rectangle given by `dimensions`; `circle`, `square` and `portrait` are the camera-bubble frames; `cutout` cuts the presenter out of the camera feed; `blob` is a wobbling bubble that grows toward the presenter's hands, and `blob-outline` is the same with a white line around it. - `media` union: Media shown during a layout. `image` or `video`, each referencing a `sourceId` from `POST /v1/sources`, `recording`, a moment from the clip's own recording, or `motion`, a Tella Motion document of the video's. - object: Image media. The image fills the section's layer per the chosen layoutName. - `slot` 'screen' | 'camera': Which slot the media fills: `screen` (the subject/main frame, the default) or `camera` (the bubble/presentation slot — a media bubble over the recording behind it). A `camera` slot requires a layout that renders the camera (e.g. camera-bubble, side-by-side, tv-presenter). - `sourceId` string, required: Source ID from `POST /v1/sources` (`kind: image`). - `type` 'image', required - object: Video media. - `muted` boolean: Silence the video's own audio. Defaults to false. - `slot` 'screen' | 'camera': Which slot the media fills: `screen` (the subject/main frame, the default) or `camera` (the bubble/presentation slot — a media bubble over the recording behind it). A `camera` slot requires a layout that renders the camera (e.g. camera-bubble, side-by-side, tv-presenter). - `sourceId` string, required: Source ID from `POST /v1/sources`. - `startTimeMs` integer: Where the video starts, in ms of the source itself (its in-point, like the editor's Trim). Defaults to 0. Must be inside the source; a layout longer than what is left of the source loops from this point. - `type` 'video', required - object: A moment from the clip's own screen recording (its uploaded footage on an uploaded clip), shown as b-roll. Reported back as `video` media on the recording's source. - `muted` boolean: Silence the recording's own audio. Defaults to true, since it would repeat the clip's. - `slot` 'screen' | 'camera': Which slot the media fills: `screen` (the subject/main frame, the default) or `camera` (the bubble/presentation slot — a media bubble over the recording behind it). A `camera` slot requires a layout that renders the camera (e.g. camera-bubble, side-by-side, tv-presenter). - `startTimeMs` integer, required: Where the b-roll starts, in ms on this clip's playback timeline. It plays the recording on for the layout's duration, including any footage cut out in that stretch. - `type` 'recording', required - object: A Tella Motion document shown as b-roll. It is linked, not copied: it plays live, so edits to the document show in the video at once. - `documentId` string, required: A Tella Motion document of this video's (ffd_…), from `POST /v1/motion/documents`. - `slot` 'screen' | 'camera': Which slot the media fills: `screen` (the subject/main frame, the default) or `camera` (the bubble/presentation slot — a media bubble over the recording behind it). A `camera` slot requires a layout that renders the camera (e.g. camera-bubble, side-by-side, tv-presenter). - `type` 'motion', required - `popOut` ClipPopOut: Pop-out for the camera: the presenter is cut out of the camera feed and rises out of a frame that sits behind their head. The frame's outline follows the layout's `cameraStyle`: the circle style gives a circle, never an ellipse, as wide as the slot's shorter side; the blob style an animated blob; any other style a rectangle in the slot's aspect, rounded by the clip's `corners`. Set `cameraStyle` (e.g. `none` with squircle `corners` for a squircle frame) when the outline is not what the user asked for. Needs a camera recording on the clip and a layout that frames it (any camera layout except cut-out and screen-only). Every field is optional; a write merges over the layout's current settings, and a fresh pop-out takes the defaults for unset fields. Responses report every field. - `amount` number: How far the frame shrinks below the presenter, as a fraction of the camera slot (0–0.5). Defaults to 0.22. - `background` 'original' | 'color': What fills the frame behind the presenter: `original` keeps the camera feed, `color` paints `color`. Defaults to `original`. - `color` string: Frame fill when `background` is `color`, as #RRGGBB or #RRGGBBAA. Defaults to #6366F1. - `outlineColor` string: Outline colour as #RRGGBB or #RRGGBBAA. Defaults to #FFFFFF. - `outlineWidth` number: Outline around the frame as a fraction of its width (0–0.05); 0 draws none. Defaults to 0. - `startTimeMs` integer: Start time in ms on the clip's playback timeline (cuts applied) - `transitionStyle` 'spring' | 'hardCut': How the editor transitions into this layout from the previous one. `spring` is the default smooth motion; `hardCut` is an instant cut. ## Response `200` OK - ClipLayoutResponse: A layout on a clip - `layout` ClipLayout, required: A layout attached to a clip. Times are in ms on the clip's playback timeline (cuts applied). Internally the layout stays anchored to the footage, so it doesn't drift when cuts change later. - `cameraStyle` 'none' | 'circle' | 'square' | 'portrait' | 'cutout' | 'blob' | 'blob-outline': The camera's frame shape, as the editor's Camera style picker sets it, overriding the named layout's own: `circle`, `square`, `portrait`, `none` (a rectangle in the camera slot's aspect, rounded by the clip's `corners`, e.g. a squircle when corners are `squircle`), `cutout` (the presenter cut out of the camera feed with no frame), `blob` or `blob-outline`. It shapes the camera bubble and the pop-out frame. Absent when the layout's own shape applies; custom layouts report it as `presentation.shape` instead. - `crop` ClipLayoutCropOutput: A crop of the clip's screen recording, as pixels of the recording removed from each edge. The edges must leave a visible area. - `bottom` number, required: Pixels of the screen recording removed from its bottom edge - `left` number, required: Pixels of the screen recording removed from its left edge - `right` number, required: Pixels of the screen recording removed from its right edge - `top` number, required: Pixels of the screen recording removed from its top edge - `durationMs` number, nullable: Layout duration in ms. Omitted for clip-spanning layouts. - `followsBase` boolean: True when this layout follows the clip's base layout: updating the `base` layout changes it too, so it needs no update of its own. False when it has its own layout. Absent on the base layout itself. - `id` string, required: Layout ID - `layout` union: Structured layout description, discriminated by `kind`. Valid named kinds depend on the clip's `layoutSceneType` and the video's aspect ratio; the server validates the kind+fields and returns a 400 if they don't fit. `custom` carries explicit per-slot geometry and is valid on any clip. - object: Single-layer fullscreen. Takes an optional `style` (regular/stretch); basic-subject clips also take an optional `screenFit`. - `kind` 'fullscreen', required - `screenFit` 'cover' | 'letterbox': Only honoured for basic-subject clips (Tella renders the screen fullscreen). Defaults to cover. - `style` 'regular' | 'stretch': `regular` (default) is plain fullscreen; `stretch` punches in to 1.15x. On basic-subject clips `stretch` needs uploaded footage (not a screen recording). - object: Centered subject. Camera-subject clips take a `shape`; basic-subject clips take no fields. - `kind` 'middle', required - `shape` 'circle' | 'square' | 'landscape' | 'portrait': Required for camera-subject clips. Rejected on basic-subject clips, which have no camera. - object: Camera and screen side by side. Combi (all ratios). Landscape splits horizontally (`position: left/right`, style regular/even/overlap/perspective); portrait and square split vertically 50/50 (`position: top/bottom` for the camera half, `style: even` only). Note that `even` crops the screen recording to fill its half; see `style`. - `kind` 'side-by-side', required - `position` 'left' | 'right' | 'top' | 'bottom', required: Where the camera sits. `left`/`right` on landscape clips; `top`/`bottom` on portrait and square clips. - `size` 'S' | 'M' | 'L': Camera size. Required when `style: "overlap"`; ignored otherwise. - `style` 'regular' | 'even' | 'overlap' | 'perspective', required: `regular` weights camera and screen unevenly, `even` splits 50/50, `overlap` lets the camera bleed over the screen edge (and requires `size`), `perspective` angles the camera and screen toward each other (landscape only). Portrait and square clips support `even` only. `regular` and `overlap` scale the whole screen recording to fit its panel; `even` fills each half edge to edge and center-crops the screen to that half-canvas box (roughly half its width on a landscape canvas), with no `screenFit`/letterbox option. Avoid `even` for terminals, code, spreadsheets or other dense screen content unless you check the result with a clip frame. In the editor's layout picker these are 'Split Left/Right' (regular), 'Split Left/Right Overlap' (overlap, size M or L), 'Split Left/Right Small' (overlap, size S) and 'Split Left/Right 50/50' (even); users often call Overlap 'overlay'. - object: Today-show layout: presenter on one side, screen on the other. Combi (landscape) only. - `kind` 'tv-presenter', required - `position` 'left' | 'right', required - `style` 'regular' | 'full' | 'overlap', required: `regular` is the standard today-show framing, `full` puts the screen fullscreen behind the presenter, `overlap` tightens the camera-screen overlap. - object: The presenter is cut out of the footage (person matting). On combi clips they are blended over the screen recording; on camera-subject clips or basic-subject clips whose subject is an uploaded video, they cover the frame over the story background. Screen-only recordings are not supported: using cut-out on them returns 400. Use fullscreen or middle instead. - `kind` 'cut-out', required - `position` 'left' | 'right': Combi clips only (required there): which side the cut-out presenter sits on in landscape. Portrait and square stories stack the two instead — `right` puts the presenter at the top, `left` at the bottom. Ignored on camera-subject clips. - `style` 'regular' | 'perspective': Landscape combi clips only. `regular` (default) places the screen beside the presenter; `perspective` fills most of the canvas with the screen, angled away toward the presenter, who stands in front in the bottom corner on `position`'s side. - object: Floating camera bubble over the screen recording. Combi (all ratios). Position is 9-way. Set `style: full` to put the screen fullscreen behind the bubble. - `kind` 'camera-bubble', required - `position` 'left' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'middle', required - `screenFit` 'cover' | 'letterbox': Only honoured when `style: "full"`. Defaults to cover. - `shape` 'circle' | 'square' | 'landscape' | 'portrait': Defaults to `circle`, as in the editor's Camera Bubble picker. - `size` 'S' | 'M' | 'L', required - `style` 'regular' | 'full': `regular` (default) keeps the screen layered behind the bubble; `full` puts the screen fullscreen behind the bubble (and honours `screenFit`). - object: Camera fills the frame or sits centered; the screen is hidden. Combi (all ratios). - `kind` 'camera-only', required - `punchIn` boolean: Only allowed when `style: "fullscreen"`; `punchIn: true` with `style: "middle"` is rejected. Defaults to false. - `shape` 'circle' | 'square' | 'landscape' | 'portrait': Required when `style: "middle"`, rejected otherwise. Allowed shapes vary by ratio (no `portrait` in portrait clips, no `square` in square clips). - `style` 'fullscreen' | 'middle', required: `fullscreen` fills the frame with the camera (optional `punchIn`); `middle` centers a shaped camera (requires `shape`). - object: Screen fills the frame or sits centered; the camera is hidden. Combi (all ratios). - `kind` 'screen-only', required - `screenFit` 'cover' | 'letterbox': Only honoured when `style: "fullscreen"`. Defaults to cover. - `style` 'fullscreen' | 'middle', required: `fullscreen` fills the frame with the screen (optional `screenFit`); `middle` centers the screen. - object: Explicit geometry per slot in artboard pixels (the video's `dimensions`), like a layout arranged by hand in the editor. Valid on any scene type. Read the clip's layouts first: a section that is already custom merges the fields you pass over its current geometry; any other layout needs full `subject` geometry. Custom layouts can't carry `media` and aren't accepted in batch edits. - `kind` 'custom', required - `presentation` CustomLayoutSlot: Geometry of one slot. `point` and `dimensions` are required unless the layout being written is already custom, in which case omitted fields keep their current values. Responses report every field. - `corners` 'none' | 'regular' | 'squircle': Corner rounding of a rectangular frame. Defaults to `regular`. - `dimensions` CustomLayoutDimensions: Slot size in artboard pixels. - `height` number, required - `width` number, required - `hidden` boolean: Leave the layer out of the picture. Defaults to false. - `order` integer: Stacking order; the lower one draws on top: 0 is the front layer and 1 the layer behind it (use only 0 and 1). Defaults to 0 for the subject and 1 for the presentation. - `point` CustomLayoutPoint: Top-left corner of the slot in artboard pixels. - `x` number, required - `y` number, required - `shape` 'none' | 'circle' | 'square' | 'portrait' | 'cutout' | 'blob' | 'blob-outline': Frame the layer is drawn in: `none` (default) is the plain rectangle given by `dimensions`; `circle`, `square` and `portrait` are the camera-bubble frames; `cutout` cuts the presenter out of the camera feed; `blob` is a wobbling bubble that grows toward the presenter's hands, and `blob-outline` is the same with a white line around it. - `subject` CustomLayoutSlot: Geometry of one slot. `point` and `dimensions` are required unless the layout being written is already custom, in which case omitted fields keep their current values. Responses report every field. - `corners` 'none' | 'regular' | 'squircle': Corner rounding of a rectangular frame. Defaults to `regular`. - `dimensions` CustomLayoutDimensions: Slot size in artboard pixels. - `height` number, required - `width` number, required - `hidden` boolean: Leave the layer out of the picture. Defaults to false. - `order` integer: Stacking order; the lower one draws on top: 0 is the front layer and 1 the layer behind it (use only 0 and 1). Defaults to 0 for the subject and 1 for the presentation. - `point` CustomLayoutPoint: Top-left corner of the slot in artboard pixels. - `x` number, required - `y` number, required - `shape` 'none' | 'circle' | 'square' | 'portrait' | 'cutout' | 'blob' | 'blob-outline': Frame the layer is drawn in: `none` (default) is the plain rectangle given by `dimensions`; `circle`, `square` and `portrait` are the camera-bubble frames; `cutout` cuts the presenter out of the camera feed; `blob` is a wobbling bubble that grows toward the presenter's hands, and `blob-outline` is the same with a white line around it. - `media` ClipMediaItem[], required: B-roll media on this layout — one entry per filled slot (screen and/or camera). Empty on the base layout and on layouts whose underlying section carries no media. Each entry's `slot` says which slot it fills. - `documentId` string: The Tella Motion document (ffd_…) that `motion` media plays. - `height` integer, nullable: Image height in pixels (image media only). - `imageUrl` string, nullable: Hosted image URL, for image media. Read-only: not accepted as input — pass `sourceId` instead. - `muted` boolean, nullable: True when video media plays with its own audio silenced. - `slot` 'screen' | 'camera': Which slot the media fills: `screen` (the subject/main frame, the default) or `camera` (the bubble/presentation slot — a media bubble over the recording behind it). A `camera` slot requires a layout that renders the camera (e.g. camera-bubble, side-by-side, tv-presenter). - `sourceId` string, nullable: Source ID the media was created from. Absent for image media added in the editor. - `startTimeMs` number, nullable: Video media only: where it starts in its source, in ms. Absent when it plays from the start. - `type` 'image' | 'video' | 'motion', required - `width` integer, nullable: Image width in pixels (image media only). - `popOut` ClipPopOut: Pop-out for the camera: the presenter is cut out of the camera feed and rises out of a frame that sits behind their head. The frame's outline follows the layout's `cameraStyle`: the circle style gives a circle, never an ellipse, as wide as the slot's shorter side; the blob style an animated blob; any other style a rectangle in the slot's aspect, rounded by the clip's `corners`. Set `cameraStyle` (e.g. `none` with squircle `corners` for a squircle frame) when the outline is not what the user asked for. Needs a camera recording on the clip and a layout that frames it (any camera layout except cut-out and screen-only). Every field is optional; a write merges over the layout's current settings, and a fresh pop-out takes the defaults for unset fields. Responses report every field. - `amount` number: How far the frame shrinks below the presenter, as a fraction of the camera slot (0–0.5). Defaults to 0.22. - `background` 'original' | 'color': What fills the frame behind the presenter: `original` keeps the camera feed, `color` paints `color`. Defaults to `original`. - `color` string: Frame fill when `background` is `color`, as #RRGGBB or #RRGGBBAA. Defaults to #6366F1. - `outlineColor` string: Outline colour as #RRGGBB or #RRGGBBAA. Defaults to #FFFFFF. - `outlineWidth` number: Outline around the frame as a fraction of its width (0–0.05); 0 draws none. Defaults to 0. - `startTimeMs` number, nullable: Layout start time in ms on the clip's playback timeline (cuts applied). Omitted for clip-spanning layouts. - `transitionStyle` 'spring' | 'hardCut': How the editor transitions into this layout from the previous one. `spring` is the default smooth motion; `hardCut` is an instant cut. ## Other responses - `400`: The request was malformed or contained invalid parameters. - `401`: Authentication is required. Provide a valid API key. - `403`: You don't have permission to access this resource. - `404`: The requested resource was not found. - `409`: The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles. - `429`: You have exceeded the rate limit. Please slow down. - `500`: An unexpected error occurred - `501`: The requested operation is not implemented. - `503`: A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay. ## Changes > 67 revisions in range; 1 not diffed. - **2026-10-22** `156b28c30e54`: 1 warning, 3 info - added the new `motion` enum value to the `layout/media/items/type` response property for the response status `200` - added `motion` discriminator mapping keys to the `media/allOf[#/components/schemas/ClipMedia]/` request property - added `#/components/schemas/ClipMediaMotion` to the `media/allOf[#/components/schemas/ClipMedia]/` request property `oneOf` list - added the optional property `layout/media/items/documentId` to the response with the `200` status - **2026-10-19** `127438d189a6`: 1 breaking, 1 info - the response property `layout/layout/allOf[#/components/schemas/ClipLayoutShape]/oneOf[subschema #6: Camera Bubble]/shape` became optional for the status `200` - the request property `layout/allOf[#/components/schemas/ClipLayoutShape]/oneOf[subschema #6: Camera Bubble]/shape` became optional - …earlier changes not shown [Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/clips/:clipId/layouts/:layoutId/patch.md) --- [API](https://skmtc.dev/withchima/apis/tella-public-api.md) - [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withchima/apis/tella-public-api/revisions/668da8c6d5f6?raw)