openapi: 3.1.0
info:
  title: Lemo Opuscar Cinema Studio
  description: Universal AI Director & Code-Based Animation Engine for ChatGPT Custom
    GPTs and Actions.
  version: 1.0.0
paths:
  /health:
    get:
      summary: Health Check
      operationId: getHealthStatus
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/styles:
    get:
      summary: List Film Styles
      description: 'Returns the curated catalog of 66 cinematic visual styles (such
        as Blueprint, Watercolor, Ukiyo-e, 80s Cel Anime, Sci-Fi HUD).

        Use this to help the user discover and choose an aesthetic style for their
        film.'
      operationId: listStyles
      parameters:
      - name: category
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Category filter (e.g. 'Documentary', 'Evidence', 'Painting',
            'Print', 'Graphic', 'Keynote', 'Anime', '3D')
          title: Category
        description: Category filter (e.g. 'Documentary', 'Evidence', 'Painting',
          'Print', 'Graphic', 'Keynote', 'Anime', '3D')
      - name: query
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Keyword search in style name, slug, or aesthetic description
          title: Query
        description: Keyword search in style name, slug, or aesthetic description
      - name: lang
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Output language: ''en'' or ''cn'''
          default: en
          title: Lang
        description: 'Output language: ''en'' or ''cn'''
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StyleSummary'
                title: Response Liststyles
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/styles/{slug}:
    get:
      summary: Get Style Details and Rules
      description: 'Retrieves full directing rules, visual invariants, color palettes,
        camera grammar, sound design palette,

        native moves, and pitfalls for a specific style slug.'
      operationId: getStyleDetails
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StyleDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/director/treatment:
    post:
      summary: Generate Director Treatment
      description: 'Acts as the AI Film Director following DIRECTOR.md.

        Synthesizes 3 candidate narrative structures, selects the best fit, generates
        a logline,

        a 3-act story arc, an intentional shot list, a synchronized musical cue map,
        and narration lines.'
      operationId: createDirectorTreatment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TreatmentRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreatmentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - actionBearer: []
  /api/director/script:
    post:
      summary: Generate Code-based Film Page
      description: 'Generates deterministic HTML5 Canvas / WebGL code adhering strictly
        to the Lemo-Opuscar contract:

        window.READY, window.render(t), window.DUR, window.TEXTS(t), and window.EV.

        Saves the project, sets up an interactive viewer URL and provides a direct
        ZIP download link.'
      operationId: generateFilmScript
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScriptGenerationRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScriptGenerationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - actionBearer: []
  /api/render/readcheck:
    post:
      summary: Verify Reading Speed of Texts
      description: 'Verifies that on-screen titles, subtitles, and labels remain visible
        long enough for comfortable reading

        using the formal Lemo formula: (CJK chars / 4.5) + (Latin chars / 15) + 1.5s
        padding.'
      operationId: verifyReadingTime
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadcheckRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadcheckResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - actionBearer: []
  /api/render/preview:
    post:
      summary: Render Still Frame Previews
      description: 'Renders high-resolution JPEG still frames at requested timestamps
        (e.g. t = 1.0, 5.0, 15.0)

        using headless Chromium. Returns direct URLs that ChatGPT can display inline
        as images.'
      operationId: renderStillPreviews
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - actionBearer: []
  /api/render/video:
    post:
      summary: Render and Bundle Video Project
      description: 'Coordinates the production pipeline: synthesizes TTS audio narration,
        generates timed subtitles (.srt),

        bundles the project, and returns interactive viewer and download links.'
      operationId: renderAndBundleVideo
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoRenderRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoRenderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - actionBearer: []
components:
  schemas:
    CueItem:
      properties:
        timestamp_seconds:
          type: number
          title: Timestamp Seconds
          description: Timestamp in seconds
        bar_beat:
          anyOf:
          - type: string
          - type: 'null'
          title: Bar Beat
          description: Musical bar and beat position, e.g. '1.1'
        event_type:
          type: string
          title: Event Type
          description: Cut, Key Action, Subtitle, SFX, or Musical Transition
        description:
          type: string
          title: Description
          description: Detailed description of the cue event
      type: object
      required:
      - timestamp_seconds
      - event_type
      - description
      title: CueItem
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PreviewRequest:
      properties:
        style_slug:
          type: string
          title: Style Slug
          description: Style slug
        html_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Html Code
          description: HTML code to render. If omitted, default style template is
            rendered
        timestamps:
          items:
            type: number
          type: array
          title: Timestamps
          description: Timestamps in seconds to capture still frames
          default:
          - 1.0
          - 5.0
          - 15.0
        width:
          anyOf:
          - type: integer
          - type: 'null'
          title: Width
          description: Viewport width
          default: 1920
        height:
          anyOf:
          - type: integer
          - type: 'null'
          title: Height
          description: Viewport height
          default: 1080
      type: object
      required:
      - style_slug
      title: PreviewRequest
    PreviewResponse:
      properties:
        status:
          type: string
          title: Status
          description: Status of the preview operation
        stills:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Stills
          description: List of generated stills with URL and timestamp
        render_time_ms:
          type: number
          title: Render Time Ms
          description: Rendering time in milliseconds
      type: object
      required:
      - status
      - stills
      - render_time_ms
      title: PreviewResponse
    ReadcheckRequest:
      properties:
        texts:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Texts
          description: 'List of text elements: [{id, text, t_start, t_end}]'
      type: object
      required:
      - texts
      title: ReadcheckRequest
    ReadcheckResult:
      properties:
        passed:
          type: boolean
          title: Passed
          description: Whether all texts meet reading time requirements
        details:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Details
          description: Evaluation per text element
        summary:
          type: string
          title: Summary
          description: Human readable evaluation summary
      type: object
      required:
      - passed
      - details
      - summary
      title: ReadcheckResult
    ScriptGenerationRequest:
      properties:
        treatment:
          $ref: '#/components/schemas/TreatmentResponse'
          description: Complete director treatment object
        style_slug:
          type: string
          title: Style Slug
          description: Style slug
        project_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Name
          description: Name for the project folder
          default: opuscar_film
      type: object
      required:
      - treatment
      - style_slug
      title: ScriptGenerationRequest
    ScriptGenerationResponse:
      properties:
        project_id:
          type: string
          title: Project Id
          description: Project identifier
        html_code:
          type: string
          title: Html Code
          description: Complete standalone HTML5 Canvas/WebGL animation code
        viewer_url:
          type: string
          title: Viewer Url
          description: URL to view and play the animation in browser
        download_url:
          type: string
          title: Download Url
          description: URL to download the full project as a ZIP bundle
        page_contract:
          additionalProperties:
            type: string
          type: object
          title: Page Contract
          description: Contract specifications satisfied
        notes:
          items:
            type: string
          type: array
          title: Notes
          description: Implementation notes
      type: object
      required:
      - project_id
      - html_code
      - viewer_url
      - download_url
      - page_contract
      title: ScriptGenerationResponse
    ShotSpec:
      properties:
        shot_number:
          type: integer
          title: Shot Number
          description: Sequential shot number
        framing:
          type: string
          title: Framing
          description: 'Framing type: wide, full, medium, close, insert'
        angle:
          type: string
          title: Angle
          description: 'Camera angle: eye-level, low, high, top-down, oblique'
        camera_move:
          type: string
          title: Camera Move
          description: 'Camera move: push, pull, pan, track, crane, zoom, lock'
        duration_seconds:
          type: number
          title: Duration Seconds
          description: Shot duration in seconds
        purpose:
          type: string
          title: Purpose
          description: Dramatic or informational intent behind this shot
        visual_description:
          type: string
          title: Visual Description
          description: Exact visual content and composition of the shot
      type: object
      required:
      - shot_number
      - framing
      - angle
      - camera_move
      - duration_seconds
      - purpose
      - visual_description
      title: ShotSpec
    StyleDetail:
      properties:
        slug:
          type: string
          title: Slug
          description: Unique slug of the visual style
        num:
          type: string
          title: Num
          description: Style number index
        en:
          type: string
          title: En
          description: English name of the style
        cn:
          type: string
          title: Cn
          description: Chinese name of the style
        category_en:
          type: string
          title: Category En
          description: Category in English
        category_cn:
          type: string
          title: Category Cn
          description: Category in Chinese
        film:
          type: string
          title: Film
          description: Benchmark film name from the library
        line:
          type: string
          title: Line
          description: One-line aesthetic premise
        line_cn:
          type: string
          title: Line Cn
          description: One-line premise in Chinese
        uses:
          items:
            type: string
          type: array
          title: Uses
          description: Recommended use cases
        dur:
          type: number
          title: Dur
          description: Default film duration in seconds
        poster_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Poster Url
          description: URL of the style poster preview
        style_prompt:
          type: string
          title: Style Prompt
          description: Complete style prompt containing materials, camera, color,
            and motion invariants
        invariants:
          additionalProperties: true
          type: object
          title: Invariants
          description: Parsed invariant rules
        sound_palette:
          items:
            type: string
          type: array
          title: Sound Palette
          description: List of acoustic and foley elements
        native_moves:
          items:
            type: string
          type: array
          title: Native Moves
          description: Medium-specific climax transitions
        pitfalls:
          items:
            type: string
          type: array
          title: Pitfalls
          description: Common visual and directing mistakes to avoid
      type: object
      required:
      - slug
      - num
      - en
      - cn
      - category_en
      - category_cn
      - film
      - line
      - line_cn
      - dur
      - style_prompt
      title: StyleDetail
    StyleSummary:
      properties:
        slug:
          type: string
          title: Slug
          description: Unique slug of the visual style
        num:
          type: string
          title: Num
          description: Style number index
        en:
          type: string
          title: En
          description: English name of the style
        cn:
          type: string
          title: Cn
          description: Chinese name of the style
        category_en:
          type: string
          title: Category En
          description: Category in English (e.g. Documentary, Evidence, Painting,
            Graphic)
        category_cn:
          type: string
          title: Category Cn
          description: Category in Chinese
        line:
          type: string
          title: Line
          description: One-line aesthetic premise
        line_cn:
          type: string
          title: Line Cn
          description: One-line premise in Chinese
        uses:
          items:
            type: string
          type: array
          title: Uses
          description: Recommended use cases
        dur:
          type: number
          title: Dur
          description: Default film duration in seconds
        poster_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Poster Url
          description: URL of the style poster preview
      type: object
      required:
      - slug
      - num
      - en
      - cn
      - category_en
      - category_cn
      - line
      - line_cn
      - dur
      title: StyleSummary
    TreatmentRequest:
      properties:
        topic:
          type: string
          title: Topic
          description: The user's topic or story premise for the film
        style_slug:
          type: string
          title: Style Slug
          description: Selected visual style slug (e.g. 'blueprint', 'watercolor',
            'ukiyo-e', 'sci-fi-hud')
        duration_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Duration Seconds
          description: Film duration in seconds (typically 30-60s)
          default: 45.0
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
          description: 'Spoken/subtitled language: ''es'', ''en'', ''zh'', or ''auto'''
          default: auto
        aspect_ratio:
          anyOf:
          - type: string
          - type: 'null'
          title: Aspect Ratio
          description: 'Aspect ratio: ''16:9'' or ''9:16'''
          default: '16:9'
        has_voiceover:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Has Voiceover
          description: Whether to include spoken narration
          default: true
        user_materials:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: User Materials
          description: Custom facts, logos, or parameters provided by user
      type: object
      required:
      - topic
      - style_slug
      title: TreatmentRequest
    TreatmentResponse:
      properties:
        title:
          type: string
          title: Title
          description: Film title
        style_slug:
          type: string
          title: Style Slug
          description: Style slug
        logline:
          type: string
          title: Logline
          description: Single sentence dramatic summary
        candidate_structures:
          items:
            additionalProperties:
              type: string
            type: object
          type: array
          title: Candidate Structures
          description: 3 candidate narrative structures evaluated
        chosen_structure:
          type: string
          title: Chosen Structure
          description: The chosen narrative structure
        chosen_structure_reason:
          type: string
          title: Chosen Structure Reason
          description: Justification for selecting this structure
        benchmark:
          additionalProperties:
            type: string
          type: object
          title: Benchmark
          description: Reference work analyzed for pacing/visuals without copying
        story_arc:
          additionalProperties:
            type: string
          type: object
          title: Story Arc
          description: Setup, turn, ending breakdown
        native_move:
          type: string
          title: Native Move
          description: Unique medium-specific climax transition
        shot_list:
          items:
            $ref: '#/components/schemas/ShotSpec'
          type: array
          title: Shot List
          description: Detailed shot-by-shot directing plan
        cue_map:
          items:
            $ref: '#/components/schemas/CueItem'
          type: array
          title: Cue Map
          description: Musical cue map aligning rhythm and cuts
        sound_design:
          additionalProperties: true
          type: object
          title: Sound Design
          description: Ambience, foley, and music arrangement
        narration_lines:
          items:
            $ref: '#/components/schemas/VoiceLine'
          type: array
          title: Narration Lines
          description: Narration voiceover lines
        total_duration:
          type: number
          title: Total Duration
          description: Total film duration in seconds
      type: object
      required:
      - title
      - style_slug
      - logline
      - candidate_structures
      - chosen_structure
      - chosen_structure_reason
      - benchmark
      - story_arc
      - native_move
      - shot_list
      - cue_map
      - sound_design
      - narration_lines
      - total_duration
      title: TreatmentResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    VideoRenderRequest:
      properties:
        project_name:
          type: string
          title: Project Name
          description: Project name
        style_slug:
          type: string
          title: Style Slug
          description: Style slug
        html_code:
          type: string
          title: Html Code
          description: Complete HTML code
        voice_lines:
          anyOf:
          - items:
              $ref: '#/components/schemas/VoiceLine'
            type: array
          - type: 'null'
          title: Voice Lines
          description: Voice lines for narration
        fps:
          anyOf:
          - type: integer
          - type: 'null'
          title: Fps
          description: Frame rate
          default: 24
        width:
          anyOf:
          - type: integer
          - type: 'null'
          title: Width
          description: Frame width
          default: 1920
        height:
          anyOf:
          - type: integer
          - type: 'null'
          title: Height
          description: Frame height
          default: 1080
      type: object
      required:
      - project_name
      - style_slug
      - html_code
      title: VideoRenderRequest
    VideoRenderResponse:
      properties:
        project_id:
          type: string
          title: Project Id
          description: Project identifier
        status:
          type: string
          title: Status
          description: Render status
        viewer_url:
          type: string
          title: Viewer Url
          description: Interactive player URL
        download_url:
          type: string
          title: Download Url
          description: ZIP download URL
        audio_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Audio Url
          description: Generated audio narration URL
        subtitles_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Subtitles Url
          description: Generated SRT subtitles URL
        duration:
          type: number
          title: Duration
          description: Film duration
        message:
          type: string
          title: Message
          description: Summary message
      type: object
      required:
      - project_id
      - status
      - viewer_url
      - download_url
      - duration
      - message
      title: VideoRenderResponse
    VoiceLine:
      properties:
        id:
          type: string
          title: Id
          description: Unique voice line ID, e.g. 'v1'
        start_time:
          type: number
          title: Start Time
          description: Start timestamp in seconds
        duration:
          type: number
          title: Duration
          description: Duration in seconds
        text:
          type: string
          title: Text
          description: Spoken narration text
        voice:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice
          description: Neural voice identifier
      type: object
      required:
      - id
      - start_time
      - duration
      - text
      title: VoiceLine
  securitySchemes:
    actionBearer:
      type: http
      scheme: bearer
servers:
- url: https://lemo.ocloud.click
  description: Lemo Opuscar production server