ffmpeg-micro-com Transcribe API

openapi: 3.2.0
info:
  title: FFmpeg Micro Transcribe 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: Transcribe
paths:
  /v1/transcribe:
    post:
      summary: Create a transcribe job (audio → SRT)
      description: 'Generate an SRT subtitle file from an audio or video URL using Whisper. Returns a short acknowledgement with `status=pending`; poll `GET /v1/transcribe/{id}` until `status` is `completed`, then fetch the SRT via `GET /v1/transcribe/{id}/download`.

        The resulting SRT is stored in your user-namespaced output bucket and can be referenced inside a transcode `subtitles=` filter to burn captions into a video (see the docs for the zoom+captions tutorial).'
      security:
      - bearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTranscribeRequest'
      responses:
        '201':
          description: Transcribe job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscribeCreated'
        '400':
          description: Invalid input (missing or invalid `media_url`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/QuotaWall'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Transcribe
      operationId: postV1Transcribe
      x-operation-id-source: derived
  /v1/transcribe/{id}:
    get:
      summary: Get transcribe job status
      security:
      - bearerApiKey: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Transcribe job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transcribe'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Transcribe
      operationId: getV1TranscribeById
      x-operation-id-source: derived
  /v1/transcribe/{id}/download:
    get:
      summary: Get a signed download URL for the generated SRT
      description: Returns a short-lived (10 minute) signed HTTPS URL for the completed SRT file. The job must be in `completed` status.
      security:
      - bearerApiKey: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Signed HTTPS URL valid for 10 minutes
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                properties:
                  url:
                    type: string
                    format: uri
                    example: https://storage.googleapis.com/…/job-id.srt?X-Goog-Signature=…
        '400':
          description: Transcribe not completed or has no output
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Transcribe
      operationId: getV1TranscribeByIdDownload
      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
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    QuotaWall:
      description: 'The account is fully capped: zero plan minutes remaining AND a zero token balance, so no job of any size can run until the plan renews, the plan is upgraded, or tokens are topped up. Returned synchronously instead of a `201` — no processing is attempted. A job record IS still created (visible in job listings with `status: failed`), and its id is returned so the blocked attempt can be inspected. Automations should treat `402` as terminal for the billing period and STOP retrying: the same request will keep returning `402` until the account''s quota state changes. Partially-capped accounts (some minutes or tokens remaining) still return `201`, with any quota failure reported asynchronously on the job''s `status`/`error_message`.

        '
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - job_id
            - upgrade_url
            properties:
              error:
                type: string
                description: Human-readable refusal naming the remedy
              job_id:
                type: string
                format: uuid
                description: The failed job row recording this blocked attempt
              upgrade_url:
                type: string
                description: Deep link to billing, carrying `job=<job_id>`
          examples:
            example:
              value:
                error: 'Quota exceeded: Video Processing Minutes. Available: 0.00 minutes and your token balance is 0. Upgrade or top up tokens to continue: https://www.ffmpeg-micro.com/dashboard/billing?utm_source=usage-alert&utm_medium=api&utm_campaign=quota-api-block&utm_content=error-message&job=6a1f0c9e-6a56-4a1a-9d2f-0d5d0f7b1c2d'
                job_id: 6a1f0c9e-6a56-4a1a-9d2f-0d5d0f7b1c2d
                upgrade_url: https://www.ffmpeg-micro.com/dashboard/billing?utm_source=usage-alert&utm_medium=api&utm_campaign=quota-api-block&utm_content=error-message&job=6a1f0c9e-6a56-4a1a-9d2f-0d5d0f7b1c2d
  schemas:
    CreateTranscribeRequest:
      type: object
      required:
      - media_url
      properties:
        media_url:
          type: string
          description: 'GCS URL (gs://bucket/object) from a presigned upload, or a public HTTP(S) URL. The referenced file can be audio or video — only the audio track is used.

            '
          example: gs://<YOUR_BUCKET>/narration.mp3
        language:
          type: string
          description: BCP-47 language code hint (e.g. "en", "es"). Auto-detected when omitted.
          example: en
        task:
          type: string
          enum:
          - transcribe
          - translate
          default: transcribe
          description: '"transcribe" keeps the source language; "translate" outputs English regardless of source language.

            '
    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'
    TranscribeCreated:
      type: object
      description: 'Acknowledgement returned by `POST /v1/transcribe` — a subset of the full Transcribe resource. Poll `GET /v1/transcribe/{id}` for the full shape.

        '
      required:
      - id
      - status
      - media_url
      - output_format
      - created_at
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - pending
          description: New transcribe jobs always start as `pending`
        media_url:
          type: string
          description: GCS URL of the source audio/video (echoed from the request)
        output_format:
          type: string
          enum:
          - srt
        created_at:
          type: string
          format: date-time
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: opaque-api-key
externalDocs:
  description: Guides and examples
  url: https://www.ffmpeg-micro.com/docs