openapi: 3.1.0
info:
  title: Mux Animated Images Thumbnails 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: Thumbnails
  description: APIs for retrieving still thumbnails from videos hosted using Mux.
  x-displayName: Thumbnails
paths:
  /{PLAYBACK_ID}/thumbnail.{EXTENSION}:
    get:
      summary: Retrieve a Video Thumbnail
      description: '[Fetch a thumbnail image from a video](https://docs.mux.com/guides/get-images-from-a-video) at a specified time with optional transformations.'
      operationId: get-thumbnail
      servers:
      - url: https://image.mux.com
      tags:
      - Thumbnails
      parameters:
      - $ref: '#/components/parameters/playback_id'
      - $ref: '#/components/parameters/token'
      - name: EXTENSION
        in: path
        required: true
        description: The image file extension, either 'jpg', 'png', or 'webp'.
        schema:
          type: string
          enum:
          - jpg
          - png
          - webp
      - name: time
        in: query
        description: The time (in seconds) of the video timeline where the image should be pulled. Defaults to the middle of the original video.
        schema:
          type: number
          format: float
      - name: width
        in: query
        description: The width of the thumbnail (in pixels). Defaults to the width of the original video.
        schema:
          type: integer
      - name: height
        in: query
        description: The height of the thumbnail (in pixels). Defaults to the height of the original video.
        schema:
          type: integer
      - name: rotate
        in: query
        description: Rotate the image clockwise by the given number of degrees.
        schema:
          type: integer
          enum:
          - 90
          - 180
          - 270
      - name: fit_mode
        in: query
        description: How to fit a thumbnail within the specified width + height.
        schema:
          type: string
          enum:
          - preserve
          - stretch
          - crop
          - smartcrop
          - pad
      - name: flip_v
        in: query
        description: Flip the image top-bottom after performing all other transformations.
        schema:
          type: boolean
      - name: flip_h
        in: query
        description: Flip the image left-right after performing all other transformations.
        schema:
          type: boolean
      - name: program_time
        in: query
        description: Set the time of the thumbnail for an asset created from a live stream when using the [instant clipping feature](https://docs.mux.com/guides/create-instant-clips). The timestamp should be provided as an epoch integer, and is compared to the program date time (PDT) generated by a live stream.
        schema:
          type: integer
      - name: latest
        in: query
        description: When set to `true`, pulls the latest thumbnail from the playback ID of an ongoing live stream. Can only be used with live streams. Can be used to build moderation and classification workflows, [see documentation for more details](https://mux.com/docs/guides/get-images-from-a-video#getting-the-latest-thumbnail-from-a-live-stream).
        schema:
          type: boolean
      responses:
        '200':
          description: Thumbnail image retrieved successfully.
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request due to invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/paths/~1%7BPLAYBACK_ID%7D~1storyboard.vtt/get/responses/400/content/application~1json/schema'
              example:
                code: 3
                message: Unrecognized fit-mode
        '404':
          description: Video asset not found.
          content:
            application/json:
              schema:
                $ref: '#/paths/~1%7BPLAYBACK_ID%7D~1storyboard.vtt/get/responses/400/content/application~1json/schema'
              example:
                code: 5
                message: Not Found
components:
  parameters:
    playback_id:
      name: PLAYBACK_ID
      in: path
      description: The asset or live stream's playback ID.
      required: true
      schema:
        type: string
    token:
      name: TOKEN
      in: query
      description: Signed token (JWT) for [secure video playback](https://docs.mux.com/guides/secure-video-playback).
      schema:
        type: string
  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