> ## Documentation Index
> Fetch the complete documentation index at: https://rendi.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run FFmpeg Command

> Submit an FFmpeg command for processing with input and output file specifications.

<Note>
  **Key naming rules**: input keys in `input_files` must start with `in_` (e.g. `in_1`, `in_video`); output keys in `output_files` must start with `out_` (e.g. `out_1`, `out_gif`). Reference them as `{{in_1}}` / `{{out_1}}` placeholders inside `ffmpeg_command`.

  **Runtime cap**: `max_command_run_seconds` defaults to 300s (5 minutes). It's a safety cap that aborts runaway FFmpeg jobs — set it explicitly on longer jobs to match the expected runtime. Maximum depends on your plan.

  **Input URLs**: any publicly accessible HTTP/HTTPS URL works — Google Drive share links, Dropbox, public/signed S3/GCS, CDNs.
</Note>


## OpenAPI

````yaml POST /v1/run-ffmpeg-command
openapi: 3.1.0
info:
  title: FFmpeg Command API
  description: API for running FFmpeg in a cloud environment
  version: 1.0.0
servers:
  - url: https://api.rendi.dev
    description: Rendi - FFmpeg API
security: []
paths:
  /v1/run-ffmpeg-command:
    post:
      tags:
        - API
        - FFmpeg Commands
      summary: Run FFmpeg Command
      description: >-
        Submit an FFmpeg command for processing with input and output file
        specifications.
      operationId: run_ffmpeg_command_v1_run_ffmpeg_command_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FFmpegCommandRequest'
        required: true
      responses:
        '200':
          description: Successfully submitted FFmpeg command
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunCommandResponse'
              example:
                command_id: 123e4567-e89b-12d3-a456-426614174000
        '401':
          description: Invalid API key
          content:
            application/json:
              example:
                detail: Invalid authorization key
        '403':
          description: Account quota exceeded or plan does not support this command
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded
      security:
        - APIKeyHeader: []
components:
  schemas:
    FFmpegCommandRequest:
      properties:
        input_files:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Input Files
          description: |-
            Dictionary mapping file aliases to their publicly accessible paths, 
                    file name should appear in the end of the url, keys are alphanumeric, with underscore allowed, must start with 'in_'. 
                    You can use public file urls, google drive, dropbox, rendi stored files, s3 stored files, etc. as long as they are publicly accessible. 
                    If not available, input_compressed_folder has to be provided
          examples:
            - in_1: >-
                https://storage.rendi.dev/sample/big_buck_bunny_720p_5sec_intro.mp4
              in_2: >-
                https://storage.rendi.dev/sample/big_buck_bunny_720p_5sec_outro.mp4
        output_files:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: string
              const: OUTPUT_FOLDER
          title: Output Files
          description: >-
            Dictionary mapping file aliases to their desired output file names,
            keys are alphanumeric, with underscore allowed, must start with
            'out_'. Or, the literal string 'OUTPUT_FOLDER' indicating compressed
            folder output.
          examples:
            - out_1: output_one.mp4
              out_2: output_two.mp4
            - OUTPUT_FOLDER
        max_command_run_seconds:
          type: number
          exclusiveMinimum: 0
          title: Max Command Run Seconds
          description: >-
            Maximum allowed runtime in seconds for a single FFmpeg command, the
            default is 300 seconds
          examples:
            - 300
        vcpu_count:
          type: integer
          exclusiveMinimum: 0
          title: Vcpu Count
          description: >-
            Number of virtual CPUs to use for a single ffmpeg command, the
            default is 8, up to your account's maximum. Multiple commands can
            run in parallel as long as their total vCPU usage doesn't exceed
            your quota.
          examples:
            - 8
        metadata:
          anyOf:
            - additionalProperties:
                anyOf:
                  - type: string
                  - type: integer
                  - type: number
                  - type: boolean
              type: object
              maxProperties: 10
              minProperties: 0
            - type: 'null'
          title: Metadata
          description: >-
            Metadata to be stored with the command, useful for webhooks and
            custom tracking and reporting
          examples:
            - key: value
        input_compressed_folder:
          anyOf:
            - type: string
            - type: 'null'
          title: Input Compressed Folder
          description: |-
            A single compressed zip archive containing input media files. 
                    Provide either this field or input_files, but not both. Value should be a publicly accessible URL or a rendi storage URL.
                    This field is only available for single FFmpeg commands, not chained commands.
          examples:
            - https://storage.rendi.dev/sample/playlist_sample.zip
        ffmpeg_command:
          type: string
          title: Ffmpeg Command
          description: >-
            FFmpeg command string using {{alias}} placeholders for input and
            output files.

            Input file keys should start with 'in_' prefix, for example:
            in_video1. Output file keys should start with 'out_' prefix, for
            example: out_1.

            If you're using an automation platform where curly brackets are used
            special as characters (like make.com, zapier, or other) add
            backslashes before the curly brackets, for example, replace {{in_1}}
            with backslashes and brackets \\{\\{in_1\\}\\}.
          examples:
            - >-
              -i {{in_1}} -i {{in_2}} -filter_complex
              "[0:v][1:v]hstack=inputs=2[v]" -map [v] {{out_1}}
      type: object
      required:
        - output_files
        - ffmpeg_command
      title: FFmpegCommandRequest
      description: >-
        Request model for submitting a single FFmpeg command.


        This model allows submitting an FFmpeg command with input and output
        file specifications.

        Input file aliases must start with 'in_' and direct to a publicly
        accessible file, and

        output file aliases must start with 'out_' and only name a file name to
        be created.


        If you're using an automation platform where curly brackets are used
        special as characters

        (like make.com, zapier, or other) add backslashes before the curly
        brackets, for example, replace {{in_1}} with backslashes and brackets
        \\{\\{in_1\\}\\}.
      example:
        ffmpeg_command: >-
          -i {{in_1}} -vf
          "select='lte(t,60)*gt(trunc(t/10),trunc(prev_t/10))',setpts='PTS*0.025',scale=trunc(oh*a/2)*2:320:force_original_aspect_ratio=decrease,pad=trunc(oh*a/2)*2:320:-1:-1"
          -an -vsync vfr {{out_1}}
        input_files:
          in_1: https://storage.rendi.dev/sample/sample.avi
        max_command_run_seconds: 300
        metadata:
          key: value
        output_files:
          out_1: output1.gif
        vcpu_count: 8
    RunCommandResponse:
      properties:
        command_id:
          type: string
          format: uuid
          title: Command Id
          description: Unique identifier for the submitted command
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
      type: object
      required:
        - command_id
      title: RunCommandResponse
      description: >-
        Response model for command submission.


        Contains the unique identifier assigned to the submitted command that
        can be used

        to poll for status and retrieve results.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY

````