> ## 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 shape overlay > Update a shape overlay's outline, fill, corners, border, shadow, timing, position, size, animation, depth or stacking order. Only the fields you send are changed. ## OpenAPI ````yaml /openapi.json patch /v1/videos/{id}/clips/{clipId}/shape-overlays/{shapeOverlayId} 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 200 requests per minute per user within a workspace. Rate limit information is returned in response headers: - `RateLimit-Policy`: Named quota, request limit, and window in seconds - `RateLimit`: Remaining quota and seconds until reset - `X-RateLimit-Limit`: Maximum requests per window - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp in milliseconds when the window resets A `429 Too Many Requests` response also includes `Retry-After` in seconds. 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: 'Tella''s editor agent, working in a video: start a chat and follow it' name: Agent chats - description: >- Viewing analytics for a video or across the workspace: plays, watch time, retention, geography, referrers name: Analytics - description: The signed-in user, their workspace, its plan and agent credits name: Account - description: Personal, workspace, and default video backgrounds name: Backgrounds - description: >- Reusable media saved to a workspace, plus Tella's curated sound effect and background music catalogs — the same items the editor's media panels show name: Library - description: >- Motion graphics documents a video plays live as a Tella Motion clip, overlay or b-roll, edited with the editor's own commands name: Tella Motion - description: >- Screen walkthroughs an agent films of a web page with no one recording. Takes are started and read over the MCP server name: Auto Capture - description: Webhook endpoint management name: Webhooks externalDocs: description: API versioning and deprecation policy url: https://www.tella.com/docs/versioning paths: /v1/videos/{id}/clips/{clipId}/shape-overlays/{shapeOverlayId}: patch: tags: - Clips summary: Update a shape overlay description: >- Update a shape overlay's outline, fill, corners, border, shadow, timing, position, size, animation, depth or stacking order. Only the fields you send are changed. operationId: updateClipShapeOverlay 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: Shape overlay ID in: path name: shapeOverlayId required: true schema: description: Shape overlay ID type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateClipShapeOverlayRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ClipShapeOverlayResponse' description: OK headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '400': content: application/json: example: docsUrl: https://docs.tella.com/ error: 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. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '401': content: application/json: example: docsUrl: https://docs.tella.com/ error: unauthorized message: Authentication is required. Provide a valid API key. schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication is required. Provide a valid API key. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '403': content: application/json: example: docsUrl: https://docs.tella.com/ error: 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. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '404': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_found message: The requested resource was not found. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested resource was not found. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '409': content: application/json: example: docsUrl: https://docs.tella.com/ error: conflict message: >- 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. schema: $ref: '#/components/schemas/ErrorResponse' description: >- 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. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '429': content: application/json: example: docsUrl: https://docs.tella.com/ error: rate_limited 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. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Retry-After: $ref: '#/components/headers/RetryAfter' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '500': content: application/json: example: docsUrl: https://docs.tella.com/ error: server_error message: An unexpected error occurred schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error occurred headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '501': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_implemented message: The requested operation is not implemented. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested operation is not implemented. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '503': content: application/json: example: docsUrl: https://docs.tella.com/ error: unavailable message: >- A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay. schema: $ref: '#/components/schemas/ErrorResponse' description: >- A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' security: - BearerAuth: [] components: schemas: UpdateClipShapeOverlayRequest: additionalProperties: false description: Update an existing shape overlay. Only provided fields change. minProperties: 1 properties: animation: allOf: - $ref: '#/components/schemas/OverlayAnimationInput' description: >- Animate how the shape enters and leaves. An omitted `intro`/`outro` keeps that side. Null removes the animation, so `transition` plays again. nullable: true border: allOf: - $ref: '#/components/schemas/ShapeBorder' description: A line just inside the outline, or null for none. corners: allOf: - $ref: '#/components/schemas/TextOverlayBackgroundShape' description: How a square's corners are rounded. depth: allOf: - $ref: '#/components/schemas/OverlayDepth' depthChanges: allOf: - $ref: '#/components/schemas/OverlayDepthChanges' dimensions: allOf: - $ref: '#/components/schemas/OverlayDimensions' durationMs: exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer fill: allOf: - $ref: '#/components/schemas/ClipBackground' description: >- What fills the shape, cut to its outline: any clip background except `ambient`. A solid `#00000000` leaves only the border. path: description: >- A custom outline as SVG path data (`d`) in a 0–100 box; it stretches with the overlay box. Sending it makes the shape a `path`. Closed subpaths (ending in Z) are filled; an open path shows only its `border`, drawn centred on the line. example: M50 0 L100 100 L0 100 Z maxLength: 10000 minLength: 1 type: string point: allOf: - $ref: '#/components/schemas/OverlayPoint' shadow: allOf: - $ref: '#/components/schemas/TextOverlayShadow' shapeType: allOf: - $ref: '#/components/schemas/ShapeType' startTimeMs: description: >- Start time. Milliseconds on the clip playback timeline (with cuts applied). maximum: 9007199254740991 minimum: 0 type: integer transition: allOf: - $ref: '#/components/schemas/TransitionStyle' description: >- Intro/outro animation: `smooth` fades the shape in and out, `hard_cut` pops it. An `animation` replaces it while set; setting `transition` without `animation` removes the animation. zIndex: description: >- Stacking position among the clip's image, video and text overlays: 0 is the backmost. `depth` applies first — a `behind_presenter` overlay stays behind the presenter whatever its zIndex — so the order only matters among overlays at the same depth. Lottie overlays share the stack but aren't listed, so listed values can skip a number. A value past the top moves the overlay to the front; the other overlays keep their relative order. example: 0 maximum: 9007199254740991 minimum: 0 type: integer type: object ClipShapeOverlayResponse: additionalProperties: false description: A shape overlay on a clip properties: shapeOverlay: $ref: '#/components/schemas/ClipShapeOverlay' required: - shapeOverlay type: object ErrorResponse: additionalProperties: false description: Standard error response format properties: docsUrl: description: Link to Tella API documentation example: https://docs.tella.com/ format: uri type: string error: description: Machine-readable error code enum: - bad_request - unauthorized - forbidden - not_found - rate_limited - server_error - conflict - edit_conflict - not_implemented - unavailable example: not_found type: string message: description: Human-readable error message example: Resource not found type: string required: - error - message - docsUrl type: object OverlayAnimationInput: additionalProperties: false description: >- How the overlay enters and leaves; when set it replaces `transition`. Each side describes the hidden state the overlay moves from on the way in and back to on the way out. An omitted side stays as it is. `{intro: {preset: 'slide_up'}, outro: {preset: 'fade'}}` is a complete animation; on text, `{textIntro: {preset: 'slide_up', text: {unit: 'words'}}}` brings the words in one by one. example: intro: preset: slide_up outro: preset: fade properties: intro: allOf: - $ref: '#/components/schemas/OverlayAnimationSideInput' description: >- How the whole overlay enters, or null to appear instantly. Takes no `text`. Omit to keep the current intro. nullable: true motionBlur: description: >- Blur the overlay along its motion while it moves, scales or turns. Defaults to true. type: boolean outro: allOf: - $ref: '#/components/schemas/OverlayAnimationSideInput' description: >- How the whole overlay leaves, or null to disappear instantly. Takes no `text`. Omit to keep the current outro. nullable: true textIntro: allOf: - $ref: '#/components/schemas/OverlayAnimationSideInput' description: >- Text overlays only: how its letters, words or lines enter, one after another, or null for none. Plays alongside `intro`: both start together. nullable: true textOutro: allOf: - $ref: '#/components/schemas/OverlayAnimationSideInput' description: >- Text overlays only: how its letters, words or lines leave, one after another, or null for none. Plays alongside `outro`: both end together. nullable: true type: object ShapeBorder: nullable: true properties: color: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#FFFFFFFF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string width: description: Artboard pixels, drawn inside the outline. exclusiveMinimum: true minimum: 0 type: number required: - color - width type: object TextOverlayBackgroundShape: description: Shape of the solid background behind the text. enum: - none - regular - squircle example: squircle type: string OverlayDepth: description: >- Where the overlay sits relative to the presenter: the person in the clip's camera recording, or in its uploaded footage when the clip has no camera. `front` paints over everything. `behind_presenter` paints it behind the person but over everything else: in any layout the person is matted out of their footage and redrawn above the overlay. Fullscreen and framed layouts keep the recorded room around them; a cut-out layout replaces the room with the clip background. New overlays start on `front`. Without a presenter the overlay paints in front either way. enum: - front - behind_presenter example: behind_presenter type: string OverlayDepthChanges: description: >- Changes of `depth` over the overlay's own time, each held until the next: `atMs` after the overlay starts it moves to that depth, so one overlay can pass in front of the presenter and back behind them (a ring orbiting their head, a title they step in front of). `depth` is where it starts. On updates, omit it to leave the changes as they are; `[]` removes them. Absent in responses while the overlay holds one depth. items: additionalProperties: false properties: atMs: description: Ms after the overlay starts. example: 1200 minimum: 0 type: number depth: $ref: '#/components/schemas/OverlayDepth' required: - atMs - depth type: object type: array OverlayDimensions: description: >- Overlay size in artboard pixels. Absolute (not a percentage) so the overlay shape never distorts when the artboard dimensions change. Both sides must be greater than 0 — the renderer lays the overlay out into this box, so a zero or negative side has no valid meaning. properties: height: example: 540 exclusiveMinimum: true minimum: 0 type: number width: example: 960 exclusiveMinimum: true minimum: 0 type: number required: - width - height type: object ClipBackground: description: >- Clip background. Use type = 'solid' with `color`, type = 'image' or 'video' with `sourceId` (from `POST /v1/sources`) or an exact catalog URL from `GET /v1/backgrounds`, type = 'gradient' with `gradientColor1`, `gradientColor2`, `gradientAngle`, type = 'shaderGradient' with `shaderGradientPreset`, or type = 'ambient'. properties: color: description: Hex color string. Required when type = 'solid'. example: '#000000ff' nullable: true type: string gradientAngle: description: Linear gradient angle in degrees. Required when type = 'gradient'. example: 45 maximum: 9007199254740991 minimum: -9007199254740991 nullable: true type: integer gradientColor1: description: Hex color string. Required when type = 'gradient'. example: '#ff0080ff' nullable: true type: string gradientColor2: description: Hex color string. Required when type = 'gradient'. example: '#7928caff' nullable: true type: string imageUrl: description: >- Hosted image URL. Present in responses and accepted as input only when copied exactly from `GET /v1/backgrounds`; otherwise pass `sourceId`. format: uri nullable: true type: string shaderGradientPreset: description: >- Animated gradient preset from `GET /v1/backgrounds`. Required when type = 'shaderGradient'. example: Halo nullable: true type: string sourceId: description: >- Source ID from `POST /v1/sources` (`kind: image` for type = 'image', `kind: video` for type = 'video'). Required for image/video backgrounds unless using an exact URL from `GET /v1/backgrounds`. Input-only. example: su_abc123 nullable: true type: string type: description: >- Background variant. `ambient`: the clip's screen, else its camera, heavily blurred; no other fields. `shaderGradient`: an animated gradient set by `shaderGradientPreset`; echoing a non-preset one unchanged keeps it. enum: - solid - gradient - image - video - shaderGradient - ambient example: solid type: string videoDurationSeconds: description: >- Video background duration in seconds. Read-only: derived from the uploaded source or catalog entry on input. example: 12.4 minimum: 0 nullable: true type: number videoUrl: description: >- Hosted video URL. Present in responses and accepted as input only when copied exactly from `GET /v1/backgrounds`; otherwise pass `sourceId`. format: uri nullable: true type: string required: - type type: object OverlayPoint: description: >- Top-left corner of the overlay, as a percentage of the video canvas (0-100). Relative so the anchor survives video aspect ratio changes. properties: xPct: example: 30 type: number yPct: example: 30 type: number required: - xPct - yPct type: object TextOverlayShadow: description: >- Drop shadow, matching the editor's Shadow menu. It falls from the background box when the text has one, else from the letters. enum: - none - subtle - deep example: subtle type: string ShapeType: description: >- The outline, stretched to fill the overlay box: a non-square box makes a rectangle or an oval. `path` draws the overlay's own `path`. enum: - square - circle - triangle - diamond - star - hexagon - arrow - path type: string TransitionStyle: description: >- How one thing gives way to the next: `smooth` eases across the change, `hard_cut` swaps instantly. enum: - smooth - hard_cut example: smooth type: string ClipShapeOverlay: additionalProperties: false description: >- A shape overlay on a clip: a square, circle, star… filled with any clip background. properties: border: $ref: '#/components/schemas/ShapeBorderOutput' corners: allOf: - $ref: '#/components/schemas/TextOverlayBackgroundShape' description: How a square's corners are rounded. depth: $ref: '#/components/schemas/OverlayDepth' depthChanges: allOf: - $ref: '#/components/schemas/OverlayDepthChanges' dimensions: $ref: '#/components/schemas/OverlayDimensionsOutput' durationMs: minimum: 0 type: number fill: allOf: - $ref: '#/components/schemas/ClipBackgroundOutput' description: What fills the shape, cut to its outline. id: description: Shape overlay ID example: ly_abc123 type: string name: nullable: true type: string path: description: SVG path data in a 0–100 box, for shapeType `path`; null otherwise. nullable: true type: string point: $ref: '#/components/schemas/OverlayPointOutput' shadow: $ref: '#/components/schemas/TextOverlayShadow' shapeType: $ref: '#/components/schemas/ShapeType' startTimeMs: minimum: 0 type: number transition: $ref: '#/components/schemas/TransitionStyle' zIndex: $ref: '#/components/schemas/OverlayZIndex' required: - id - name - shapeType - path - fill - corners - border - shadow - startTimeMs - durationMs - point - dimensions - transition - depth - zIndex type: object OverlayAnimationSideInput: additionalProperties: false description: >- One side of an overlay animation. A side starts from its `preset` (or from the side as it is) and the fields you give adjust it. properties: blur: description: Blur of the hidden state in pixels. maximum: 200 minimum: 0 type: number clip: description: Clip the motion to the overlay's box, so it wipes in like a mask. type: boolean durationMs: description: >- How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays. Defaults to 500. maximum: 5000 minimum: 50 type: number easing: allOf: - $ref: '#/components/schemas/OverlayAnimationEasingInput' moveX: description: >- Horizontal offset of the hidden state, as a fraction of the overlay's width (of a line's height on a text side); positive is right. maximum: 10 minimum: -10 type: number moveY: description: >- Vertical offset of the hidden state, as a fraction of the overlay's height (of a line's height on a text side); positive is down. maximum: 10 minimum: -10 type: number opacity: description: Opacity of the hidden state, 0 to 1. maximum: 1 minimum: 0 type: number preset: allOf: - $ref: '#/components/schemas/OverlayAnimationPreset' description: >- Start from a ready-made side; the other fields adjust it. Without it the side starts from what it is now; a new whole side starts still and a new text side from `fade`. rotate: description: Clockwise rotation of the hidden state in degrees. maximum: 3600 minimum: -3600 type: number scale: description: Scale of the hidden state; 1 is its resting size. maximum: 10 minimum: 0 type: number text: allOf: - $ref: '#/components/schemas/OverlayAnimationTextInput' type: object ShapeBorderOutput: additionalProperties: false nullable: true properties: color: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#FFFFFFFF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string width: description: Artboard pixels, drawn inside the outline. exclusiveMinimum: true minimum: 0 type: number required: - color - width type: object OverlayDimensionsOutput: additionalProperties: false description: >- Overlay size in artboard pixels. Absolute (not a percentage) so the overlay shape never distorts when the artboard dimensions change. Both sides must be greater than 0 — the renderer lays the overlay out into this box, so a zero or negative side has no valid meaning. properties: height: example: 540 exclusiveMinimum: true minimum: 0 type: number width: example: 960 exclusiveMinimum: true minimum: 0 type: number required: - width - height type: object ClipBackgroundOutput: additionalProperties: false description: >- Clip background. Use type = 'solid' with `color`, type = 'image' or 'video' with `sourceId` (from `POST /v1/sources`) or an exact catalog URL from `GET /v1/backgrounds`, type = 'gradient' with `gradientColor1`, `gradientColor2`, `gradientAngle`, type = 'shaderGradient' with `shaderGradientPreset`, or type = 'ambient'. properties: color: description: Hex color string. Required when type = 'solid'. example: '#000000ff' nullable: true type: string gradientAngle: description: Linear gradient angle in degrees. Required when type = 'gradient'. example: 45 maximum: 9007199254740991 minimum: -9007199254740991 nullable: true type: integer gradientColor1: description: Hex color string. Required when type = 'gradient'. example: '#ff0080ff' nullable: true type: string gradientColor2: description: Hex color string. Required when type = 'gradient'. example: '#7928caff' nullable: true type: string imageUrl: description: >- Hosted image URL. Present in responses and accepted as input only when copied exactly from `GET /v1/backgrounds`; otherwise pass `sourceId`. format: uri nullable: true type: string shaderGradientPreset: description: >- Animated gradient preset from `GET /v1/backgrounds`. Required when type = 'shaderGradient'. example: Halo nullable: true type: string sourceId: description: >- Source ID from `POST /v1/sources` (`kind: image` for type = 'image', `kind: video` for type = 'video'). Required for image/video backgrounds unless using an exact URL from `GET /v1/backgrounds`. Input-only. example: su_abc123 nullable: true type: string type: description: >- Background variant. `ambient`: the clip's screen, else its camera, heavily blurred; no other fields. `shaderGradient`: an animated gradient set by `shaderGradientPreset`; echoing a non-preset one unchanged keeps it. enum: - solid - gradient - image - video - shaderGradient - ambient example: solid type: string videoDurationSeconds: description: >- Video background duration in seconds. Read-only: derived from the uploaded source or catalog entry on input. example: 12.4 minimum: 0 nullable: true type: number videoUrl: description: >- Hosted video URL. Present in responses and accepted as input only when copied exactly from `GET /v1/backgrounds`; otherwise pass `sourceId`. format: uri nullable: true type: string required: - type type: object OverlayPointOutput: additionalProperties: false description: >- Top-left corner of the overlay, as a percentage of the video canvas (0-100). Relative so the anchor survives video aspect ratio changes. properties: xPct: example: 30 type: number yPct: example: 30 type: number required: - xPct - yPct type: object OverlayZIndex: description: >- Stacking position among the clip's image, video and text overlays: 0 is the backmost. `depth` applies first — a `behind_presenter` overlay stays behind the presenter whatever its zIndex — so the order only matters among overlays at the same depth. Lottie overlays share the stack but aren't listed, so listed values can skip a number. example: 0 maximum: 9007199254740991 minimum: 0 type: integer OverlayAnimationEasingInput: additionalProperties: false description: >- How the side accelerates. Without it a new side slows down into place on the way in and speeds up on the way out. properties: bezier: description: 'For `custom`: the handles. Defaults to the side''s current curve.' example: - 0.25 - 0.1 - 0.25 - 1 items: anyOf: - maximum: 1 minimum: 0 type: number - type: number - maximum: 1 minimum: 0 type: number - type: number maxItems: 4 minItems: 4 type: array curve: $ref: '#/components/schemas/OverlayAnimationCurve' intensity: description: >- How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it. Defaults to 0.5. maximum: 1 minimum: 0 type: number spring: allOf: - $ref: '#/components/schemas/OverlayAnimationSpring' description: >- For `spring`: its physics. Defaults to stiffness 200, damping 12, mass 1. required: - curve type: object OverlayAnimationPreset: description: >- A ready-made side, the same as the editor's Animate presets. A `slide_*` or `mask_*` arrow is the direction the overlay travels, so a `slide_up` intro rises into place and a `slide_up` outro rises away. enum: - fade - slide_up - slide_down - slide_left - slide_right - mask_up - mask_down - grow - shrink - blur - blur_slide_up example: slide_up type: string OverlayAnimationTextInput: additionalProperties: false description: >- On `textIntro`/`textOutro` only: which units play the side, each in turn. Required on a new text side. properties: delayMs: description: >- How long after one unit the next starts, in ms (0 to 2000). Defaults to 100. maximum: 2000 minimum: 0 type: number order: description: >- Which unit goes first. `random` uses the same shuffle every time. Defaults to `forward`. enum: - forward - backward - center - edges - random example: forward type: string smoothing: description: Eases the delays across the units. Defaults to `linear`. enum: - linear - smooth - natural - slow_down - accelerate - elastic - overshoot - impulse - swing example: linear type: string unit: description: What animates on its own. enum: - letters - words - lines example: words type: string required: - unit type: object OverlayAnimationCurve: description: >- How a side accelerates. `linear` keeps one speed. `smooth`, `natural`, `slow_down`, `accelerate`, `elastic`, `bounce`, `overshoot`, `impulse` and `swing` are shaped by `intensity`. `custom` follows `bezier`, `spring` follows `spring`. enum: - linear - smooth - natural - slow_down - accelerate - elastic - bounce - overshoot - impulse - swing - custom - spring example: slow_down type: string OverlayAnimationSpring: description: >- Spring physics. The spring sets the side's `durationMs`: it lasts until the spring comes to rest. properties: damping: example: 12 maximum: 300 minimum: 1 type: number mass: example: 1 maximum: 10 minimum: 0.1 type: number stiffness: example: 200 maximum: 1000 minimum: 1 type: number required: - stiffness - damping - mass type: object headers: Deprecation: description: Indicates that an API operation is deprecated, following RFC 9745 example: '@1767225600' schema: type: string RateLimit: description: >- Current quota with remaining requests (`r`) and seconds until reset (`t`) example: '"public-api";r=95;t=42' schema: type: string RateLimitPolicy: description: >- Named quota policy with the request limit (`q`) and window in seconds (`w`) example: '"public-api";q=100;w=60' schema: type: string Sunset: description: >- Indicates when a deprecated API operation will become unavailable, following RFC 8594 example: Tue, 30 Jun 2026 23:59:59 GMT schema: type: string XRateLimitLimit: description: Maximum requests allowed in the current window example: 100 schema: type: integer XRateLimitRemaining: description: Requests remaining in the current window example: 95 schema: type: integer XRateLimitReset: description: Unix timestamp in milliseconds when the window resets example: 1704067200000 schema: format: int64 type: integer RetryAfter: description: Seconds to wait before retrying a rate-limited request example: 45 schema: minimum: 1 type: integer securitySchemes: BearerAuth: description: API key obtained from your Tella account settings scheme: bearer type: http ```` ## Related topics - [Shape overlays](https://www.tella.com/docs/mcp-tools/shape-overlays.md) - [Batch edits](https://www.tella.com/docs/mcp-tools/batch-edits.md) - [Overlays](https://www.tella.com/docs/mcp-tools/overlays.md) - [Update an overlay](https://www.tella.com/docs/api-reference/clips/update-an-overlay.md) - [Update a text overlay](https://www.tella.com/docs/api-reference/clips/update-a-text-overlay.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.