ffmpeg-micro-com Transcribes API

openapi: 3.2.0
info:
  title: FFmpeg Micro Transcribes 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: Transcribes
paths:
  /v1/transcribes:
    get:
      summary: List transcribe jobs (for the authenticated user)
      security:
      - bearerApiKey: []
      parameters:
      - in: query
        name: status
        schema:
          $ref: '#/components/schemas/TranscodeStatus'
        description: 'Filter by status. The value is not validated against the enum — an unknown value returns an empty result set, not an error.

          '
      - in: query
        name: page
        schema:
          type: integer
          minimum: 1
          default: 1
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        description: Values outside 1-100 are clamped; non-numeric values return 400
      - in: query
        name: order
        schema:
          type: string
          enum:
          - created_at.desc
          - updated_at.asc
          - updated_at.desc
          default: created_at.desc
        description: 'Result ordering. Use `updated_at.asc` for cursor-based polling so the sort matches the `since` filter, or `updated_at.desc` for a newest-first view on the same cursor column. Unknown values return 400.

          '
      - in: query
        name: since
        schema:
          type: string
          format: date-time
        description: 'Return transcribes last updated at/after this timestamp (filters on `updated_at`). Invalid dates are rejected with 400.

          '
      - in: query
        name: until
        schema:
          type: string
          format: date-time
        description: Return transcribes last updated at/before this timestamp (filters on `updated_at`)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transcribe'
                  page:
                    type: integer
                  limit:
                    type: integer
                  total:
                    type: integer
        '400':
          description: Invalid page, limit, since, or until parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Transcribes
      operationId: getV1Transcribes
      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:
    Transcribe:
      type: object
      required:
      - id
      - status
      - media_url
      - output_format
      - created_at
      properties:
        id:
          type: string
          format: uuid
          example: f8e6a1f4-2da3-496e-9e29-4d63502ad90c
        status:
          $ref: '#/components/schemas/TranscodeStatus'
        job_type:
          type: string
          enum:
          - transcribe
        media_url:
          type: string
          description: GCS URL of the source audio/video (echoed from the request)
          example: gs://<YOUR_BUCKET>/narration.mp3
        input_url:
          type: string
          description: Same value as `media_url` (legacy field name on reads)
        output_format:
          type: string
          enum:
          - srt
          description: Always `srt` for transcribe jobs
        output_url:
          type:
          - string
          - 'null'
          description: '`gs://` URL of the generated SRT once `status` is `completed`. Use `/v1/transcribe/{id}/download` to obtain a signed HTTPS URL.

            '
          example: gs://ffmpeg-micro-user-<user-id>-output/<job-id>.srt
        error_message:
          type:
          - string
          - 'null'
          description: Populated when status is `failed` or `canceled` ("Job canceled by user")
        error_category:
          type: string
          enum:
          - processing_limit
          - file_size
          - quota
          - upload
          - storage
          - validation
          - processing
          - transient
          - unknown
          description: 'Machine classification derived from error_message (generated column). Only meaningful when status is `failed`; jobs with no error carry `unknown`, never null.

            '
        duration_seconds:
          type:
          - number
          - 'null'
          description: Duration of the source media (drives billing — input minutes)
        billable_minutes:
          type:
          - number
          - 'null'
          description: 'Billable minutes, metered per second on input duration (a 19-second job bills 0.3167). Not an integer.

            '
        processing_time_seconds:
          type:
          - number
          - 'null'
          description: Wall-clock processing time measured by the toolkit; null until completed
        queue_position:
          type:
          - integer
          - 'null'
          description: 'Jobs waiting in the job''s toolkit lane at acceptance, this one included: the accepting worker''s queue length right after this job was enqueued, so 1 means it was next in line. Set once at acceptance and never updated: a rough "how far back was I", not a live counter. Once `started_at` is set the job is no longer waiting, whatever this says. Null on jobs accepted before the field existed, or when the toolkit''s accept response carried no queue length.

            '
          example: 3
        lane:
          type:
          - string
          - 'null'
          enum:
          - short
          - long
          - heavy
          - null
          description: 'The processing lane the job runs in. Jobs with many large inputs (more than five 4K frames'' worth of pixels in total) go to `heavy`, a service with more memory. Otherwise, inputs longer than two minutes (by probed length or requested output span) go to `long`; everything else is `short`. Each lane is a separate service, so nothing in one can delay a job in another. Null on jobs accepted before lanes existed.

            '
        started_at:
          type:
          - string
          - 'null'
          format: date-time
          description: 'When the toolkit began executing the job. Set as soon as encoding starts, so null means the job is still waiting in its lane and non-null with status `processing` means it is encoding now. If that start signal was missed, it is filled from the completion or failure report. `started_at - created_at` is submission-to-start and includes the gateway''s own download and probe before dispatch, so it is an upper bound on queue wait, not the wait itself.

            '
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
        user_id:
          type: string
          description: Internal user identifier resolved from API key
    TranscodeStatus:
      type: string
      enum:
      - pending
      - processing
      - completed
      - failed
      - canceled
      description: 'Job lifecycle: `pending` (created, awaiting pickup) → `processing` → `completed` | `failed`; a user cancellation sets `canceled` (US spelling). Note there is no `queued` status — new jobs start as `pending`.

        '
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        details:
          type:
          - string
          - 'null'
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: opaque-api-key
externalDocs:
  description: Guides and examples
  url: https://www.ffmpeg-micro.com/docs