Execute a preset by providing input files. The FFmpeg command and output files are defined by the preset.

Execute Preset

POST /api/v1/presets/:presetId/execute

Execute a preset by providing only the input files. The FFmpeg command configuration and output file definitions come from the preset. This simplifies repeated processing -- instead of specifying the full command each time, you reference a preset and supply the inputs.

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

Path parameters

Parameter	Type	Required	Description
`presetId`	`string`	Yes	The unique identifier of the preset to execute.

Body

interface ExecutePresetRequest {
  input_files: Record<string, string>;
  metadata?: Record<string, string | number | boolean>;
  webhook_url?: string;
}

Field	Type	Required	Description
`input_files`	`Record<string, string>`	Yes	Map of `in_*` alias keys to file URLs. Must match the preset's `input_file_keys` exactly -- no missing keys, no extra keys.
`metadata`	`Record<string, string \| number \| boolean>`	No	Additional metadata for this execution. Merged with the preset's metadata. Maximum 10 keys.
`webhook_url`	`string`	No	URL to receive a POST request when the command completes. Overrides any account-level webhook configuration.

The input_files keys are validated against the preset's input_file_keys. If any expected key is missing or any unexpected key is provided, the request is rejected with a 422 error.

Response

200 OK

{
  command_id: string;
}

Field	Type	Description
`command_id`	`string`	Unique identifier for the command. Use this to poll for status via `GET /api/v1/commands/:commandId`.

Error responses

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid API key.
`404`	`NOT_FOUND`	Preset does not exist or does not belong to your account.
`422`	`VALIDATION_ERROR`	Input file keys do not match the preset's expected keys (missing or extra keys).
`429`	`RATE_LIMITED`	Too many requests. Retry after the period indicated in the `Retry-After` header.

Examples

curl

curl -X POST https://renderio.dev/api/v1/presets/prs_abc123/execute \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: ffsk_your_api_key_here" \
  -d '{
    "input_files": {
      "in_video": "https://example.com/sample.mp4"
    },
    "metadata": {
      "batch": "2024-01",
      "source": "upload"
    }
  }'

JavaScript (fetch)

const presetId = "prs_abc123";

const response = await fetch(
  `https://renderio.dev/api/v1/presets/${presetId}/execute`,
  {
    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",
      },
      metadata: {
        batch: "2024-01",
        source: "upload",
      },
    }),
  },
);

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

Python (requests)

import requests

preset_id = "prs_abc123"

response = requests.post(
    f"https://renderio.dev/api/v1/presets/{preset_id}/execute",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "ffsk_your_api_key_here",
    },
    json={
        "input_files": {
            "in_video": "https://example.com/sample.mp4",
        },
        "metadata": {
            "batch": "2024-01",
            "source": "upload",
        },
    },
)

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

Execute Preset

On this page