Skip to main content
POST
Add a layout to a clip

Authorizations

Authorization
string
header
required

API key obtained from your Tella account settings

Path Parameters

id
string
required

Video identifier

Example:

"vid_abc123def456"

clipId
string
required

Clip identifier

Example:

"cl_xyz789ghi012"

Body

application/json

Add a layout to a clip

cameraStyle
enum<string> | null

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).

Available options:
none,
circle,
square,
portrait,
cutout,
blob,
blob-outline
crop
object | null

Crop the clip's screen recording for this layout only — the editor's crop modal on “This layout only”. Other layouts keep following the clip's crop; null makes this layout follow it again. Masks that start in the layout stay anchored to their content, and a custom layout's screen box keeps its on-canvas scale unless the same request writes layout geometry. Needs a screen recording in the clip. To crop the recording across the whole clip use auto-crop.

durationMs
integer

Optional. Provide together with startTimeMs for a time-ranged layout. Minimum 200ms.

Required range: 200 <= x <= 9007199254740991
layout
Fullscreen · object

Layout shape. May be omitted when media is provided to use the default full-frame B-roll layout.

media
ClipMediaImage · object

Optional media content to show during this layout. Only valid on time-ranged layouts.

popOut
object | null

Pop the presenter out of the camera frame. Omitted or null leaves it off.

startTimeMs
integer

Optional. Provide together with durationMs for a time-ranged layout. In ms on the clip's playback timeline (cuts applied).

Required range: 0 <= x <= 9007199254740991
transitionStyle
enum<string>

Optional. Only valid on time-ranged layouts. Defaults to the user's saved layout intro transition when omitted. The user's saved layout outro transition is applied when the following layout begins or resumes.

Available options:
spring,
hardCut

Response

OK

A layout on a clip

layout
object
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.