ffmpeg-micro-com Ffprobe API

openapi: 3.2.0
info:
  title: FFmpeg Micro Ffprobe API
  version: 1.0.0
  description: 'The FFmpeg Micro API runs FFmpeg for you. Upload a file or point at a URL,

    create a transcode or transcription job, poll it, and download the result

    from a signed URL.


    Getting started:


    1. Sign up at https://www.ffmpeg-micro.com and create an API key on the dashboard.

    2. Send the key on every request as `Authorization: Bearer `.

    3. Create a job with `POST /v1/transcodes` (or `POST /v1/transcribe`), poll

    `GET /v1/transcodes/{id}` until `status` is `completed`, then call

    `GET /v1/transcodes/{id}/download` for a signed download URL.


    Billing is metered per second of input duration. Free accounts start with a

    one-time token grant and no card.


    This file is the official contract. It is the same spec the API serves at

    https://api.ffmpeg-micro.com/openapi.yaml, and the public Postman

    workspace is generated from it.'
servers:
- url: https://api.ffmpeg-micro.com
  description: Production
tags:
- name: Ffprobe
paths:
  /v1/ffprobe:
    post:
      summary: Read an uploaded file's details (free)
      description: 'Run ffprobe on a file you have uploaded and get back what it reports: duration, container format, size, dimensions, frame rate, codecs, and whether it has video and audio. No job is created and no tokens are charged. The file is named by the `gs://` address that `POST /v1/upload/confirm` returned; that response already carries the same details for a file you just uploaded. A public HTTP(S) address is not accepted: upload the file first. Your plan''s per-file size limit applies. Rate limited to 30 requests per minute per API key.'
      security:
      - bearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  description: The `fileUrl` (a `gs://` address) returned by `POST /v1/upload/confirm`.
                  example: gs://<YOUR_BUCKET>/20251023-143045-my-video.mp4
      responses:
        '200':
          description: What ffprobe reported
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: The address as sent
                  metadata:
                    $ref: '#/components/schemas/MediaMetadata'
              example:
                url: gs://<YOUR_BUCKET>/20251023-143045-my-video.mp4
                metadata:
                  duration_seconds: 123.45
                  format: mov,mp4,m4a,3gp,3g2,mj2
                  size_bytes: 10485760
                  width: 1920
                  height: 1080
                  fps: 30
                  codec_video: h264
                  codec_audio: aac
                  has_video: true
                  has_audio: true
        '400':
          description: 'The `url` is missing or not acceptable. `error` is one of `Missing required field: url`, `Unsupported URL` (anything that is not a `gs://` address), `Placeholder bucket name`, `Invalid input` or `Invalid GCS URL`.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProbeError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No uploaded file has that address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProbeError'
        '422':
          description: '`File too large`: the file is over your plan''s per-file limit. `Could not read media`: ffprobe could not read it as audio, video or an image.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProbeError'
        '429':
          description: More than 30 requests in a minute from this API key.
        '502':
          description: The probe could not run right now. Nothing was charged; try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProbeError'
      tags:
      - Ffprobe
      operationId: postV1Ffprobe
      x-operation-id-source: derived
components:
  schemas:
    ProbeError:
      type: object
      properties:
        error:
          type: string
          example: Could not read media
        details:
          type: array
          items:
            type: string
          description: The reason, in words written for the caller.
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        details:
          type:
          - string
          - 'null'
    MediaMetadata:
      type: object
      description: 'What ffprobe reported about a media file. `duration_seconds`, `format` and `size_bytes` may carry `0` or `"unknown"` when the probe ran but could not determine them (a still image has no duration). `width`, `height`, `fps`, `codec_video`, `codec_audio`, `has_video` and `has_audio` are present only when the probe reported them: a plain audio file has no `width`. Cover art embedded in an audio file is a video stream to ffprobe, so such a file reports `has_video: true` with the artwork''s dimensions. `width` and `height` are the stored dimensions, before any rotation the file carries: a phone video shot upright can report 1920 by 1080.

        '
      properties:
        duration_seconds:
          type: number
          example: 123.45
        format:
          type: string
          description: Container format as ffprobe names it
          example: mov,mp4,m4a,3gp,3g2,mj2
        size_bytes:
          type: integer
          example: 10485760
        width:
          type: integer
          description: Video width in pixels; absent for audio-only files
        height:
          type: integer
          description: Video height in pixels; absent for audio-only files
        fps:
          type: number
          description: Frame rate of the video stream; absent for audio-only files
          example: 29.97
        codec_video:
          type: string
          description: Codec of the video stream (e.g. h264); absent when there is none
        codec_audio:
          type: string
          description: Codec of the audio stream (e.g. aac); absent when there is none
        has_video:
          type: boolean
          description: Whether the file has a video stream
        has_audio:
          type: boolean
          description: Whether the file has an audio stream
  responses:
    Unauthorized:
      description: Missing/invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              value:
                error: unauthorized
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: opaque-api-key
externalDocs:
  description: Guides and examples
  url: https://www.ffmpeg-micro.com/docs