openapi: 3.2.0
info:
  title: FrameThrower Films API
  version: 1.0.0
  summary: Cinematography reference search over 5,489 films.
  description: Search a film stills library indexed frame by frame on lighting, lens character, shot size, camera angle, colour palette and mood — in plain language, by reference image, or by colour.
  contact:
    name: FrameThrower
    url: https://framethrower.ai/developers
    email: contact@framethrower.ai
  license:
    name: Proprietary
    url: https://framethrower.ai/legal/tos
  termsOfService: https://framethrower.ai/legal/tos
servers:
- url: https://framethrower.ai/api/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Films
  description: The film catalogue
paths:
  /films:
    get:
      tags:
      - Films
      operationId: listFilms
      summary: Film catalogue
      description: 'Paginated catalogue with poster art. Every entry carries `slug`, `frameCount` and a ready-made `framesUrl`.


        **Cost: 2 credits.** $1 = 1,000 credits. Returns 402 when the balance is short.'
      security:
      - bearerAuth: []
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: per_page
        in: query
        schema:
          type: integer
          default: 50
          maximum: 100
      - name: q
        in: query
        schema:
          type: string
        description: Filter by film title, director or cinematographer
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - title
          - frames
          - year
          default: title
        description: frames = best-covered films first
      - name: min_frames
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Films
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
  /films/{slug}:
    get:
      tags:
      - Films
      operationId: getFilm
      summary: Film detail
      description: 'Plot, runtime, rating, dominant colours and sample frames.


        **Cost: 2 credits.** $1 = 1,000 credits. Returns 402 when the balance is short.'
      security:
      - bearerAuth: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        examples:
          blade:
            value: blade-runner-2049-2017
      responses:
        '200':
          description: The film
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '404':
          description: No such film
  /films/frames:
    get:
      tags:
      - Films
      operationId: listFilmFrames
      summary: One film's frames
      description: 'Every frame held for one film, paginated. `meta.total` is the film''s full frame count, so page 1 tells you the whole size.


        **Cost: 2 credits.** $1 = 1,000 credits. Returns 402 when the balance is short.'
      security:
      - bearerAuth: []
      parameters:
      - name: slug
        in: query
        required: true
        schema:
          type: string
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        schema:
          type: integer
          default: 100
          maximum: 200
      responses:
        '200':
          description: Frames
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Frame'
                  meta:
                    type: object
                    additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        docs:
          type: string
        api_reference:
          type: string
    Frame:
      type: object
      description: A single film frame. Thumbnails and deep links only — never raw image bytes.
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
          description: Deep link to this frame on FrameThrower
        thumbnail:
          type: string
          format: uri
        depthUrl:
          type: string
          format: uri
          nullable: true
          description: Precomputed depth map (Depth-Anything V2), WebP, same pixel dimensions as the frame — feed straight to a depth ControlNet. null when the frame has no map; a stale URL 404s, in which case compute depth locally. Never falls back to the colour image.
        score:
          type: number
          description: Relevance, when the call was a search
        film:
          type: object
          properties:
            title:
              type: string
            year:
              type: integer
            slug:
              type: string
            frameCount:
              type: integer
            director:
              type: string
            cinematographer:
              type: string
        shot_type:
          type: string
        lens_character:
          type: string
        camera_angle:
          type: string
        setting:
          type: string
        time_of_day:
          type: string
        visual_style:
          type: string
        colorPalette:
          type: array
          items:
            type: string
          description: Dominant colours as hex
        colorDescription:
          type: string
        prompt:
          type: string
          description: Stored descriptive prompt for the frame
  responses:
    Unauthorized:
      description: Missing, malformed, revoked or unknown token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InsufficientCredits:
      description: Not enough credits. The body carries everything needed to recover without reading docs.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              code:
                type: string
                const: insufficient_credits
              cost:
                type: integer
              balance:
                type: integer
              buy_credits:
                type: string
                format: uri
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Personal access token, prefix `ft_`. Create one at https://framethrower.ai/settings?tab=api — free accounts included, no plan required.
externalDocs:
  url: https://framethrower.ai/developers
  description: Developer documentation