> ## 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. # Get a video's timeline > 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 every response. Use `include=all` for the complete edit state. Effect and word times are ms on each clip's playback timeline (cuts applied). Raw cuts retain the source-recording timing used by the clip endpoints. ## OpenAPI ````yaml /openapi.json get /v1/videos/{id}/timeline 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: Personal, workspace, and default video backgrounds name: Backgrounds - description: >- Reusable media saved to a workspace, plus Tella's curated sound effect catalog — the same items the editor's media panels show name: Library - description: Webhook endpoint management name: Webhooks paths: /v1/videos/{id}/timeline: get: tags: - Videos summary: Get a video's timeline description: >- 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 every response. Use `include=all` for the complete edit state. Effect and word times are ms on each clip's playback timeline (cuts applied). Raw cuts retain the source-recording timing used by the clip endpoints. operationId: getVideoTimeline parameters: - description: Unique video identifier in: path name: id required: true schema: description: Unique video identifier example: vid_abc123def456 type: string - description: >- Comma-separated clip IDs to return details for. The complete ordered clip outline is always returned. in: query name: clipIds schema: description: >- Comma-separated clip IDs to return details for. The complete ordered clip outline is always returned. example: scn_abc123,scn_def456 type: string - description: >- Comma-separated details to include: all, settings, chapters, backgroundMusic, clipSettings, cuts, layouts, zooms, blurs, highlights, overlays, textOverlays, soundEffects, transcript, words. Default: none. in: query name: include schema: description: >- Comma-separated details to include: all, settings, chapters, backgroundMusic, clipSettings, cuts, layouts, zooms, blurs, highlights, overlays, textOverlays, soundEffects, transcript, words. Default: none. example: layouts,zooms,words type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GetTimelineResponse' description: The video's edit state '400': $ref: '#/components/responses/400ErrorResponse' '401': $ref: '#/components/responses/401ErrorResponse' '403': $ref: '#/components/responses/403ErrorResponse' '404': $ref: '#/components/responses/404ErrorResponse' '422': $ref: '#/components/responses/422ErrorResponse' '429': $ref: '#/components/responses/429ErrorResponse' '500': $ref: '#/components/responses/500ErrorResponse' security: - BearerAuth: [] components: schemas: GetTimelineResponse: additionalProperties: false description: >- A compact video timeline with optional video-level and clip-level details properties: clips: description: Complete clip outline in playback order items: $ref: '#/components/schemas/TimelineClip' type: array details: allOf: - $ref: '#/components/schemas/TimelineDetails' description: Present only when at least one detail category is requested included: description: Detail categories included in this response items: enum: - settings - chapters - backgroundMusic - clipSettings - cuts - layouts - zooms - blurs - highlights - overlays - textOverlays - soundEffects - transcript - words type: string type: array video: $ref: '#/components/schemas/TimelineVideo' required: - video - clips - included type: object TimelineClip: additionalProperties: false description: A compact clip entry in the video's ordered timeline properties: contents: $ref: '#/components/schemas/TimelineContentCounts' durationMs: description: Clip playback duration in ms, with cuts removed minimum: 0 type: number id: type: string name: type: string order: maximum: 9007199254740991 minimum: -9007199254740991 type: integer timelineStartMs: description: Clip start time in ms on the complete video timeline minimum: 0 type: number required: - id - name - order - timelineStartMs - durationMs - contents type: object TimelineDetails: additionalProperties: false properties: clips: items: $ref: '#/components/schemas/TimelineClipDetails' type: array video: allOf: - $ref: '#/components/schemas/TimelineVideoDetails' type: object TimelineVideo: additionalProperties: false description: Minimal video timeline summary properties: aspectRatio: example: '16:9' type: string description: maxLength: 5000 type: string dimensions: additionalProperties: false properties: height: description: Canvas height in pixels type: number width: description: Canvas width in pixels type: number required: - width - height type: object durationMs: description: Total playback duration in ms minimum: 0 type: number id: type: string name: type: string updatedAt: description: ISO-8601 timestamp of the video version represented type: string required: - id - name - description - updatedAt - aspectRatio - dimensions - durationMs 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 TimelineContentCounts: additionalProperties: false properties: blurs: maximum: 9007199254740991 minimum: 0 type: integer cuts: maximum: 9007199254740991 minimum: 0 type: integer highlights: maximum: 9007199254740991 minimum: 0 type: integer layouts: maximum: 9007199254740991 minimum: 0 type: integer overlays: maximum: 9007199254740991 minimum: 0 type: integer soundEffects: maximum: 9007199254740991 minimum: 0 type: integer textOverlays: maximum: 9007199254740991 minimum: 0 type: integer transcriptWords: description: >- Number of transcript words on the clip playback timeline, including hidden words. Null when transcript data could not be read. maximum: 9007199254740991 minimum: 0 nullable: true type: integer zooms: maximum: 9007199254740991 minimum: 0 type: integer required: - cuts - layouts - zooms - blurs - highlights - overlays - textOverlays - soundEffects - transcriptWords type: object TimelineClipDetails: additionalProperties: false description: Only the explicitly requested detail fields are present properties: background: allOf: - $ref: '#/components/schemas/ClipBackgroundOutput' blurs: items: $ref: '#/components/schemas/ClipMask' type: array clipId: type: string cuts: description: Raw cut definitions in ms of the source recording, matching get_clip items: $ref: '#/components/schemas/CutOutput' type: array highlights: items: $ref: '#/components/schemas/ClipMask' type: array layoutSceneType: allOf: - $ref: '#/components/schemas/LayoutSceneType' layouts: items: $ref: '#/components/schemas/ClipLayout' type: array microphoneVolume: description: >- Clip microphone volume override: a number when overridden, null when following the video, absent when there is no microphone audio maximum: 2 minimum: 0 nullable: true type: number overlays: items: $ref: '#/components/schemas/ClipOverlay' type: array soundEffects: items: $ref: '#/components/schemas/ClipSoundEffect' type: array studioSound: description: >- Effective Studio Sound state: the video-level switch minus this clip's opt-out type: boolean systemAudioVolume: description: >- Clip system audio override: a number when overridden, null when following the video, absent when there is no system audio maximum: 2 minimum: 0 nullable: true type: number textOverlays: items: $ref: '#/components/schemas/ClipTextOverlay' type: array transcript: allOf: - $ref: '#/components/schemas/TimelineTranscript' words: description: >- Words in ms on the clip playback timeline. Includes hidden words so indices remain usable with transcript editing endpoints. Null when transcript data could not be read. items: $ref: '#/components/schemas/TranscriptWord' nullable: true type: array zooms: items: $ref: '#/components/schemas/ClipZoom' type: array required: - clipId type: object TimelineVideoDetails: additionalProperties: false properties: backgroundMusic: allOf: - $ref: '#/components/schemas/BackgroundMusic' nullable: true chapters: items: $ref: '#/components/schemas/Chapter' type: array settings: allOf: - $ref: '#/components/schemas/VideoSettings' 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`, or type = 'gradient' with `gradientColor1`, `gradientColor2`, `gradientAngle`. 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 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 enum: - solid - gradient - image - video 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 ClipMask: additionalProperties: false description: >- A blur or highlight mask on a clip. Times are in ms on the clip's playback timeline (cuts applied). Internally the mask stays anchored to the footage, so it doesn't drift when cuts change later. properties: dimensions: $ref: '#/components/schemas/MaskDimensionsOutput' durationMs: example: 2000 minimum: 0 type: number id: description: Mask ID example: ly_abc123 type: string point: $ref: '#/components/schemas/MaskPointOutput' startTimeMs: description: Start time in ms on the clip's playback timeline (cuts applied) example: 1000 minimum: 0 type: number type: enum: - blur - highlight example: blur type: string required: - id - type - startTimeMs - durationMs - point - dimensions type: object CutOutput: additionalProperties: false description: >- A range of the raw recording removed from playback. Cut definitions are the one place raw-recording coordinates appear: replacing the cut set describes the playback timeline you'd get after clearing all cuts. Cuts are always undoable — replace with `[]` to restore everything. properties: durationMs: description: Length of the cut, in milliseconds example: 750 exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer startTimeMs: description: Start of the cut, in ms of the raw recording example: 1500 maximum: 9007199254740991 minimum: 0 type: integer required: - startTimeMs - durationMs type: object LayoutSceneType: description: >- How a clip composes its layers, which determines the set of layouts it accepts: `basicSubject` (screen-only), `cameraSubject` (camera-only), or `combi` (camera + presentation). enum: - basicSubject - cameraSubject - combi example: combi 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 ClipOverlay: additionalProperties: false description: An image or video overlay on a clip. properties: dimensions: $ref: '#/components/schemas/OverlayDimensionsOutput' durationMs: example: 5000 minimum: 0 type: number id: description: Overlay ID example: ly_abc123 type: string imageUrl: description: >- Hosted image URL, for image overlays. Read-only: not accepted as input — pass `sourceId` instead. nullable: true type: string name: example: Logo nullable: true type: string point: $ref: '#/components/schemas/OverlayPointOutput' sourceId: description: Source ID the overlay was created from. example: su_abc123 nullable: true type: string startTimeMs: description: >- Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript. example: 1000 minimum: 0 type: number type: enum: - image - video example: image type: string required: - id - type - startTimeMs - durationMs - point - dimensions type: object ClipSoundEffect: additionalProperties: false description: A sound effect on a clip. properties: durationMs: example: 3000 minimum: 0 type: number id: description: Sound effect ID example: ly_abc123 type: string name: example: Whoosh nullable: true type: string sourceId: example: su_abc123 nullable: true type: string startTimeMs: description: >- Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript. example: 1000 minimum: 0 type: number volume: description: Playback volume (1 = original). example: 1 type: number required: - id - startTimeMs - durationMs - volume type: object ClipTextOverlay: additionalProperties: false description: >- A text overlay on a clip. Unlike image and video overlays it references no source — the copy and its font live on the overlay itself. properties: background: allOf: - $ref: '#/components/schemas/TextOverlayBackgroundOutput' description: >- Background behind the text. Overlays with no visible box report a solid #00000000. backgroundShape: $ref: '#/components/schemas/TextOverlayBackgroundShape' 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 dimensions: $ref: '#/components/schemas/OverlayDimensionsOutput' durationMs: example: 5000 minimum: 0 type: number fontFamily: description: >- The overlay's font family. Normally one of the catalog families accepted on write, but overlays created before that catalog can report another bundled family, such as `Graphik`. example: Inter type: string fontSize: description: >- Font size in artboard pixels — absolute, like `dimensions`, so text keeps its size relative to the frame. Renderers scale it by their render scale factor. example: 81 exclusiveMinimum: true minimum: 0 type: number fontWeight: description: Variable-font weight axis — 100 (thin) to 900 (black). example: 500 type: number fontWidth: description: >- Variable-font width axis, as a percentage — 100 is normal, 50 ultra-condensed, 150 extra-expanded. example: 100 type: number id: description: Text overlay ID example: ly_abc123 type: string point: $ref: '#/components/schemas/OverlayPointOutput' startTimeMs: description: >- Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript. example: 1000 minimum: 0 type: number text: example: Welcome back type: string textAlign: $ref: '#/components/schemas/TextOverlayTextAlign' required: - id - text - fontFamily - fontSize - color - fontWeight - fontWidth - textAlign - background - backgroundShape - startTimeMs - durationMs - point - dimensions type: object TimelineTranscript: additionalProperties: false description: Null when the clip has no speech or its transcript is unavailable nullable: true properties: text: description: Visible transcript text type: string wordCount: maximum: 9007199254740991 minimum: 0 type: integer required: - text - wordCount type: object TranscriptWord: additionalProperties: false description: A single transcribed word properties: endTimeMs: description: Word end time, in ms on the clip's playback timeline example: 1800 minimum: 0 type: number hidden: description: Whether the word is hidden by an edit example: false type: boolean index: description: Stable index of the word in the source recording example: 12 maximum: 9007199254740991 minimum: 0 type: integer startTimeMs: description: Word start time, in ms on the clip's playback timeline example: 1500 minimum: 0 type: number text: description: Word text example: Hello type: string required: - index - startTimeMs - endTimeMs - text - hidden type: object ClipZoom: additionalProperties: false description: >- A zoom effect applied to the clip's screen layer (does not affect the camera). Use `manualZoom` with a `focusPoint`, or `trackingZoom` to follow the cursor automatically. Times are in ms on the clip's playback timeline (cuts applied). Internally the zoom stays anchored to the footage, so it doesn't drift when cuts change later. properties: durationMs: description: >- Duration in ms of playback. 0 when the zoom's footage is entirely cut out. example: 2000 minimum: 0 type: number focusPoint: allOf: - $ref: '#/components/schemas/ZoomFocusPointOutput' nullable: true id: description: Zoom ID example: ef_abc123 type: string scale: description: Magnification factor (1 = no zoom, 3.5 = max). example: 2 maximum: 3.5 minimum: 1 nullable: true type: number startTimeMs: description: Start time in ms on the clip's playback timeline (cuts applied) example: 1000 minimum: 0 type: number type: description: >- `manualZoom` zooms into a fixed `focusPoint` on the screen. `trackingZoom` automatically follows the cursor in the screen recording. enum: - manualZoom - trackingZoom example: manualZoom type: string required: - id - type - startTimeMs - durationMs type: object BackgroundMusic: additionalProperties: false description: >- One video-wide track that loops over the whole video and is included in exports properties: durationMs: description: Audio track duration in milliseconds example: 180036 exclusiveMinimum: true minimum: 0 type: number name: description: Optional display name for the track example: Calm Product Tour nullable: true type: string url: description: HTTPS URL of the audio track example: https://ucarecdn.com/example-track/ format: uri pattern: ^https:\/\/.* type: string volume: description: Track volume from 0 (silent) to 1 (full volume) example: 0.2 maximum: 1 minimum: 0 type: number required: - url - durationMs - volume - name type: object Chapter: additionalProperties: false description: A chapter/section within a video properties: description: description: Chapter description example: Overview of what we'll cover maxLength: 5000 type: string timestampSeconds: description: Chapter start time in seconds example: 0 minimum: 0 type: number title: description: Chapter title example: Introduction maxLength: 255 minLength: 1 type: string required: - title - description - timestampSeconds type: object VideoSettings: additionalProperties: false description: Video playback and access settings properties: allowedEmbedDomains: description: >- Restrict embedding to these domains only (Premium feature). Empty array allows all domains. example: - example.com - mysite.org items: type: string type: array captionGrouping: description: 'How subtitle text is grouped: sentence chunks or one word at a time.' enum: - chunked - singleWord example: chunked type: string captionPosition: allOf: - $ref: '#/components/schemas/CaptionPosition' description: >- Normalized subtitle position, or null for automatic placement. Applies if subtitles are enabled on the video. nullable: true captionSize: description: Subtitle text size. Applies if subtitles are enabled on the video. enum: - small - medium - large example: medium type: string captionStyle: $ref: '#/components/schemas/CaptionStyle' captionsDefaultEnabled: description: Show subtitles to viewers by default example: true type: boolean commentEmailsEnabled: description: Send email notifications for new comments example: false type: boolean commentsEnabled: description: Allow viewers to comment example: true type: boolean customThumbnailURL: description: Custom thumbnail image URL example: https://example.com/custom-thumbnail.jpg format: uri nullable: true type: string defaultPlaybackRate: description: Default playback speed (0.5-2.0). Viewers can still adjust. example: 1 maximum: 2 minimum: 0.5 type: number downloadsEnabled: description: Allow viewers to download the video example: true type: boolean linkScope: allOf: - $ref: '#/components/schemas/VideoSettingsLinkScope' description: Current access level, including `org` for workspace-visible videos microphoneVolume: description: >- Volume of the microphone (webcam) audio across the video. 1 is the recorded level, 0 mutes it, 2 doubles it. A clip can override it for one of its sources. example: 1 maximum: 2 minimum: 0 type: number publishDateEnabled: description: Show publish date on video page example: true type: boolean rawDownloadsEnabled: description: Allow viewers to download raw source files example: false type: boolean searchEngineIndexingEnabled: description: Allow search engines to index the video page example: true type: boolean studioSound: description: >- Studio Sound (AI audio enhancement) master switch for the video. Individual clips can opt out via the clip's `studioSound` field. example: false type: boolean subtitlesEnabled: description: Allow viewers to enable subtitles example: true type: boolean systemAudioVolume: description: >- Volume of the system/screen audio across the video — everything that is not microphone audio. 1 is the recorded level, 0 mutes it, 2 doubles it. A clip can override it for one of its sources. example: 1 maximum: 2 minimum: 0 type: number transcriptsEnabled: description: Show transcript panel to viewers example: true type: boolean viewCountEnabled: description: Show view count on video page example: true type: boolean required: - defaultPlaybackRate - captionsDefaultEnabled - subtitlesEnabled - captionStyle - captionSize - captionGrouping - captionPosition - transcriptsEnabled - publishDateEnabled - viewCountEnabled - commentsEnabled - commentEmailsEnabled - downloadsEnabled - rawDownloadsEnabled - linkScope - searchEngineIndexingEnabled - allowedEmbedDomains - customThumbnailURL - studioSound - microphoneVolume - systemAudioVolume type: object MaskDimensionsOutput: additionalProperties: false description: Size of the masked rectangle (percentages) properties: heightPct: example: 50 maximum: 100 minimum: 0 type: number widthPct: example: 50 maximum: 100 minimum: 0 type: number required: - widthPct - heightPct type: object MaskPointOutput: additionalProperties: false description: Top-left corner of the masked rectangle (percentages) properties: xPct: example: 25 maximum: 100 minimum: 0 type: number yPct: example: 25 maximum: 100 minimum: 0 type: number required: - xPct - yPct type: object ClipLayoutShape: description: >- Structured layout description, discriminated by `kind`. Valid kinds depend on the clip's `layoutSceneType` and the video'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 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 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 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 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 TextOverlayBackgroundOutput: additionalProperties: false description: >- Background behind a text overlay, in the same object shape as a clip background. properties: color: description: >- Hex color string. Required when type = 'solid'. Transparent backgrounds use #00000000. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string type: description: >- Background variant. Text overlays take a solid background; the other `ClipBackground` variants are not supported behind text. enum: - solid example: solid type: string required: - type - color type: object TextOverlayBackgroundShape: description: Shape of the solid background behind the text. enum: - none - regular - squircle example: squircle type: string TextOverlayTextAlign: description: Horizontal alignment of the text inside its overlay box. enum: - left - center - right example: center type: string ZoomFocusPointOutput: additionalProperties: false description: >- Point on the screen recording to zoom into, expressed as percentages of the screen dimensions. Required for `manualZoom`; ignored for `trackingZoom`. properties: xPct: description: Horizontal position on the screen frame (0-100). 0 = left edge. example: 50 maximum: 100 minimum: 0 type: number yPct: description: Vertical position on the screen frame (0-100). 0 = top edge. example: 50 maximum: 100 minimum: 0 type: number required: - xPct - yPct type: object CaptionPosition: additionalProperties: false description: >- Normalized subtitle position. Applies if subtitles are enabled on the video. Null uses automatic placement. properties: x: maximum: 1 minimum: 0 type: number 'y': maximum: 1 minimum: 0 type: number required: - x - 'y' type: object CaptionStyle: description: >- Subtitle style. Applies if subtitles are enabled on the video. Every style-specific field is required and fields from other styles are rejected. discriminator: mapping: backdrop: $ref: '#/components/schemas/BackdropCaptionStyle' cannes: $ref: '#/components/schemas/CannesCaptionStyle' classic: $ref: '#/components/schemas/ClassicCaptionStyle' highlight: $ref: '#/components/schemas/HighlightCaptionStyle' mono: $ref: '#/components/schemas/MonoCaptionStyle' propertyName: name oneOf: - $ref: '#/components/schemas/BackdropCaptionStyle' - $ref: '#/components/schemas/HighlightCaptionStyle' - $ref: '#/components/schemas/MonoCaptionStyle' - $ref: '#/components/schemas/CannesCaptionStyle' - $ref: '#/components/schemas/ClassicCaptionStyle' type: object VideoSettingsLinkScope: description: >- Current video access level. The read-only `org` value means the video is visible across its workspace; public updates intentionally do not accept that value. enum: - public - private - org - password - embedonly example: org type: string 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 BackdropCaptionStyle: additionalProperties: false properties: backgroundColor: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string name: enum: - backdrop type: string textColor: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string wordLevelHighlights: type: boolean required: - name - backgroundColor - textColor - wordLevelHighlights title: Backdrop type: object CannesCaptionStyle: additionalProperties: false properties: name: enum: - cannes type: string shadowColor: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string textColor: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string required: - name - textColor - shadowColor title: Cannes type: object ClassicCaptionStyle: additionalProperties: false properties: name: enum: - classic type: string outlineColor: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string textColor: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string required: - name - textColor - outlineColor title: Classic type: object HighlightCaptionStyle: additionalProperties: false properties: highlightColor: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string name: enum: - highlight type: string primaryTextColor: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string secondaryTextColor: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string required: - name - primaryTextColor - secondaryTextColor - highlightColor title: Highlight type: object MonoCaptionStyle: additionalProperties: false properties: highlightColor: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string name: enum: - mono type: string textColor: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string required: - name - textColor - highlightColor title: Mono type: object responses: 400ErrorResponse: 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. 401ErrorResponse: 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. 403ErrorResponse: 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. 404ErrorResponse: 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. 422ErrorResponse: 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. 429ErrorResponse: 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. 500ErrorResponse: 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. securitySchemes: BearerAuth: description: API key obtained from your Tella account settings scheme: bearer type: http ```` ## Related topics - [Get video chapters](/docs/api-reference/videos/get-video-chapters.md) - [Get a video thumbnail or animated preview](/docs/api-reference/videos/get-a-video-thumbnail-or-animated-preview.md) - [Model Context Protocol (MCP)](/docs/mcp-server.md) - [Get video information](/docs/api-reference/videos/get-video-information.md) - [Get video export status](/docs/api-reference/videos/get-video-export-status.md)