> ## 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 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: >-
      Viewing analytics for a video or across the workspace: plays, watch time,
      retention, geography, referrers
    name: Analytics
  - description: Personal, workspace, and default video backgrounds
    name: Backgrounds
  - description: >-
      Reusable media saved to a workspace, plus Tella's curated sound effect and
      background music catalogs — the same items the editor's media panels show
    name: Library
  - description: Webhook endpoint management
    name: Webhooks
externalDocs:
  description: API versioning and deprecation policy
  url: https://www.tella.com/docs/versioning
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
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '400':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: bad_request
                message: The request was malformed or contained invalid parameters.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The request was malformed or contained invalid parameters.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '401':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: unauthorized
                message: Authentication is required. Provide a valid API key.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication is required. Provide a valid API key.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '403':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: forbidden
                message: You don't have permission to access this resource.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: You don't have permission to access this resource.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '404':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: not_found
                message: The requested resource was not found.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The requested resource was not found.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '409':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: conflict
                message: >-
                  The request conflicts with the resource's current state, e.g.
                  an Idempotency-Key whose first request is still in progress.
                  Retry once it settles.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            The request conflicts with the resource's current state, e.g. an
            Idempotency-Key whose first request is still in progress. Retry once
            it settles.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '429':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: rate_limited
                message: You have exceeded the rate limit. Please slow down.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: You have exceeded the rate limit. Please slow down.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '500':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: server_error
                message: An unexpected error occurred
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An unexpected error occurred
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '501':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: not_implemented
                message: The requested operation is not implemented.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The requested operation is not implemented.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '503':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: unavailable
                message: >-
                  A dependency was unavailable and the request was not executed.
                  Safe to resend unchanged after the Retry-After delay.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            A dependency was unavailable and the request was not executed. Safe
            to resend unchanged after the Retry-After delay.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
      security:
        - BearerAuth: []
components:
  schemas:
    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
    ErrorResponse:
      additionalProperties: false
      description: Standard error response format
      properties:
        docsUrl:
          description: Link to Tella API documentation
          example: https://docs.tella.com/
          format: uri
          type: string
        error:
          description: Machine-readable error code
          enum:
            - bad_request
            - unauthorized
            - forbidden
            - not_found
            - rate_limited
            - server_error
            - conflict
            - edit_conflict
            - not_implemented
            - unavailable
          example: not_found
          type: string
        message:
          description: Human-readable error message
          example: Resource not found
          type: string
      required:
        - error
        - message
        - docsUrl
      type: object
    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
    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. shaderGradient is read-only: responses include
            its two colors but no angle. Echoing the unchanged background
            preserves it; creating or modifying a shaderGradient through this
            API is not supported.
          enum:
            - solid
            - gradient
            - image
            - video
            - shaderGradient
          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
        intensity:
          description: >-
            Strength from 0 to 1. Blur: 0 is the standard blur and 1 blurs three
            times as heavily; the content stays fully hidden at every value
            (defaults to 0). Highlight: how dark the area outside the highlight
            goes, 0 = no dimming, 1 = black (defaults to 0.7).
          example: 0.7
          maximum: 1
          minimum: 0
          type: number
        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
        - intensity
      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:
        crop:
          allOf:
            - $ref: '#/components/schemas/ClipLayoutCropOutput'
          description: >-
            The crop of the clip's screen recording while this layout shows —
            the layout's own crop, else the clip's. Absent when the recording is
            uncropped.
          nullable: true
        durationMs:
          description: Layout duration in ms. Omitted for clip-spanning layouts.
          example: 5000
          minimum: 0
          nullable: true
          type: number
        followsBase:
          description: >-
            True when this layout follows the clip's base layout: updating the
            `base` layout changes it too, so it needs no update of its own.
            False when it has its own layout. Absent on the base layout itself.
          type: boolean
        id:
          description: Layout ID
          type: string
        layout:
          allOf:
            - $ref: '#/components/schemas/ClipLayoutShape'
          description: >-
            Structured layout for this section. Custom layouts, whether arranged
            in the editor or written through the API, report their geometry as
            `kind: custom`. Null only for internal layouts outside the public
            vocabulary.
          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
        popOut:
          allOf:
            - $ref: '#/components/schemas/ClipPopOut'
          description: The camera's pop-out while this layout shows. Absent when it is off.
          nullable: true
        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:
        depth:
          $ref: '#/components/schemas/OverlayDepth'
        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
        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. New overlays
            start on `hard_cut`.
          example: hard_cut
        type:
          enum:
            - image
            - video
          example: image
          type: string
        zIndex:
          $ref: '#/components/schemas/OverlayZIndex'
      required:
        - id
        - type
        - startTimeMs
        - durationMs
        - point
        - dimensions
        - transition
        - depth
        - zIndex
      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
        depth:
          $ref: '#/components/schemas/OverlayDepth'
        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
        outline:
          $ref: '#/components/schemas/TextOverlayOutline'
        point:
          $ref: '#/components/schemas/OverlayPointOutput'
        shadow:
          $ref: '#/components/schemas/TextOverlayShadow'
        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'
        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. New text overlays
            start on `hard_cut`.
          example: hard_cut
        zIndex:
          $ref: '#/components/schemas/OverlayZIndex'
      required:
        - id
        - text
        - fontFamily
        - fontSize
        - color
        - fontWeight
        - fontWidth
        - textAlign
        - background
        - backgroundShape
        - outline
        - shadow
        - startTimeMs
        - durationMs
        - point
        - dimensions
        - transition
        - depth
        - zIndex
      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:
        breakAfter:
          description: >-
            Whether a subtitle break is forced after this word, so the next word
            always starts a new subtitle block
          example: false
          type: boolean
        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
        keepWithNext:
          description: >-
            Whether this word's subtitle block is kept together with the next
            word across punctuation and pauses. The lines-per-block limit still
            applies and `breakAfter` wins.
          example: false
          type: boolean
        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
        - breakAfter
        - keepWithNext
      type: object
    ClipZoom:
      additionalProperties: false
      description: >-
        A zoom effect applied to the footage in the clip's Screen slot — 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 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
        captionFontFamily:
          $ref: '#/components/schemas/CaptionFontFamily'
        captionFontSize:
          $ref: '#/components/schemas/CaptionFontSize'
        captionFontWeight:
          $ref: '#/components/schemas/CaptionFontWeight'
        captionGrouping:
          description: 'How subtitle text is grouped: sentence chunks or one word at a time.'
          enum:
            - chunked
            - singleWord
          example: chunked
          type: string
        captionLinesPerBlock:
          $ref: '#/components/schemas/CaptionLinesPerBlock'
        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
        cursor:
          $ref: '#/components/schemas/CursorSettings'
        customThumbnailURL:
          description: Custom thumbnail image URL
          example: https://example.com/custom-thumbnail.jpg
          format: uri
          nullable: true
          type: string
        defaultClipTransition:
          allOf:
            - $ref: '#/components/schemas/TransitionStyle'
          description: >-
            How each clip enters from the previous one, unless the clip
            overrides it via its own `transition`.
          example: hard_cut
        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
        layoutAnimationStyle:
          description: >-
            How layout transitions animate, gentlest to snappiest. Zooms have
            their own `zoomAnimationStyle`. `custom` is a spring set outside the
            named styles.
          enum:
            - gentlest
            - gentle
            - relaxed
            - moderate
            - brisk
            - snappy
            - snappiest
            - custom
          example: moderate
          type: string
        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
        motionBlur:
          description: >-
            Blur fast zoom, pan, and cursor movement. Defaults on for new
            videos.
          example: true
          type: boolean
        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
        shrinkCameraDuringZooms:
          description: Shrink camera bubbles while a zoom is active. Defaults on.
          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
        thumbnailInpointMs:
          description: >-
            Time in ms on the video's playback timeline of the frame picked as
            the thumbnail (set via `inpointMs`). Null when the thumbnail is an
            uploaded image or the default. A picked frame leaves
            `customThumbnailURL` null, so check this field to verify it.
          example: 12000
          maximum: 9007199254740991
          minimum: 0
          nullable: true
          type: integer
        transcriptsEnabled:
          description: Show transcript panel to viewers
          example: true
          type: boolean
        viewCountEnabled:
          description: Show view count on video page
          example: true
          type: boolean
        zoomAnimationStyle:
          description: >-
            How zooms ease in, out, and between each other, gentlest to
            snappiest. Zooms follow `layoutAnimationStyle` until one is set.
            `custom` is a spring set outside the named styles.
          enum:
            - gentlest
            - gentle
            - relaxed
            - moderate
            - brisk
            - snappy
            - snappiest
            - custom
          example: moderate
          type: string
      required:
        - defaultPlaybackRate
        - captionsDefaultEnabled
        - subtitlesEnabled
        - captionStyle
        - captionSize
        - captionGrouping
        - captionPosition
        - captionFontFamily
        - captionFontWeight
        - captionFontSize
        - captionLinesPerBlock
        - transcriptsEnabled
        - publishDateEnabled
        - viewCountEnabled
        - commentsEnabled
        - commentEmailsEnabled
        - downloadsEnabled
        - rawDownloadsEnabled
        - linkScope
        - searchEngineIndexingEnabled
        - allowedEmbedDomains
        - customThumbnailURL
        - thumbnailInpointMs
        - studioSound
        - defaultClipTransition
        - microphoneVolume
        - systemAudioVolume
        - motionBlur
        - shrinkCameraDuringZooms
        - layoutAnimationStyle
        - zoomAnimationStyle
        - cursor
      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
    ClipLayoutCropOutput:
      additionalProperties: false
      description: >-
        A crop of the clip's screen recording, as pixels of the recording
        removed from each edge. The edges must leave a visible area.
      properties:
        bottom:
          description: Pixels of the screen recording removed from its bottom edge
          minimum: 0
          type: number
        left:
          description: Pixels of the screen recording removed from its left edge
          minimum: 0
          type: number
        right:
          description: Pixels of the screen recording removed from its right edge
          minimum: 0
          type: number
        top:
          description: Pixels of the screen recording removed from its top edge
          minimum: 0
          type: number
      required:
        - top
        - right
        - bottom
        - left
      type: object
    ClipLayoutShape:
      description: >-
        Structured layout description, discriminated by `kind`. Valid named
        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. `custom` carries explicit per-slot geometry and is valid on
        any clip.
      discriminator:
        mapping:
          camera-bubble: '#/components/schemas/CameraBubbleLayout'
          camera-only: '#/components/schemas/CameraOnlyLayout'
          custom: '#/components/schemas/CustomLayout'
          cut-out: '#/components/schemas/CutOutLayout'
          fullscreen: '#/components/schemas/FullscreenLayout'
          middle: '#/components/schemas/MiddleLayout'
          screen-only: '#/components/schemas/ScreenOnlyLayout'
          side-by-side: '#/components/schemas/SideBySideLayout'
          tv-presenter: '#/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/CutOutLayout'
        - $ref: '#/components/schemas/CameraBubbleLayout'
        - $ref: '#/components/schemas/CameraOnlyLayout'
        - $ref: '#/components/schemas/ScreenOnlyLayout'
        - $ref: '#/components/schemas/CustomLayout'
      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
    ClipPopOut:
      additionalProperties: false
      description: >-
        Pop-out for the camera: the presenter is cut out of the camera feed and
        rises out of a frame that keeps the camera's shape (circle, square or
        squircle) and sits behind their head. Needs a camera recording on the
        clip and a layout that frames it (any camera layout except cut-out and
        screen-only). Every field is optional; a write merges over the layout's
        current settings, and a fresh pop-out takes the defaults for unset
        fields. Responses report every field.
      properties:
        amount:
          description: >-
            How far the frame shrinks below the presenter, as a fraction of the
            camera slot (0–0.5). Defaults to 0.22.
          maximum: 0.5
          minimum: 0
          type: number
        background:
          description: >-
            What fills the frame behind the presenter: `original` keeps the
            camera feed, `color` paints `color`. Defaults to `original`.
          enum:
            - original
            - color
          type: string
        color:
          description: >-
            Frame fill when `background` is `color`, as #RRGGBB or #RRGGBBAA.
            Defaults to #6366F1.
          pattern: ^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$
          type: string
        outlineColor:
          description: 'Outline colour as #RRGGBB or #RRGGBBAA. Defaults to #FFFFFF.'
          pattern: ^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$
          type: string
        outlineWidth:
          description: >-
            Outline around the frame as a fraction of its width (0–0.05); 0
            draws none. Defaults to 0.
          maximum: 0.05
          minimum: 0
          type: number
      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
    OverlayDepth:
      description: >-
        Where the overlay sits relative to the presenter on a clip with a camera
        layout: `front` paints over everything, `behind_presenter` tucks it
        behind the cut-out presenter but above the clip background and screen.
        New overlays start on `front`. Without a camera in the layout the
        overlay paints in front either way.
      enum:
        - front
        - behind_presenter
      example: behind_presenter
      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
    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
    OverlayZIndex:
      description: >-
        Stacking position among the clip's image, video and text overlays: 0 is
        the backmost. `depth` applies first — a `behind_presenter` overlay stays
        behind the presenter whatever its zIndex — so the order only matters
        among overlays at the same depth. Lottie overlays share the stack but
        aren't listed, so listed values can skip a number.
      example: 0
      maximum: 9007199254740991
      minimum: 0
      type: integer
    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
    TextOverlayOutline:
      description: >-
        Color of the outline (stroke) drawn around the letters, or null for no
        outline.
      example: '#000000FF'
      nullable: true
      pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
      type: string
    TextOverlayShadow:
      description: >-
        Drop shadow, matching the editor's Shadow menu. It falls from the
        background box when the text has one, else from the letters.
      enum:
        - none
        - subtle
        - deep
      example: subtle
      type: string
    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 zoomed footage to zoom into, expressed as percentages of
        its 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
    CaptionFontFamily:
      description: >-
        Subtitle font family. On write, one of Tella's catalog font families
        (the list the editor's font picker offers, and the same one `fontFamily`
        accepts on text overlays), or the video's current family to keep an
        uploaded font. Reads report the family the subtitles render with, which
        on videos styled before the catalog can be a legacy bundled family such
        as `Arial`.
      example: Inter
      minLength: 1
      type: string
    CaptionFontSize:
      description: >-
        Exact subtitle text size, 40 to 200 — the editor's Size slider.
        `captionSize` is the same setting in buckets (small 40, medium 64, large
        80), so a request passes one or the other, not both.
      example: 64
      maximum: 200
      minimum: 40
      type: number
    CaptionFontWeight:
      description: >-
        Variable-font weight axis — 100 (thin) to 1000. Clamped to the range the
        family supports, so a read reports the weight that renders. Sent without
        `captionFontFamily`, it re-weights the video's current font.
      example: 500
      maximum: 1000
      minimum: 100
      type: number
    CaptionLinesPerBlock:
      description: >-
        Lines a caption block may span when `captionGrouping` is `chunked`: 1,
        2, or 3, or 0 for no limit, where blocks only break on pauses and
        sentence ends.
      example: 1
      maximum: 3
      minimum: 0
      type: integer
    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.
        Background, shadow, and outline colors and toggles are available on
        every style.
      discriminator:
        mapping:
          backdrop: '#/components/schemas/BackdropCaptionStyle'
          cannes: '#/components/schemas/CannesCaptionStyle'
          classic: '#/components/schemas/ClassicCaptionStyle'
          highlight: '#/components/schemas/HighlightCaptionStyle'
          mono: '#/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
    CursorSettings:
      additionalProperties: false
      description: Animated cursor settings
      properties:
        clickRipple:
          description: Show a ripple on mouse clicks. Defaults off for new videos.
          example: false
          type: boolean
        hideWhenInactive:
          description: >-
            Fade the animated cursor out while inactive and back in when
            activity resumes.
          example: false
          type: boolean
        returnToStart:
          description: >-
            Move the cursor back to its opening position at the end for cleaner
            loops.
          example: false
          type: boolean
        size:
          description: Animated cursor size multiplier.
          example: 3.05
          maximum: 6
          minimum: 0.5
          type: number
        smoothing:
          description: Smooth cursor movement. Defaults off for new videos.
          example: false
          type: boolean
        style:
          $ref: '#/components/schemas/CursorStyle'
      required:
        - style
        - size
        - smoothing
        - clickRipple
        - hideWhenInactive
        - returnToStart
      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"`, rejected otherwise. 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
    CustomLayout:
      additionalProperties: false
      description: >-
        Explicit geometry per slot in artboard pixels (the video's
        `dimensions`), like a layout arranged by hand in the editor. Valid on
        any scene type. Read the clip's layouts first: a section that is already
        custom merges the fields you pass over its current geometry; any other
        layout needs full `subject` geometry. Custom layouts can't carry `media`
        and aren't accepted in batch edits.
      properties:
        kind:
          enum:
            - custom
          type: string
        presentation:
          allOf:
            - $ref: '#/components/schemas/CustomLayoutSlot'
          description: >-
            The camera on combi clips. When omitted on a clip that has a camera
            and no custom geometry yet, the camera is kept but hidden.
        subject:
          allOf:
            - $ref: '#/components/schemas/CustomLayoutSlot'
          description: >-
            The main layer: the screen recording on combi and basic-subject
            clips, the camera on camera-subject clips. A screen keeps its
            recording's aspect ratio: `dimensions` are fitted to it around the
            same centre.
      required:
        - kind
      title: Custom
      type: object
    CutOutLayout:
      additionalProperties: false
      description: >-
        The presenter is cut out of the camera feed (person matting). On combi
        clips they are blended over the screen recording; on camera-subject
        clips they cover the frame over the story background.
      properties:
        kind:
          enum:
            - cut-out
          type: string
        position:
          description: >-
            Combi clips only (required there): which side the cut-out presenter
            sits on in landscape. Portrait and square stories stack the two
            instead — `right` puts the presenter at the top, `left` at the
            bottom. Ignored on camera-subject clips.
          enum:
            - left
            - right
          type: string
      required:
        - kind
      title: Cut Out
      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. Rejected on basic-subject clips,
            which have no camera.
          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
    BackdropCaptionStyle:
      additionalProperties: false
      properties:
        activeWordTextColor:
          description: >-
            Text color of the spoken word when highlightMode is background.
            Defaults to textColor.
          example: '#5E51F8FF'
          pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
          type: string
        backgroundColor:
          description: >-
            Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha
            channel is rendered exactly; #RRGGBB is fully opaque. Responses use
            uppercase #RRGGBBAA and report the effective rendered color.
          example: '#5E51F8FF'
          pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
          type: string
        backgroundEnabled:
          type: boolean
        highlightColor:
          description: >-
            Spoken-word color. Omit to retain the legacy text-opacity
            progression.
          example: '#5E51F8FF'
          pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
          type: string
        highlightMode:
          description: How the spoken word is emphasized. Defaults to text.
          enum:
            - text
            - background
            - fadeRest
          type: string
        name:
          enum:
            - backdrop
          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
        outlineEnabled:
          type: boolean
        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
        shadowEnabled:
          type: boolean
        textCase:
          description: Letter case applied to every caption word. Defaults to original.
          enum:
            - original
            - uppercase
            - lowercase
          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:
        - backgroundColor
        - name
        - textColor
        - wordLevelHighlights
      title: Backdrop
      type: object
    CannesCaptionStyle:
      additionalProperties: false
      properties:
        activeWordTextColor:
          description: >-
            Text color of the spoken word when highlightMode is background.
            Defaults to textColor.
          example: '#5E51F8FF'
          pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
          type: string
        backgroundColor:
          description: >-
            Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha
            channel is rendered exactly; #RRGGBB is fully opaque. Responses use
            uppercase #RRGGBBAA and report the effective rendered color.
          example: '#5E51F8FF'
          pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
          type: string
        backgroundEnabled:
          type: boolean
        highlightColor:
          description: Spoken-word color. Defaults to textColor.
          example: '#5E51F8FF'
          pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
          type: string
        highlightMode:
          description: How the spoken word is emphasized. Defaults to text.
          enum:
            - text
            - background
            - fadeRest
          type: string
        name:
          enum:
            - cannes
          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
        outlineEnabled:
          type: boolean
        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
        shadowEnabled:
          type: boolean
        textCase:
          description: Letter case applied to every caption word. Defaults to original.
          enum:
            - original
            - uppercase
            - lowercase
          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:
          description: Highlight each word as it is spoken. Defaults to false.
          type: boolean
      required:
        - shadowColor
        - name
        - textColor
      title: Cannes
      type: object
    ClassicCaptionStyle:
      additionalProperties: false
      properties:
        activeWordTextColor:
          description: >-
            Text color of the spoken word when highlightMode is background.
            Defaults to textColor.
          example: '#5E51F8FF'
          pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
          type: string
        backgroundColor:
          description: >-
            Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha
            channel is rendered exactly; #RRGGBB is fully opaque. Responses use
            uppercase #RRGGBBAA and report the effective rendered color.
          example: '#5E51F8FF'
          pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
          type: string
        backgroundEnabled:
          type: boolean
        highlightColor:
          description: Spoken-word color. Defaults to textColor.
          example: '#5E51F8FF'
          pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
          type: string
        highlightMode:
          description: How the spoken word is emphasized. Defaults to text.
          enum:
            - text
            - background
            - fadeRest
          type: string
        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
        outlineEnabled:
          type: boolean
        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
        shadowEnabled:
          type: boolean
        textCase:
          description: Letter case applied to every caption word. Defaults to original.
          enum:
            - original
            - uppercase
            - lowercase
          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:
          description: Highlight each word as it is spoken. Defaults to false.
          type: boolean
      required:
        - outlineColor
        - name
        - textColor
      title: Classic
      type: object
    HighlightCaptionStyle:
      additionalProperties: false
      properties:
        backgroundColor:
          description: >-
            Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha
            channel is rendered exactly; #RRGGBB is fully opaque. Responses use
            uppercase #RRGGBBAA and report the effective rendered color.
          example: '#5E51F8FF'
          pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
          type: string
        backgroundEnabled:
          type: boolean
        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
        highlightMode:
          description: How the spoken word is emphasized. Defaults to background.
          enum:
            - text
            - background
            - fadeRest
          type: string
        name:
          enum:
            - highlight
          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
        outlineEnabled:
          type: boolean
        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
        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
        shadowEnabled:
          type: boolean
        textCase:
          description: Letter case applied to every caption word. Defaults to original.
          enum:
            - original
            - uppercase
            - lowercase
          type: string
        wordLevelHighlights:
          description: Highlight each word as it is spoken. Defaults to true.
          type: boolean
      required:
        - name
        - primaryTextColor
        - secondaryTextColor
        - highlightColor
      title: Highlight
      type: object
    MonoCaptionStyle:
      additionalProperties: false
      properties:
        activeWordTextColor:
          description: >-
            Text color of the spoken word when highlightMode is background.
            Defaults to textColor.
          example: '#5E51F8FF'
          pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
          type: string
        backgroundColor:
          description: >-
            Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha
            channel is rendered exactly; #RRGGBB is fully opaque. Responses use
            uppercase #RRGGBBAA and report the effective rendered color.
          example: '#5E51F8FF'
          pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
          type: string
        backgroundEnabled:
          type: boolean
        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
        highlightMode:
          description: How the spoken word is emphasized. Defaults to text.
          enum:
            - text
            - background
            - fadeRest
          type: string
        name:
          enum:
            - mono
          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
        outlineEnabled:
          type: boolean
        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
        shadowEnabled:
          type: boolean
        textCase:
          description: Letter case applied to every caption word. Defaults to original.
          enum:
            - original
            - uppercase
            - lowercase
          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:
          description: Highlight each word as it is spoken. Defaults to true.
          type: boolean
      required:
        - name
        - textColor
        - highlightColor
      title: Mono
      type: object
    CursorStyle:
      description: >-
        Animated cursor artwork. mac is the pre-Tahoe style; macTahoe and
        macGoldenGate match those macOS generations; windows and touch use
        platform-specific artwork.
      enum:
        - mac
        - macTahoe
        - macGoldenGate
        - windows
        - touch
      example: macTahoe
      type: string
    CustomLayoutSlot:
      additionalProperties: false
      description: >-
        Geometry of one slot. `point` and `dimensions` are required unless the
        layout being written is already custom, in which case omitted fields
        keep their current values. Responses report every field.
      properties:
        corners:
          description: Corner rounding of a rectangular frame. Defaults to `regular`.
          enum:
            - none
            - regular
            - squircle
          type: string
        dimensions:
          allOf:
            - $ref: '#/components/schemas/CustomLayoutDimensions'
        hidden:
          description: Leave the layer out of the picture. Defaults to false.
          type: boolean
        order:
          description: >-
            Stacking order; higher draws on top. Defaults to 0 for the subject
            and 1 for the presentation.
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        point:
          allOf:
            - $ref: '#/components/schemas/CustomLayoutPoint'
        shape:
          description: >-
            Frame the layer is drawn in: `none` (default) is the plain rectangle
            given by `dimensions`; `circle`, `square` and `portrait` are the
            camera-bubble frames; `cutout` cuts the presenter out of the camera
            feed; `blob` is a wobbling bubble that grows toward the presenter's
            hands, and `blob-outline` is the same with a white line around it.
          enum:
            - none
            - circle
            - square
            - portrait
            - cutout
            - blob
            - blob-outline
          type: string
      type: object
    CustomLayoutDimensions:
      additionalProperties: false
      description: Slot size in artboard pixels.
      properties:
        height:
          exclusiveMinimum: true
          minimum: 0
          type: number
        width:
          exclusiveMinimum: true
          minimum: 0
          type: number
      required:
        - width
        - height
      type: object
    CustomLayoutPoint:
      additionalProperties: false
      description: Top-left corner of the slot in artboard pixels.
      properties:
        x:
          type: number
        'y':
          type: number
      required:
        - x
        - 'y'
      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

- [Videos](/docs/mcp-tools/videos.md)
- [Get video chapters](/docs/api-reference/videos/get-video-chapters.md)
- [Get a video storyboard](/docs/api-reference/videos/get-a-video-storyboard.md)
- [Get a video thumbnail or animated preview](/docs/api-reference/videos/get-a-video-thumbnail-or-animated-preview.md)
- [Clips](/docs/mcp-tools/clips.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.