> ## 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. # Apply many video edits > 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. ## OpenAPI ````yaml /openapi.json post /v1/videos/{id}/edits 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 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: 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 externalDocs: description: API versioning and deprecation policy url: https://www.tella.com/docs/versioning paths: /v1/videos/{id}/edits: post: tags: - Videos summary: Apply many video edits description: >- 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. operationId: applyVideoEdits parameters: - description: Unique video identifier in: path name: id required: true schema: description: Unique video identifier example: vid_abc123def456 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ApplyVideoEditsRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ApplyVideoEditsResponse' description: Edits applied 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' '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' security: - BearerAuth: [] components: schemas: ApplyVideoEditsRequest: additionalProperties: false description: >- Add, update, and remove up to 200 sound effects, text overlays, zooms, blurs, highlights, image/video overlays, and layouts in one editor revision. Operations run in array order; the complete batch is validated before anything is applied. Cuts, transcript edits, clip settings, and auto layouts are not batchable. properties: operations: items: $ref: '#/components/schemas/VideoEditOperation' maxItems: 200 minItems: 1 type: array required: - operations type: object ApplyVideoEditsResponse: additionalProperties: false description: >- One result per operation, in request order: the created resource ID for adds, the affected resource ID for updates and removes. properties: results: items: additionalProperties: false properties: id: description: Created or affected resource ID type: string operationId: type: string type: enum: - sound_effect - text_overlay - zoom - blur - highlight - media_overlay - layout type: string required: - operationId - type - id type: object type: array revision: maximum: 9007199254740991 minimum: 0 type: integer required: - revision - results 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 - not_implemented example: not_found type: string message: description: Human-readable error message example: Resource not found type: string required: - error - message - docsUrl type: object VideoEditOperation: description: >- One timeline edit — an add, update, or remove. Operations may target different clips in the same video, and update/remove operations may reference a resource added earlier in the batch by that operation's operationId. discriminator: mapping: add_blur: $ref: '#/components/schemas/BatchAddBlurOperation' add_highlight: $ref: '#/components/schemas/BatchAddHighlightOperation' add_layout: $ref: '#/components/schemas/BatchAddLayoutOperation' add_media_overlay: $ref: '#/components/schemas/BatchAddMediaOverlayOperation' add_sound_effect: $ref: '#/components/schemas/BatchAddSoundEffectOperation' add_text_overlay: $ref: '#/components/schemas/BatchAddTextOverlayOperation' add_zoom: $ref: '#/components/schemas/BatchAddZoomOperation' remove_blur: $ref: '#/components/schemas/BatchRemoveBlurOperation' remove_highlight: $ref: '#/components/schemas/BatchRemoveHighlightOperation' remove_layout: $ref: '#/components/schemas/BatchRemoveLayoutOperation' remove_media_overlay: $ref: '#/components/schemas/BatchRemoveMediaOverlayOperation' remove_sound_effect: $ref: '#/components/schemas/BatchRemoveSoundEffectOperation' remove_text_overlay: $ref: '#/components/schemas/BatchRemoveTextOverlayOperation' remove_zoom: $ref: '#/components/schemas/BatchRemoveZoomOperation' update_blur: $ref: '#/components/schemas/BatchUpdateBlurOperation' update_highlight: $ref: '#/components/schemas/BatchUpdateHighlightOperation' update_layout: $ref: '#/components/schemas/BatchUpdateLayoutOperation' update_media_overlay: $ref: '#/components/schemas/BatchUpdateMediaOverlayOperation' update_sound_effect: $ref: '#/components/schemas/BatchUpdateSoundEffectOperation' update_text_overlay: $ref: '#/components/schemas/BatchUpdateTextOverlayOperation' update_zoom: $ref: '#/components/schemas/BatchUpdateZoomOperation' propertyName: type oneOf: - $ref: '#/components/schemas/BatchAddSoundEffectOperation' - $ref: '#/components/schemas/BatchAddTextOverlayOperation' - $ref: '#/components/schemas/BatchAddZoomOperation' - $ref: '#/components/schemas/BatchAddBlurOperation' - $ref: '#/components/schemas/BatchAddHighlightOperation' - $ref: '#/components/schemas/BatchAddMediaOverlayOperation' - $ref: '#/components/schemas/BatchUpdateZoomOperation' - $ref: '#/components/schemas/BatchRemoveZoomOperation' - $ref: '#/components/schemas/BatchUpdateBlurOperation' - $ref: '#/components/schemas/BatchRemoveBlurOperation' - $ref: '#/components/schemas/BatchUpdateHighlightOperation' - $ref: '#/components/schemas/BatchRemoveHighlightOperation' - $ref: '#/components/schemas/BatchUpdateMediaOverlayOperation' - $ref: '#/components/schemas/BatchRemoveMediaOverlayOperation' - $ref: '#/components/schemas/BatchUpdateTextOverlayOperation' - $ref: '#/components/schemas/BatchRemoveTextOverlayOperation' - $ref: '#/components/schemas/BatchUpdateSoundEffectOperation' - $ref: '#/components/schemas/BatchRemoveSoundEffectOperation' - $ref: '#/components/schemas/BatchAddLayoutOperation' - $ref: '#/components/schemas/BatchUpdateLayoutOperation' - $ref: '#/components/schemas/BatchRemoveLayoutOperation' type: object BatchAddBlurOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string dimensions: $ref: '#/components/schemas/MaskDimensions' durationMs: example: 2000 exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string point: $ref: '#/components/schemas/MaskPoint' startTimeMs: description: Start time in ms on the clip's playback timeline (cuts applied) example: 1000 maximum: 9007199254740991 minimum: 0 type: integer type: enum: - add_blur type: string required: - type - operationId - clipId - startTimeMs - durationMs - point - dimensions type: object BatchAddHighlightOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string dimensions: $ref: '#/components/schemas/MaskDimensions' durationMs: example: 2000 exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string point: $ref: '#/components/schemas/MaskPoint' startTimeMs: description: Start time in ms on the clip's playback timeline (cuts applied) example: 1000 maximum: 9007199254740991 minimum: 0 type: integer type: enum: - add_highlight type: string required: - type - operationId - clipId - startTimeMs - durationMs - point - dimensions type: object BatchAddLayoutOperation: additionalProperties: false description: >- Add a layout. With startTimeMs and durationMs, overlapping layouts are trimmed, split, or removed to make room, exactly like the single-call add; without them the clip's base layout is set and the result ID is `base`. properties: clipId: description: Clip ID minLength: 1 type: string durationMs: description: >- Optional. Provide together with startTimeMs for a time-ranged layout. Minimum 200ms. maximum: 9007199254740991 minimum: 200 type: integer layout: allOf: - $ref: '#/components/schemas/ClipLayoutShape' description: >- Layout shape. May be omitted when media is provided to use the default full-frame B-roll layout. media: allOf: - $ref: '#/components/schemas/ClipMedia' description: >- Optional media content to show during this layout. Only valid on time-ranged layouts. operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string startTimeMs: description: >- Optional. Provide together with durationMs for a time-ranged layout. In ms on the clip's playback timeline (cuts applied). maximum: 9007199254740991 minimum: 0 type: integer transitionStyle: allOf: - $ref: '#/components/schemas/LayoutTransitionStyle' description: >- Optional. Only valid on time-ranged layouts. Defaults to the user's saved layout intro transition when omitted. The user's saved layout outro transition is applied when the following layout begins or resumes. type: enum: - add_layout type: string required: - type - operationId - clipId type: object BatchAddMediaOverlayOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string dimensions: allOf: - $ref: '#/components/schemas/OverlayDimensions' durationMs: example: 5000 exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer name: example: Logo type: string operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string point: allOf: - $ref: '#/components/schemas/OverlayPoint' sourceId: description: >- Source ID from `POST /v1/sources` (`kind: image` or `kind: video`). The overlay type follows the source's kind. example: su_abc123 type: string startTimeMs: description: >- Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript. example: 1000 maximum: 9007199254740991 minimum: 0 type: integer type: enum: - add_media_overlay type: string required: - type - operationId - clipId - sourceId - startTimeMs - durationMs type: object BatchAddSoundEffectOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string durationMs: example: 3000 exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer name: example: Whoosh type: string operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string presetId: description: >- Preset ID of a curated Tella sound effect, from a `default` item in `GET /v1/library?scope=default`. Placing one copies the effect into a source owned by your workspace, so nothing needs uploading. Mutually exclusive with `sourceId`; exactly one is required. example: cha-ching type: string sourceId: description: >- Source ID for the audio, from `POST /v1/sources` (`kind: audio` with the audio's duration) or from a `private`/`workspace` item in `GET /v1/library?type=sound-effect`. When uploading, send the audio file as-is — MP3, WAV, M4A, … — no need to wrap it in an MP4. Mutually exclusive with `presetId`; exactly one is required. example: su_abc123 type: string startTimeMs: description: >- Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript. example: 1000 maximum: 9007199254740991 minimum: 0 type: integer type: enum: - add_sound_effect type: string volume: description: Playback volume (0 = muted, 1 = original). Defaults to 1. example: 1 minimum: 0 type: number required: - type - operationId - clipId - startTimeMs - durationMs type: object BatchAddTextOverlayOperation: additionalProperties: false properties: background: allOf: - $ref: '#/components/schemas/TextOverlayBackground' description: Background behind the text. Defaults to transparent. backgroundShape: allOf: - $ref: '#/components/schemas/TextOverlayBackgroundShape' description: Defaults to none. clipId: description: Clip ID minLength: 1 type: string color: description: Defaults to white. example: '#FFFFFFFF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string dimensions: allOf: - $ref: '#/components/schemas/OverlayDimensions' durationMs: example: 5000 exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer fontFamily: allOf: - $ref: '#/components/schemas/TextOverlayFontFamily' description: >- One of Tella's catalog font families. Defaults to Inter. Anything outside the catalog is rejected rather than silently falling back. fontSize: description: >- Font size in artboard pixels. Defaults to 7.5% of the video's shorter side, which is the editor's default and readable at any canvas size. example: 81 exclusiveMinimum: true minimum: 0 type: number fontWeight: description: >- Variable-font weight axis — 100 (thin) to 900 (black), 500 by default. Values outside the chosen font's own axis range are clamped when rendered. example: 500 maximum: 1000 minimum: 1 type: number fontWidth: description: >- Variable-font width axis, as a percentage — 100 is normal, 50 ultra-condensed, 150 extra-expanded, 100 by default. Values outside the chosen font's own axis range are clamped when rendered. example: 100 exclusiveMinimum: true minimum: 0 type: number operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string point: allOf: - $ref: '#/components/schemas/OverlayPoint' startTimeMs: description: >- Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript. example: 1000 maximum: 9007199254740991 minimum: 0 type: integer text: example: Welcome back minLength: 1 type: string textAlign: allOf: - $ref: '#/components/schemas/TextOverlayTextAlign' description: Defaults to center. type: enum: - add_text_overlay type: string required: - type - operationId - clipId - text - startTimeMs - durationMs type: object BatchAddZoomOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string durationMs: example: 2000 exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer focusPoint: allOf: - $ref: '#/components/schemas/ZoomFocusPoint' operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string scale: description: >- Magnification factor (1 = no zoom, 3.5 = max). Required — a zoom without a scale cannot be rendered. example: 2 maximum: 3.5 minimum: 1 type: number startTimeMs: description: Start time in ms on the clip's playback timeline (cuts applied) example: 1000 maximum: 9007199254740991 minimum: 0 type: integer type: enum: - add_zoom type: string zoomType: description: 'Zoom variant: manualZoom or trackingZoom.' enum: - manualZoom - trackingZoom example: manualZoom type: string required: - type - operationId - clipId - zoomType - startTimeMs - durationMs - scale type: object BatchRemoveBlurOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string maskId: description: >- Blur ID, or the operationId of an add operation earlier in this batch. minLength: 1 type: string operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string type: enum: - remove_blur type: string required: - type - operationId - clipId - maskId type: object BatchRemoveHighlightOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string maskId: description: >- Highlight ID, or the operationId of an add operation earlier in this batch. minLength: 1 type: string operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string type: enum: - remove_highlight type: string required: - type - operationId - clipId - maskId type: object BatchRemoveLayoutOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string layoutId: description: >- Layout ID, or the operationId of an add operation earlier in this batch. minLength: 1 type: string operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string type: enum: - remove_layout type: string required: - type - operationId - clipId - layoutId type: object BatchRemoveMediaOverlayOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string overlayId: description: >- Overlay ID, or the operationId of an add operation earlier in this batch. minLength: 1 type: string type: enum: - remove_media_overlay type: string required: - type - operationId - clipId - overlayId type: object BatchRemoveSoundEffectOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string soundEffectId: description: >- Sound effect ID, or the operationId of an add operation earlier in this batch. minLength: 1 type: string type: enum: - remove_sound_effect type: string required: - type - operationId - clipId - soundEffectId type: object BatchRemoveTextOverlayOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string textOverlayId: description: >- Text overlay ID, or the operationId of an add operation earlier in this batch. minLength: 1 type: string type: enum: - remove_text_overlay type: string required: - type - operationId - clipId - textOverlayId type: object BatchRemoveZoomOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string type: enum: - remove_zoom type: string zoomId: description: >- Zoom ID, or the operationId of an add operation earlier in this batch. minLength: 1 type: string required: - type - operationId - clipId - zoomId type: object BatchUpdateBlurOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string dimensions: allOf: - $ref: '#/components/schemas/MaskDimensions' durationMs: exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer maskId: description: >- Blur ID, or the operationId of an add operation earlier in this batch. minLength: 1 type: string operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string point: allOf: - $ref: '#/components/schemas/MaskPoint' startTimeMs: description: Start time in ms on the clip's playback timeline (cuts applied) maximum: 9007199254740991 minimum: 0 type: integer type: enum: - update_blur type: string required: - type - operationId - clipId - maskId type: object BatchUpdateHighlightOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string dimensions: allOf: - $ref: '#/components/schemas/MaskDimensions' durationMs: exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer maskId: description: >- Highlight ID, or the operationId of an add operation earlier in this batch. minLength: 1 type: string operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string point: allOf: - $ref: '#/components/schemas/MaskPoint' startTimeMs: description: Start time in ms on the clip's playback timeline (cuts applied) maximum: 9007199254740991 minimum: 0 type: integer type: enum: - update_highlight type: string required: - type - operationId - clipId - maskId type: object BatchUpdateLayoutOperation: additionalProperties: false description: >- Update a layout. Time-ranged layouts support the same b-roll media replacement and layout-shape changes as the single-call update. The base layout accepts `layout` only. properties: clipId: description: Clip ID minLength: 1 type: string durationMs: maximum: 9007199254740991 minimum: 200 type: integer layout: allOf: - $ref: '#/components/schemas/ClipLayoutShape' layoutId: description: >- Layout ID, `base` for the clip-spanning layout, or the operationId of an add_layout operation earlier in this batch. minLength: 1 type: string media: allOf: - $ref: '#/components/schemas/ClipMedia' description: >- Replace the layout's media content. Only valid on time-ranged layouts; rejected on the base (clip-spanning) layout. operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string startTimeMs: description: Start time in ms on the clip's playback timeline (cuts applied) maximum: 9007199254740991 minimum: 0 type: integer transitionStyle: allOf: - $ref: '#/components/schemas/LayoutTransitionStyle' description: >- Only valid on time-ranged layouts; rejected on the base (clip-spanning) layout. type: enum: - update_layout type: string required: - type - operationId - clipId - layoutId type: object BatchUpdateMediaOverlayOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string dimensions: allOf: - $ref: '#/components/schemas/OverlayDimensions' durationMs: exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string overlayId: description: >- Overlay ID, or the operationId of an add operation earlier in this batch. minLength: 1 type: string point: allOf: - $ref: '#/components/schemas/OverlayPoint' startTimeMs: description: >- Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript. maximum: 9007199254740991 minimum: 0 type: integer transition: allOf: - $ref: '#/components/schemas/TransitionStyle' description: >- Intro/outro animation: `smooth` fades the overlay in at its start and out at its end, `hard_cut` pops it in and out. type: enum: - update_media_overlay type: string required: - type - operationId - clipId - overlayId type: object BatchUpdateSoundEffectOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string durationMs: exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string soundEffectId: description: >- Sound effect ID, or the operationId of an add operation earlier in this batch. minLength: 1 type: string startTimeMs: description: >- Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript. maximum: 9007199254740991 minimum: 0 type: integer type: enum: - update_sound_effect type: string volume: description: Playback volume (0 = muted, 1 = original). minimum: 0 type: number required: - type - operationId - clipId - soundEffectId type: object BatchUpdateTextOverlayOperation: additionalProperties: false properties: background: allOf: - $ref: '#/components/schemas/TextOverlayBackground' backgroundShape: allOf: - $ref: '#/components/schemas/TextOverlayBackgroundShape' clipId: description: Clip ID minLength: 1 type: string 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: allOf: - $ref: '#/components/schemas/OverlayDimensions' durationMs: exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer fontFamily: allOf: - $ref: '#/components/schemas/TextOverlayFontFamily' fontSize: description: Font size in artboard pixels. exclusiveMinimum: true minimum: 0 type: number fontWeight: maximum: 1000 minimum: 1 type: number fontWidth: exclusiveMinimum: true minimum: 0 type: number operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string point: allOf: - $ref: '#/components/schemas/OverlayPoint' startTimeMs: description: >- Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript. maximum: 9007199254740991 minimum: 0 type: integer text: minLength: 1 type: string textAlign: allOf: - $ref: '#/components/schemas/TextOverlayTextAlign' textOverlayId: description: >- Text overlay ID, or the operationId of an add operation earlier in this batch. minLength: 1 type: string transition: allOf: - $ref: '#/components/schemas/TransitionStyle' description: >- Intro/outro animation: `smooth` fades the text in at its start and out at its end, `hard_cut` pops it in and out. type: enum: - update_text_overlay type: string required: - type - operationId - clipId - textOverlayId type: object BatchUpdateZoomOperation: additionalProperties: false properties: clipId: description: Clip ID minLength: 1 type: string durationMs: exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer focusPoint: allOf: - $ref: '#/components/schemas/ZoomFocusPoint' operationId: description: >- Caller-chosen ID used to match this operation to its result. Must be unique within the batch. example: sound-1 minLength: 1 type: string scale: description: Magnification factor (1 = no zoom, 3.5 = max). example: 2 maximum: 3.5 minimum: 1 type: number startTimeMs: description: Start time in ms on the clip's playback timeline (cuts applied) maximum: 9007199254740991 minimum: 0 type: integer type: enum: - update_zoom type: string zoomId: description: >- Zoom ID, or the operationId of an add operation earlier in this batch. minLength: 1 type: string zoomType: description: 'Zoom variant: manualZoom or trackingZoom.' enum: - manualZoom - trackingZoom example: manualZoom type: string required: - type - operationId - clipId - zoomId type: object MaskDimensions: 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 MaskPoint: 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 ClipMedia: description: >- Media shown during a layout. `image` or `video`, each referencing a `sourceId` from `POST /v1/sources`. discriminator: mapping: image: $ref: '#/components/schemas/ClipMediaImage' video: $ref: '#/components/schemas/ClipMediaVideo' propertyName: type oneOf: - $ref: '#/components/schemas/ClipMediaImage' - $ref: '#/components/schemas/ClipMediaVideo' type: object LayoutTransitionStyle: description: >- How the editor transitions into this layout from the previous one. `spring` is the default smooth motion; `hardCut` is an instant cut. enum: - spring - hardCut title: LayoutTransitionStyle type: string 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 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 TextOverlayBackground: 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 TextOverlayFontFamily: description: >- One of Tella's catalog font families — the same list the editor's font picker offers. enum: - Inter - Roboto Mono - Archivo - Barlow - Caveat - DM Sans - Figtree - Lora - Merriweather - Montserrat - Nunito Sans - Open Sans - Oswald - Playfair Display - Poppins - Raleway - Roboto - Roboto Flex - Source Sans 3 - Space Grotesk example: Inter type: string TextOverlayTextAlign: description: Horizontal alignment of the text inside its overlay box. enum: - left - center - right example: center type: string ZoomFocusPoint: 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 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 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). Note that `even` crops the screen recording to fill its half; see `style`. 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. `regular` and `overlap` scale the whole screen recording to fit its panel; `even` fills each half edge to edge and center-crops the screen to that half-canvas box (roughly half its width on a landscape canvas), with no `screenFit`/letterbox option. Avoid `even` for terminals, code, spreadsheets or other dense screen content unless you check the result with a clip frame. enum: - regular - even - overlap type: string required: - kind - position - style title: Side by Side type: object TVPresenterLayout: additionalProperties: false description: >- Today-show layout: presenter on one side, screen on the other. Combi (landscape) only. properties: kind: enum: - tv-presenter type: string position: enum: - left - right type: string style: description: >- `regular` is the standard today-show framing, `full` puts the screen fullscreen behind the presenter, `overlap` tightens the camera-screen overlap. enum: - regular - full - overlap type: string required: - kind - position - style title: TV Presenter type: object ClipMediaImage: additionalProperties: false description: >- Image media. The image fills the section's layer per the chosen layoutName. properties: slot: description: >- Which slot the media fills: `screen` (the subject/main frame, the default) or `camera` (the bubble/presentation slot — a media bubble over the recording behind it). A `camera` slot requires a layout that renders the camera (e.g. camera-bubble, side-by-side, tv-presenter). enum: - screen - camera type: string sourceId: description: 'Source ID from `POST /v1/sources` (`kind: image`).' minLength: 1 type: string type: enum: - image type: string required: - type - sourceId title: ClipMediaImage type: object ClipMediaVideo: additionalProperties: false description: Video media. properties: slot: description: >- Which slot the media fills: `screen` (the subject/main frame, the default) or `camera` (the bubble/presentation slot — a media bubble over the recording behind it). A `camera` slot requires a layout that renders the camera (e.g. camera-bubble, side-by-side, tv-presenter). enum: - screen - camera type: string sourceId: description: Source ID from `POST /v1/sources`. minLength: 1 type: string type: enum: - video type: string required: - type - sourceId title: ClipMediaVideo type: object 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 - [Low-res mode (edit faster)](/docs/help/editing/low-res-mode.md) - [How to edit a video](/docs/help/editing/edit-a-video.md) - [Style subtitles](/docs/help/editing/style-subtitles.md) - [Move videos to another workspace or account](/docs/help/admin/move-videos-between-workspaces.md) - [Video tutorials](/docs/help/introduction/tutorials.md)