# Tella: Developers ## Developers ### Getting Started - [Introduction](https://www.tella.com/docs/introduction.md): Welcome to the Tella Public API documentation - [Quickstart](https://www.tella.com/docs/quickstart.md): Make your first API call in minutes - [AI onboarding](https://www.tella.com/docs/ai-onboarding.md): Everything you need to onboard your AI agent to Tella. - [Authentication](https://www.tella.com/docs/authentication.md): Secure your API requests with Bearer tokens - [Rate limiting](https://www.tella.com/docs/rate-limiting.md): Understand the shared API and MCP rate limit and learn how to handle it. - [API versioning and deprecation](https://www.tella.com/docs/versioning.md): Learn how Tella versions its public API and announces deprecated endpoints and sunset dates. ### Guides - [Webhooks](https://www.tella.com/docs/webhooks.md): Receive real-time notifications when events happen in your workspace - [Model Context Protocol (MCP)](https://www.tella.com/docs/mcp-server.md): Connect Claude, ChatGPT, Muse, Grok Bot, Cursor, Codex, and other AI assistants to your Tella workspace. - [Media library API](https://www.tella.com/docs/media-library-api.md): Upload reusable media, browse Tella's curated sound effects and background music, and reuse them across your videos. - [Embed API](https://www.tella.com/docs/embed-api.md): Control embedded Tella videos with JavaScript ### MCP Tools #### Managing videos - [Videos](https://www.tella.com/docs/mcp-tools/videos.md): Find, read, configure, export, and share the videos in your workspace. - [Playlists](https://www.tella.com/docs/mcp-tools/playlists.md): Create playlists and sidebar groups, and organize videos into them. - [Tags](https://www.tella.com/docs/mcp-tools/tags.md): Categorize and filter your library with workspace and private tags. - [Webhooks](https://www.tella.com/docs/mcp-tools/webhooks.md): List and update your webhook subscriptions. - [Social publishing](https://www.tella.com/docs/mcp-tools/social-publishing.md): Publish a video to the user's connected YouTube, LinkedIn, X, Instagram and Facebook accounts, and check on each publish. - [Analytics](https://www.tella.com/docs/mcp-tools/analytics.md): Read plays, watch time, retention, geography, and referrers for a video or the whole workspace. #### Editing videos - [Batch edits](https://www.tella.com/docs/mcp-tools/batch-edits.md): Apply up to 200 timeline edits across a video's clips in one call with apply_video_edits. - [Sources](https://www.tella.com/docs/mcp-tools/sources.md): Upload media, 3D .cube LUTs, and custom fonts to use in your videos. - [Library](https://www.tella.com/docs/mcp-tools/library.md): Save reusable media to the workspace library and browse Tella's curated sound effects and music. - [AI media generation](https://www.tella.com/docs/mcp-tools/ai-media-generation.md): Generate images and sound effects from a text prompt and place them in a video. - [Backgrounds](https://www.tella.com/docs/mcp-tools/backgrounds.md): Browse personal, workspace, and default backgrounds to apply to a clip. - [Chapters](https://www.tella.com/docs/mcp-tools/chapters.md): Read and replace a video's chapter markers. - [Clips](https://www.tella.com/docs/mcp-tools/clips.md): Add, cut, reorder, inspect, and transcribe the clips that make up a video. - [Layouts](https://www.tella.com/docs/mcp-tools/layouts.md): Compose a clip's camera and screen layers, add B-roll, and let AI lay out a clip. - [Cropping](https://www.tella.com/docs/mcp-tools/cropping.md): Detect the visible content in a screen recording and crop to it. - [Background Music](https://www.tella.com/docs/mcp-tools/background-music.md): Set or remove a video's looping background music track. - [Zooms](https://www.tella.com/docs/mcp-tools/zooms.md): Zoom into a point on the screen, follow the cursor, or generate zooms from clicks. - [Mouse events](https://www.tella.com/docs/mcp-tools/mouse-events.md): Read the cursor path and clicks recorded with a screen recording. - [Blurs and highlights](https://www.tella.com/docs/mcp-tools/blurs-and-highlights.md): Blur sensitive regions or highlight areas of the screen for a time range. - [Overlays](https://www.tella.com/docs/mcp-tools/overlays.md): Place an image or video on top of a clip for a time range. - [Text overlays](https://www.tella.com/docs/mcp-tools/text-overlays.md): Put titles, callouts, and labels on top of a clip. - [Sound effects](https://www.tella.com/docs/mcp-tools/sound-effects.md): Play a curated or uploaded sound effect over a clip. ### API Reference #### Analytics - [Get workspace analytics](https://www.tella.com/docs/api-reference/analytics/get-workspace-analytics.md): Viewing analytics aggregated across videos: by default every video shared with the workspace, or with scope=mine only the videos you created. Includes the same summary, plays per day, retention, geography and referrer breakdowns as a single video, plus the videos ranked by plays. Only topVideos is p… - [Get video analytics](https://www.tella.com/docs/api-reference/analytics/get-video-analytics.md): Viewing analytics for one video: plays, unique sessions, watch time, plays per day, retention per one-percent slice, geography, referrers, UTM traffic sources, and call-to-action clicks. Available to the video's creator, its collaborators, and workspace members it is shared with. Dates are whole UTC… #### Backgrounds - [List available backgrounds](https://www.tella.com/docs/api-reference/backgrounds/list-available-backgrounds.md): Returns personal uploads, workspace uploads, and Tella's default image and animated backgrounds in named categories. Each item includes a preview URL and a background value that can be passed directly to the clip update endpoint. #### Library - [List library items](https://www.tella.com/docs/api-reference/library/list-library-items.md): Returns a page of reusable media saved to the library — images, videos, screenshots, sound effects, music and LUTs — for one scope. Items added through the API include a `sourceId` you can pass anywhere a source is accepted, including images. Editor-added images, screenshots, music and LUTs expose a… - [Add a source to the library](https://www.tella.com/docs/api-reference/library/add-a-source-to-the-library.md): Saves an uploaded source to the library so it can be listed and reused later, both here and in the editor's media panels. Create the source via `POST /v1/sources` and upload the bytes first, then pass its `sourceId`. Without this a source is only reachable through the clips that already reference it… - [Generate media with AI](https://www.tella.com/docs/api-reference/library/generate-media-with-ai.md): Starts generating an image or a sound effect from a text prompt with the same AI generators the editor's media panels use. Generation is asynchronous: the response is a `generation` whose `id` is the private library item the result is saved as. Poll `GET /v1/library/generations/{id}` every few secon… - [Get a generation's status](https://www.tella.com/docs/api-reference/library/get-a-generations-status.md): Returns the current status of a generation started with `POST /v1/library/generations`. Poll until `status` is `completed` (then `item` holds the finished library item) or `failed` (then `error` says why; start a new generation). - [Capture a web page or social post](https://www.tella.com/docs/api-reference/library/capture-a-web-page-or-social-post.md): Captures a public web page or a single post on X, Instagram, LinkedIn or TikTok and saves it to the caller's private library. Pages are captured above the fold; social posts are cropped to their embed card. Set scroll=true to record a scrolling web page as video (ignored for social posts). Returns a… - [Remove a library item](https://www.tella.com/docs/api-reference/library/remove-a-library-item.md): Removes an item from the library. This removes the library entry only — clips already using the underlying source keep working. #### Playlist Groups - [List playlist groups](https://www.tella.com/docs/api-reference/playlist-groups/list-playlist-groups.md): Returns the sidebar playlist groups for the authenticated user, in sidebar order. Personal groups are only visible to you; org groups are shared with the whole workspace. - [Create a playlist group](https://www.tella.com/docs/api-reference/playlist-groups/create-a-playlist-group.md): Create a sidebar group to organize playlists into. Use the groupId field on PATCH /v1/playlists/{id} to move playlists into it. - [Delete a playlist group](https://www.tella.com/docs/api-reference/playlist-groups/delete-a-playlist-group.md): Delete a playlist group. Playlists in the group are not deleted, they just become ungrouped. - [Rename or reorder a playlist group](https://www.tella.com/docs/api-reference/playlist-groups/rename-or-reorder-a-playlist-group.md): Rename a playlist group and/or move it to a position in its sidebar section (0 = top) #### Playlists - [List all playlists](https://www.tella.com/docs/api-reference/playlists/list-all-playlists.md): Returns a list of all playlists for the authenticated user - [Create a new playlist](https://www.tella.com/docs/api-reference/playlists/create-a-new-playlist.md): Create a new playlist for the authenticated user - [Get playlist details](https://www.tella.com/docs/api-reference/playlists/get-playlist-details.md): Returns detailed information about a playlist including its videos - [Delete a playlist](https://www.tella.com/docs/api-reference/playlists/delete-a-playlist.md): Permanently delete a playlist. Videos in the playlist are not deleted. - [Update a playlist](https://www.tella.com/docs/api-reference/playlists/update-a-playlist.md): Update a playlist's name and/or description - [Add a video to a playlist](https://www.tella.com/docs/api-reference/playlists/add-a-video-to-a-playlist.md): Adds an existing video to the specified playlist - [Remove a video from a playlist](https://www.tella.com/docs/api-reference/playlists/remove-a-video-from-a-playlist.md): Removes a video from the specified playlist. The video itself is not deleted. #### Videos - [List connected social accounts](https://www.tella.com/docs/api-reference/videos/list-connected-social-accounts.md): Lists the social accounts you have connected in Tella that POST /v1/videos/{id}/publish can post with: each one's `id` (pass it as `accountId`), its name, and the destinations it posts to. Accounts are connected in Tella (Settings → Connections); this API can't connect one. - [List subtitle presets](https://www.tella.com/docs/api-reference/videos/list-subtitle-presets.md): Returns Tella's built-in subtitle presets and the authenticated user's saved presets. Each includes a captionStyle preview. Apply by presetId to restore the full preset, including typography and saved layout settings. - [Save a subtitle preset](https://www.tella.com/docs/api-reference/videos/save-a-subtitle-preset.md): Saves a subtitle look as a personal preset, like the editor's "Save as preset". Pass `videoId` to snapshot that video's current subtitles (style, font, weight, size, position, grouping and lines per block), `captionStyle` to build one from scratch on the style's defaults, or both — explicit caption… - [List all videos](https://www.tella.com/docs/api-reference/videos/list-all-videos.md): Returns a paginated list of all videos for the authenticated user. Use playlistId query parameter to filter videos by playlist. - [Create a video](https://www.tella.com/docs/api-reference/videos/create-a-video.md): Create a new video from an uploaded source. First create a source (POST /v1/sources), PUT the video bytes to its uploadUrl, then call this endpoint with the sourceId — it becomes the new video's first clip. - [Search videos](https://www.tella.com/docs/api-reference/videos/search-videos.md): Search the authenticated user's direct video library by title or indexed transcript sentences. - [Get video information](https://www.tella.com/docs/api-reference/videos/get-video-information.md): Returns detailed information about a video including chapters, transcript, and thumbnails - [Delete a video](https://www.tella.com/docs/api-reference/videos/delete-a-video.md): Permanently delete a video - [Update a video](https://www.tella.com/docs/api-reference/videos/update-a-video.md): Update a video's settings including viewer options, download permissions, access controls, and metadata. Some features require Premium plan. - [Set background music](https://www.tella.com/docs/api-reference/videos/set-background-music.md): Sets the video's background music track. It loops over the whole video and is included in exports. Volume is 0-1 and defaults to 0.2. - [Remove background music](https://www.tella.com/docs/api-reference/videos/remove-background-music.md): Removes the video's background music track. - [Download video captions](https://www.tella.com/docs/api-reference/videos/download-video-captions.md): Returns ready, non-empty captions as a SubRip or WebVTT attachment. - [Get video chapters](https://www.tella.com/docs/api-reference/videos/get-video-chapters.md): Returns chapters ordered by timestamp in seconds on the final video timeline. Chapter IDs are intentionally omitted because they are not stable across reads. - [Replace video chapters](https://www.tella.com/docs/api-reference/videos/replace-video-chapters.md): Replaces the complete chapter list. Timestamps are seconds on the final video timeline and must be non-negative, ascending, and within the video duration. Pass an empty array to clear all chapters. - [Add a collaborator to a video](https://www.tella.com/docs/api-reference/videos/add-a-collaborator-to-a-video.md): Grants access to a video for the specified user. The user must be a member of your workspace. - [Duplicate a video](https://www.tella.com/docs/api-reference/videos/duplicate-a-video.md): Creates a copy of the specified video. Optionally specify a new name for the duplicate. - [Apply many video edits](https://www.tella.com/docs/api-reference/videos/apply-many-video-edits.md): Adds up to 200 sound effects, text overlays, zooms, blurs, highlights, and image/video overlays across clips in one video. Operations run in array order and commit as one editor revision. Use this instead of repeated single-add requests. - [List video exports](https://www.tella.com/docs/api-reference/videos/list-video-exports.md): Lists all exports for the specified video with their current status, progress, and download URL when ready. Requires edit access to the video, or viewer access to a video with downloads (or raw downloads) enabled. - [Start a video export](https://www.tella.com/docs/api-reference/videos/start-a-video-export.md): Starts an export of the specified video. Export processing is asynchronous: poll GET /v1/videos/{id}/exports/{exportId} for status and a download URL, or listen for the export.ready webhook. Creators and editors can always export. Viewers can only start an export if the video's download settings all… - [Get video export status](https://www.tella.com/docs/api-reference/videos/get-video-export-status.md): Returns the current status and progress of an export. The download URL appears when the export is complete. The export ID contains slashes and must be percent-encoded as a single path segment. Requires edit access to the video, or viewer access to a video with downloads (or raw downloads) enabled. - [List social publications](https://www.tella.com/docs/api-reference/videos/list-social-publications.md): Lists the latest publish of the video to each social destination and account, including publishes made in the Tella app. Poll this after POST /v1/videos/{id}/publish until the publication's status is `completed` (with the post `url`) or `failed` (with `error`). Requires edit access to the video. - [Publish a video to social media](https://www.tella.com/docs/api-reference/videos/publish-a-video-to-social-media.md): Posts the video to one of your connected social accounts: YouTube, YouTube Shorts, LinkedIn, X, Instagram (post, reel or story) or Facebook (post or story). This posts under your own account, so check the destination, text and privacy before calling it. It uploads an export with the `export` setting… - [Get a video storyboard](https://www.tella.com/docs/api-reference/videos/get-a-video-storyboard.md): Returns a signed 4x4 WebP storyboard whose 16 tiles are sampled evenly across the requested window (`durationMs`/16 apart; every 5 seconds for the default 80s window) on the video's playback timeline (cuts applied, cumulative across clips). Only `startTimeMs` and `durationMs` control the storyboard;… - [Apply a subtitle preset](https://www.tella.com/docs/api-reference/videos/apply-a-subtitle-preset.md): Apply a preset returned by GET /v1/subtitle-presets. Built-in presets restore style, font, weight, and size, preserving position, grouping, and lines per block. Personal presets also restore those saved layout settings. Does not change transcript text or whether subtitles are enabled. Changes sync t… - [Get a video thumbnail or animated preview](https://www.tella.com/docs/api-reference/videos/get-a-video-thumbnail-or-animated-preview.md): Returns a signed CDN URL for a still image (jpg/png/webp) or animated preview (gif/mp4) of a video at a time on the video's playback timeline (cuts applied, cumulative across clips). By default returns a 302 redirect — set `?response=json` to get `{url}` JSON instead. - [Set a video's thumbnail](https://www.tella.com/docs/api-reference/videos/set-a-videos-thumbnail.md): Sets the video's thumbnail from either an uploaded image or a frame of the video itself. Provide exactly one of `sourceId` (an image source from `POST /v1/sources` with `kind: "image"` — upload the image bytes to its `uploadUrl` first) or `inpointMs` (a time on the video's playback timeline). Settin… - [Remove a video's custom thumbnail](https://www.tella.com/docs/api-reference/videos/remove-a-videos-custom-thumbnail.md): Removes the custom thumbnail (uploaded image or picked frame) and reverts the video to its default auto-generated thumbnail. - [Get a video's timeline](https://www.tella.com/docs/api-reference/videos/get-a-videos-timeline.md): Returns a compact ordered timeline outline by default: video identity, version, dimensions and duration plus every clip's video-timeline start, playback duration and content counts. Use `include` to fetch specific video or clip details, optionally scoped by `clipIds`; the complete outline remains in… #### Sources - [Create a source upload (video, audio, image, or LUT)](https://www.tella.com/docs/api-reference/sources/create-a-source-upload-video-audio-image-or-lut.md): Returns a `sourceId` and a pre-signed S3 URL. PUT the file bytes to `uploadUrl`, then reference `sourceId` from clips, layouts (b-roll media), overlays, or backgrounds. For a 3D .cube LUT use `kind: "lut"`, omit dimensions and duration, upload unchanged, then save it with `POST /v1/library` and appl… - [Get a source's processing status](https://www.tella.com/docs/api-reference/sources/get-a-sources-processing-status.md): Returns whether a source from `POST /v1/sources` is ready to use, however it was placed (clip, b-roll, overlay, background, background music or sound effect). Poll it after placing a newly uploaded source: while it is `processing`, frames and previews of videos that use it answer not-ready instead o… - [Get a streaming upload storyboard](https://www.tella.com/docs/api-reference/sources/get-a-streaming-upload-storyboard.md): Returns a signed 4x4 WebP storyboard whose 16 tiles are sampled evenly across the requested window (`durationMs`/16 apart; every 5 seconds for the default 80s window) from a streaming upload source owned by the caller or their workspace. `startTimeMs` is relative to the source. Only `startTimeMs` an… - [Get a thumbnail of a source on no clip](https://www.tella.com/docs/api-reference/sources/get-a-thumbnail-of-a-source-on-no-clip.md): Get a thumbnail or animated preview of a streaming upload source owned by the caller or their workspace, without a video or clip — for a source that isn't on any clip yet. `startTimeMs` is relative to the source. If you pass `width`/`height`, the aspect ratio must match the source's native ratio. Om… - [Get the audio waveform JSON for a source on no clip](https://www.tella.com/docs/api-reference/sources/get-the-audio-waveform-json-for-a-source-on-no-clip.md): Returns the audio waveform JSON, in BBC audiowaveform format, for a streaming upload source owned by the caller or their workspace, without a video or clip — for a source that isn't on any clip yet. #### Tags - [List all tags](https://www.tella.com/docs/api-reference/tags/list-all-tags.md): Returns all tags visible to the authenticated user: the workspace's shared tags plus the user's private tags - [Create a new tag](https://www.tella.com/docs/api-reference/tags/create-a-new-tag.md): Create a workspace or private tag. When no color is given, one is derived deterministically from the name. - [Delete a tag](https://www.tella.com/docs/api-reference/tags/delete-a-tag.md): Permanently delete a tag and remove it from all videos. Private tags can only be deleted by their creator. - [Update a tag](https://www.tella.com/docs/api-reference/tags/update-a-tag.md): Update a tag's name, color and/or description. Private tags can only be updated by their creator. - [List a video's tags](https://www.tella.com/docs/api-reference/tags/list-a-videos-tags.md): Returns the tags on a video that are visible to the authenticated user - [Add a tag to a video](https://www.tella.com/docs/api-reference/tags/add-a-tag-to-a-video.md): Tag a video. Requires edit access to the video. Adding a private tag only affects the authenticated user's library. - [Remove a tag from a video](https://www.tella.com/docs/api-reference/tags/remove-a-tag-from-a-video.md): Untag a video. Requires edit access to the video. Private tags can only be removed by their owner. #### Clips - [List text presets](https://www.tella.com/docs/api-reference/clips/list-text-presets.md): Returns Tella's built-in text styles and the authenticated user's saved text presets — the tiles the editor's Text panel shows. Pass a presetId as `presetId` when adding or updating a text overlay to style it in one call; `fontSizeScale` is relative to the editor's default size so a preset reads the… - [Save a text preset](https://www.tella.com/docs/api-reference/clips/save-a-text-preset.md): Saves a personal text preset, like the editor's "Save style" on a text overlay. The style starts from an existing text overlay when `videoId` and `textOverlayId` are given (keeping a custom font and reading the size relative to that video's canvas), else from the editor's default text look; every st… - [Delete a text preset](https://www.tella.com/docs/api-reference/clips/delete-a-text-preset.md): Deletes one of the authenticated user's saved text presets. Built-in `default:` presets can't be deleted. Text overlays already styled with the preset keep their look. - [List clips for a video](https://www.tella.com/docs/api-reference/clips/list-clips-for-a-video.md): Returns the clips of a video in playback order. - [Add a clip from an uploaded source](https://www.tella.com/docs/api-reference/clips/add-a-clip-from-an-uploaded-source.md): Add a new clip to a video. Create a source via `POST /v1/sources`, PUT the bytes, then pass the returned `sourceId` here. - [Get a clip](https://www.tella.com/docs/api-reference/clips/get-a-clip.md): Returns a single clip in a video. - [Delete a clip](https://www.tella.com/docs/api-reference/clips/delete-a-clip.md): Removes a clip from its video. The underlying recording is preserved. - [Update a clip](https://www.tella.com/docs/api-reference/clips/update-a-clip.md): Update a clip's name, ordering, cuts, background, transition, audio, or frame styling (corner rounding and border style). At least one field must be provided. - [Get audio levels in a clip](https://www.tella.com/docs/api-reference/clips/get-audio-levels-in-a-clip.md): Returns how loud a clip's voice track is over a stretch of its playback timeline (cuts applied, the same times as the transcript and silences endpoints): the peak level in dBFS for each step (0 is full scale; speech is usually above about -30, room tone well below -40; null where there is no audio).… - [Auto-crop a clip's screen recording](https://www.tella.com/docs/api-reference/clips/auto-crop-a-clips-screen-recording.md): Detects the visible content at a frame and applies the recommended crop to the clip's screen recording. The frame time uses the clip playback timeline, with cuts already removed. Existing masks and custom-layout geometry are adjusted with the crop. - [List blurs on a clip](https://www.tella.com/docs/api-reference/clips/list-blurs-on-a-clip.md): Returns the blur masks on a clip. - [Add a blur to a clip](https://www.tella.com/docs/api-reference/clips/add-a-blur-to-a-clip.md): Adds a blur mask to a clip. Targets the footage in the clip's Screen slot at startTimeMs: the screen recording, or b-roll media a layout puts there. - [Remove a blur](https://www.tella.com/docs/api-reference/clips/remove-a-blur.md): Removes a blur mask from a clip. - [Update a blur](https://www.tella.com/docs/api-reference/clips/update-a-blur.md): Update a blur mask's timing, position, or size. Only the fields you send are changed. - [Cut one or more time ranges from a clip](https://www.tella.com/docs/api-reference/clips/cut-one-or-more-time-ranges-from-a-clip.md): Cut one or more time ranges from a clip in a single request. Pass `cuts: [{fromMs, toMs}, ...]` for multiple ranges or the legacy `fromMs`/`toMs` pair for a single range. Overlapping or adjacent ranges are merged into the clip's existing cuts. To clear all cuts, call updateClip with cuts: []. - [Cut clip ranges by transcript word indices](https://www.tella.com/docs/api-reference/clips/cut-clip-ranges-by-transcript-word-indices.md): Cut one or more ranges from a clip by referencing word indices in the transcript. The server reads each word's exact `startTimeMs` / `endTimeMs` and merges the resulting cuts — no padding is applied to word boundaries. - [Duplicate a clip](https://www.tella.com/docs/api-reference/clips/duplicate-a-clip.md): Duplicates an existing clip in its video. By default the new clip is inserted right after the source. - [Get clip color filters](https://www.tella.com/docs/api-reference/clips/get-clip-color-filters.md): Get the editor's Style → Filters settings for a clip's camera and screen recordings, including presets, sliders and LUTs. - [Set clip color filters](https://www.tella.com/docs/api-reference/clips/set-clip-color-filters.md): Grade camera, screen or both. Only supplied fields change. A preset replaces the entire filter first. Pass null to remove a filter. Apply to each clip to grade a whole video, and check the result with a clip frame preview. - [List highlights on a clip](https://www.tella.com/docs/api-reference/clips/list-highlights-on-a-clip.md): Returns the highlight masks on a clip. - [Add a highlight to a clip](https://www.tella.com/docs/api-reference/clips/add-a-highlight-to-a-clip.md): Adds a highlight mask to a clip. Targets the footage in the clip's Screen slot at startTimeMs: the screen recording, or b-roll media a layout puts there. - [Remove a highlight](https://www.tella.com/docs/api-reference/clips/remove-a-highlight.md): Removes a highlight mask from a clip. - [Update a highlight](https://www.tella.com/docs/api-reference/clips/update-a-highlight.md): Update a highlight mask's timing, position, or size. Only the fields you send are changed. - [List layouts on a clip](https://www.tella.com/docs/api-reference/clips/list-layouts-on-a-clip.md): Returns the layouts (sections) attached to a clip. - [Add a layout to a clip](https://www.tella.com/docs/api-reference/clips/add-a-layout-to-a-clip.md): Adds a layout to a clip. Provide both startTimeMs and durationMs for a time-ranged layout, or omit both for a clip-spanning layout. - [Auto-generate layouts with AI](https://www.tella.com/docs/api-reference/clips/auto-generate-layouts-with-ai.md): Deprecated: lay clips out with the `tella-auto-layouts` agent skill (`npx skills add tellahq/skills`), which uses the layout endpoints and keeps the clip's camera style and pop-out. This endpoint keeps working for now. Lets AI watch the clip and lay it out — the API twin of the editor's "Auto layout… - [Remove a layout](https://www.tella.com/docs/api-reference/clips/remove-a-layout.md): Removes a layout from a clip. - [Update a layout](https://www.tella.com/docs/api-reference/clips/update-a-layout.md): 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`. - [List mouse events on a clip](https://www.tella.com/docs/api-reference/clips/list-mouse-events-on-a-clip.md): Returns the cursor path and clicks recorded with the clip's screen recording, mapped onto the clip's playback timeline (cuts applied). Positions are percentages of the screen recording's dimensions — the same coordinate space as zoom focus points. Events during cut-out footage are dropped, and move… - [List overlays on a clip](https://www.tella.com/docs/api-reference/clips/list-overlays-on-a-clip.md): Returns the image and video overlays on a clip. - [Add an overlay to a clip](https://www.tella.com/docs/api-reference/clips/add-an-overlay-to-a-clip.md): Adds an image or video overlay to a clip. Upload the bytes via `POST /v1/sources` (`kind: image` or `kind: video`) and pass the `sourceId`; the overlay type follows the source's kind. - [Remove an overlay](https://www.tella.com/docs/api-reference/clips/remove-an-overlay.md): Removes an image or video overlay from a clip. - [Update an overlay](https://www.tella.com/docs/api-reference/clips/update-an-overlay.md): Update an overlay's name, timing, position, or dimensions. Only the fields you send are changed. - [Remove filler words from a clip](https://www.tella.com/docs/api-reference/clips/remove-filler-words-from-a-clip.md): Detects filler words ('um', 'uh', 'hmm', etc.) and adds cuts that bracket each filler. New cuts are merged with any existing cuts. Returns the updated clip. - [Remove silences from a clip](https://www.tella.com/docs/api-reference/clips/remove-silences-from-a-clip.md): Detects silent pauses in the clip's audio and adds cuts that remove them, like the editor's Remove silences tool. `mode` controls aggressiveness: natural cuts pauses longer than 800ms, fast longer than 500ms, faster longer than 300ms (default natural). New cuts are merged with any existing cuts. Ret… - [Reorder a clip](https://www.tella.com/docs/api-reference/clips/reorder-a-clip.md): Moves a clip to a new position within its video. Other clips are renumbered to keep ordering contiguous. - [Get silent ranges in a clip](https://www.tella.com/docs/api-reference/clips/get-silent-ranges-in-a-clip.md): Returns silent ranges in a clip's audio, in ms on the clip's playback timeline (cuts applied) — pass ranges directly to the cut endpoint. Silences already removed by cuts are not reported. - [List sound effects on a clip](https://www.tella.com/docs/api-reference/clips/list-sound-effects-on-a-clip.md): Returns the sound effects (audio overlays) on a clip. - [Add a sound effect to a clip](https://www.tella.com/docs/api-reference/clips/add-a-sound-effect-to-a-clip.md): Adds a sound effect to a clip from Tella's curated catalog (`presetId`) or your own audio (`sourceId`). - [Remove a sound effect](https://www.tella.com/docs/api-reference/clips/remove-a-sound-effect.md): Removes a sound effect from a clip. - [Update a sound effect](https://www.tella.com/docs/api-reference/clips/update-a-sound-effect.md): Update a sound effect's name, timing, or volume. Only the fields you send are changed. - [List sources for a clip](https://www.tella.com/docs/api-reference/clips/list-sources-for-a-clip.md): Returns the underlying sources used by a clip's layers, each with the volume it plays at in this clip. - [Get a source thumbnail or animated preview](https://www.tella.com/docs/api-reference/clips/get-a-source-thumbnail-or-animated-preview.md): Get a thumbnail of a source. If you pass `width`/`height`, the aspect ratio must match the source's native ratio. Omit both to default to the source's native size. - [Get the audio waveform JSON for a source](https://www.tella.com/docs/api-reference/clips/get-the-audio-waveform-json-for-a-source.md): Returns the audio waveform JSON for a source in BBC audiowaveform format. Use the `data` array to render a custom waveform visualization. - [Get a clip storyboard](https://www.tella.com/docs/api-reference/clips/get-a-clip-storyboard.md): Returns a signed 4x4 WebP storyboard whose 16 tiles are sampled evenly across the requested window (`durationMs`/16 apart; every 5 seconds for the default 80s window) from a rendered clip, including its layouts, b-roll, zooms, and masks. `startTimeMs` is on the clip's playback timeline (cuts applied… - [List text overlays on a clip](https://www.tella.com/docs/api-reference/clips/list-text-overlays-on-a-clip.md): Returns the text overlays on a clip. - [Add a text overlay to a clip](https://www.tella.com/docs/api-reference/clips/add-a-text-overlay-to-a-clip.md): Adds a text overlay to a clip. Nothing needs uploading — pass the copy directly. Font, color, position and size all fall back to the editor's defaults. - [Remove a text overlay](https://www.tella.com/docs/api-reference/clips/remove-a-text-overlay.md): Removes a text overlay from a clip. - [Update a text overlay](https://www.tella.com/docs/api-reference/clips/update-a-text-overlay.md): Update a text overlay's copy, font, color, timing, position, or dimensions. Only the fields you send are changed. - [Get a clip thumbnail or animated preview](https://www.tella.com/docs/api-reference/clips/get-a-clip-thumbnail-or-animated-preview.md): Returns a signed CDN URL for a still image (jpg/png/webp) or animated preview (gif/mp4) of a clip — the rendered composite with the clip's layouts, zooms, and masks. By default returns a 302 redirect to the URL — set `?response=json` to get `{url}` JSON instead. `startTimeMs` is on the clip's playba… - [Get clip transcript](https://www.tella.com/docs/api-reference/clips/get-clip-transcript.md): Returns the words spoken in a clip with cuts applied — what viewers actually hear. Times are in ms relative to the clip's playback start. Word indices are stable identifiers for cut-by-transcript; they don't shift when cuts change. Pass `startTimeMs`/`endTimeMs` to read a long clip in windows; a wor… - [Correct transcript words](https://www.tella.com/docs/api-reference/clips/correct-transcript-words.md): Correct what a clip's transcript says, one or more words at a time (at most 100 per request). Each edit addresses a word by its transcript `index` and sets either `text` (the corrected wording, which also unhides the word) or `hidden` (whether the word appears in captions and subtitles). Edits chang… - [List zooms on a clip](https://www.tella.com/docs/api-reference/clips/list-zooms-on-a-clip.md): Returns the zoom effects on a clip. - [Add a zoom to a clip](https://www.tella.com/docs/api-reference/clips/add-a-zoom-to-a-clip.md): Adds a zoom to the footage in the clip's Screen slot at startTimeMs — the screen recording, or b-roll media a layout puts there (the camera is unaffected). Use `manualZoom` with a `focusPoint`, or `trackingZoom` to follow the cursor. - [Auto-generate zooms from mouse activity](https://www.tella.com/docs/api-reference/clips/auto-generate-zooms-from-mouse-activity.md): Generates tracking zooms from the mouse clicks in the clip's screen recording — the API twin of the editor's "Generate zooms". Every click opens a zoom window; nearby windows are merged. Requires the clip to contain a screen recording; returns an empty list when it has no usable mouse clicks. - [Remove a zoom](https://www.tella.com/docs/api-reference/clips/remove-a-zoom.md): Removes a zoom effect from a clip. - [Update a zoom](https://www.tella.com/docs/api-reference/clips/update-a-zoom.md): Update a zoom's type, timing, focus point, or scale. Only the fields you send are changed. #### Webhooks - [List webhook endpoints](https://www.tella.com/docs/api-reference/webhooks/list-webhook-endpoints.md): Lists the webhook subscriptions owned by the authenticated API key's user. Endpoints are scoped per user rather than shared across the workspace. Events are routed to the user context that emits them; playlist.video_added is delivered to the user who adds the video, who may be a playlist editor rath… - [Create a webhook endpoint](https://www.tella.com/docs/api-reference/webhooks/create-a-webhook-endpoint.md): Creates a new webhook endpoint owned by the authenticated API key's user. Events are routed to the user context that emits them; playlist.video_added is delivered to the user who adds the video, who may be a playlist editor rather than its owner. Returns the endpoint ID and signing secret. - [Delete a webhook endpoint](https://www.tella.com/docs/api-reference/webhooks/delete-a-webhook-endpoint.md): Permanently deletes a webhook endpoint - [Update a webhook endpoint](https://www.tella.com/docs/api-reference/webhooks/update-a-webhook-endpoint.md): Updates the delivery URL, subscribed event types, or delivery status for a webhook endpoint. - [Get endpoint signing secret](https://www.tella.com/docs/api-reference/webhooks/get-endpoint-signing-secret.md): Retrieves the signing secret for a webhook endpoint. Use this to verify incoming webhook payloads. - [List recent webhook messages](https://www.tella.com/docs/api-reference/webhooks/list-recent-webhook-messages.md): Returns a list of recently sent webhook messages for debugging purposes - [Get a specific webhook message](https://www.tella.com/docs/api-reference/webhooks/get-a-specific-webhook-message.md): Returns details of a specific webhook message by ID ### Webhooks #### Videos - [Export ready](https://www.tella.com/docs/api-reference/videos/export-ready.md): Triggered when a video export completes and is ready for download. - [Transcript ready](https://www.tella.com/docs/api-reference/videos/transcript-ready.md): Triggered when a video's transcript has been generated and is ready. - [Video created](https://www.tella.com/docs/api-reference/videos/video-created.md): Triggered when a new video is created in your workspace. - [View milestone reached](https://www.tella.com/docs/api-reference/videos/view-milestone-reached.md): Triggered when a video's view count crosses a threshold of 1, 5, 10, 25, 50, 100, or 500. - [Video viewed](https://www.tella.com/docs/api-reference/videos/video-viewed.md): Triggered for each view received on one of your videos. #### Playlists - [Playlist created](https://www.tella.com/docs/api-reference/playlists/playlist-created.md): Triggered when a new playlist is created in your workspace. - [Video added to playlist](https://www.tella.com/docs/api-reference/playlists/video-added-to-playlist.md): Triggered when a video is added to a playlist. ## OpenAPI Specs - [openapi](/docs/openapi.json) - [webhooks](/docs/webhooks.json)