Submit a single FFmpeg command for execution in the cloud. Returns a command ID for polling.

Run FFmpeg Command

POST /api/v1/run-ffmpeg-command

Submit a single FFmpeg command for asynchronous execution. RenderIO downloads your input files, runs the FFmpeg command in a secure sandbox, and stores the output files. The endpoint returns immediately with a command_id that you use to poll for results.

Authentication

Requires API key via X-API-KEY header.

Request

Headers

Header	Type	Required	Description
`Content-Type`	`string`	Yes	Must be `application/json`
`X-API-KEY`	`string`	Yes	Your API key with `ffsk_` prefix

Body

interface RunFFmpegCommandRequest {
  input_files: Record<string, string>;   // in_* aliases mapped to URLs
  output_files: Record<string, string>;  // out_* aliases mapped to filenames
  ffmpeg_command: string;                // FFmpeg command with {{alias}} placeholders
  metadata?: Record<string, string | number | boolean>; // Max 10 keys
  webhook_url?: string;                  // Per-command webhook override
}

Field	Type	Required	Description
`input_files`	`Record<string, string>`	Yes	Map of alias names (must start with `in_`) to file URLs. These URLs are downloaded before FFmpeg runs.
`output_files`	`Record<string, string>`	Yes	Map of alias names (must start with `out_`) to output filenames. These files are uploaded to storage after FFmpeg runs.
`ffmpeg_command`	`string`	Yes	The FFmpeg command to execute. Use `{{alias}}` placeholders to reference input and output files.
`metadata`	`Record<string, string \| number \| boolean>`	No	Arbitrary key-value metadata attached to the command. Maximum 10 keys.
`webhook_url`	`string`	No	URL to receive a POST request when the command completes. Overrides any account-level webhook configuration.

Response

200 OK

{
  command_id: string;
}

Field	Type	Description
`command_id`	`string`	Unique identifier for the command. Use this to poll for status.

Error responses

Status	Error	Description
`400`	`INVALID_REQUEST`	Missing required fields, invalid aliases, or malformed FFmpeg command.
`401`	`UNAUTHORIZED`	Missing or invalid API key.
`422`	`VALIDATION_ERROR`	Input validation failed (e.g., metadata exceeds 10 keys, invalid URL).
`429`	`RATE_LIMITED`	Too many requests. Retry after the period indicated in the `Retry-After` header.

Examples

curl -X POST https://renderio.dev/api/v1/run-ffmpeg-command \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: ffsk_your_api_key_here" \
  -d '{
    "input_files": {
      "in_video": "https://example.com/sample.mp4"
    },
    "output_files": {
      "out_video": "result.webm"
    },
    "ffmpeg_command": "ffmpeg -i {{in_video}} -c:v libvpx-vp9 -crf 30 -b:v 0 {{out_video}}",
    "metadata": {
      "project": "demo",
      "priority": 1
    }
  }'

import requests

response = requests.post(
    "https://renderio.dev/api/v1/run-ffmpeg-command",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "ffsk_your_api_key_here",
    },
    json={
        "input_files": {
            "in_video": "https://example.com/sample.mp4",
        },
        "output_files": {
            "out_video": "result.webm",
        },
        "ffmpeg_command": "ffmpeg -i {{in_video}} -c:v libvpx-vp9 -crf 30 -b:v 0 {{out_video}}",
        "metadata": {
            "project": "demo",
            "priority": 1,
        },
    },
)

data = response.json()
print("Command ID:", data["command_id"])

interface RunCommandRequest {
  input_files: Record<string, string>;
  output_files: Record<string, string>;
  ffmpeg_command: string;
  metadata?: Record<string, string | number | boolean>;
}

interface RunCommandResponse {
  command_id: string;
}

const body: RunCommandRequest = {
  input_files: {
    in_video: "https://example.com/sample.mp4",
  },
  output_files: {
    out_video: "result.webm",
  },
  ffmpeg_command:
    "ffmpeg -i {{in_video}} -c:v libvpx-vp9 -crf 30 -b:v 0 {{out_video}}",
  metadata: {
    project: "demo",
    priority: 1,
  },
};

const response = await fetch("https://renderio.dev/api/v1/run-ffmpeg-command", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-KEY": "ffsk_your_api_key_here",
  },
  body: JSON.stringify(body),
});

const { command_id } = (await response.json()) as RunCommandResponse;
console.log("Command ID:", command_id);

const response = await fetch("https://renderio.dev/api/v1/run-ffmpeg-command", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-KEY": "ffsk_your_api_key_here",
  },
  body: JSON.stringify({
    input_files: {
      in_video: "https://example.com/sample.mp4",
    },
    output_files: {
      out_video: "result.webm",
    },
    ffmpeg_command:
      "ffmpeg -i {{in_video}} -c:v libvpx-vp9 -crf 30 -b:v 0 {{out_video}}",
    metadata: {
      project: "demo",
      priority: 1,
    },
  }),
});

const { command_id } = await response.json();
console.log("Command ID:", command_id);

<?php
$ch = curl_init("https://renderio.dev/api/v1/run-ffmpeg-command");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-API-KEY: ffsk_your_api_key_here",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "input_files" => [
        "in_video" => "https://example.com/sample.mp4",
    ],
    "output_files" => [
        "out_video" => "result.webm",
    ],
    "ffmpeg_command" => "ffmpeg -i {{in_video}} -c:v libvpx-vp9 -crf 30 -b:v 0 {{out_video}}",
    "metadata" => [
        "project" => "demo",
        "priority" => 1,
    ],
]));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "Command ID: " . $data["command_id"] . "\n";

Run FFmpeg Command

On this page