openapi: 3.1.0
info:
  title: Mux Animated Images Find Key Moments API
  description: Mux is how developers build online video. This API encompasses both Mux Video and Mux Data functionality to help you build your video-related projects better and faster than ever before.
  version: v1
  contact:
    name: Mux DevEx
    url: https://docs.mux.com
    email: devex@mux.com
servers:
- url: https://api.mux.com
  description: Mux Production API
- url: https://image.mux.com
- url: https://stream.mux.com
- url: https://stats.mux.com
tags:
- name: Find Key Moments
  description: Identify key moments in a video.
  x-displayName: Find Key Moments
paths:
  /robots/v0/jobs/find-key-moments:
    post:
      operationId: create-find-key-moments-job
      summary: Create a 'find-Key-Moments' Job
      description: Creates a new job that uses AI to identify key moments in a Mux Video asset.
      tags:
      - Find Key Moments
      requestBody:
        description: Key moments extraction parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFindKeyMomentsJobRequest'
            example:
              parameters:
                asset_id: mux_asset_123abc
                max_moments: 5
                target_duration_ms:
                  min: 15000
                  max: 45000
      responses:
        '202':
          description: Key moments job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindKeyMomentsJobResponse'
              example:
                data:
                  id: rjob_example123
                  workflow: find-key-moments
                  status: pending
                  units_consumed: 0
                  created_at: 1700000000
                  updated_at: 1700000060
                  parameters:
                    asset_id: mux_asset_123abc
                    max_moments: 5
                    target_duration_ms:
                      min: 15000
                      max: 45000
        '401':
          description: Missing Mux credentials for transcript access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Asset not found, missing playback ID, or no transcript
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      servers:
      - url: https://api.mux.com
      security:
      - accessToken: []
      - authorizationToken: []
  /robots/v0/jobs/find-key-moments/{JOB_ID}:
    get:
      operationId: get-find-key-moments-job
      summary: Get a 'find-Key-Moments' Job
      description: Retrieves the current status and results of a 'find-key-moments' job. Jobs are automatically deleted after 30 days.
      tags:
      - Find Key Moments
      parameters:
      - schema:
          type: string
          minLength: 1
          maxLength: 255
        required: true
        name: JOB_ID
        in: path
      responses:
        '200':
          description: Current status for the requested job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindKeyMomentsJobResponse'
              example:
                data:
                  id: rjob_example123
                  workflow: find-key-moments
                  status: completed
                  units_consumed: 1
                  created_at: 1700000000
                  updated_at: 1700000060
                  parameters:
                    asset_id: mux_asset_123abc
                    max_moments: 5
                    target_duration_ms:
                      min: 15000
                      max: 45000
                  outputs:
                    moments:
                    - start_ms: 15000
                      end_ms: 45000
                      cues:
                      - start_ms: 15000
                        end_ms: 20000
                        text: This is the moment everything changed.
                      - start_ms: 20000
                        end_ms: 30000
                        text: We realized the entire approach was wrong.
                      overall_score: 0.92
                      title: The Pivotal Realization
                      audible_narrative: The speaker describes the turning point that reshaped the project direction.
                      notable_audible_concepts:
                      - pivotal realization moment
                      - project direction change
                      visual_narrative: The speaker gestures emphatically at a whiteboard diagram while the camera zooms in.
                      notable_visual_concepts:
                      - concept: whiteboard diagram emphasis
                        score: 0.88
                        rationale: The diagram directly illustrates the pivotal realization being described.
                      - concept: speaker emphatic gestures
                        score: 0.75
                        rationale: Body language reinforces the emotional weight of the turning point.
        '403':
          description: Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No job exists for the supplied id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      servers:
      - url: https://api.mux.com
      security:
      - accessToken: []
      - authorizationToken: []
components:
  schemas:
    FindKeyMomentsJobOutputs:
      type: object
      properties:
        moments:
          type: array
          items:
            type: object
            properties:
              start_ms:
                type: number
                minimum: 0
                description: Moment start time in milliseconds.
              end_ms:
                type: number
                minimum: 0
                description: Moment end time in milliseconds.
              cues:
                type: array
                items:
                  type: object
                  properties:
                    start_ms:
                      type: number
                      minimum: 0
                      description: Cue start time in milliseconds.
                    end_ms:
                      type: number
                      minimum: 0
                      description: Cue end time in milliseconds.
                    text:
                      type: string
                      minLength: 1
                      description: Transcript text for this cue.
                  required:
                  - start_ms
                  - end_ms
                  - text
                minItems: 1
                description: Contiguous transcript segments that comprise this moment.
              overall_score:
                type: number
                minimum: 0
                maximum: 1
                description: Weighted quality score from 0.0 to 1.0 based on hook strength, clarity, emotional intensity, novelty, and soundbite quality.
              title:
                type: string
                minLength: 1
                description: Short catchy title for the moment (3-8 words).
              audible_narrative:
                type: string
                minLength: 1
                description: One-sentence summary of what is being said during the moment.
              notable_audible_concepts:
                type: array
                items:
                  type: string
                  minLength: 3
                minItems: 1
                description: Multi-word descriptive phrases (2-5 words each) capturing key audible concepts.
              visual_narrative:
                type: string
                minLength: 1
                description: One-sentence summary of what is visually happening. Present for video assets only.
              notable_visual_concepts:
                type: array
                items:
                  type: object
                  properties:
                    concept:
                      type: string
                      minLength: 3
                      description: Multi-word visual concept (2-5 words).
                    score:
                      type: number
                      minimum: 0
                      maximum: 1
                      description: Relevance score from 0.0 to 1.0 measuring how closely the visual concept relates to the audible narrative.
                    rationale:
                      type: string
                      minLength: 1
                      description: Brief explanation of the relevance score.
                  required:
                  - concept
                  - score
                  - rationale
                minItems: 1
                description: Scored visual concepts extracted from sampled frames. Present for video assets only.
            required:
            - start_ms
            - end_ms
            - cues
            - overall_score
            - title
            - audible_narrative
            - notable_audible_concepts
          description: Extracted key moments, ordered by position in the video.
      required:
      - moments
      example:
        moments:
        - start_ms: 15000
          end_ms: 45000
          cues:
          - start_ms: 15000
            end_ms: 20000
            text: This is the moment everything changed.
          - start_ms: 20000
            end_ms: 30000
            text: We realized the entire approach was wrong.
          overall_score: 0.92
          title: The Pivotal Realization
          audible_narrative: The speaker describes the turning point that reshaped the project direction.
          notable_audible_concepts:
          - pivotal realization moment
          - project direction change
          visual_narrative: The speaker gestures emphatically at a whiteboard diagram while the camera zooms in.
          notable_visual_concepts:
          - concept: whiteboard diagram emphasis
            score: 0.88
            rationale: The diagram directly illustrates the pivotal realization being described.
          - concept: speaker emphatic gestures
            score: 0.75
            rationale: Body language reinforces the emotional weight of the turning point.
      description: Workflow results. Present when status is 'completed'.
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Machine-readable error type.
            message:
              type: string
              description: Human-readable error message describing what went wrong.
          required:
          - type
          - message
      required:
      - error
    FindKeyMomentsJob:
      type: object
      properties:
        id:
          type: string
          description: Unique job identifier.
        passthrough:
          type: string
          description: Arbitrary string supplied at creation, returned as-is.
        units_consumed:
          type: integer
          minimum: 0
          description: Number of Mux AI units consumed by this job.
        created_at:
          type: integer
          minimum: 0
          description: Unix timestamp (seconds) when the job was created.
        updated_at:
          type: integer
          minimum: 0
          description: Unix timestamp (seconds) when the job was last updated.
        workflow:
          type: string
          enum:
          - find-key-moments
        parameters:
          $ref: '#/components/schemas/FindKeyMomentsJobParameters'
        status:
          $ref: '#/components/schemas/JobStatus'
        outputs:
          $ref: '#/components/schemas/FindKeyMomentsJobOutputs'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/JobError'
          description: Error details. Present when status is 'errored'.
        resources:
          $ref: '#/components/schemas/Resources'
      required:
      - id
      - units_consumed
      - created_at
      - updated_at
      - workflow
      - parameters
      - status
    JobError:
      type: object
      properties:
        type:
          type: string
          description: Stable public error category identifier.
        message:
          type: string
          description: Human-readable public error message.
        retryable:
          type: boolean
          description: Whether retrying this job may resolve the error.
      required:
      - type
      - message
    SlimlineAsset:
      type: object
      properties:
        id:
          type: string
          description: Mux asset ID.
        meta:
          type: object
          properties:
            title:
              type: string
              description: Asset title from Mux metadata.
            creator_id:
              type: string
              description: Creator identifier from Mux metadata.
            external_id:
              type: string
              description: External identifier from Mux metadata.
          description: Mux asset metadata, if available.
        passthrough:
          type: string
          description: Passthrough string from the Mux asset.
        _links:
          type: object
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
                  description: URL to the Mux asset resource.
              required:
              - href
          required:
          - self
          description: Hypermedia links for the asset.
      required:
      - id
      - _links
    FindKeyMomentsJobResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/FindKeyMomentsJob'
      required:
      - data
    JobStatus:
      type: string
      enum:
      - pending
      - processing
      - completed
      - errored
      - cancelled
      description: Current job status.
    Resources:
      type: object
      properties:
        assets:
          type: array
          items:
            $ref: '#/components/schemas/SlimlineAsset'
          description: Mux assets associated with this job.
      required:
      - assets
      example:
        assets:
        - id: abc123asset
          meta:
            title: My Video
            creator_id: user123
            external_id: ext456
          _links:
            self:
              href: https://api.mux.com/video/v1/assets/abc123asset
      description: Related Mux resources linked to this job.
    FindKeyMomentsJobParameters:
      type: object
      properties:
        asset_id:
          type: string
          minLength: 1
          description: The Mux asset ID of the video to analyze.
        max_moments:
          type: integer
          minimum: 1
          maximum: 10
          description: Maximum number of key moments to extract. Defaults to 5.
        target_duration_ms:
          type: object
          properties:
            min:
              type: integer
              exclusiveMinimum: 0
              description: Preferred minimum highlight duration in milliseconds.
            max:
              type: integer
              exclusiveMinimum: 0
              description: Preferred maximum highlight duration in milliseconds.
          required:
          - min
          - max
          description: Preferred highlight duration range in milliseconds. When provided, the model will aim to select moments within this range.
      required:
      - asset_id
      example:
        asset_id: mux_asset_123abc
        max_moments: 5
        target_duration_ms:
          min: 15000
          max: 45000
    CreateFindKeyMomentsJobRequest:
      type: object
      properties:
        passthrough:
          type: string
          description: Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems.
        parameters:
          $ref: '#/components/schemas/FindKeyMomentsJobParameters'
      required:
      - parameters
  securitySchemes:
    accessToken:
      description: 'The Mux Video API uses an Access Token and Secret Key for authentication. If you haven''t already, [generate a new Access Token](https://dashboard.mux.com/settings/access-tokens) in the Access Token settings of your Mux account dashboard.


        Once you have an Access Token ID and Secret, you can then simply include those as the username (id) and password (secret) in the same way you use traditional basic auth.

        '
      scheme: basic
      type: http
    authorizationToken:
      description: 'OAuth authorization token, used as a Bearer Auth header

        '
      scheme: bearer
      type: http
x-tagGroups:
- name: Video
  tags:
  - Assets
  - Live Streams
  - Playback ID
  - URL Signing Keys
  - Direct Uploads
  - Delivery Usage
  - Playback Restrictions
  - DRM Configurations
  - Transcription Vocabularies
- name: Data
  tags:
  - Video Views
  - Errors
  - Filters
  - Exports
  - Metrics
  - Monitoring
  - Real-Time
  - Dimensions
  - Incidents
  - Annotations
  - View and Viewer Counts
- name: System
  tags:
  - Signing Keys
  - Utilities
- name: Robots
  tags:
  - Jobs
  - Ask Questions
  - Edit Captions
  - Find Key Moments
  - Generate Chapters
  - Moderate
  - Summarize
  - Translate Captions
- name: Playback
  tags:
  - Thumbnails
  - Animated Images
  - Storyboards
  - Streaming
  - Captions and Transcripts