openapi: 3.1.0
info:
  title: Mux Animated Images Summarize 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: Summarize
  description: Generate a title, description, and tags for a video.
  x-displayName: Summarize
paths:
  /robots/v0/jobs/summarize:
    post:
      operationId: create-summarize-job
      summary: Create a 'summarize' Job
      description: Creates a new job that uses AI to generate a title, description, and tags for a Mux Video asset.
      tags:
      - Summarize
      requestBody:
        description: Summarization parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSummarizeJobRequest'
            example:
              parameters:
                asset_id: mux_asset_123abc
                tone: neutral
                tag_count: 10
      responses:
        '202':
          description: Summarize job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummarizeJobResponse'
              example:
                data:
                  id: rjob_example123
                  workflow: summarize
                  status: pending
                  units_consumed: 0
                  created_at: 1700000000
                  updated_at: 1700000060
                  parameters:
                    asset_id: mux_asset_123abc
                    tone: neutral
                    tag_count: 10
        '401':
          description: Missing Mux credentials
          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 or missing playback 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: []
  /robots/v0/jobs/summarize/{JOB_ID}:
    get:
      operationId: get-summarize-job
      summary: Get a 'summarize' Job
      description: Retrieves the current status and results of a 'summarize' job. Jobs are automatically deleted after 30 days.
      tags:
      - Summarize
      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/SummarizeJobResponse'
              example:
                data:
                  id: rjob_example123
                  workflow: summarize
                  status: completed
                  units_consumed: 1
                  created_at: 1700000000
                  updated_at: 1700000060
                  parameters:
                    asset_id: mux_asset_123abc
                    tone: neutral
                    tag_count: 10
                  outputs:
                    title: How to Build a Sustainable Garden in Your Backyard
                    description: This video walks through the step-by-step process of creating a sustainable backyard garden, covering soil preparation, plant selection, and organic pest control methods.
                    tags:
                    - gardening
                    - sustainability
                    - backyard
                    - organic
                    - soil preparation
                    - composting
                    - pest control
                    - beginner
                    - how-to
                    - plants
        '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:
    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
    CreateSummarizeJobRequest:
      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/SummarizeJobParameters'
      required:
      - parameters
    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
    SummarizeJobParameters:
      type: object
      properties:
        asset_id:
          type: string
          minLength: 1
          description: The Mux asset ID of the video to summarize.
        tone:
          type: string
          enum:
          - neutral
          - playful
          - professional
          description: Tone for the generated summary. "neutral" for straightforward analysis, "playful" for witty and conversational, "professional" for executive-level reporting.
        prompt_overrides:
          type: object
          properties:
            task:
              type: string
              minLength: 1
              description: Override the core task instruction for summarization.
            title:
              type: string
              minLength: 1
              description: Override the title generation requirements.
            description:
              type: string
              minLength: 1
              description: Override the description generation requirements.
            keywords:
              type: string
              minLength: 1
              description: Override the keyword/tag extraction requirements.
            quality_guidelines:
              type: string
              minLength: 1
              description: Override the quality standards for analysis.
          description: Override specific sections of the summarization prompt.
        title_length:
          type: integer
          minimum: 1
          description: Maximum title length in words.
        description_length:
          type: integer
          minimum: 1
          description: Maximum description length in words.
        tag_count:
          type: integer
          minimum: 1
          description: Maximum number of tags to include in the generated output. Defaults to 10.
        language_code:
          type: string
          minLength: 1
          description: BCP 47 language code of the caption track to analyze (e.g. "en", "fr"). When omitted, the SDK uses the default track.
        output_language_code:
          type: string
          minLength: 1
          description: BCP 47 language code for the generated summary output (e.g. "en", "fr", "ja"). Auto-detected from the transcript if omitted.
      required:
      - asset_id
      example:
        asset_id: mux_asset_123abc
        tone: neutral
        tag_count: 10
    SummarizeJob:
      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:
          - summarize
        parameters:
          $ref: '#/components/schemas/SummarizeJobParameters'
        status:
          $ref: '#/components/schemas/JobStatus'
        outputs:
          $ref: '#/components/schemas/SummarizeJobOutputs'
        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
    SummarizeJobOutputs:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          description: Generated title capturing the essence of the video.
        description:
          type: string
          minLength: 1
          description: Generated description of the video content (typically 2-4 sentences).
        tags:
          type: array
          items:
            type: string
          description: Generated keyword tags for the video.
      required:
      - title
      - description
      - tags
      example:
        title: How to Build a Sustainable Garden in Your Backyard
        description: This video walks through the step-by-step process of creating a sustainable backyard garden, covering soil preparation, plant selection, and organic pest control methods.
        tags:
        - gardening
        - sustainability
        - backyard
        - organic
        - soil preparation
        - composting
        - pest control
        - beginner
        - how-to
        - plants
      description: Workflow results. Present when status is 'completed'.
    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.
    SummarizeJobResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SummarizeJob'
      required:
      - data
  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