{ "openapi": "3.1.0", "info": { "title": "Runware API - FFmpeg", "summary": "Raw FFmpeg processing for video, audio and image files", "description": "FFmpeg is a media processing tool that runs one FFmpeg command over files you pass by URL and returns a single output file. It takes up to 10 video, audio or image inputs and accepts raw input options, output options, filter graphs and stream maps. It fits transcoding, trimming, scaling, overlays, audio extraction and format conversion between generation steps.", "version": "1.0.0", "x-model-id": "ffmpeg", "x-air-id": "runware:ffmpeg@0", "x-status": "live", "x-capabilities": [ "media-process" ], "x-modes": [ { "id": "media", "inputs": [ "media" ] } ], "x-released-at": "2000-12-20T00:00:00Z", "x-cover-image": "https://assets.runware.ai/covers/ffmpeg.jpg" }, "externalDocs": { "description": "FFmpeg on Runware", "url": "https://runware.ai/docs/models/ffmpeg" }, "servers": [ { "url": "https://api.runware.ai/v1", "description": "Runware REST API" } ], "components": { "securitySchemes": { "apiKeyAuth": { "type": "http", "scheme": "bearer", "description": "Runware API Key (e.g., Bearer )" } }, "schemas": { "AuthenticationTask": { "title": "Authentication", "description": "Authenticates a connection using an API key. Can be sent as the first element of the request array as an alternative to using the Authorization header.", "type": "object", "x-response-schema": "https://schemas.runware.ai/responses/utilities/authentication.json", "properties": { "taskType": { "title": "Task Type", "description": "Identifier for the type of task being performed.", "type": "string", "const": "authentication" }, "apiKey": { "title": "API Key", "description": "Your Runware API key.", "type": "string" }, "connectionSessionUUID": { "title": "Connection Session UUID", "description": "Optional session UUID to resume a previous connection and receive any buffered results.", "type": "string", "format": "uuid" } }, "required": [ "taskType", "apiKey" ], "additionalProperties": false }, "RequestBody": { "type": "array", "items": { "type": "object", "x-constraints": [ { "operation": "fileSize", "parameters": [ "inputs.media" ], "maximum": 5368709120, "scope": "each" } ], "properties": { "model": { "const": "runware:ffmpeg@0", "title": "Model", "description": "Identifier of the tool to run.", "type": "string" }, "outputFormat": { "type": "string", "title": "Output Format", "description": "File format for the output file. Image formats return a single frame.", "enum": [ "MP4", "WEBM", "MOV", "MKV", "MP3", "WAV", "AAC", "FLAC", "OGG", "PNG", "JPG", "WEBP" ], "default": "MP4" }, "inputs": { "title": "Inputs", "description": "Input assets for the task.", "type": "object", "properties": { "media": { "type": "array", "title": "Media", "description": "Ordered list of video, audio or image inputs. The position of each item is the FFmpeg input index that `settings.filterComplex` and `settings.maps` reference.", "items": { "type": "object", "properties": { "options": { "type": "array", "title": "Options", "description": "Raw FFmpeg input options placed before this input, one token per element. `-i` is not accepted.", "items": { "type": "string" } }, "url": { "type": "string", "title": "URL", "description": "Publicly accessible URL of the input file. UUIDs are not supported." } }, "required": [ "url" ], "additionalProperties": false }, "minItems": 1, "maxItems": 10 } }, "required": [ "media" ], "additionalProperties": false }, "settings": { "title": "Settings", "description": "Global inference settings.", "type": "object", "properties": { "filterComplex": { "type": "string", "title": "Filter Complex", "description": "Raw FFmpeg `-filter_complex` graph. Inputs are referenced by their index in `inputs.media`." }, "maps": { "type": "array", "title": "Maps", "description": "Streams written to the output file (`-map`), as filter labels from `settings.filterComplex` or `input:stream` specifiers. FFmpeg selects the streams when omitted.", "items": { "type": "string" } }, "outputOptions": { "type": "array", "title": "Output Options", "description": "Raw FFmpeg output options, one token per element. `-i`, `-attach` and `-progress` are not accepted. Must produce a single file, so `-f` followed by `hls`, `segment`, `dash` or `image2` is not accepted.", "items": { "type": "string" } } }, "additionalProperties": false }, "taskType": { "title": "Task Type", "description": "Identifier for the type of task being performed.", "type": "string", "const": "tools" }, "taskUUID": { "title": "Task UUID", "description": "UUID v4 identifier for tracking tasks and matching async responses. Must be unique per task.", "type": "string", "format": "uuid" }, "webhookURL": { "title": "Webhook URL", "description": "Webhook URL that receives JSON responses via HTTP POST when generation tasks complete. For batch requests with multiple results, each completed item triggers a separate webhook call as it becomes available.", "type": "string", "format": "uri" }, "includeCost": { "title": "Include Cost", "description": "Include task cost in the response.", "type": "boolean" }, "ttl": { "title": "TTL", "description": "Time-to-live (TTL) in seconds for the output files.", "type": "integer", "minimum": 60 }, "deliveryMethod": { "title": "Delivery Method", "description": "Determines how the API delivers task results.", "type": "string", "oneOf": [ { "const": "sync", "description": "Returns complete results directly in the API response." }, { "const": "async", "description": "Returns an immediate acknowledgment with the task UUID. Poll for results using getResponse." } ], "default": "sync" } }, "required": [ "inputs", "taskType", "taskUUID", "model" ], "additionalProperties": false }, "description": "You must always POST an array of task objects." }, "ResponseBody": { "type": "object", "properties": { "data": { "type": "array", "items": { "title": "Tools Response", "type": "object", "additionalProperties": false, "properties": { "taskType": { "title": "Task Type", "description": "Identifier for the type of task this response belongs to.", "type": "string", "const": "tools" }, "taskUUID": { "title": "Task UUID", "description": "UUID v4 identifier echoed from the original request, used to match async responses to their tasks.", "type": "string", "format": "uuid" }, "cost": { "title": "Cost", "description": "Task cost in USD. Present when `includeCost` is set to `true` in the request.", "type": "number" }, "outputs": { "title": "Outputs", "description": "Generated output artifacts.", "type": "object", "properties": { "files": { "title": "Output Files", "description": "Generated output files.", "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "uuid": { "title": "File UUID", "description": "UUID of the output file.", "type": "string", "format": "uuid" }, "url": { "title": "File URL", "description": "URL of the output file.", "type": "string", "format": "uri" } }, "required": [ "uuid", "url" ], "additionalProperties": false } } }, "required": [ "files" ], "additionalProperties": false } }, "required": [ "taskType", "taskUUID", "outputs" ] } } } }, "ErrorResponse": { "title": "Error Response", "description": "Standard error response returned by the Runware API.", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "A short identifier for the error (e.g., invalidApiKey, timeoutProvider)." }, "message": { "type": "string", "description": "A human-readable explanation of what went wrong." }, "parameter": { "type": "string", "description": "The request parameter related to the error, if applicable." }, "taskType": { "type": "string", "description": "The task type of the request that failed." }, "taskUUID": { "type": "string", "description": "The unique identifier of the failed request." }, "documentation": { "type": "string", "description": "A link to relevant documentation." } } } } }, "required": [ "errors" ], "additionalProperties": false } } }, "paths": { "/": { "post": { "summary": "Run FFmpeg", "description": "FFmpeg is a media processing tool that runs one FFmpeg command over files you pass by URL and returns a single output file. It takes up to 10 video, audio or image inputs and accepts raw input options, output options, filter graphs and stream maps. It fits transcoding, trimming, scaling, overlays, audio extraction and format conversion between generation steps.", "operationId": "run_ffmpeg", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestBody" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseBody" } } } }, "400": { "description": "Bad Request — Missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — No valid API key provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required — Insufficient account balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — The API key lacks permissions for this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests — Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server Error — Something went wrong on Runware's end.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable — Temporarily unavailable (maintenance or capacity).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] }