> ## Documentation Index > Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update a layout ## OpenAPI ````yaml /openapi.json patch /v1/videos/{id}/clips/{clipId}/layouts/{layoutId} openapi: 3.0.3 info: description: >- The Tella Public API allows you to programmatically access your videos and playlists, including transcripts, chapters, and thumbnails. ## Authentication All requests require a Bearer token in the Authorization header: ``` Authorization: Bearer tella_pk_xxxxx... ``` API keys can be generated in your Tella workspace settings. ## Rate Limiting The API is rate-limited to 100 requests per minute per organization. Rate limit information is returned in response headers: - `X-RateLimit-Limit`: Maximum requests per window - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp when the window resets title: Tella Public API version: 1.0.0 servers: - description: Production url: https://api.tella.com security: [] tags: - description: Video operations name: Videos - description: Sections of a video name: Clips - description: Playlist operations name: Playlists - description: Sidebar groups for organizing playlists name: Playlist Groups - description: Tags for categorizing and filtering videos name: Tags - description: Webhook endpoint management name: Webhooks paths: /v1/videos/{id}/clips/{clipId}/layouts/{layoutId}: patch: tags: - Clips summary: Update a layout operationId: updateClipLayout parameters: - description: Video ID in: path name: id required: true schema: description: Video ID type: string - description: Clip ID in: path name: clipId required: true schema: description: Clip ID type: string - description: Layout (section) ID in: path name: layoutId required: true schema: description: Layout (section) ID type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateClipLayoutRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ClipLayoutResponse' description: OK '400': content: application/json: example: error: code: bad_request doc_url: https://tella.tv/docs/api-reference/errors#bad-request message: The request was malformed or contained invalid parameters. schema: $ref: '#/components/schemas/ErrorResponse' description: The request was malformed or contained invalid parameters. '401': content: application/json: example: error: code: unauthorized doc_url: https://tella.tv/docs/api-reference/errors#unauthorized message: Authentication is required. Provide a valid API key. schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication is required. Provide a valid API key. '403': content: application/json: example: error: code: forbidden doc_url: https://tella.tv/docs/api-reference/errors#forbidden message: You don't have permission to access this resource. schema: $ref: '#/components/schemas/ErrorResponse' description: You don't have permission to access this resource. '404': content: application/json: example: error: code: not_found doc_url: https://tella.tv/docs/api-reference/errors#not-found message: The requested resource was not found. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested resource was not found. '422': content: application/json: example: error: code: unprocessable_entity doc_url: >- https://tella.tv/docs/api-reference/errors#unprocessable-entity message: The request was well-formed but contained semantic errors. schema: $ref: '#/components/schemas/ErrorResponse' description: The request was well-formed but contained semantic errors. '429': content: application/json: example: error: code: rate_limit_exceeded doc_url: >- https://tella.tv/docs/api-reference/errors#rate-limit-exceeded message: You have exceeded the rate limit. Please slow down. schema: $ref: '#/components/schemas/ErrorResponse' description: You have exceeded the rate limit. Please slow down. '500': content: application/json: example: error: code: internal_server_error doc_url: >- https://tella.tv/docs/api-reference/errors#internal-server-error message: An unexpected error occurred on the server. schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error occurred on the server. security: - BearerAuth: [] components: schemas: UpdateClipLayoutRequest: additionalProperties: false description: Update an existing layout on a clip properties: durationMs: exclusiveMinimum: true maximum: 9007199254740991 type: integer layout: allOf: - $ref: '#/components/schemas/ClipLayoutShape' media: allOf: - $ref: '#/components/schemas/ClipMedia' description: >- Replace the layout's media content. Only valid on time-ranged layouts; rejected on the base (clip-spanning) layout. startTimeMs: description: Start time in ms on the clip's playback timeline (cuts applied) maximum: 9007199254740991 minimum: 0 type: integer transitionStyle: allOf: - $ref: '#/components/schemas/LayoutTransitionStyle' description: >- Only valid on time-ranged layouts; rejected on the base (clip-spanning) layout. type: object ClipLayoutResponse: additionalProperties: false description: A layout on a clip properties: layout: $ref: '#/components/schemas/ClipLayout' required: - layout type: object ErrorResponse: additionalProperties: false description: Standard error response format properties: error: additionalProperties: false description: Error details properties: code: description: Machine-readable error code enum: - bad_request - unauthorized - forbidden - not_found - unprocessable_entity - rate_limit_exceeded - internal_server_error example: not_found type: string doc_url: description: Link to documentation for this error example: https://tella.tv/docs/api-reference/errors#not-found format: uri type: string message: description: Human-readable error message example: The requested resource was not found. type: string required: - code - message - doc_url type: object required: - error type: object ClipLayoutShape: description: >- Structured layout description, discriminated by `kind`. Valid kinds depend on the clip's `layoutSceneType` and the story's aspect ratio; the server validates the kind+fields and returns a 400 if they don't fit. discriminator: mapping: camera-bubble: $ref: '#/components/schemas/CameraBubbleLayout' camera-only: $ref: '#/components/schemas/CameraOnlyLayout' fullscreen: $ref: '#/components/schemas/FullscreenLayout' middle: $ref: '#/components/schemas/MiddleLayout' screen-only: $ref: '#/components/schemas/ScreenOnlyLayout' side-by-side: $ref: '#/components/schemas/SideBySideLayout' tv-presenter: $ref: '#/components/schemas/TVPresenterLayout' propertyName: kind oneOf: - $ref: '#/components/schemas/FullscreenLayout' - $ref: '#/components/schemas/MiddleLayout' - $ref: '#/components/schemas/SideBySideLayout' - $ref: '#/components/schemas/TVPresenterLayout' - $ref: '#/components/schemas/CameraBubbleLayout' - $ref: '#/components/schemas/CameraOnlyLayout' - $ref: '#/components/schemas/ScreenOnlyLayout' type: object ClipMedia: description: >- Media shown during a layout. `image` or `video`, each referencing a `sourceId` from `POST /v1/sources`. discriminator: mapping: image: $ref: '#/components/schemas/ClipMediaImage' video: $ref: '#/components/schemas/ClipMediaVideo' propertyName: type oneOf: - $ref: '#/components/schemas/ClipMediaImage' - $ref: '#/components/schemas/ClipMediaVideo' type: object LayoutTransitionStyle: description: >- How the editor transitions into this layout from the previous one. `spring` is the default smooth motion; `hardCut` is an instant cut. enum: - spring - hardCut title: LayoutTransitionStyle type: string ClipLayout: additionalProperties: false description: >- 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. properties: durationMs: description: Layout duration in ms. Omitted for clip-spanning layouts. example: 5000 minimum: 0 nullable: true type: number id: description: Layout ID type: string layout: allOf: - $ref: '#/components/schemas/ClipLayoutShape' description: >- Structured layout for this section. Null when the underlying layout isn't expressible in the public structured shape (e.g. Custom layouts created in the editor). nullable: true media: description: >- 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. items: $ref: '#/components/schemas/ClipMediaItem' type: array startTimeMs: description: >- Layout start time in ms on the clip's playback timeline (cuts applied). Omitted for clip-spanning layouts. example: 0 minimum: 0 nullable: true type: number transitionStyle: allOf: - $ref: '#/components/schemas/LayoutTransitionStyle' description: >- Transition into this layout. Omitted on the base layout, or when the section uses an internal style not exposed via the public API. nullable: true required: - id - media type: object CameraBubbleLayout: additionalProperties: false description: >- 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. properties: kind: enum: - camera-bubble type: string position: enum: - left - right - top - bottom - top-left - top-right - bottom-left - bottom-right - middle type: string screenFit: description: 'Only honoured when `style: "full"`. Defaults to cover.' enum: - cover - letterbox type: string shape: enum: - circle - square - landscape - portrait type: string size: enum: - S - M - L type: string style: description: >- `regular` (default) keeps the screen layered behind the bubble; `full` puts the screen fullscreen behind the bubble (and honours `screenFit`). enum: - regular - full type: string required: - kind - position - shape - size title: Camera Bubble type: object CameraOnlyLayout: additionalProperties: false description: >- Camera fills the frame or sits centered; the screen is hidden. Combi (all ratios). properties: kind: enum: - camera-only type: string punchIn: description: 'Only honoured when `style: "fullscreen"`. Defaults to false.' type: boolean shape: description: >- Required when `style: "middle"`. Allowed shapes vary by ratio (no `portrait` in portrait clips, no `square` in square clips). enum: - circle - square - landscape - portrait type: string style: description: >- `fullscreen` fills the frame with the camera (optional `punchIn`); `middle` centers a shaped camera (requires `shape`). enum: - fullscreen - middle type: string required: - kind - style title: Camera Only type: object FullscreenLayout: additionalProperties: false description: >- Single-layer fullscreen. Camera-subject clips take an optional `style` (regular/stretch); basic-subject clips take an optional `screenFit`. properties: kind: enum: - fullscreen type: string screenFit: description: >- Only honoured for basic-subject clips (Tella renders the screen fullscreen). Defaults to cover. enum: - cover - letterbox type: string style: description: >- Only honoured for camera-subject clips: `regular` (default) is plain fullscreen, `stretch` stretches the subject. Ignored on basic-subject clips. enum: - regular - stretch type: string required: - kind title: Fullscreen type: object MiddleLayout: additionalProperties: false description: >- Centered subject. Camera-subject clips take a `shape`; basic-subject clips take no fields. properties: kind: enum: - middle type: string shape: description: Required for camera-subject clips. Ignored for basic-subject clips. enum: - circle - square - landscape - portrait type: string required: - kind title: Middle type: object ScreenOnlyLayout: additionalProperties: false description: >- Screen fills the frame or sits centered; the camera is hidden. Combi (all ratios). properties: kind: enum: - screen-only type: string screenFit: description: 'Only honoured when `style: "fullscreen"`. Defaults to cover.' enum: - cover - letterbox type: string style: description: >- `fullscreen` fills the frame with the screen (optional `screenFit`); `middle` centers the screen. enum: - fullscreen - middle type: string required: - kind - style title: Screen Only type: object SideBySideLayout: additionalProperties: false description: >- Camera and screen side by side. Combi (all ratios). Landscape splits horizontally (`position: left/right`, style regular/even/overlap); portrait and square split vertically 50/50 (`position: top/bottom` for the camera half, `style: even` only). properties: kind: enum: - side-by-side type: string position: description: >- Where the camera sits. `left`/`right` on landscape clips; `top`/`bottom` on portrait and square clips. enum: - left - right - top - bottom type: string size: description: 'Camera size. Required when `style: "overlap"`; ignored otherwise.' enum: - S - M - L type: string style: description: >- `regular` weights camera and screen unevenly, `even` splits 50/50, `overlap` lets the camera bleed over the screen edge (and requires `size`). Portrait and square clips support `even` only. enum: - regular - even - overlap type: string required: - kind - position - style title: Side by Side type: object TVPresenterLayout: additionalProperties: false description: >- Today-show layout: presenter on one side, screen on the other. Combi (landscape) only. properties: kind: enum: - tv-presenter type: string position: enum: - left - right type: string style: description: >- `regular` is the standard today-show framing, `full` puts the screen fullscreen behind the presenter, `overlap` tightens the camera-screen overlap. enum: - regular - full - overlap type: string required: - kind - position - style title: TV Presenter type: object ClipMediaImage: additionalProperties: false description: >- Image media. The image fills the section's layer per the chosen layoutName. properties: slot: description: >- 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). enum: - screen - camera type: string sourceId: description: 'Source ID from `POST /v1/sources` (`kind: image`).' minLength: 1 type: string type: enum: - image type: string required: - type - sourceId title: ClipMediaImage type: object ClipMediaVideo: additionalProperties: false description: Video media. properties: slot: description: >- 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). enum: - screen - camera type: string sourceId: description: Source ID from `POST /v1/sources`. minLength: 1 type: string type: enum: - video type: string required: - type - sourceId title: ClipMediaVideo type: object ClipMediaItem: additionalProperties: false description: Media on a layout, as returned in responses. properties: height: description: Image height in pixels (image media only). maximum: 9007199254740991 minimum: -9007199254740991 nullable: true type: integer imageUrl: description: >- Hosted image URL, for image media. Read-only: not accepted as input — pass `sourceId` instead. nullable: true type: string slot: description: >- 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). enum: - screen - camera type: string sourceId: description: >- Source ID the media was created from. Absent for image media added in the editor. nullable: true type: string type: enum: - image - video type: string width: description: Image width in pixels (image media only). maximum: 9007199254740991 minimum: -9007199254740991 nullable: true type: integer required: - type type: object securitySchemes: BearerAuth: description: API key obtained from your Tella account settings scheme: bearer type: http ````