ffmpeg-micro-com Upload API

openapi: 3.2.0
info:
  title: FFmpeg Micro Upload 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: Upload
paths:
  /v1/upload/presigned-url:
    post:
      summary: Generate presigned upload URL
      description: 'Generates a presigned URL for direct file upload to Google Cloud Storage. This is the first step in the upload workflow - use the returned URL to upload your file.

        **Upload Workflow:** 1. Call this endpoint to get a presigned URL 2. Upload file directly to GCS using HTTP PUT 3. Call `/v1/upload/confirm` to verify upload 4. Use the GCS URL in your transcode request

        **Benefits:** - No server bandwidth usage - Faster uploads (direct to GCS) - Secure (presigned URLs expire)'
      security:
      - bearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - filename
              - contentType
              - fileSize
              properties:
                filename:
                  type: string
                  description: Original filename (will be prefixed with timestamp)
                  example: my-video.mp4
                contentType:
                  type: string
                  description: 'MIME type of the file. Must be one of the supported types below — note AVI is `video/x-msvideo` (not `video/avi`). Matroska/MKV is not supported.

                    '
                  enum:
                  - video/mp4
                  - video/webm
                  - video/quicktime
                  - video/x-msvideo
                  - audio/mpeg
                  - audio/mp4
                  - audio/aac
                  - audio/wav
                  - audio/ogg
                  - audio/opus
                  - audio/flac
                  - image/jpeg
                  - image/png
                  - image/gif
                  - image/webp
                  example: video/mp4
                fileSize:
                  type: integer
                  description: 'File size in bytes as a JSON number (not a string). Must be finite, positive, and under the hard cap of 1.9 GiB (2040109465 bytes). String values (including digit-only strings like "1024") are rejected with 400. Plans also carry their own maximum input file size (100 MB on Free, 1 GB on Starter, 2 GB on Pro); that limit is checked asynchronously after job creation — an oversize input still returns 201 from POST /v1/transcodes and the job then transitions to `failed` with `error_category: file_size`.

                    '
                  minimum: 1
                  maximum: 2040109465
                  example: 10485760
            example:
              filename: my-video.mp4
              contentType: video/mp4
              fileSize: 10485760
      responses:
        '200':
          description: Presigned URL generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  result:
                    type: object
                    properties:
                      uploadUrl:
                        type: string
                        format: uri
                        description: Presigned URL for HTTP PUT upload
                        example: https://storage.googleapis.com/bucket/timestamp-my-video.mp4?X-Goog-Algorithm=...
                      filename:
                        type: string
                        description: Final filename in GCS (with timestamp prefix)
                        example: 20251023-143045-my-video.mp4
              example:
                success: true
                result:
                  uploadUrl: https://storage.googleapis.com/my-bucket/20251023-143045-my-video.mp4?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=...
                  filename: 20251023-143045-my-video.mp4
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              examples:
                missingFields:
                  value:
                    error: 'Missing required fields: filename, contentType, fileSize'
                invalidFileSize:
                  value:
                    error: Invalid fileSize. Must be a positive number in bytes (not a formatted string like '1.46mbs')
                invalidFileType:
                  value:
                    error: Invalid file type. Only video, audio, or image files are allowed.
                fileTooLarge:
                  value:
                    error: File size too large. Maximum allowed size is 2GB.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Upload
      operationId: postV1UploadPresignedUrl
      x-operation-id-source: derived
  /v1/upload/confirm:
    post:
      summary: Confirm file upload
      description: 'Confirms that a file has been successfully uploaded to GCS. This is the final step in the upload workflow.

        **Use the returned GCS URL in your transcode requests:** - Format: `gs://bucket-name/filename` - Example: `gs:///20251023-143045-my-video.mp4`'
      security:
      - bearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - filename
              - fileSize
              properties:
                filename:
                  type: string
                  description: Filename returned from presigned URL generation
                  example: 20251023-143045-my-video.mp4
                fileSize:
                  type: integer
                  description: 'Actual uploaded size in bytes as a JSON number (must match the object in GCS). Same rules as presign: not a string, must be finite and positive.

                    '
                  example: 10485760
                uploadId:
                  type: string
                  description: Optional upload ID for tracking
                  example: upload-12345
            example:
              filename: 20251023-143045-my-video.mp4
              fileSize: 10485760
              uploadId: upload-12345
      responses:
        '200':
          description: Upload confirmed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  result:
                    type: object
                    properties:
                      fileUrl:
                        type: string
                        description: GCS URL (`gs://…`) for use in transcode/transcribe requests
                        example: gs://<YOUR_BUCKET>/20251023-143045-my-video.mp4
                      downloadUrl:
                        type: string
                        format: uri
                        description: Short-lived (1 hour) signed HTTPS URL for the uploaded file
                        example: https://storage.googleapis.com/my-bucket/20251023-143045-my-video.mp4?X-Goog-Algorithm=...
                      filename:
                        type: string
                        example: 20251023-143045-my-video.mp4
                      fileSize:
                        type: integer
                        description: Actual size in bytes as verified in GCS
                        example: 10485760
                      uploadedAt:
                        type: string
                        format: date-time
                      metadata:
                        allOf:
                        - $ref: '#/components/schemas/MediaMetadata'
                        description: 'Best-effort media probe of the uploaded file. Empty object when the probe request itself fails. When the probe responds but cannot determine a value, sentinel values are returned rather than the key being omitted: `duration_seconds: 0`, `format: "unknown"`, `size_bytes: 0`. The other fields are present only when the probe reported them.

                          '
              example:
                success: true
                result:
                  fileUrl: gs://<YOUR_BUCKET>/20251023-143045-my-video.mp4
                  downloadUrl: https://storage.googleapis.com/my-bucket/20251023-143045-my-video.mp4?X-Goog-Algorithm=...
                  filename: 20251023-143045-my-video.mp4
                  fileSize: 10485760
                  uploadedAt: '2026-08-18T19:04:05.000Z'
                  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: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              examples:
                missingFields:
                  value:
                    error: 'Missing required fields: filename, fileSize'
                invalidFileSize:
                  value:
                    error: Invalid fileSize. Must be a positive number in bytes (not a formatted string like '1.46mbs')
                fileNotFound:
                  value:
                    error: File not found in GCS bucket
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Upload
      operationId: postV1UploadConfirm
      x-operation-id-source: derived
components:
  responses:
    Unauthorized:
      description: Missing/invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              value:
                error: unauthorized
    ServerError:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    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
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: opaque-api-key
externalDocs:
  description: Guides and examples
  url: https://www.ffmpeg-micro.com/docs