ffmpeg-micro-com Blueprints API

openapi: 3.2.0
info:
  title: FFmpeg Micro Blueprints 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: Blueprints
paths:
  /v1/blueprints/{slug}/runs:
    post:
      summary: Start a blueprint run (server-side recipe pipeline)
      description: 'Kick off a blueprint recipe as a background pipeline. Available slugs: `product-ad` (generative; charges tokens server-side, 402 when the balance is insufficient), `caption-video` (transcribe then burn; pauses at `awaiting_review` for transcript edits), `viral-short` (optional audio swap then hook overlay), `quote-card` (styled quote card on the dark background; no media input required), `watermark` (logo overlay at a chosen corner and size), `resize-format` (reframe to a target aspect by pad or crop). Inputs are URLs from the upload chain (`gs://` in the upload bucket) or public HTTPS URLs. Poll `GET /v1/blueprints/runs/{id}` for progress; runs continue in the background after the client disconnects.'
      security:
      - bearerApiKey: []
      parameters:
      - in: path
        name: slug
        required: true
        schema:
          type: string
          enum:
          - product-ad
          - caption-video
          - viral-short
          - quote-card
          - watermark
          - resize-format
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: 'Per-slug inputs. product-ad: `logo_url`, `photo_url`, optional `music_url`. caption-video: `video_url`, optional `language`, `style`. viral-short: `video_url`, `hook_text`, optional `style`, `music_url`. quote-card: `quote`, optional `name`, `handle`, `photo_url` (profile photo; initials avatar without it). watermark: `video_url`, `logo_url`, optional `position` (top-left|top-right|bottom-left|bottom-right|center, default bottom-right), `size` (small|medium|large, default small). resize-format: `video_url`, optional `format` (9x16|1x1|16x9|4x5, default 9x16), `fit` (pad|crop, default pad).

                '
              properties:
                logo_url:
                  type: string
                photo_url:
                  type: string
                video_url:
                  type: string
                hook_text:
                  type: string
                  maxLength: 200
                quote:
                  type: string
                  maxLength: 280
                name:
                  type: string
                  maxLength: 60
                handle:
                  type: string
                  maxLength: 60
                position:
                  type: string
                size:
                  type: string
                format:
                  type: string
                fit:
                  type: string
                language:
                  type: string
                style:
                  type: string
                music_url:
                  type: string
      responses:
        '201':
          description: Run created (pipeline executing in the background)
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    example: pending
                  blueprint:
                    type: string
                  tokens_charged:
                    type: integer
        '400':
          description: Invalid or missing inputs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Insufficient token balance (generative blueprints)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: insufficient_tokens
                  tokens_required:
                    type: integer
        '404':
          description: Unknown blueprint slug
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many active generative runs for this account
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: too_many_active_runs
                  max_active_runs:
                    type: integer
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Blueprints
      operationId: postV1BlueprintsBySlugRuns
      x-operation-id-source: derived
  /v1/blueprints/runs/{id}:
    get:
      summary: Poll a blueprint run
      security:
      - bearerApiKey: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Run status and, when completed, a signed output URL (10 min TTL)
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  blueprint:
                    type: string
                  status:
                    type: string
                    enum:
                    - pending
                    - processing
                    - awaiting_review
                    - completed
                    - failed
                  step:
                    type:
                    - string
                    - 'null'
                  output_url:
                    type:
                    - string
                    - 'null'
                  error_message:
                    type:
                    - string
                    - 'null'
                  tokens_spent:
                    type: integer
                  srt_text:
                    type: string
                    description: Present only while an Auto Captions run awaits transcript review
                  created_at:
                    type: string
                    format: date-time
                  completed_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Run not found (or belongs to another user)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Blueprints
      operationId: getV1BlueprintsRunsById
      x-operation-id-source: derived
  /v1/blueprints/runs/{id}/continue:
    post:
      summary: Resume a paused run with a reviewed transcript
      description: 'For `caption-video` runs in `awaiting_review`: submit the (possibly edited) SRT and the burn continues in the background.'
      security:
      - bearerApiKey: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - srt_text
              properties:
                srt_text:
                  type: string
                  maxLength: 200000
      responses:
        '200':
          description: Burn resumed
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    example: processing
                  step:
                    type: string
                    example: burn
        '400':
          description: Missing or oversized srt_text
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Run is not awaiting review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Blueprints
      operationId: postV1BlueprintsRunsByIdContinue
      x-operation-id-source: derived
components:
  responses:
    ServerError:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing/invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              value:
                error: unauthorized
  schemas:
    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