ffmpeg-micro-com Generate API

openapi: 3.2.0
info:
  title: FFmpeg Micro Generate 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: Generate
paths:
  /v1/generate/scenes:
    post:
      summary: Split a narration script into scenes (free)
      description: 'Break a script into ordered scenes, each with the narration for that scene (same language as the input) and an English image prompt for it. Free: it is the step you iterate on before committing to paid images and speech. Rate limited to 60 requests per minute per API key.'
      security:
      - bearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateScenesRequest'
      responses:
        '200':
          description: Scenes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateScenesResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/GenerateRateLimited'
        '502':
          $ref: '#/components/responses/GenerationFailed'
      tags:
      - Generate
      operationId: postV1GenerateScenes
      x-operation-id-source: derived
  /v1/generate/translate:
    post:
      summary: Translate an ordered list of narrations (free)
      description: Translate scene narrations into another language, preserving count and order, so the images built for the source language can be reused and a re-voice costs speech tokens only. Free; rate limited to 60/min per key.
      security:
      - bearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateTranslateRequest'
      responses:
        '200':
          description: Translations, same length and order as `texts`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateTranslateResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/GenerateRateLimited'
        '502':
          $ref: '#/components/responses/GenerationFailed'
      tags:
      - Generate
      operationId: postV1GenerateTranslate
      x-operation-id-source: derived
  /v1/generate/image:
    post:
      summary: Generate an image (6 or 10 tokens)
      description: 'Text to image. Default model `flux-schnell` bills 6 tokens per image. `model: nano-banana` (10 tokens) follows style instructions more faithfully. With `reference_urls` (1–4 https images) the result is an EDIT that keeps the referenced character and product identical — the way to build a consistent storyboard; references force `nano-banana`. Tokens are spent before the provider call and refunded if it fails. Rate limited to 30/min per key.'
      security:
      - bearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateImageRequest'
      responses:
        '200':
          description: Image generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateImageResponse'
        '400':
          description: Invalid input (charged nothing)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientTokens'
        '429':
          $ref: '#/components/responses/GenerateRateLimited'
        '502':
          $ref: '#/components/responses/GenerationFailed'
      tags:
      - Generate
      operationId: postV1GenerateImage
      x-operation-id-source: derived
  /v1/generate/speech:
    post:
      summary: Generate speech from text (25 tokens per 1,000 characters)
      description: Narration-quality text to speech (ElevenLabs multilingual, 29 languages; the same voice reads every language, so a re-voice keeps the narrator). Billed per character of `text`, pro rata, spent before the call and refunded on provider failure. Rate limited to 30/min.
      security:
      - bearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateSpeechRequest'
      responses:
        '200':
          description: Speech generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateSpeechResponse'
        '400':
          description: Invalid input (charged nothing)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientTokens'
        '429':
          $ref: '#/components/responses/GenerateRateLimited'
        '502':
          $ref: '#/components/responses/GenerationFailed'
      tags:
      - Generate
      operationId: postV1GenerateSpeech
      x-operation-id-source: derived
  /v1/generate/animate:
    post:
      summary: Animate an image into a video clip (18 tokens per second)
      description: 'Image to video (Kling 2.5 Turbo Pro), 5 or 10 seconds. Asynchronous: the balance is checked, the render is submitted, and the tokens are charged under the returned `id`. Poll `GET /v1/generate/animate/{id}` until `completed` or `failed`; a failed render is refunded on that poll. If the render cannot be charged after submit it is cancelled and the response carries its `id` and `cancelled`. Rate limited to 30/min.'
      security:
      - bearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateAnimateRequest'
      responses:
        '202':
          description: Render queued and charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateAnimateQueued'
        '400':
          description: Invalid input (charged nothing)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientTokens'
        '429':
          $ref: '#/components/responses/GenerateRateLimited'
        '502':
          $ref: '#/components/responses/GenerationFailed'
      tags:
      - Generate
      operationId: postV1GenerateAnimate
      x-operation-id-source: derived
  /v1/generate/animate/{id}:
    get:
      summary: Poll an animation
      description: 'Status of a render you submitted. `queued` / `processing` mean keep polling; `completed` carries the video `url` (a signed URL — download promptly); `failed` means the tokens were refunded. A 503 with `status: unknown` means the provider could not be reached for the moment — the render is untouched and still charged; retry after `retry_after_seconds`. Only your own renders are visible.'
      security:
      - bearerApiKey: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The `id` returned by `POST /v1/generate/animate`
      responses:
        '200':
          description: Render state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateAnimateStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No render with that id belongs to the caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Provider unreachable; the render is unaffected. Retry after `retry_after_seconds`.
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateAnimateStatus'
      tags:
      - Generate
      operationId: getV1GenerateAnimateById
      x-operation-id-source: derived
components:
  schemas:
    GenerateTranslateRequest:
      type: object
      required:
      - texts
      - language
      properties:
        texts:
          type: array
          minItems: 1
          maxItems: 20
          items:
            type: string
            maxLength: 2000
        language:
          type: string
          description: ISO 639-1 target language, e.g. `fr`
          example: fr
    GenerateAnimateQueued:
      type: object
      properties:
        id:
          type: string
          description: Poll handle for GET /v1/generate/animate/:id
        status:
          type: string
          enum:
          - queued
        duration:
          type: integer
        aspect:
          type: string
        tokens_charged:
          type: number
          example: 90
    GenerateAnimateRequest:
      type: object
      required:
      - image_url
      - prompt
      properties:
        image_url:
          type: string
          format: uri
          description: https start frame
        prompt:
          type: string
          maxLength: 2000
          description: What moves and how
        duration:
          type: integer
          enum:
          - 5
          - 10
          default: 5
        aspect:
          type: string
          enum:
          - '16:9'
          - '9:16'
          - '1:1'
          default: '16:9'
        negative_prompt:
          type: string
          maxLength: 500
          description: What the motion must not introduce
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        details:
          type:
          - string
          - 'null'
    GenerateSpeechResponse:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: mp3
        characters:
          type: integer
        tokens_charged:
          type: number
          example: 1.16
    GenerateImageRequest:
      type: object
      required:
      - prompt
      properties:
        prompt:
          type: string
          maxLength: 2000
        aspect:
          type: string
          enum:
          - landscape_16_9
          - portrait_9_16
          - square_1_1
          default: landscape_16_9
        model:
          type: string
          enum:
          - flux-schnell
          - nano-banana
          default: flux-schnell
          description: Ignored when `reference_urls` is given (references force `nano-banana`)
        reference_urls:
          type: array
          minItems: 1
          maxItems: 4
          items:
            type: string
            format: uri
          description: https images the result must stay faithful to (a character sheet, a product shot)
        seed:
          type: integer
          minimum: 0
          description: Fixed seed for repeatability. Omit for random; `null` is rejected.
    GenerateScenesRequest:
      type: object
      required:
      - script
      properties:
        script:
          type: string
          maxLength: 20000
          description: The narration script, any language
        max_scenes:
          type: integer
          minimum: 1
          maximum: 20
          default: 6
    GenerateScenesResponse:
      type: object
      properties:
        scenes:
          type: array
          items:
            $ref: '#/components/schemas/GenerateScene'
        tokens_charged:
          type: number
          example: 0
    GenerateTranslateResponse:
      type: object
      properties:
        texts:
          type: array
          items:
            type: string
        language:
          type: string
        tokens_charged:
          type: number
          example: 0
    GenerateImageResponse:
      type: object
      properties:
        url:
          type: string
          format: uri
        aspect:
          type: string
        model:
          type: string
          enum:
          - flux-schnell
          - nano-banana
        tokens_charged:
          type: number
          example: 6
    GenerateAnimateStatus:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          - unknown
        url:
          type: string
          format: uri
          description: Present when `completed` (signed
          expires): null
        detail:
          type: string
          description: Present when `failed`
        retry_after_seconds:
          type: integer
          description: Present when `unknown`
        tokens_charged:
          type: number
          description: 0 after a refund; unchanged while queued/processing/unknown
        refund:
          type: string
          enum:
          - failed
          description: Present only if a refund could not be recorded
    GenerateScene:
      type: object
      properties:
        text:
          type: string
          description: Narration for this scene
          same language as the script: null
        image_prompt:
          type: string
          description: English visual description for an image generator
    GenerateSpeechRequest:
      type: object
      required:
      - text
      properties:
        text:
          type: string
          maxLength: 2000
        voice:
          type: string
          description: Provider voice name; omit for the default narrator
  responses:
    InsufficientTokens:
      description: Not enough tokens for this call; nothing was charged (for `animate`, `id` and `cancelled` are present if a render had already been submitted)
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                enum:
                - insufficient_tokens
              tokens_required:
                type: number
              id:
                type: string
              cancelled:
                type: boolean
    Unauthorized:
      description: Missing/invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              value:
                error: unauthorized
    GenerationFailed:
      description: The provider failed; any tokens spent were refunded unless `refund` says otherwise
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                enum:
                - generation_failed
              detail:
                type: string
              tokens_charged:
                type: number
              refund:
                type: string
                enum:
                - failed
    GenerateRateLimited:
      description: Per-API-key rate limit exceeded (free routes 60/min, paid routes 30/min); see `x-ratelimit-*` headers
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: opaque-api-key
externalDocs:
  description: Guides and examples
  url: https://www.ffmpeg-micro.com/docs