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

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.

Last modified on October 6, 2026