> ## Documentation Index
> Fetch the complete documentation index at: https://docs.framelane.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Validate or preview a composition

> Validate a RenderRequest cheaply, or preview it at a single frame or over a short window without a full render. Pass `dry_run: true` for the free linter (cross-element and whole-timeline invariants, no render). A pixel preview reuses the exact render pipeline restricted to an outputSlice, so it is faithful to the final export; the returned job is a preview (not billed) that you poll via GET /v1/renders/{id}.



## OpenAPI

````yaml /openapi.json post /v1/preview
openapi: 3.1.0
info:
  title: Framelane API
  description: >
    Framelane renders video and runs AI media tasks from a single declarative
    request.


    ### Getting access (self-serve, no human needed)

    You can provision your own workspace and API key end-to-end — no dashboard,
    no sales call:

    1. `POST /v1/signup` with a `workspace_name` and an `email` you control. You
    get an API key
       back immediately and a 6-digit code is emailed to that address.
    2. Read the code from that inbox and `POST /v1/signup/verify` with it. If
    you drive a
       programmatic inbox (e.g. an agent mail service), this whole loop runs unattended.
    3. Your key works the moment the email is verified. Until then every authed
    call returns
       `403 email_not_verified` — verification is the only gate, so an unverified workspace can
       never spend. Re-calling `POST /v1/signup` re-keys the workspace and requires re-verifying.

    `POST /v1/signup`, `POST /v1/signup/verify`, and `GET /v1/capabilities` need
    **no** API key.


    ### Authentication

    Send your API key as a bearer token: `Authorization: Bearer fl_live_...`.


    ### Core workflow

    1. **Get media in.** Pass any publicly accessible URL directly, or `POST
    /v1/uploads` to
       get a signed URL, then `PUT` your file to it.
    2. **Submit one JSON payload.** `POST /v1/renders` composes a whole scene
    (canvas +
       `elements[]` + `transitions[]`) in a single request; `POST /v1/tasks/{type}` runs an AI
       operation (remove-background, gaze-redirect, super-resolution, transcribe).
    3. **Wait for completion.** Jobs are async: poll `GET
    /v1/{renders|tasks}/{id}` or register
       a webhook. Statuses end in `completed`, `failed`, or `cancelled`.
    4. **Fetch the result.** `GET /v1/{renders|tasks}/{id}/download` redirects
    to a short-lived
       signed URL for the output artifact.

    ### Discovering what's possible

    Call **`GET /v1/capabilities`** (no auth) for the machine-readable catalog
    of every effect,

    motion, transition, format, element type, and task parameter — each flagged
    with whether the

    renderer supports it, plus all numeric ranges and rate limits. Validate
    against it before

    submitting to avoid `422`s.


    ### Idempotency

    `POST` endpoints accept an `Idempotency-Key` header. The same key with the
    same body replays

    the original response (`200`); with a different body it returns `409
    Conflict`.


    ### Errors

    Every error has the shape `{"error": {"code", "message", "details"}}`. The
    machine-readable

    `code` (e.g. `source_not_found`, `quota_exceeded`, `codec_unsupported`) is
    stable — branch on

    it to self-correct.
  version: dev
servers:
  - url: https://api.framelane.io
    description: Production
security: []
tags:
  - name: capabilities
    description: Discover supported features, formats, and limits.
  - name: renders
    description: Compose and render video from a declarative timeline.
  - name: projects
    description: >-
      Stateful editing: read a composition, apply targeted ops, preview, and
      render the head.
  - name: preview
    description: >-
      Validate a composition for free and preview a frame or window cheaply,
      without a full render.
  - name: tasks
    description: >-
      Run AI media operations: background removal, gaze redirect,
      super-resolution, transcription.
  - name: uploads
    description: Get signed URLs to upload source media into Framelane storage.
  - name: webhooks
    description: Subscribe to job lifecycle events with signed delivery.
  - name: workspace
    description: Manage your workspace, usage, and assets.
  - name: api-keys
    description: Create and revoke API keys.
  - name: auth
    description: Session sync for the first-party console.
  - name: signup
    description: Create a workspace and verify email.
  - name: billing
    description: Manage your subscription and billing portal.
  - name: system
    description: Health, readiness, and version probes.
paths:
  /v1/preview:
    post:
      tags:
        - preview
      summary: Validate or preview a composition
      description: >-
        Validate a RenderRequest cheaply, or preview it at a single frame or
        over a short window without a full render. Pass `dry_run: true` for the
        free linter (cross-element and whole-timeline invariants, no render). A
        pixel preview reuses the exact render pipeline restricted to an
        outputSlice, so it is faithful to the final export; the returned job is
        a preview (not billed) that you poll via GET /v1/renders/{id}.
      operationId: create_preview
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewRequest'
        required: true
      responses:
        '200':
          description: Validation result (dry-run).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewResponse'
        '202':
          description: Preview render queued; poll job via GET /v1/renders/{id}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Malformed request or unsupported source.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - ApiKey: []
components:
  schemas:
    PreviewRequest:
      properties:
        at:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: At
          description: >-
            Timeline seconds for a single-frame preview. Mutually exclusive with
            'window' and 'contact_sheet'.
        window:
          anyOf:
            - $ref: '#/components/schemas/PreviewWindow'
            - type: 'null'
          description: >-
            Time range for a short clip preview (with audio), or the range a
            contact_sheet spans.
        contact_sheet:
          anyOf:
            - $ref: '#/components/schemas/ContactSheetOptions'
            - type: 'null'
          description: >-
            Produce a contact sheet (grid of composition-aware frames) instead
            of a single frame or clip.
        width:
          anyOf:
            - type: integer
              maximum: 3840
              minimum: 16
            - type: 'null'
          title: Width
          description: >-
            Preview width in px; height derives from the aspect ratio. Defaults
            to a small draft width.
        dry_run:
          type: boolean
          title: Dry Run
          description: 'Validate only: run the linter and return violations, no render.'
          default: false
        target_duration_sec:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: 'null'
          title: Target Duration Sec
          description: >-
            Optional target timeline length; emits TARGET_DURATION_MISSED when
            outside tolerance.
        target_tolerance_sec:
          type: number
          minimum: 0
          title: Target Tolerance Sec
          default: 0.5
        render_request:
          $ref: '#/components/schemas/RenderRequest-Input'
          description: The composition to preview.
      additionalProperties: false
      type: object
      required:
        - render_request
      title: PreviewRequest
    PreviewResponse:
      properties:
        kind:
          type: string
          title: Kind
          description: '''validation'' (dry-run), ''frame'', ''window'', or ''contact_sheet''.'
        ok:
          type: boolean
          title: Ok
          description: True when there are no error-severity violations.
        violations:
          items:
            $ref: '#/components/schemas/Violation'
          type: array
          title: Violations
        job:
          anyOf:
            - $ref: '#/components/schemas/JobOut'
            - type: 'null'
          description: >-
            For a pixel preview: the preview render job to poll via GET
            /v1/renders/{id} (is_preview=true, not billed). Absent for a
            dry-run.
        sheet:
          anyOf:
            - $ref: '#/components/schemas/ContactSheetPlan'
            - type: 'null'
          description: >-
            For a contact_sheet: the sampling plan (cells + grid shape). Present
            even on a dry-run.
      type: object
      required:
        - kind
        - ok
      title: PreviewResponse
    ApiError:
      description: >-
        The error envelope returned on every 4xx/5xx response: `{"error":
        {...}}`.
      properties:
        error:
          $ref: '#/components/schemas/ErrorResponse'
      required:
        - error
      title: ApiError
      type: object
    PreviewWindow:
      properties:
        from:
          type: number
          minimum: 0
          title: From
          description: Window start in timeline seconds.
        to:
          type: number
          exclusiveMinimum: 0
          title: To
          description: Window end in timeline seconds.
      additionalProperties: false
      type: object
      required:
        - from
        - to
      title: PreviewWindow
      description: A ``[from, to]`` time range, in timeline seconds.
    ContactSheetOptions:
      properties:
        detail:
          type: string
          enum:
            - overview
            - balanced
            - detailed
          title: Detail
          description: >-
            Cell budget: overview (~9), balanced (~16), detailed (~36); capped
            down for short clips.
          default: balanced
        columns:
          anyOf:
            - type: integer
              maximum: 12
              minimum: 1
            - type: 'null'
          title: Columns
          description: Grid columns. Defaults to a near-square layout.
        max_cells:
          anyOf:
            - type: integer
              maximum: 64
              minimum: 1
            - type: 'null'
          title: Max Cells
          description: Hard cap on the number of cells, below the tier budget.
      additionalProperties: false
      type: object
      title: ContactSheetOptions
      description: >-
        Knobs for a contact-sheet preview. Range + cell width come from the
        parent

        ``PreviewOptions`` (``window`` / ``width``).
    RenderRequest-Input:
      properties:
        width:
          anyOf:
            - type: integer
              maximum: 8192
              minimum: 16
            - type: 'null'
          title: Width
          description: >-
            Output width in pixels. Must be set together with `height` or both
            omitted.
          example: 1920
        height:
          anyOf:
            - type: integer
              maximum: 8192
              minimum: 16
            - type: 'null'
          title: Height
          description: >-
            Output height in pixels. Must be set together with `width` or both
            omitted.
          example: 1080
        duration:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: 'null'
          title: Duration
          description: >-
            Total composition duration in seconds. Inferred from elements when
            omitted.
          example: 15
        frame_rate:
          anyOf:
            - type: integer
              maximum: 240
              minimum: 1
            - type: 'null'
          title: Frame Rate
          description: Frames per second. Defaults to 30 when omitted.
          example: 30
        output_format:
          $ref: '#/components/schemas/OutputFormat'
          description: Container and codec for the output file.
          default: mp4
          example: mp4
        output_filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Output Filename
          description: >-
            Custom filename for the artifact (without extension). Auto-generated
            when omitted.
          example: my-render
        background_color:
          type: string
          pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
          title: Background Color
          description: RGBA background color in hex format (#RRGGBBAA).
          default: '#000000ff'
          example: '#000000ff'
        background_image_url:
          anyOf:
            - type: string
              maxLength: 2083
              minLength: 1
              format: uri
            - type: 'null'
          title: Background Image Url
          description: URL of an image to use as the composition background.
          example: https://cdn.example.com/bg.jpg
        alpha:
          type: boolean
          title: Alpha
          description: >-
            When true, produce an alpha-channel (transparent background) output.
            Requires `output_format=webm` or `output_format=mov`.
          default: false
          example: false
        elements:
          items:
            oneOf:
              - $ref: '#/components/schemas/VideoElement'
              - $ref: '#/components/schemas/AudioElement'
              - $ref: '#/components/schemas/TextElement'
              - $ref: '#/components/schemas/ImageElement'
              - $ref: '#/components/schemas/CompositionElement-Input'
              - $ref: '#/components/schemas/GradientElement'
              - $ref: '#/components/schemas/ShapeElement'
            discriminator:
              propertyName: type
              mapping:
                audio:
                  $ref: '#/components/schemas/AudioElement'
                composition:
                  $ref: '#/components/schemas/CompositionElement-Input'
                gradient:
                  $ref: '#/components/schemas/GradientElement'
                image:
                  $ref: '#/components/schemas/ImageElement'
                shape:
                  $ref: '#/components/schemas/ShapeElement'
                text:
                  $ref: '#/components/schemas/TextElement'
                video:
                  $ref: '#/components/schemas/VideoElement'
          type: array
          title: Elements
          description: Ordered list of timeline elements (video, image, text, audio, etc.).
        transitions:
          items:
            $ref: '#/components/schemas/Transition'
          type: array
          title: Transitions
          description: Transition effects applied between consecutive elements.
        groups:
          items:
            $ref: '#/components/schemas/Group'
          type: array
          title: Groups
          description: >-
            Transform groups over member elements (compose member→group→parent;
            optional stack layout). §5.
        motion_blur:
          anyOf:
            - $ref: '#/components/schemas/MotionBlur'
            - type: 'null'
          description: >-
            Shutter-based motion blur over the whole composition (§5c). Graphics
            motion smears; opt-in, N× render cost.
        background_gradient:
          anyOf:
            - $ref: '#/components/schemas/Gradient'
            - type: 'null'
          description: >-
            Canvas-sized gradient fill behind every layer (§6). Rendered for the
            full output slice.
        watermark_url:
          anyOf:
            - type: string
              maxLength: 2083
              minLength: 1
              format: uri
            - type: 'null'
          title: Watermark Url
          description: Watermark image overlaid on the output (§6).
        custom_animations:
          anyOf:
            - $ref: '#/components/schemas/CustomAnimationRegistry'
            - type: 'null'
          description: >-
            Inline custom-animation definitions (§3), referenced by name from
            element/text animations.
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
          description: Arbitrary key-value pairs echoed back in all webhook payloads.
          example:
            project_id: proj_123
        webhook_url:
          anyOf:
            - type: string
              maxLength: 2083
              minLength: 1
              format: uri
            - type: 'null'
          title: Webhook Url
          description: >-
            Per-request webhook URL. Overrides workspace-level webhooks for this
            job only. Receives `render.completed`, `render.failed`, and progress
            events.
          example: https://app.example.com/hooks/framelane
        ingest_external:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Ingest External
          description: >-
            Controls handling of source URLs that are not already hosted by
            Framelane. When `true`, such public files are copied into Framelane
            storage before rendering: the job starts in the `ingesting` state
            and moves to `queued` once the copy completes (you receive an
            `asset.ready` webhook per file). When `false`, the URL is passed
            straight to the renderer (the legacy behavior; video/audio still
            require an explicit `out_point`). Defaults to the workspace setting
            when omitted.
          example: true
      additionalProperties: false
      type: object
      title: RenderRequest
      description: >-
        Body for ``POST /v1/renders``.


        Defines the composition to render: dimensions, output format, timeline
        elements,

        and optional transitions. The render engine produces a single video
        artifact.
    Violation:
      properties:
        code:
          type: string
          title: Code
          description: Stable machine code, e.g. 'DANGLING_TRANSITION'.
        message:
          type: string
          title: Message
          description: Human-readable explanation.
        severity:
          $ref: '#/components/schemas/Severity'
          description: '''error'' blocks a good render; ''warning'' is advisory.'
          default: error
        path:
          anyOf:
            - type: string
            - type: 'null'
          title: Path
          description: Where it happened, e.g. 'elements[2]' or 'transitions[0].from_id'.
      type: object
      required:
        - code
        - message
      title: Violation
    JobOut:
      properties:
        id:
          type: string
          title: Id
          description: 'Unique job ID. Prefix indicates type: `render_` or `task_`.'
          example: render_01J8QR2K5VKDGN2T4FBM3CZYX7
        kind:
          $ref: '#/components/schemas/JobKind'
          description: Whether this is a `render` or a `task`.
          example: render
        is_preview:
          type: boolean
          title: Is Preview
          description: >-
            True for a cheap preview render. Previews are not billed and are
            excluded from the renders list.
          default: false
          example: false
        task_type:
          anyOf:
            - $ref: '#/components/schemas/TaskType'
            - type: 'null'
          description: For `task` jobs only — the specific AI operation.
          example: transcribe
        workspace_id:
          type: string
          title: Workspace Id
          description: ID of the workspace that owns this job.
          example: ws_01J8QR2K5VKDGN2T4FBM3CZYX8
        status:
          $ref: '#/components/schemas/JobStatus'
          description: >-
            Current lifecycle state: `queued` → `processing` → `completed` /
            `failed` / `cancelled`.
          example: queued
        progress_percent:
          type: integer
          maximum: 100
          minimum: 0
          title: Progress Percent
          description: 0–100 progress indicator updated by the render engine.
          default: 0
          example: 0
        progress_stage:
          anyOf:
            - $ref: '#/components/schemas/ProgressStage'
            - type: 'null'
          description: Current processing phase within a job.
          example: compositing
        output:
          anyOf:
            - $ref: '#/components/schemas/JobOutput'
            - type: 'null'
          description: >-
            Populated once `status == completed`. Contains the signed artifact
            URL.
        error:
          anyOf:
            - $ref: '#/components/schemas/JobError'
            - type: 'null'
          description: Populated when `status == failed`. Contains a structured error code.
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: >-
            Caller-supplied key-value pairs echoed back on every webhook and
            response.
          example:
            project_id: proj_123
            user_ref: usr_abc
        created_at:
          type: string
          format: date-time
          title: Created At
          description: ISO-8601 UTC timestamp when the job was created.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: ISO-8601 UTC timestamp of the last status change.
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
          description: ISO-8601 UTC timestamp when the job reached a terminal state.
      type: object
      required:
        - id
        - kind
        - workspace_id
        - status
        - created_at
        - updated_at
      title: JobOut
      description: A render job or AI task.
    ContactSheetPlan:
      properties:
        columns:
          type: integer
          title: Columns
        rows:
          type: integer
          title: Rows
        width:
          type: integer
          title: Width
          description: Per-cell width in px.
        window:
          $ref: '#/components/schemas/PreviewWindow'
          description: Timeline range the sheet spans.
        cells:
          items:
            $ref: '#/components/schemas/ContactSheetCell'
          type: array
          title: Cells
      type: object
      required:
        - columns
        - rows
        - width
        - window
      title: ContactSheetPlan
      description: >-
        The sampling plan: which frames the sheet will show, and the grid shape.


        Returned immediately (even on ``dry_run``), so an agent gets the
        composition-

        aware sample plan for free before any render.
    ErrorResponse:
      description: >-
        The structured error body — the value of the `error` key on an error
        response.
      properties:
        code:
          $ref: '#/components/schemas/ApiErrorCode'
        message:
          title: Message
          type: string
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          title: Details
      required:
        - code
        - message
      title: ErrorResponse
      type: object
    OutputFormat:
      type: string
      enum:
        - mp4
        - webm
        - mov
        - gif
        - png
        - jpg
      title: OutputFormat
      description: >-
        Values:

        - `mp4` — H.264 MP4 video — the default, widely compatible delivery
        format.

        - `webm` — VP9 WebM video — supports a transparent (alpha) background.

        - `mov` — QuickTime MOV — roadmap; not yet emitted by the renderer.

        - `gif` — Animated GIF — roadmap; not yet emitted by the renderer.

        - `png` — Single-frame PNG still — roadmap; not yet emitted by the
        renderer.

        - `jpg` — Single-frame JPEG still — roadmap; not yet emitted by the
        renderer.
      x-enumDescriptions:
        mp4: H.264 MP4 video — the default, widely compatible delivery format.
        webm: VP9 WebM video — supports a transparent (alpha) background.
        mov: QuickTime MOV — roadmap; not yet emitted by the renderer.
        gif: Animated GIF — roadmap; not yet emitted by the renderer.
        png: Single-frame PNG still — roadmap; not yet emitted by the renderer.
        jpg: Single-frame JPEG still — roadmap; not yet emitted by the renderer.
    VideoElement:
      properties:
        lut_url:
          anyOf:
            - type: string
              maxLength: 2083
              minLength: 1
              format: uri
            - type: 'null'
          title: Lut Url
        lut_intensity:
          type: number
          maximum: 100
          minimum: 0
          title: Lut Intensity
          default: 100
        brightness:
          type: number
          title: Brightness
          default: 0
        contrast:
          type: number
          title: Contrast
          default: 0
        saturation:
          type: number
          title: Saturation
          default: 0
        exposure:
          type: number
          title: Exposure
          default: 0
        sharpness:
          type: number
          title: Sharpness
          default: 0
        blur:
          type: number
          title: Blur
          default: 0
        noise:
          type: number
          title: Noise
          default: 0
        vignette:
          type: number
          title: Vignette
          default: 0
        hue_rotate:
          type: number
          title: Hue Rotate
          default: 0
        temperature:
          type: number
          title: Temperature
          default: 0
        tint:
          type: number
          title: Tint
          default: 0
        vibrance:
          type: number
          title: Vibrance
          default: 0
        highlights:
          type: number
          title: Highlights
          default: 0
        shadows:
          type: number
          title: Shadows
          default: 0
        crop_top:
          type: number
          maximum: 1
          minimum: 0
          title: Crop Top
          default: 0
        crop_bottom:
          type: number
          maximum: 1
          minimum: 0
          title: Crop Bottom
          default: 0
        crop_left:
          type: number
          maximum: 1
          minimum: 0
          title: Crop Left
          default: 0
        crop_right:
          type: number
          maximum: 1
          minimum: 0
          title: Crop Right
          default: 0
        border_radius:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Border Radius
          default: 0
        border_color:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Border Color
        border_width:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Border Width
          default: 0
        shadow_color:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Shadow Color
        shadow_blur:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Shadow Blur
          default: 0
        shadow_x:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Shadow X
          default: 0
        shadow_y:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Shadow Y
          default: 0
        x:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X
          default: 50%
        'y':
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: 'Y'
          default: 50%
        width:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Width
          default: 100%
        height:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Height
          default: 100%
        aspect_ratio:
          anyOf:
            - type: number
            - type: 'null'
          title: Aspect Ratio
        x_anchor:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Anchor
          default: 50%
        y_anchor:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Anchor
          default: 50%
        x_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Rotation
          default: 0°
        y_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Rotation
          default: 0°
        z_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Z Rotation
          default: 0°
        x_scale:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Scale
          default: 100%
        y_scale:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Scale
          default: 100%
        flip_horizontal:
          type: boolean
          title: Flip Horizontal
          default: false
        flip_vertical:
          type: boolean
          title: Flip Vertical
          default: false
        opacity:
          type: number
          maximum: 100
          minimum: 0
          title: Opacity
          default: 100
        z_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Z Index
        blend_mode:
          $ref: '#/components/schemas/BlendMode'
          default: none
        mask_shape:
          anyOf:
            - $ref: '#/components/schemas/MaskShape'
            - type: 'null'
        mask:
          anyOf:
            - $ref: '#/components/schemas/MaskConfig'
            - type: 'null'
        mask_keyframes:
          anyOf:
            - items:
                $ref: '#/components/schemas/MaskKeyframe'
              type: array
            - type: 'null'
          title: Mask Keyframes
        matte:
          anyOf:
            - $ref: '#/components/schemas/Matte'
            - type: 'null'
        backdrop_blur:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Backdrop Blur
          default: 0
        clip:
          type: boolean
          title: Clip
          default: false
        color_overlay:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Color Overlay
        type:
          type: string
          const: video
          title: Type
          default: video
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: >-
            Unique identifier for this element. **Required on image elements** —
            an empty or missing ID causes the image to be silently skipped by
            the renderer. Recommended on all elements that are referenced by a
            transition.
          example: clip_01
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Optional human-readable label. Not used by the renderer.
        track:
          anyOf:
            - type: integer
              maximum: 255
              minimum: 0
            - type: 'null'
          title: Track
          description: >-
            Timeline track index (0–255). Informational only; not used by the
            renderer.
        time:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Time
          description: >-
            When this element starts on the output timeline, in seconds.
            Defaults to `0` when omitted.
          example: 0
        visible:
          type: boolean
          title: Visible
          description: >-
            Set to `false` to skip this element without removing it from the
            request.
          default: true
        source_url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Source Url
          description: URL of the video file. Must be accessible by the renderer.
          example: https://cdn.example.com/clip.mp4
        in_point:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: In Point
          description: >-
            In point — seconds into the source file to start playing from.
            Defaults to `0`.
          example: 0
        out_point:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: 'null'
          title: Out Point
          description: >-
            Out point — seconds into the source file to stop playing. Defaults
            to end of source when omitted. Controls clip length on the timeline.
          example: 6
        speed:
          type: number
          maximum: 4
          minimum: 0.25
          title: Speed
          description: >-
            Playback speed. `1.0` = normal speed, `2.0` = 2× (half duration),
            `0.5` = half speed (double duration).
          default: 1
          example: 1
        playback_rate_keyframes:
          anyOf:
            - items:
                $ref: '#/components/schemas/RateKeyframe'
              type: array
            - type: 'null'
          title: Playback Rate Keyframes
          description: >-
            Speed ramp (§5c): piecewise-linear playback-rate keyframes (absolute
            timeline seconds; rate 0 = freeze). Audio keeps the static rate —
            mute or detach it on ramped clips.
        volume:
          type: number
          maximum: 100
          minimum: 0
          title: Volume
          description: >-
            Embedded audio volume as a percentage (0–100). Affects only the
            audio track inside this video clip.
          default: 100
          example: 100
        fade_in_duration:
          type: number
          title: Fade In Duration
          description: Duration in seconds of a linear audio fade-in at the clip's start.
          default: 0
          example: 0
        fade_out_duration:
          type: number
          title: Fade Out Duration
          description: Duration in seconds of a linear audio fade-out at the clip's end.
          default: 0
          example: 0
        effects:
          items:
            $ref: '#/components/schemas/Effect'
          type: array
          title: Effects
          default: []
        motion:
          items:
            $ref: '#/components/schemas/Motion'
          type: array
          title: Motion
          default: []
      additionalProperties: false
      type: object
      required:
        - source_url
      title: VideoElement
    AudioElement:
      properties:
        type:
          type: string
          const: audio
          title: Type
          default: audio
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: >-
            Unique identifier for this element. **Required on image elements** —
            an empty or missing ID causes the image to be silently skipped by
            the renderer. Recommended on all elements that are referenced by a
            transition.
          example: clip_01
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Optional human-readable label. Not used by the renderer.
        track:
          anyOf:
            - type: integer
              maximum: 255
              minimum: 0
            - type: 'null'
          title: Track
          description: >-
            Timeline track index (0–255). Informational only; not used by the
            renderer.
        time:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Time
          description: >-
            When this element starts on the output timeline, in seconds.
            Defaults to `0` when omitted.
          example: 0
        visible:
          type: boolean
          title: Visible
          description: >-
            Set to `false` to skip this element without removing it from the
            request.
          default: true
        source_url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Source Url
          description: URL of the audio file. Must be accessible by the renderer.
          example: https://cdn.example.com/music.mp3
        in_point:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: In Point
          description: >-
            In point — seconds into the source file to start from. Defaults to
            `0`.
          example: 0
        out_point:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: 'null'
          title: Out Point
          description: >-
            Out point — seconds into the source file to stop. Defaults to end of
            source when omitted. Controls clip length on the timeline.
          example: 30
        speed:
          type: number
          maximum: 4
          minimum: 0.25
          title: Speed
          description: Playback speed. `1.0` = normal speed, `2.0` = 2× speed.
          default: 1
          example: 1
        volume:
          type: number
          maximum: 100
          exclusiveMinimum: 0
          title: Volume
          description: >-
            Audio volume as a percentage (1–100). **Must be greater than 0** —
            the renderer silently drops audio streams with `volume <= 0`.
          default: 100
          example: 100
        fade_in_duration:
          type: number
          title: Fade In Duration
          description: Duration in seconds of a linear audio fade-in at the clip's start.
          default: 0
          example: 0
        fade_out_duration:
          type: number
          title: Fade Out Duration
          description: Duration in seconds of a linear audio fade-out at the clip's end.
          default: 0
          example: 0
      additionalProperties: false
      type: object
      required:
        - source_url
      title: AudioElement
    TextElement:
      properties:
        border_radius:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Border Radius
          default: 0
        border_color:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Border Color
        border_width:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Border Width
          default: 0
        shadow_color:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Shadow Color
        shadow_blur:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Shadow Blur
          default: 0
        shadow_x:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Shadow X
          default: 0
        shadow_y:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Shadow Y
          default: 0
        x:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X
          default: 50%
        'y':
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: 'Y'
          default: 50%
        width:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Width
          default: 100%
        height:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Height
          default: 100%
        aspect_ratio:
          anyOf:
            - type: number
            - type: 'null'
          title: Aspect Ratio
        x_anchor:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Anchor
          default: 50%
        y_anchor:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Anchor
          default: 50%
        x_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Rotation
          default: 0°
        y_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Rotation
          default: 0°
        z_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Z Rotation
          default: 0°
        x_scale:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Scale
          default: 100%
        y_scale:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Scale
          default: 100%
        flip_horizontal:
          type: boolean
          title: Flip Horizontal
          default: false
        flip_vertical:
          type: boolean
          title: Flip Vertical
          default: false
        opacity:
          type: number
          maximum: 100
          minimum: 0
          title: Opacity
          default: 100
        z_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Z Index
        blend_mode:
          $ref: '#/components/schemas/BlendMode'
          default: none
        mask_shape:
          anyOf:
            - $ref: '#/components/schemas/MaskShape'
            - type: 'null'
        mask:
          anyOf:
            - $ref: '#/components/schemas/MaskConfig'
            - type: 'null'
        mask_keyframes:
          anyOf:
            - items:
                $ref: '#/components/schemas/MaskKeyframe'
              type: array
            - type: 'null'
          title: Mask Keyframes
        matte:
          anyOf:
            - $ref: '#/components/schemas/Matte'
            - type: 'null'
        backdrop_blur:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Backdrop Blur
          default: 0
        clip:
          type: boolean
          title: Clip
          default: false
        color_overlay:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Color Overlay
        type:
          type: string
          const: text
          title: Type
          default: text
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: >-
            Unique identifier for this element. **Required on image elements** —
            an empty or missing ID causes the image to be silently skipped by
            the renderer. Recommended on all elements that are referenced by a
            transition.
          example: clip_01
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Optional human-readable label. Not used by the renderer.
        track:
          anyOf:
            - type: integer
              maximum: 255
              minimum: 0
            - type: 'null'
          title: Track
          description: >-
            Timeline track index (0–255). Informational only; not used by the
            renderer.
        time:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Time
          description: >-
            When this element starts on the output timeline, in seconds.
            Defaults to `0` when omitted.
          example: 0
        visible:
          type: boolean
          title: Visible
          description: >-
            Set to `false` to skip this element without removing it from the
            request.
          default: true
        duration:
          type: number
          exclusiveMinimum: 0
          title: Duration
          description: >-
            **Required.** Duration in seconds the text is visible. Omitting this
            field produces a zero-length window and the element will not appear
            in the render.
          example: 5
        text:
          type: string
          minLength: 1
          title: Text
          description: The text content to render.
          example: Hello World
        font_family:
          type: string
          title: Font Family
          description: Font family name. Must be available to the renderer.
          default: Inter
          example: Inter
        font_size:
          type: number
          exclusiveMinimum: 0
          title: Font Size
          description: Font size in pixels.
          default: 16
          example: 48
        font_weight:
          type: integer
          maximum: 900
          minimum: 100
          title: Font Weight
          description: Font weight (100–900). `400` = regular, `700` = bold.
          default: 400
          example: 400
        font_style:
          type: string
          enum:
            - normal
            - italic
            - bold
            - bolditalic
          title: Font Style
          description: Font style variant.
          default: normal
        text_color:
          type: string
          pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
          title: Text Color
          description: Text fill color as a hex string.
          default: '#ffffff'
          example: '#ffffff'
        text_align:
          type: string
          enum:
            - left
            - center
            - right
          title: Text Align
          description: Horizontal text alignment.
          default: center
        text_direction:
          type: string
          enum:
            - ltr
            - rtl
          title: Text Direction
          description: Text direction. `rtl` for right-to-left scripts (§4).
          default: ltr
        text_decoration:
          type: string
          enum:
            - none
            - underline
            - strikethrough
          title: Text Decoration
          default: none
        tracking:
          type: number
          title: Tracking
          description: >-
            Letter spacing (tracking) in pixels. Positive values add space
            between characters.
          default: 0
          example: 0
        leading:
          type: number
          title: Leading
          description: >-
            Line height (leading) as a multiplier of font size. `1.2` = 20%
            taller than the font size.
          default: 1.2
          example: 1.2
        stroke_color:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Stroke Color
          description: >-
            Outline color. Set together with `stroke_width` to enable text
            outlines.
          example: '#000000'
        stroke_width:
          type: number
          title: Stroke Width
          description: >-
            Outline width, em-relative (fraction of `font_size` — e.g. `0.05` =
            5% of the font size). Has no effect unless `stroke_color` is also
            set.
          default: 0
        background_color:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Background Color
          description: Background fill color. Only rendered when `background` is `true`.
        background_opacity:
          type: number
          maximum: 100
          minimum: 0
          title: Background Opacity
          default: 100
        x_padding:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Padding
          default: 0
        y_padding:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Padding
          default: 0
        background:
          type: boolean
          title: Background
          description: >-
            Solid color box behind the full text block. Set `background_color`
            to choose the color.
          default: false
        stroke:
          type: boolean
          title: Stroke
          description: >-
            Outline-only mode — draws the glyph stroke with no fill. Requires
            `stroke_color` and `stroke_width`. When `false`, setting
            `stroke_color` + `stroke_width` gives fill + stroke (outlined).
          default: false
        shadow:
          type: boolean
          title: Shadow
          description: Built-in drop shadow.
          default: false
        motion:
          items:
            $ref: '#/components/schemas/Motion'
          type: array
          title: Motion
          default: []
        word_animation:
          anyOf:
            - $ref: '#/components/schemas/WordAnimation'
            - type: 'null'
          description: >-
            Word-level animation style with per-word timestamps. When provided,
            this takes precedence over the `animation_preset` field.
          example:
            style: glow
            words:
              - end: 0.5
                start: 0
                text: Hello
        words:
          anyOf:
            - items:
                $ref: '#/components/schemas/WordSpec'
              type: array
            - type: 'null'
          title: Words
          description: >-
            Per-word timing and optional per-word style overrides (§4). Emitted
            as a top-level `words[]` array; use alongside
            `motion`/`animation_preset` for the animation. Editorial-emphasis
            captions = word timings + a styled keyword.
          example:
            - end: 3
              start: 0
              style:
                color: '#e8734a'
              word: launch
        counter:
          anyOf:
            - $ref: '#/components/schemas/ValueCounter'
            - type: 'null'
          description: >-
            Rewrite this text from an eased numeric sweep (§4). Takes precedence
            over countdown on the same element.
        glow:
          anyOf:
            - $ref: '#/components/schemas/TextGlow'
            - type: 'null'
          description: Soft glow around the glyphs (§4).
        text_wrap:
          type: string
          enum:
            - wrap
            - nowrap
          title: Text Wrap
          default: wrap
        animation_preset:
          anyOf:
            - type: string
            - type: 'null'
          title: Animation Preset
          description: >-
            Renderer animation shorthand (e.g. `'typewriter'`). Use `motion[]`
            for structured control. Ignored when `word_animation` is set.
      additionalProperties: false
      type: object
      required:
        - duration
        - text
      title: TextElement
    ImageElement:
      properties:
        lut_url:
          anyOf:
            - type: string
              maxLength: 2083
              minLength: 1
              format: uri
            - type: 'null'
          title: Lut Url
        lut_intensity:
          type: number
          maximum: 100
          minimum: 0
          title: Lut Intensity
          default: 100
        brightness:
          type: number
          title: Brightness
          default: 0
        contrast:
          type: number
          title: Contrast
          default: 0
        saturation:
          type: number
          title: Saturation
          default: 0
        exposure:
          type: number
          title: Exposure
          default: 0
        sharpness:
          type: number
          title: Sharpness
          default: 0
        blur:
          type: number
          title: Blur
          default: 0
        noise:
          type: number
          title: Noise
          default: 0
        vignette:
          type: number
          title: Vignette
          default: 0
        hue_rotate:
          type: number
          title: Hue Rotate
          default: 0
        temperature:
          type: number
          title: Temperature
          default: 0
        tint:
          type: number
          title: Tint
          default: 0
        vibrance:
          type: number
          title: Vibrance
          default: 0
        highlights:
          type: number
          title: Highlights
          default: 0
        shadows:
          type: number
          title: Shadows
          default: 0
        crop_top:
          type: number
          maximum: 1
          minimum: 0
          title: Crop Top
          default: 0
        crop_bottom:
          type: number
          maximum: 1
          minimum: 0
          title: Crop Bottom
          default: 0
        crop_left:
          type: number
          maximum: 1
          minimum: 0
          title: Crop Left
          default: 0
        crop_right:
          type: number
          maximum: 1
          minimum: 0
          title: Crop Right
          default: 0
        border_radius:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Border Radius
          default: 0
        border_color:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Border Color
        border_width:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Border Width
          default: 0
        shadow_color:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Shadow Color
        shadow_blur:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Shadow Blur
          default: 0
        shadow_x:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Shadow X
          default: 0
        shadow_y:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Shadow Y
          default: 0
        x:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X
          default: 50%
        'y':
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: 'Y'
          default: 50%
        width:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Width
          default: 100%
        height:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Height
          default: 100%
        aspect_ratio:
          anyOf:
            - type: number
            - type: 'null'
          title: Aspect Ratio
        x_anchor:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Anchor
          default: 50%
        y_anchor:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Anchor
          default: 50%
        x_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Rotation
          default: 0°
        y_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Rotation
          default: 0°
        z_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Z Rotation
          default: 0°
        x_scale:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Scale
          default: 100%
        y_scale:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Scale
          default: 100%
        flip_horizontal:
          type: boolean
          title: Flip Horizontal
          default: false
        flip_vertical:
          type: boolean
          title: Flip Vertical
          default: false
        opacity:
          type: number
          maximum: 100
          minimum: 0
          title: Opacity
          default: 100
        z_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Z Index
        blend_mode:
          $ref: '#/components/schemas/BlendMode'
          default: none
        mask_shape:
          anyOf:
            - $ref: '#/components/schemas/MaskShape'
            - type: 'null'
        mask:
          anyOf:
            - $ref: '#/components/schemas/MaskConfig'
            - type: 'null'
        mask_keyframes:
          anyOf:
            - items:
                $ref: '#/components/schemas/MaskKeyframe'
              type: array
            - type: 'null'
          title: Mask Keyframes
        matte:
          anyOf:
            - $ref: '#/components/schemas/Matte'
            - type: 'null'
        backdrop_blur:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Backdrop Blur
          default: 0
        clip:
          type: boolean
          title: Clip
          default: false
        color_overlay:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Color Overlay
        type:
          type: string
          const: image
          title: Type
          default: image
        id:
          type: string
          minLength: 1
          title: Id
          description: >-
            **Required.** Unique identifier for this image. An empty or missing
            ID causes the image to be silently skipped by the renderer.
          example: logo_01
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Optional human-readable label. Not used by the renderer.
        track:
          anyOf:
            - type: integer
              maximum: 255
              minimum: 0
            - type: 'null'
          title: Track
          description: >-
            Timeline track index (0–255). Informational only; not used by the
            renderer.
        time:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Time
          description: >-
            When this element starts on the output timeline, in seconds.
            Defaults to `0` when omitted.
          example: 0
        visible:
          type: boolean
          title: Visible
          description: >-
            Set to `false` to skip this element without removing it from the
            request.
          default: true
        duration:
          type: number
          exclusiveMinimum: 0
          title: Duration
          description: >-
            **Required.** Duration in seconds the image is visible. Omitting
            this field produces a zero-length window and the image will not
            appear in the render.
          example: 5
        source_url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Source Url
          description: URL of the image file (PNG, JPG, WebP, GIF).
          example: https://cdn.example.com/logo.png
        effects:
          items:
            $ref: '#/components/schemas/Effect'
          type: array
          title: Effects
          default: []
        motion:
          items:
            $ref: '#/components/schemas/Motion'
          type: array
          title: Motion
          default: []
      additionalProperties: false
      type: object
      required:
        - id
        - duration
        - source_url
      title: ImageElement
    CompositionElement-Input:
      properties:
        border_radius:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Border Radius
          default: 0
        border_color:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Border Color
        border_width:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Border Width
          default: 0
        shadow_color:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Shadow Color
        shadow_blur:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Shadow Blur
          default: 0
        shadow_x:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Shadow X
          default: 0
        shadow_y:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Shadow Y
          default: 0
        x:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X
          default: 50%
        'y':
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: 'Y'
          default: 50%
        width:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Width
          default: 100%
        height:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Height
          default: 100%
        aspect_ratio:
          anyOf:
            - type: number
            - type: 'null'
          title: Aspect Ratio
        x_anchor:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Anchor
          default: 50%
        y_anchor:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Anchor
          default: 50%
        x_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Rotation
          default: 0°
        y_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Rotation
          default: 0°
        z_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Z Rotation
          default: 0°
        x_scale:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Scale
          default: 100%
        y_scale:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Scale
          default: 100%
        flip_horizontal:
          type: boolean
          title: Flip Horizontal
          default: false
        flip_vertical:
          type: boolean
          title: Flip Vertical
          default: false
        opacity:
          type: number
          maximum: 100
          minimum: 0
          title: Opacity
          default: 100
        z_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Z Index
        blend_mode:
          $ref: '#/components/schemas/BlendMode'
          default: none
        mask_shape:
          anyOf:
            - $ref: '#/components/schemas/MaskShape'
            - type: 'null'
        mask:
          anyOf:
            - $ref: '#/components/schemas/MaskConfig'
            - type: 'null'
        mask_keyframes:
          anyOf:
            - items:
                $ref: '#/components/schemas/MaskKeyframe'
              type: array
            - type: 'null'
          title: Mask Keyframes
        matte:
          anyOf:
            - $ref: '#/components/schemas/Matte'
            - type: 'null'
        backdrop_blur:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Backdrop Blur
          default: 0
        clip:
          type: boolean
          title: Clip
          default: false
        color_overlay:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Color Overlay
        type:
          type: string
          const: composition
          title: Type
          default: composition
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: >-
            Unique identifier for this element. **Required on image elements** —
            an empty or missing ID causes the image to be silently skipped by
            the renderer. Recommended on all elements that are referenced by a
            transition.
          example: clip_01
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Optional human-readable label. Not used by the renderer.
        track:
          anyOf:
            - type: integer
              maximum: 255
              minimum: 0
            - type: 'null'
          title: Track
          description: >-
            Timeline track index (0–255). Informational only; not used by the
            renderer.
        time:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Time
          description: >-
            When this element starts on the output timeline, in seconds.
            Defaults to `0` when omitted.
          example: 0
        visible:
          type: boolean
          title: Visible
          description: >-
            Set to `false` to skip this element without removing it from the
            request.
          default: true
        elements:
          items:
            oneOf:
              - $ref: '#/components/schemas/VideoElement'
              - $ref: '#/components/schemas/AudioElement'
              - $ref: '#/components/schemas/TextElement'
              - $ref: '#/components/schemas/ImageElement'
              - $ref: '#/components/schemas/CompositionElement-Input'
              - $ref: '#/components/schemas/GradientElement'
              - $ref: '#/components/schemas/ShapeElement'
            discriminator:
              propertyName: type
              mapping:
                audio:
                  $ref: '#/components/schemas/AudioElement'
                composition:
                  $ref: '#/components/schemas/CompositionElement-Input'
                gradient:
                  $ref: '#/components/schemas/GradientElement'
                image:
                  $ref: '#/components/schemas/ImageElement'
                shape:
                  $ref: '#/components/schemas/ShapeElement'
                text:
                  $ref: '#/components/schemas/TextElement'
                video:
                  $ref: '#/components/schemas/VideoElement'
          type: array
          minItems: 1
          title: Elements
      additionalProperties: false
      type: object
      required:
        - elements
      title: CompositionElement
      description: >-
        [TODO] renderer Compound clips (roadmap). Currently rejected by
        translator.
    GradientElement:
      properties:
        x:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X
          default: 50%
        'y':
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: 'Y'
          default: 50%
        width:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Width
          default: 100%
        height:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Height
          default: 100%
        aspect_ratio:
          anyOf:
            - type: number
            - type: 'null'
          title: Aspect Ratio
        x_anchor:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Anchor
          default: 50%
        y_anchor:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Anchor
          default: 50%
        x_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Rotation
          default: 0°
        y_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Rotation
          default: 0°
        z_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Z Rotation
          default: 0°
        x_scale:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Scale
          default: 100%
        y_scale:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Scale
          default: 100%
        flip_horizontal:
          type: boolean
          title: Flip Horizontal
          default: false
        flip_vertical:
          type: boolean
          title: Flip Vertical
          default: false
        opacity:
          type: number
          maximum: 100
          minimum: 0
          title: Opacity
          default: 100
        z_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Z Index
        blend_mode:
          $ref: '#/components/schemas/BlendMode'
          default: none
        mask_shape:
          anyOf:
            - $ref: '#/components/schemas/MaskShape'
            - type: 'null'
        mask:
          anyOf:
            - $ref: '#/components/schemas/MaskConfig'
            - type: 'null'
        mask_keyframes:
          anyOf:
            - items:
                $ref: '#/components/schemas/MaskKeyframe'
              type: array
            - type: 'null'
          title: Mask Keyframes
        matte:
          anyOf:
            - $ref: '#/components/schemas/Matte'
            - type: 'null'
        backdrop_blur:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Backdrop Blur
          default: 0
        clip:
          type: boolean
          title: Clip
          default: false
        color_overlay:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Color Overlay
        type:
          type: string
          const: gradient
          title: Type
          default: gradient
        id:
          type: string
          minLength: 1
          title: Id
          description: '**Required.** Unique identifier.'
          example: cta-bar
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Optional human-readable label. Not used by the renderer.
        track:
          anyOf:
            - type: integer
              maximum: 255
              minimum: 0
            - type: 'null'
          title: Track
          description: >-
            Timeline track index (0–255). Informational only; not used by the
            renderer.
        time:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Time
          description: >-
            When this element starts on the output timeline, in seconds.
            Defaults to `0` when omitted.
          example: 0
        visible:
          type: boolean
          title: Visible
          description: >-
            Set to `false` to skip this element without removing it from the
            request.
          default: true
        duration:
          type: number
          exclusiveMinimum: 0
          title: Duration
          description: '**Required.** Seconds the gradient is visible.'
          example: 4
        gradient:
          $ref: '#/components/schemas/Gradient'
          description: The gradient fill (≥2 stops).
        corner_radius:
          type: number
          maximum: 1
          minimum: 0
          title: Corner Radius
          description: Corner radius, normalized 0–1.
          default: 0
        shadow:
          anyOf:
            - $ref: '#/components/schemas/DropShadow'
            - type: 'null'
          description: Optional drop shadow.
        effects:
          items:
            $ref: '#/components/schemas/Effect'
          type: array
          title: Effects
          description: Shader effect chain (§6 W3), e.g. aurora.
          default: []
        motion:
          items:
            $ref: '#/components/schemas/Motion'
          type: array
          title: Motion
          default: []
      additionalProperties: false
      type: object
      required:
        - id
        - duration
        - gradient
      title: GradientElement
      description: A rounded gradient card / bar / pill as one element (§5e).
    ShapeElement:
      properties:
        x:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X
          default: 50%
        'y':
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: 'Y'
          default: 50%
        width:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Width
          default: 100%
        height:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Height
          default: 100%
        aspect_ratio:
          anyOf:
            - type: number
            - type: 'null'
          title: Aspect Ratio
        x_anchor:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Anchor
          default: 50%
        y_anchor:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Anchor
          default: 50%
        x_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Rotation
          default: 0°
        y_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Rotation
          default: 0°
        z_rotation:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Z Rotation
          default: 0°
        x_scale:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: X Scale
          default: 100%
        y_scale:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Y Scale
          default: 100%
        flip_horizontal:
          type: boolean
          title: Flip Horizontal
          default: false
        flip_vertical:
          type: boolean
          title: Flip Vertical
          default: false
        opacity:
          type: number
          maximum: 100
          minimum: 0
          title: Opacity
          default: 100
        z_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Z Index
        blend_mode:
          $ref: '#/components/schemas/BlendMode'
          default: none
        mask_shape:
          anyOf:
            - $ref: '#/components/schemas/MaskShape'
            - type: 'null'
        mask:
          anyOf:
            - $ref: '#/components/schemas/MaskConfig'
            - type: 'null'
        mask_keyframes:
          anyOf:
            - items:
                $ref: '#/components/schemas/MaskKeyframe'
              type: array
            - type: 'null'
          title: Mask Keyframes
        matte:
          anyOf:
            - $ref: '#/components/schemas/Matte'
            - type: 'null'
        backdrop_blur:
          anyOf:
            - type: integer
            - type: number
            - type: string
          title: Backdrop Blur
          default: 0
        clip:
          type: boolean
          title: Clip
          default: false
        color_overlay:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Color Overlay
        type:
          type: string
          const: shape
          title: Type
          default: shape
        id:
          type: string
          minLength: 1
          title: Id
          description: '**Required.** Unique identifier.'
          example: blob-1
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Optional human-readable label. Not used by the renderer.
        track:
          anyOf:
            - type: integer
              maximum: 255
              minimum: 0
            - type: 'null'
          title: Track
          description: >-
            Timeline track index (0–255). Informational only; not used by the
            renderer.
        time:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Time
          description: >-
            When this element starts on the output timeline, in seconds.
            Defaults to `0` when omitted.
          example: 0
        visible:
          type: boolean
          title: Visible
          description: >-
            Set to `false` to skip this element without removing it from the
            request.
          default: true
        duration:
          type: number
          exclusiveMinimum: 0
          title: Duration
          description: '**Required.** Seconds the shape is visible.'
          example: 4
        path:
          type: string
          minLength: 1
          title: Path
          description: SVG path `d` (M L H V C S Q T Z; arcs straighten).
          example: M50 0 L100 100 L0 100 Z
        view_box:
          items:
            type: number
          type: array
          maxItems: 4
          minItems: 4
          title: View Box
          description: '`[x, y, width, height]` path coordinate space.'
          default:
            - 0
            - 0
            - 100
            - 100
        fill:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: string
              const: none
          title: Fill
          description: Fill colour (hex, alpha ok) or 'none' for outline-only.
          default: '#000000'
        fill_rule:
          type: string
          enum:
            - nonzero
            - evenodd
          title: Fill Rule
          default: nonzero
        stroke:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Stroke
          description: Stroke colour.
        stroke_width:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Stroke Width
          description: Stroke width in viewBox units (absent = SVG 1.0; 0 disables).
        stroke_dash:
          anyOf:
            - items:
                type: number
              type: array
              maxItems: 2
              minItems: 2
            - type: 'null'
          title: Stroke Dash
          description: '`[on, off]` dash lengths in viewBox units.'
        corner_radius:
          type: number
          maximum: 1
          minimum: 0
          title: Corner Radius
          description: Corner radius, normalized 0–1.
          default: 0
        shadow:
          anyOf:
            - $ref: '#/components/schemas/DropShadow'
            - type: 'null'
        path_keyframes:
          anyOf:
            - items:
                $ref: '#/components/schemas/PathKeyframe'
              type: array
            - type: 'null'
          title: Path Keyframes
          description: Morph the path between keyframes (timeline seconds).
        trim:
          anyOf:
            - $ref: '#/components/schemas/TrimPath'
            - type: 'null'
          description: 'Trim paths (draw-on): animate trim.end 0→1 on a stroked path.'
        effects:
          items:
            $ref: '#/components/schemas/Effect'
          type: array
          title: Effects
          description: Shader effect chain (§6 W3).
          default: []
        motion:
          items:
            $ref: '#/components/schemas/Motion'
          type: array
          title: Motion
          default: []
      additionalProperties: false
      type: object
      required:
        - id
        - duration
        - path
      title: ShapeElement
      description: 'A first-class vector primitive: SVG path fill + stroke, morphing (§5b).'
    Transition:
      properties:
        type:
          $ref: '#/components/schemas/TransitionType'
          description: Transition effect applied between elements.
          example: fade
        duration:
          type: number
          exclusiveMinimum: 0
          title: Duration
          description: Transition duration in seconds.
          example: 0.5
        from_id:
          anyOf:
            - type: string
            - type: 'null'
          title: From Id
          description: ID of the outgoing element (omit for the very first transition).
          example: video_01
        to_id:
          anyOf:
            - type: string
            - type: 'null'
          title: To Id
          description: ID of the incoming element (omit for the very last transition).
          example: video_02
        z_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Z Index
          description: Z-stack position of the transition layer.
          example: 1
      additionalProperties: false
      type: object
      required:
        - type
        - duration
      title: Transition
    Group:
      properties:
        id:
          type: string
          minLength: 1
          title: Id
          description: '**Required.** Unique group id.'
          example: hero
        parent:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent
          description: Parent group id for nesting.
        pivot:
          $ref: '#/components/schemas/Point'
          description: Rotation/scale pivot.
        translate:
          anyOf:
            - $ref: '#/components/schemas/Point'
            - type: 'null'
          description: Group translation (normalized).
        scale:
          type: number
          exclusiveMinimum: 0
          title: Scale
          description: Group scale.
          default: 1
        rotation_degrees:
          type: number
          title: Rotation Degrees
          description: In-plane (z) rotation of the group.
          default: 0
        opacity:
          type: number
          maximum: 1
          minimum: 0
          title: Opacity
          description: Group opacity.
          default: 1
        members:
          items:
            type: string
          type: array
          title: Members
          description: Member element uuids.
        animations:
          items:
            $ref: '#/components/schemas/Motion'
          type: array
          title: Animations
          default: []
        layout:
          anyOf:
            - $ref: '#/components/schemas/StackLayout'
            - type: 'null'
          description: Optional stack layout.
      additionalProperties: false
      type: object
      required:
        - id
      title: Group
      description: >-
        A transform group over member elements (§5, A6). Composes member → group
        → parent.
    MotionBlur:
      properties:
        samples:
          type: integer
          maximum: 32
          minimum: 2
          title: Samples
          description: Temporal samples per frame (2–32).
        shutter:
          type: number
          maximum: 1
          exclusiveMinimum: 0
          title: Shutter
          description: Shutter fraction of the frame interval (0–1).
          default: 0.5
      additionalProperties: false
      type: object
      required:
        - samples
      title: MotionBlur
      description: >-
        Shutter-based temporal supersampling of the whole composition (§5c).
        Opt-in, N× cost.
    Gradient:
      properties:
        kind:
          type: string
          enum:
            - linear
            - radial
          title: Kind
          default: linear
        angle_degrees:
          type: number
          title: Angle Degrees
          description: Linear gradient angle in degrees. 0 = left→right.
          default: 0
        stops:
          items:
            $ref: '#/components/schemas/GradientStop'
          type: array
          minItems: 2
          title: Stops
          description: Two or more colour stops.
      additionalProperties: false
      type: object
      required:
        - stops
      title: Gradient
    CustomAnimationRegistry:
      properties:
        element:
          items:
            $ref: '#/components/schemas/CustomAnimation'
          type: array
          title: Element
          default: []
        text:
          items:
            $ref: '#/components/schemas/CustomAnimation'
          type: array
          title: Text
          default: []
      additionalProperties: false
      type: object
      title: CustomAnimationRegistry
      description: Inline custom-animation registries for element and text animations (§3).
    Severity:
      type: string
      enum:
        - error
        - warning
      title: Severity
    JobKind:
      type: string
      enum:
        - render
        - task
      title: JobKind
    TaskType:
      type: string
      enum:
        - remove_background
        - gaze_redirect
        - super_resolution
        - transcribe
      title: TaskType
      description: >-
        The 4 task types exposed by the public API.


        Renderer tasks (remove_background, gaze_redirect, super_resolution) are

        dispatched via the Redis broker; transcribe is dispatched via
        AssemblyAI.


        Values:

        - `remove_background` — AI background removal — outputs media with a
        transparent background.

        - `gaze_redirect` — AI gaze redirection — adjusts on-screen eyes to face
        the camera.

        - `super_resolution` — AI upscaling — increases resolution by a 1–4×
        factor.

        - `transcribe` — Speech-to-text transcription (via AssemblyAI) with
        optional analysis.
      x-enumDescriptions:
        remove_background: AI background removal — outputs media with a transparent background.
        gaze_redirect: AI gaze redirection — adjusts on-screen eyes to face the camera.
        super_resolution: AI upscaling — increases resolution by a 1–4× factor.
        transcribe: Speech-to-text transcription (via AssemblyAI) with optional analysis.
    JobStatus:
      type: string
      enum:
        - ingesting
        - queued
        - processing
        - completed
        - failed
        - cancelled
      title: JobStatus
      description: >-
        Values:

        - `ingesting` — External source files are being copied into Framelane
        storage.

        - `queued` — Accepted and waiting for a worker to pick it up.

        - `processing` — Actively rendering or processing.

        - `completed` — Finished successfully; the output artifact is available.

        - `failed` — Terminated with an error (see `error`).

        - `cancelled` — Cancelled by the caller before completion.
      x-enumDescriptions:
        ingesting: External source files are being copied into Framelane storage.
        queued: Accepted and waiting for a worker to pick it up.
        processing: Actively rendering or processing.
        completed: Finished successfully; the output artifact is available.
        failed: Terminated with an error (see `error`).
        cancelled: Cancelled by the caller before completion.
    ProgressStage:
      type: string
      enum:
        - downloading
        - compositing
        - encoding
        - uploading
      title: ProgressStage
      description: |-
        Values:
        - `downloading` — Fetching source media.
        - `compositing` — Compositing the scene on the GPU.
        - `encoding` — Encoding the output video.
        - `uploading` — Uploading the finished artifact to storage.
      x-enumDescriptions:
        downloading: Fetching source media.
        compositing: Compositing the scene on the GPU.
        encoding: Encoding the output video.
        uploading: Uploading the finished artifact to storage.
    JobOutput:
      properties:
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: CDN URL to the completed artifact.
          example: https://cdn-user.framelane.io/render_01J.../output.mp4
        width:
          anyOf:
            - type: integer
            - type: 'null'
          title: Width
          description: Output video width in pixels.
          example: 1920
        height:
          anyOf:
            - type: integer
            - type: 'null'
          title: Height
          description: Output video height in pixels.
          example: 1080
        duration:
          anyOf:
            - type: number
            - type: 'null'
          title: Duration
          description: Output duration in seconds.
          example: 15.3
        size_bytes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Size Bytes
          description: Artifact file size in bytes.
          example: 12582912
      type: object
      title: JobOutput
    JobError:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
          description: Machine-readable error code.
          example: invalid_source
        message:
          type: string
          title: Message
          description: Human-readable error description.
          example: Source URL returned 404.
      type: object
      required:
        - code
        - message
      title: JobError
    ContactSheetCell:
      properties:
        index:
          type: integer
          title: Index
          description: Position in the grid, row-major from 0.
        at:
          type: number
          title: At
          description: Timeline seconds of this frame (snapped to the frame grid).
        reason:
          $ref: '#/components/schemas/SampleReason'
          description: Why this moment was sampled.
      type: object
      required:
        - index
        - at
        - reason
      title: ContactSheetCell
      description: >-
        One frame in the grid: where it is on the timeline and why it was
        picked.
    ApiErrorCode:
      description: >-
        Machine-readable error code returned on a 4xx/5xx response. Branch on
        `error.code` to

        handle failures programmatically.


        Values:

        - `invalid_request` — The request was malformed or failed validation.

        - `unauthorized` — Missing or invalid API key.

        - `forbidden` — Authenticated but not permitted to perform this action.

        - `not_found` — The requested resource does not exist.

        - `conflict` — Conflicts with current state (e.g. a reused
        Idempotency-Key with a different body).

        - `unsupported_feature` — The composition uses a feature the renderer
        does not support.

        - `invalid_source` — A source URL is malformed or unreachable.

        - `source_not_found` — A referenced source file could not be found.

        - `source_too_large` — A source file exceeds the allowed size.

        - `asset_not_ready` — A referenced asset is still ingesting and is not
        ready yet.

        - `ingest_failed` — Copying an external source into Framelane storage
        failed.

        - `codec_unsupported` — A source uses a codec the renderer cannot
        decode.

        - `quota_exceeded` — The workspace has exhausted its plan quota (HTTP
        402).

        - `rate_limited` — Too many requests; retry after the Retry-After
        interval.

        - `internal` — An unexpected server error occurred.

        - `email_not_verified` — The workspace email is unverified; verify it
        before making authed calls.

        - `email_in_use` — The email is already associated with another
        workspace.

        - `invalid_otp` — The verification code is incorrect or expired.

        - `unsupported_content_type` — The provided content type is not
        supported.

        - `http_error` — A generic HTTP error not covered by a more specific
        code.
      enum:
        - invalid_request
        - unauthorized
        - forbidden
        - not_found
        - conflict
        - unsupported_feature
        - invalid_source
        - source_not_found
        - source_too_large
        - asset_not_ready
        - ingest_failed
        - codec_unsupported
        - quota_exceeded
        - rate_limited
        - internal
        - email_not_verified
        - email_in_use
        - invalid_otp
        - unsupported_content_type
        - http_error
      title: ErrorCode
      type: string
      x-enumDescriptions:
        invalid_request: The request was malformed or failed validation.
        unauthorized: Missing or invalid API key.
        forbidden: Authenticated but not permitted to perform this action.
        not_found: The requested resource does not exist.
        conflict: >-
          Conflicts with current state (e.g. a reused Idempotency-Key with a
          different body).
        unsupported_feature: The composition uses a feature the renderer does not support.
        invalid_source: A source URL is malformed or unreachable.
        source_not_found: A referenced source file could not be found.
        source_too_large: A source file exceeds the allowed size.
        asset_not_ready: A referenced asset is still ingesting and is not ready yet.
        ingest_failed: Copying an external source into Framelane storage failed.
        codec_unsupported: A source uses a codec the renderer cannot decode.
        quota_exceeded: The workspace has exhausted its plan quota (HTTP 402).
        rate_limited: Too many requests; retry after the Retry-After interval.
        internal: An unexpected server error occurred.
        email_not_verified: >-
          The workspace email is unverified; verify it before making authed
          calls.
        email_in_use: The email is already associated with another workspace.
        invalid_otp: The verification code is incorrect or expired.
        unsupported_content_type: The provided content type is not supported.
        http_error: A generic HTTP error not covered by a more specific code.
    BlendMode:
      type: string
      enum:
        - none
        - multiply
        - screen
        - overlay
        - darken
        - lighten
        - color_dodge
        - color_burn
        - hard_light
        - soft_light
        - difference
        - add
        - exclusion
        - hue
        - saturation
        - color
        - luminosity
      title: BlendMode
      description: >-
        Values:

        - `none` — Normal compositing (source-over) — the default.

        - `multiply` — Multiply blend — darkens by multiplying layer colors.

        - `screen` — Screen blend — lightens by inverting, multiplying,
        inverting.

        - `overlay` — Overlay blend — multiply in shadows, screen in highlights.

        - `darken` — Darken blend — keeps the darker of the two layers per
        channel.

        - `lighten` — Lighten blend — keeps the lighter of the two layers per
        channel.

        - `color_dodge` — Color-dodge blend — brightens the base toward the
        blend color.

        - `color_burn` — Color-burn blend — darkens the base toward the blend
        color.

        - `hard_light` — Hard-light blend — overlay with layers swapped.

        - `soft_light` — Soft-light blend — a gentler hard-light.

        - `difference` — Difference blend — absolute difference of the two
        layers per channel.

        - `add` — Additive (linear-dodge) blend — sums layer colors, clamped.

        - `exclusion` — Exclusion blend — like difference, lower contrast.

        - `hue` — Hue blend — backdrop luminosity + saturation with the blend
        layer's hue.

        - `saturation` — Saturation blend — backdrop hue + luminosity with the
        blend layer's saturation.

        - `color` — Color blend — backdrop luminosity with the blend layer's hue
        + saturation.

        - `luminosity` — Luminosity blend — backdrop hue + saturation with the
        blend layer's luminosity.
      x-enumDescriptions:
        none: Normal compositing (source-over) — the default.
        multiply: Multiply blend — darkens by multiplying layer colors.
        screen: Screen blend — lightens by inverting, multiplying, inverting.
        overlay: Overlay blend — multiply in shadows, screen in highlights.
        darken: Darken blend — keeps the darker of the two layers per channel.
        lighten: Lighten blend — keeps the lighter of the two layers per channel.
        color_dodge: Color-dodge blend — brightens the base toward the blend color.
        color_burn: Color-burn blend — darkens the base toward the blend color.
        hard_light: Hard-light blend — overlay with layers swapped.
        soft_light: Soft-light blend — a gentler hard-light.
        difference: Difference blend — absolute difference of the two layers per channel.
        add: Additive (linear-dodge) blend — sums layer colors, clamped.
        exclusion: Exclusion blend — like difference, lower contrast.
        hue: >-
          Hue blend — backdrop luminosity + saturation with the blend layer's
          hue.
        saturation: >-
          Saturation blend — backdrop hue + luminosity with the blend layer's
          saturation.
        color: >-
          Color blend — backdrop luminosity with the blend layer's hue +
          saturation.
        luminosity: >-
          Luminosity blend — backdrop hue + saturation with the blend layer's
          luminosity.
    MaskShape:
      type: string
      enum:
        - circle
        - diamond
        - hexagon
        - star
        - heart
        - triangle
      title: MaskShape
      description: >-
        Analytic (SDF) shape mask that clips an element's coverage. §1.


        Values:

        - `circle` — Circular (ellipse) analytic mask, fit to the element
        bounds.

        - `diamond` — Diamond (rotated square) analytic mask.

        - `hexagon` — Regular hexagon analytic mask.

        - `star` — Five-point star analytic mask.

        - `heart` — Heart analytic mask.

        - `triangle` — Upward triangle analytic mask.
      x-enumDescriptions:
        circle: Circular (ellipse) analytic mask, fit to the element bounds.
        diamond: Diamond (rotated square) analytic mask.
        hexagon: Regular hexagon analytic mask.
        star: Five-point star analytic mask.
        heart: Heart analytic mask.
        triangle: Upward triangle analytic mask.
    MaskConfig:
      properties:
        feather:
          type: number
          minimum: 0
          title: Feather
          description: Soften the mask's SDF edge.
          default: 0
        scale:
          type: number
          exclusiveMinimum: 0
          title: Scale
          description: Mask scale (iris reveals).
          default: 1
        center:
          anyOf:
            - $ref: '#/components/schemas/Point'
            - type: 'null'
          description: Mask centre (wipes).
      additionalProperties: false
      type: object
      title: MaskConfig
      description: >-
        Animated/feathered mask params layered on the analytic `mask_shape`
        (§5c).
    MaskKeyframe:
      properties:
        time:
          type: number
          minimum: 0
          title: Time
          description: Timeline seconds.
        feather:
          anyOf:
            - type: number
            - type: 'null'
          title: Feather
        scale:
          anyOf:
            - type: number
            - type: 'null'
          title: Scale
        center:
          anyOf:
            - $ref: '#/components/schemas/Point'
            - type: 'null'
        easing:
          anyOf:
            - type: string
            - type: 'null'
          title: Easing
          description: Easing curve name.
      additionalProperties: false
      type: object
      required:
        - time
      title: MaskKeyframe
      description: >-
        A keyframe for animated masks (§5c). Absent fields inherit the static
        mask.
    Matte:
      properties:
        source:
          type: string
          minLength: 1
          title: Source
          description: uuid of the source layer (auto-hidden). Text sources supported.
        mode:
          type: string
          enum:
            - alpha
            - luma
          title: Mode
          default: alpha
        invert:
          type: boolean
          title: Invert
          default: false
      additionalProperties: false
      type: object
      required:
        - source
      title: Matte
      description: >-
        Track matte (§5d): drive this element's coverage from another layer's
        render.
    RateKeyframe:
      properties:
        time:
          type: number
          minimum: 0
          title: Time
          description: Timeline seconds.
        rate:
          type: number
          minimum: 0
          title: Rate
          description: Playback rate (0 = freeze-frame).
      additionalProperties: false
      type: object
      required:
        - time
        - rate
      title: RateKeyframe
      description: A point on a video speed ramp (§5c). Absolute timeline seconds.
    Effect:
      properties:
        type:
          $ref: '#/components/schemas/EffectType'
        intensity:
          type: number
          maximum: 100
          minimum: 0
          title: Intensity
          default: 50
        intensity_keyframes:
          anyOf:
            - items:
                $ref: '#/components/schemas/IntensityKeyframe'
              type: array
            - type: 'null'
          title: Intensity Keyframes
          description: >-
            Animate intensity over time (§2): piecewise-linear `[{time, value}]`
            in timeline seconds. Overrides the static `intensity` when set.
        props:
          anyOf:
            - additionalProperties:
                type: number
              type: object
            - type: 'null'
          title: Props
          description: >-
            Per-shader scalar props (§2), bound as `u_prop_<key>` (e.g.
            `{"speed": 0.6}` for aurora). Ignored for chroma_key (use
            `chroma_settings`).
        chroma_settings:
          anyOf:
            - $ref: '#/components/schemas/ChromaKeyProps'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - type
      title: Effect
    Motion:
      properties:
        type:
          $ref: '#/components/schemas/MotionType'
        time:
          type: number
          minimum: 0
          title: Time
          description: >-
            Absolute start time on the output timeline in seconds. For entrances
            and loops set this to the element's `time`. For exits set this to
            element `time + duration − motion duration`.
        duration:
          type: number
          exclusiveMinimum: 0
          title: Duration
          description: How long the animation runs in seconds.
        easing:
          $ref: '#/components/schemas/Easing'
          default: ease_in_out
        reversed:
          type: boolean
          title: Reversed
          default: false
        scope:
          $ref: '#/components/schemas/MotionScope'
          default: element
        delay:
          type: number
          title: Delay
          default: 0
        loop:
          type: boolean
          title: Loop
          default: false
        audio:
          anyOf:
            - $ref: '#/components/schemas/AudioGenerator'
            - type: 'null'
          description: >-
            Audio-reactive offsets (§3). Attach to any animation; use the `fade`
            preset as a no-op carrier for a pure generator.
        selector:
          anyOf:
            - $ref: '#/components/schemas/RangeSelector'
            - type: 'null'
          description: >-
            AE-style range selector shaping the animation amount by position
            (§4, text only).
      additionalProperties: false
      type: object
      required:
        - type
        - time
        - duration
      title: Motion
    WordAnimation:
      properties:
        style:
          $ref: '#/components/schemas/WordAnimationStyle'
        words:
          items:
            $ref: '#/components/schemas/Word'
          type: array
          minItems: 1
          title: Words
      additionalProperties: false
      type: object
      required:
        - style
        - words
      title: WordAnimation
    WordSpec:
      properties:
        word:
          type: string
          minLength: 1
          title: Word
          description: The word (whole-word match; UTF-8).
        start:
          type: number
          minimum: 0
          title: Start
          description: Word reveal start, seconds.
        end:
          type: number
          exclusiveMinimum: 0
          title: End
          description: Word reveal end, seconds.
        style:
          anyOf:
            - $ref: '#/components/schemas/WordStyle'
            - type: 'null'
          description: Optional per-word style override.
      additionalProperties: false
      type: object
      required:
        - word
        - start
        - end
      title: WordSpec
      description: Per-word timing + optional style, keyed by word text (§4).
    ValueCounter:
      properties:
        from_value:
          type: number
          title: From Value
          description: Start value.
          default: 0
        to_value:
          type: number
          title: To Value
          description: End value.
          default: 100
        decimals:
          type: integer
          maximum: 6
          minimum: 0
          title: Decimals
          description: Decimal places (0–6).
          default: 0
        prefix:
          type: string
          title: Prefix
          description: Text prepended to the number.
          default: ''
        suffix:
          type: string
          title: Suffix
          description: Text appended to the number, e.g. '%'.
          default: ''
        easing:
          anyOf:
            - type: string
            - type: 'null'
          title: Easing
          description: >-
            Easing curve name (e.g. 'quadOut', 'spring'). Overshooting easings
            overshoot the number.
        start_time:
          type: number
          minimum: 0
          title: Start Time
          description: Seconds into the element to start the sweep.
          default: 0
        length:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: 'null'
          title: Length
          description: Sweep duration; defaults to the element's remaining life.
      additionalProperties: false
      type: object
      title: ValueCounter
      description: >-
        Rewrite a text element from an eased numeric sweep (the animated stat
        hero, §4).
    TextGlow:
      properties:
        color:
          type: string
          pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
          title: Color
          example: '#ffffff'
        size:
          type: number
          minimum: 0
          title: Size
          description: Glow size, em-relative.
          default: 0.15
        intensity:
          type: number
          minimum: 0
          title: Intensity
          description: Glow intensity.
          default: 1
      additionalProperties: false
      type: object
      required:
        - color
      title: TextGlow
      description: Soft glow around the glyphs (§4).
    DropShadow:
      properties:
        color:
          type: string
          pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
          title: Color
          example: '#00000066'
        distance:
          type: number
          minimum: 0
          title: Distance
          description: Shadow offset distance in px.
          default: 0
        direction:
          type: number
          title: Direction
          description: Shadow direction in degrees (polar; 90 = down).
          default: 90
        blur:
          type: number
          minimum: 0
          title: Blur
          description: Shadow blur radius in px.
          default: 0
      additionalProperties: false
      type: object
      required:
        - color
      title: DropShadow
    PathKeyframe:
      properties:
        time:
          type: number
          minimum: 0
          title: Time
          description: Timeline seconds for this path.
        d:
          type: string
          minLength: 1
          title: D
          description: SVG path `d` at this time.
        easing:
          anyOf:
            - $ref: '#/components/schemas/Easing'
            - type: 'null'
          description: Ease into this keyframe.
      additionalProperties: false
      type: object
      required:
        - time
        - d
      title: PathKeyframe
    TrimPath:
      properties:
        start:
          type: number
          maximum: 1
          minimum: 0
          title: Start
          description: Trim start, 0–1 along the path.
          default: 0
        end:
          type: number
          maximum: 1
          minimum: 0
          title: End
          description: Trim end, 0–1 along the path.
          default: 1
      additionalProperties: false
      type: object
      title: TrimPath
    TransitionType:
      type: string
      enum:
        - cross_dissolve
        - dip_to_black
        - dip_to_white
        - wipe_left
        - wipe_right
        - wipe_up
        - wipe_down
        - diagonal_wipe
        - barn_doors_horizontal
        - barn_doors_vertical
        - iris
        - page_turn
        - cross_zoom
        - gradient_wipe
        - band_wipe
        - box_wipe
        - swirl
        - glitch_memories
        - window_slice
        - cube
        - doorway
        - pinwheel
        - water_drop
        - crosshatch
        - dreamy
        - angular
        - burn
        - heart
        - circle_open
        - color_phase
        - squares_wire
        - whip_pan
        - cinematic_zoom
        - burn_edge
        - shatter
        - domain_warp
      title: TransitionType
      description: >-
        Values:

        - `cross_dissolve` — Cross-dissolve — fades one clip into the next.

        - `dip_to_black` — Dips through black between clips.

        - `dip_to_white` — Dips through white between clips.

        - `wipe_left` — Wipes the next clip in from the right to the left.

        - `wipe_right` — Wipes the next clip in from the left to the right.

        - `wipe_up` — Wipes the next clip in from the bottom upward.

        - `wipe_down` — Wipes the next clip in from the top downward.

        - `diagonal_wipe` — Wipes across on a diagonal split.

        - `barn_doors_horizontal` — Two halves part horizontally like barn
        doors.

        - `barn_doors_vertical` — Two halves part vertically like barn doors.

        - `iris` — Circular iris (bullseye) open/close between clips.

        - `page_turn` — Page-flip / page-curl reveal.

        - `cross_zoom` — Zoom-blur push from one clip into the next.

        - `gradient_wipe` — Soft gradient-driven dissolve wipe.

        - `band_wipe` — Interleaved stripes wipe the next clip in.

        - `box_wipe` — Rectangular box grows to reveal the next clip.

        - `swirl` — Swirls the outgoing clip away in a spiral.

        - `glitch_memories` — Glitchy, memory-like distortion between clips.

        - `window_slice` — Slices the frame into sliding window strips.

        - `cube` — 3D cube rotation between the two clips.

        - `doorway` — Clips part like opening doors to reveal the next.

        - `pinwheel` — Pinwheel rotation wipe between clips.

        - `water_drop` — Rippling water-drop distortion reveals the next clip.

        - `crosshatch` — Crosshatch pattern dissolve between clips.

        - `dreamy` — Soft, dreamy blur-dissolve between clips.

        - `angular` — Angular wedge sweep between clips.

        - `burn` — Burning-film dissolve between clips.

        - `heart` — Heart-shaped iris reveal of the next clip.

        - `circle_open` — Expanding circle opens onto the next clip.

        - `color_phase` — Color-phase shift blends between clips.

        - `squares_wire` — Wireframe squares wipe between clips.

        - `whip_pan` — Directional motion-blur whip pan.

        - `cinematic_zoom` — Punch zoom with radial blur + chromatic fringing.

        - `burn_edge` — Noise-ridged burn front with ember glow and sparks.

        - `shatter` — Jittered shards fly apart revealing the incoming clip.

        - `domain_warp` — Organic noise-warped dissolve with an emissive
        frontier.
      x-enumDescriptions:
        cross_dissolve: Cross-dissolve — fades one clip into the next.
        dip_to_black: Dips through black between clips.
        dip_to_white: Dips through white between clips.
        wipe_left: Wipes the next clip in from the right to the left.
        wipe_right: Wipes the next clip in from the left to the right.
        wipe_up: Wipes the next clip in from the bottom upward.
        wipe_down: Wipes the next clip in from the top downward.
        diagonal_wipe: Wipes across on a diagonal split.
        barn_doors_horizontal: Two halves part horizontally like barn doors.
        barn_doors_vertical: Two halves part vertically like barn doors.
        iris: Circular iris (bullseye) open/close between clips.
        page_turn: Page-flip / page-curl reveal.
        cross_zoom: Zoom-blur push from one clip into the next.
        gradient_wipe: Soft gradient-driven dissolve wipe.
        band_wipe: Interleaved stripes wipe the next clip in.
        box_wipe: Rectangular box grows to reveal the next clip.
        swirl: Swirls the outgoing clip away in a spiral.
        glitch_memories: Glitchy, memory-like distortion between clips.
        window_slice: Slices the frame into sliding window strips.
        cube: 3D cube rotation between the two clips.
        doorway: Clips part like opening doors to reveal the next.
        pinwheel: Pinwheel rotation wipe between clips.
        water_drop: Rippling water-drop distortion reveals the next clip.
        crosshatch: Crosshatch pattern dissolve between clips.
        dreamy: Soft, dreamy blur-dissolve between clips.
        angular: Angular wedge sweep between clips.
        burn: Burning-film dissolve between clips.
        heart: Heart-shaped iris reveal of the next clip.
        circle_open: Expanding circle opens onto the next clip.
        color_phase: Color-phase shift blends between clips.
        squares_wire: Wireframe squares wipe between clips.
        whip_pan: Directional motion-blur whip pan.
        cinematic_zoom: Punch zoom with radial blur + chromatic fringing.
        burn_edge: Noise-ridged burn front with ember glow and sparks.
        shatter: Jittered shards fly apart revealing the incoming clip.
        domain_warp: Organic noise-warped dissolve with an emissive frontier.
    Point:
      properties:
        x:
          type: number
          title: X
          default: 0.5
        'y':
          type: number
          title: 'Y'
          default: 0.5
      additionalProperties: false
      type: object
      title: Point
    StackLayout:
      properties:
        type:
          type: string
          const: stack
          title: Type
          default: stack
        direction:
          type: string
          enum:
            - row
            - column
          title: Direction
          default: row
        gap:
          type: number
          title: Gap
          description: Gap between members, normalized along the main axis.
          default: 0
        align:
          type: string
          enum:
            - start
            - center
            - end
          title: Align
          default: center
        origin:
          anyOf:
            - $ref: '#/components/schemas/Point'
            - type: 'null'
          description: Centre of the whole stack.
      additionalProperties: false
      type: object
      title: StackLayout
      description: Resolve members into a row/column stack (§5, A2).
    GradientStop:
      properties:
        offset:
          type: number
          maximum: 1
          minimum: 0
          title: Offset
          description: Position along the gradient, 0–1.
        color:
          type: string
          pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
          title: Color
          description: Stop colour (hex, alpha supported).
          example: '#e07a4f'
      additionalProperties: false
      type: object
      required:
        - offset
        - color
      title: GradientStop
    CustomAnimation:
      properties:
        name:
          type: string
          minLength: 1
          title: Name
          description: Reference name (reserved/catalog-shadowing names are rejected).
        keyframes:
          items:
            $ref: '#/components/schemas/AnimationKeyframe'
          type: array
          minItems: 1
          title: Keyframes
      additionalProperties: false
      type: object
      required:
        - name
        - keyframes
      title: CustomAnimation
      description: >-
        A task-supplied keyframe animation, referenced by `name` from an
        animation entry (§3).
    ErrorCode:
      type: string
      enum:
        - invalid_source
        - source_not_found
        - source_too_large
        - asset_not_ready
        - codec_unsupported
        - decode_failed
        - encode_failed
        - timeout
        - out_of_memory
        - gpu_error
        - upload_failed
        - provider_error
        - ingest_failed
        - internal
        - cancelled
      title: ErrorCode
      description: >-
        Structured error codes surfaced on Job.error_code.


        Values:

        - `invalid_source` — A source URL was malformed or inaccessible.

        - `source_not_found` — A source URL returned 404.

        - `source_too_large` — A source file exceeded the maximum allowed size.

        - `asset_not_ready` — A referenced asset was still ingesting when the
        job ran.

        - `codec_unsupported` — A source used a codec the renderer cannot
        decode.

        - `decode_failed` — A source file could not be decoded.

        - `encode_failed` — The output could not be encoded.

        - `timeout` — Processing exceeded the time limit.

        - `out_of_memory` — The renderer ran out of GPU memory.

        - `gpu_error` — A GPU hardware/driver error occurred.

        - `upload_failed` — The output artifact failed to upload to storage.

        - `provider_error` — An upstream provider (e.g. AssemblyAI) returned an
        error.

        - `ingest_failed` — Copying an external source into storage failed.

        - `internal` — An unexpected internal error occurred.

        - `cancelled` — The job was cancelled.
      x-enumDescriptions:
        invalid_source: A source URL was malformed or inaccessible.
        source_not_found: A source URL returned 404.
        source_too_large: A source file exceeded the maximum allowed size.
        asset_not_ready: A referenced asset was still ingesting when the job ran.
        codec_unsupported: A source used a codec the renderer cannot decode.
        decode_failed: A source file could not be decoded.
        encode_failed: The output could not be encoded.
        timeout: Processing exceeded the time limit.
        out_of_memory: The renderer ran out of GPU memory.
        gpu_error: A GPU hardware/driver error occurred.
        upload_failed: The output artifact failed to upload to storage.
        provider_error: An upstream provider (e.g. AssemblyAI) returned an error.
        ingest_failed: Copying an external source into storage failed.
        internal: An unexpected internal error occurred.
        cancelled: The job was cancelled.
    SampleReason:
      type: string
      enum:
        - first_frame
        - element_start
        - transition
        - caption
        - uniform
        - last_frame
      title: SampleReason
      description: >-
        Why a contact-sheet cell was sampled -- what the frame is showing.


        Composition-aware: because we own the timeline, cells land on meaningful

        moments (an element entering, a transition, a caption starting) instead
        of

        blind scene detection, and each carries its reason so the agent knows
        what

        it is looking at.
    EffectType:
      type: string
      enum:
        - vintage
        - polaroid
        - portra
        - super8
        - filmic
        - add_grain
        - rgb_split
        - ghosting
        - displacement_map
        - posterize
        - mosaic
        - mosaic_blur
        - mosaic_posterize
        - cc_halftone
        - cc_halftone_blue
        - cc_halftone_green
        - cc_halftone_red
        - invert
        - optics_compensation
        - viewfinder
        - night_vision
        - thermal
        - camera_lens_blur
        - camera_lens_blur_bg
        - box_blur
        - lens_flare
        - strobe_light
        - snow
        - glow
        - sepia
        - echo
        - chromatic_aberration
        - vhs
        - vhs_overlay
        - crt
        - television
        - glitch
        - compression_glitch
        - scanlines
        - prism
        - light_leaks
        - film_burn
        - duotone
        - cross_process
        - bleach_bypass
        - chroma_key
        - aurora
      title: EffectType
      description: >-
        Values:

        - `vintage` — Faded, warm retro film look with lifted blacks.

        - `polaroid` — Instant-photo look — soft contrast, warm cast, subtle
        vignette.

        - `portra` — Kodak Portra-style film emulation with natural skin tones.

        - `super8` — Super-8 home-movie look — grain, gate weave, warm color.

        - `filmic` — Cinematic film grade with rolled-off highlights and rich
        contrast.

        - `add_grain` — Adds dusty analog film grain over the image.

        - `rgb_split` — Offsets the red/green/blue channels for a glitchy
        chromatic split.

        - `ghosting` — Trailing motion echoes, like persistence-of-vision
        smearing.

        - `displacement_map` — Warps the image with a displacement texture for a
        melted look.

        - `posterize` — Reduces the image to a small number of flat color bands.

        - `mosaic` — Pixelates the image into large mosaic blocks.

        - `mosaic_blur` — Pixelated mosaic with softened, blurred block edges.

        - `mosaic_posterize` — Combines mosaic pixelation with posterized
        colors.

        - `cc_halftone` — Comic-style halftone dot pattern.

        - `cc_halftone_blue` — Halftone dot pattern tinted blue.

        - `cc_halftone_green` — Halftone dot pattern tinted green.

        - `cc_halftone_red` — Halftone dot pattern tinted red.

        - `invert` — Inverts all colors (photo-negative).

        - `optics_compensation` — Fish-eye / lens-distortion warp.

        - `viewfinder` — Camera viewfinder overlay (REC indicator, framing
        marks).

        - `night_vision` — Green night-vision look with glow and noise.

        - `thermal` — Thermal-camera false-color heat map.

        - `camera_lens_blur` — Realistic bokeh lens blur across the frame.

        - `camera_lens_blur_bg` — Bokeh lens blur applied to the background
        only.

        - `box_blur` — Fast, uniform box blur.

        - `lens_flare` — Adds an anamorphic lens-flare streak and glints.

        - `strobe_light` — Rapid brightness strobing / flashing.

        - `snow` — Falling-snow particle overlay.

        - `glow` — Dreamy soft-glow bloom over highlights.

        - `sepia` — Sepia-toned monochrome with a vignette.

        - `echo` — Soft ghosted dream-echo overlay.

        - `chromatic_aberration` — Color-fringing at edges, like cheap-lens
        dispersion.

        - `vhs` — VHS tape look: tracking noise, color bleed, and wobble.

        - `vhs_overlay` — VHS noise/scanline layer composited over the source.

        - `crt` — CRT monitor look: screen curvature, scanlines, and phosphor
        glow.

        - `television` — Analog TV look: scanlines, static, and signal
        distortion.

        - `glitch` — Digital glitch: block displacement and channel tearing.

        - `compression_glitch` — MPEG compression artifacts: blocky macroblocks
        and datamosh.

        - `scanlines` — Horizontal scanlines overlaid on the image.

        - `prism` — Prismatic light refraction with a rainbow color split.

        - `light_leaks` — Warm light-leak streaks bleeding across the frame.

        - `film_burn` — Burning-film look with scorched edges and flares.

        - `duotone` — Two-tone color map (shadows to one hue, highlights to
        another).

        - `cross_process` — Cross-processed film look with shifted, punchy
        colors.

        - `bleach_bypass` — High-contrast, desaturated bleach-bypass film grade.

        - `chroma_key` — Keys out a color (green/blue screen); tune via
        `chroma_settings`.

        - `aurora` — Animated domain-warped fluid-gradient wash (§6); tune flow
        via `props` speed.
      x-enumDescriptions:
        vintage: Faded, warm retro film look with lifted blacks.
        polaroid: Instant-photo look — soft contrast, warm cast, subtle vignette.
        portra: Kodak Portra-style film emulation with natural skin tones.
        super8: Super-8 home-movie look — grain, gate weave, warm color.
        filmic: Cinematic film grade with rolled-off highlights and rich contrast.
        add_grain: Adds dusty analog film grain over the image.
        rgb_split: Offsets the red/green/blue channels for a glitchy chromatic split.
        ghosting: Trailing motion echoes, like persistence-of-vision smearing.
        displacement_map: Warps the image with a displacement texture for a melted look.
        posterize: Reduces the image to a small number of flat color bands.
        mosaic: Pixelates the image into large mosaic blocks.
        mosaic_blur: Pixelated mosaic with softened, blurred block edges.
        mosaic_posterize: Combines mosaic pixelation with posterized colors.
        cc_halftone: Comic-style halftone dot pattern.
        cc_halftone_blue: Halftone dot pattern tinted blue.
        cc_halftone_green: Halftone dot pattern tinted green.
        cc_halftone_red: Halftone dot pattern tinted red.
        invert: Inverts all colors (photo-negative).
        optics_compensation: Fish-eye / lens-distortion warp.
        viewfinder: Camera viewfinder overlay (REC indicator, framing marks).
        night_vision: Green night-vision look with glow and noise.
        thermal: Thermal-camera false-color heat map.
        camera_lens_blur: Realistic bokeh lens blur across the frame.
        camera_lens_blur_bg: Bokeh lens blur applied to the background only.
        box_blur: Fast, uniform box blur.
        lens_flare: Adds an anamorphic lens-flare streak and glints.
        strobe_light: Rapid brightness strobing / flashing.
        snow: Falling-snow particle overlay.
        glow: Dreamy soft-glow bloom over highlights.
        sepia: Sepia-toned monochrome with a vignette.
        echo: Soft ghosted dream-echo overlay.
        chromatic_aberration: Color-fringing at edges, like cheap-lens dispersion.
        vhs: 'VHS tape look: tracking noise, color bleed, and wobble.'
        vhs_overlay: VHS noise/scanline layer composited over the source.
        crt: 'CRT monitor look: screen curvature, scanlines, and phosphor glow.'
        television: 'Analog TV look: scanlines, static, and signal distortion.'
        glitch: 'Digital glitch: block displacement and channel tearing.'
        compression_glitch: 'MPEG compression artifacts: blocky macroblocks and datamosh.'
        scanlines: Horizontal scanlines overlaid on the image.
        prism: Prismatic light refraction with a rainbow color split.
        light_leaks: Warm light-leak streaks bleeding across the frame.
        film_burn: Burning-film look with scorched edges and flares.
        duotone: Two-tone color map (shadows to one hue, highlights to another).
        cross_process: Cross-processed film look with shifted, punchy colors.
        bleach_bypass: High-contrast, desaturated bleach-bypass film grade.
        chroma_key: Keys out a color (green/blue screen); tune via `chroma_settings`.
        aurora: >-
          Animated domain-warped fluid-gradient wash (§6); tune flow via `props`
          speed.
    IntensityKeyframe:
      properties:
        time:
          type: number
          minimum: 0
          title: Time
          description: Absolute timeline seconds.
        value:
          type: number
          maximum: 1
          minimum: 0
          title: Value
          description: Effect intensity 0–1 at this time.
      additionalProperties: false
      type: object
      required:
        - time
        - value
      title: IntensityKeyframe
      description: >-
        A point on a keyframed effect-intensity ramp (§2). Absolute timeline
        seconds.
    ChromaKeyProps:
      properties:
        hue_min:
          type: number
          title: Hue Min
          default: 60
        hue_max:
          type: number
          title: Hue Max
          default: 180
        sat_min:
          type: number
          title: Sat Min
          default: 0.3
        sat_max:
          type: number
          title: Sat Max
          default: 1
        lum_min:
          type: number
          title: Lum Min
          default: 0.2
        lum_max:
          type: number
          title: Lum Max
          default: 0.9
      additionalProperties: false
      type: object
      title: ChromaKeyProps
      description: Used when ``EffectType.CHROMA_KEY`` is selected.
    MotionType:
      type: string
      enum:
        - fade
        - slide_up
        - slide_down
        - slide_left
        - slide_right
        - zoom_in
        - zoom_out
        - rotate_cw
        - rotate_ccw
        - bounce
        - wipe_left
        - wipe_right
        - wipe_up
        - wipe_down
        - ken_burns_in
        - ken_burns_out
        - ken_burns_in_out
        - loop_wiggle
        - loop_rotate
        - loop_rotate_smooth
        - loop_3d_spin
        - loop_3d_sway
        - blur
        - evaporate
        - overlay
        - difference
        - rubber_in
        - whip_up
        - whip_down
        - glitch_pop
        - drift_in
        - drift_out
        - loop_breathe
        - loop_shimmer
        - swing_in
        - swing_out
        - elastic_rise
        - elastic_drop
        - tilt_zoom
        - loop_orbit
        - smooth_pop
      title: MotionType
      description: >-
        Values:

        - `fade` — Fade in (entrance) or out (exit) via opacity.

        - `slide_up` — Slide in from below / out upward.

        - `slide_down` — Slide in from above / out downward.

        - `slide_left` — Slide in from the right / out to the left.

        - `slide_right` — Slide in from the left / out to the right.

        - `zoom_in` — Scale up from small to full size (entrance).

        - `zoom_out` — Scale down to small (exit).

        - `rotate_cw` — Spin in/out clockwise.

        - `rotate_ccw` — Spin in/out counter-clockwise.

        - `bounce` — Bounce in with an elastic overshoot / bounce out.

        - `wipe_left` — Reveal/conceal with a left-moving wipe.

        - `wipe_right` — Reveal/conceal with a right-moving wipe.

        - `wipe_up` — Reveal/conceal with an upward wipe.

        - `wipe_down` — Reveal/conceal with a downward wipe.

        - `ken_burns_in` — Slow zoom-in pan (Ken Burns) — entrance only.

        - `ken_burns_out` — Slow zoom-out pan (Ken Burns) — entrance only.

        - `ken_burns_in_out` — Slow zoom in then out (Ken Burns) — entrance
        only.

        - `loop_wiggle` — Continuous subtle wiggle (looping).

        - `loop_rotate` — Continuous stepped rotation (looping).

        - `loop_rotate_smooth` — Continuous smooth rotation (looping).

        - `loop_3d_spin` — Continuous 3D spin (looping).

        - `loop_3d_sway` — Continuous 3D sway (looping).

        - `blur` — Per-glyph soft blur-in (text entrance).

        - `evaporate` — Per-glyph rise, blur, and fade-out (text exit only).

        - `overlay` — Static Overlay blend fill (timing ignored).

        - `difference` — Static Difference blend fill (timing ignored).

        - `rubber_in` — Per-glyph rubbery overshoot as text springs in (text
        entrance).

        - `whip_up` — Per-glyph whip upward into place (text entrance).

        - `whip_down` — Per-glyph whip downward out of frame (text exit only).

        - `glitch_pop` — Per-glyph glitchy pop-in with jitter (text entrance).

        - `drift_in` — Per-glyph gentle drift and fade in (text entrance).

        - `drift_out` — Per-glyph gentle drift and fade out (text exit only).

        - `loop_breathe` — Per-glyph continuous breathing scale loop (text).

        - `loop_shimmer` — Per-glyph continuous shimmer loop (text).

        - `swing_in` — Element swings into place from an angle (entrance).

        - `swing_out` — Element swings away out of frame (exit only).

        - `elastic_rise` — Element rises with an elastic overshoot (entrance).

        - `elastic_drop` — Element drops away with an elastic recoil (exit
        only).

        - `tilt_zoom` — Element tilts and zooms into place (entrance).

        - `loop_orbit` — Element orbits continuously around its center (loop).

        - `smooth_pop` — Element pops in with a smooth bezier ease (entrance).
      x-enumDescriptions:
        fade: Fade in (entrance) or out (exit) via opacity.
        slide_up: Slide in from below / out upward.
        slide_down: Slide in from above / out downward.
        slide_left: Slide in from the right / out to the left.
        slide_right: Slide in from the left / out to the right.
        zoom_in: Scale up from small to full size (entrance).
        zoom_out: Scale down to small (exit).
        rotate_cw: Spin in/out clockwise.
        rotate_ccw: Spin in/out counter-clockwise.
        bounce: Bounce in with an elastic overshoot / bounce out.
        wipe_left: Reveal/conceal with a left-moving wipe.
        wipe_right: Reveal/conceal with a right-moving wipe.
        wipe_up: Reveal/conceal with an upward wipe.
        wipe_down: Reveal/conceal with a downward wipe.
        ken_burns_in: Slow zoom-in pan (Ken Burns) — entrance only.
        ken_burns_out: Slow zoom-out pan (Ken Burns) — entrance only.
        ken_burns_in_out: Slow zoom in then out (Ken Burns) — entrance only.
        loop_wiggle: Continuous subtle wiggle (looping).
        loop_rotate: Continuous stepped rotation (looping).
        loop_rotate_smooth: Continuous smooth rotation (looping).
        loop_3d_spin: Continuous 3D spin (looping).
        loop_3d_sway: Continuous 3D sway (looping).
        blur: Per-glyph soft blur-in (text entrance).
        evaporate: Per-glyph rise, blur, and fade-out (text exit only).
        overlay: Static Overlay blend fill (timing ignored).
        difference: Static Difference blend fill (timing ignored).
        rubber_in: Per-glyph rubbery overshoot as text springs in (text entrance).
        whip_up: Per-glyph whip upward into place (text entrance).
        whip_down: Per-glyph whip downward out of frame (text exit only).
        glitch_pop: Per-glyph glitchy pop-in with jitter (text entrance).
        drift_in: Per-glyph gentle drift and fade in (text entrance).
        drift_out: Per-glyph gentle drift and fade out (text exit only).
        loop_breathe: Per-glyph continuous breathing scale loop (text).
        loop_shimmer: Per-glyph continuous shimmer loop (text).
        swing_in: Element swings into place from an angle (entrance).
        swing_out: Element swings away out of frame (exit only).
        elastic_rise: Element rises with an elastic overshoot (entrance).
        elastic_drop: Element drops away with an elastic recoil (exit only).
        tilt_zoom: Element tilts and zooms into place (entrance).
        loop_orbit: Element orbits continuously around its center (loop).
        smooth_pop: Element pops in with a smooth bezier ease (entrance).
    Easing:
      type: string
      enum:
        - linear
        - ease_in
        - ease_out
        - ease_in_out
      title: Easing
      description: |-
        Values:
        - `linear` — Constant speed, no acceleration.
        - `ease_in` — Starts slow, accelerates.
        - `ease_out` — Starts fast, decelerates.
        - `ease_in_out` — Slow start and end, faster in the middle.
      x-enumDescriptions:
        linear: Constant speed, no acceleration.
        ease_in: Starts slow, accelerates.
        ease_out: Starts fast, decelerates.
        ease_in_out: Slow start and end, faster in the middle.
    MotionScope:
      type: string
      enum:
        - element
        - character
      title: MotionScope
      description: >-
        Whether a motion preset applies to the whole element or per-glyph (text
        only).


        Values:

        - `element` — The motion animates the whole element as one unit.

        - `character` — The motion animates each text glyph individually (text
        only).
      x-enumDescriptions:
        element: The motion animates the whole element as one unit.
        character: The motion animates each text glyph individually (text only).
    AudioGenerator:
      properties:
        feature:
          type: string
          enum:
            - amplitude
            - bass
            - mid
            - high
            - beat
          title: Feature
          default: amplitude
        scale:
          type: number
          title: Scale
          description: Scale offset per unit feature.
          default: 0
        opacity:
          type: number
          title: Opacity
          description: Opacity offset per unit feature.
          default: 0
        translate:
          anyOf:
            - $ref: '#/components/schemas/Point'
            - type: 'null'
          description: Translate offset per unit feature.
        rotate:
          type: number
          title: Rotate
          description: Rotation offset (degrees) per unit feature.
          default: 0
      additionalProperties: false
      type: object
      title: AudioGenerator
      description: >-
        Audio-reactive property offsets driven by the soundtrack FFT (§3, W2).


        Each frame the mix reduces to the chosen feature and the element's
        properties

        get offset by ``amount × feature`` — beat-bounce, bass-pumped scale,
        etc.
    RangeSelector:
      properties:
        based_on:
          type: string
          enum:
            - glyph
            - word
          title: Based On
          default: glyph
        start:
          type: number
          maximum: 1
          minimum: 0
          title: Start
          description: Range start, fraction along the text.
          default: 0
        end:
          type: number
          maximum: 1
          minimum: 0
          title: End
          description: Range end, fraction along the text.
          default: 1
        falloff:
          type: number
          minimum: 0
          title: Falloff
          description: Ease to zero over this fraction beyond each edge.
          default: 0
        ease:
          anyOf:
            - type: string
            - type: 'null'
          title: Ease
          description: Easing curve name for the falloff.
        invert:
          type: boolean
          title: Invert
          default: false
      additionalProperties: false
      type: object
      title: RangeSelector
      description: >-
        AE-style range selector: shape a text animation's amount by position
        (§4, W2).
    WordAnimationStyle:
      type: string
      enum:
        - glow
        - box
        - scale_pop
        - slide_up
        - fly_in
        - color
      title: WordAnimationStyle
      description: |-
        [API extension] Word-level animations (require word_animation.words).

        Values:
        - `glow` — Highlights the active word with a glowing emphasis.
        - `box` — Draws a colored box behind the active word.
        - `scale_pop` — Pops the active word with a quick scale punch.
        - `slide_up` — Floats each word up into place as it becomes active.
        - `fly_in` — Drops each word in from above as it becomes active.
        - `color` — Recolors the active word (karaoke-style highlight).
      x-enumDescriptions:
        glow: Highlights the active word with a glowing emphasis.
        box: Draws a colored box behind the active word.
        scale_pop: Pops the active word with a quick scale punch.
        slide_up: Floats each word up into place as it becomes active.
        fly_in: Drops each word in from above as it becomes active.
        color: Recolors the active word (karaoke-style highlight).
    Word:
      properties:
        text:
          type: string
          title: Text
        start:
          type: number
          minimum: 0
          title: Start
        end:
          type: number
          exclusiveMinimum: 0
          title: End
      additionalProperties: false
      type: object
      required:
        - text
        - start
        - end
      title: Word
    WordStyle:
      properties:
        color:
          anyOf:
            - type: string
              pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
            - type: 'null'
          title: Color
        bold:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Bold
        italic:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Italic
        underline:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Underline
      additionalProperties: false
      type: object
      title: WordStyle
      description: Per-word style override (§4 W3). Whole-word matches only.
    AnimationKeyframe:
      properties:
        time:
          type: number
          maximum: 1
          minimum: 0
          title: Time
          description: Fraction of the animation (0–1).
        easing:
          anyOf:
            - type: string
            - type: 'null'
          title: Easing
          description: Easing into this keyframe.
        translate:
          anyOf:
            - $ref: '#/components/schemas/Point'
            - type: 'null'
        scale:
          anyOf:
            - type: number
            - type: 'null'
          title: Scale
        rotate:
          anyOf:
            - type: number
            - type: 'null'
          title: Rotate
        opacity:
          anyOf:
            - type: number
            - type: 'null'
          title: Opacity
      additionalProperties: false
      type: object
      required:
        - time
      title: AnimationKeyframe
      description: >-
        A keyframe in a custom animation definition (§3). Time is 0–1 of the
        animation.
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer

````