Run FFmpeg from Python with an API

Send the FFmpeg command you already run in a terminal to Rendobar's FFmpeg API with requests. The job runs on Rendobar's machines, so nothing on your side needs an ffmpeg binary, and you get a URL to the output back. The program below is complete: it sends the job, waits, stops on a failure and saves the file.

Guide
FFmpeg API
Updated
November 2026
transcode.py
import os
import time
import requests
API = "https://api.rendobar.com"
HEADERS = {"Authorization": f"Bearer {os.environ['RENDOBAR_API_KEY']}"}
def run_ffmpeg(command: str, inputs: dict[str, str]) -> dict:
"""Send an FFmpeg command as a job and return the finished job."""
res = requests.post(
f"{API}/jobs",
headers=HEADERS,
json={"type": "ffmpeg", "inputs": inputs, "params": {"command": command}},
timeout=30,
)
res.raise_for_status()
job_id = res.json()["data"]["id"]
while True:
res = requests.get(f"{API}/jobs/{job_id}", headers=HEADERS, timeout=30)
res.raise_for_status()
job = res.json()["data"]
if job["status"] in ("complete", "failed", "cancelled"):
return job
time.sleep(2)
job = run_ffmpeg(
"ffmpeg -i source.mp4 -vf scale=1280:-2 -c:v libx264 -crf 23 -c:a aac out.mp4",
{"source.mp4": "https://example.com/video.mp4"},
)
if job["status"] == "failed":
err = job["error"]
raise RuntimeError(f"{err['code']}: {err['message']}\n{err['detail'] or ''}")
if job["status"] == "cancelled":
raise RuntimeError(f"Job {job['id']} was cancelled")
# The output URL needs no key. Stream it to disk.
with requests.get(job["output"]["file"]["url"], stream=True, timeout=60) as res:
res.raise_for_status()
with open("out.mp4", "wb") as f:
for chunk in res.iter_content(chunk_size=1024 * 1024):
f.write(chunk)

How

How it works

  1. Install requests and set your key

    Create an API key in the dashboard under Settings, API keys, and put it in RENDOBAR_API_KEY. The script reads it from the environment, so the key never sits in your code. requests is the only package it needs.

    terminal
    pip install requests
    export RENDOBAR_API_KEY="YOUR_API_KEY"
    python transcode.py
  2. Send the command

    POST /jobs takes the job type, your FFmpeg command and an inputs map. Each key is a name the command reads with -i and each value is the URL Rendobar downloads it from. The response comes back as soon as the job is saved. Any command from the recipes runs the same way.

    What POST /jobs returns
    data.id
    job_8f2c41d07a6e4b19
    data.status
    waiting
  3. Wait for it

    GET /jobs/{id} returns the job and its status. Poll every 2 seconds until it reads complete, failed or cancelled. The loop always ends, because a job that runs past its plan's time limit fails with JOB_TIMEOUT. On complete, output.file.url is the file your command wrote, and output.expiresAt says when that link stops working. Fetch the job again for a fresh one.

    Job status, from GET /jobs/{id}
    waiting
    Saved and queued
    dispatched
    Sent to a machine
    running
    FFmpeg is running
    complete
    output is ready
    failed
    error says why
    cancelled
    Stopped before it finished
  4. Read a failed job

    A failed job carries error in place of output. error.code is the reason as a constant, error.message says it in words, and error.detail is the tail of FFmpeg's own stderr, so a typo in a filter reads the way it would in your terminal. error.retryable says whether the same job can succeed if you send it again. Every code is in the error reference.

    error on a failed job
    code
    UNSUPPORTED_CODEC
    message
    FFmpeg exited with code 1 …
    detail
    Unknown encoder 'libx265x'
    retryable
    false
  5. Send a local file

    A job reads its inputs from URLs, so a file on disk goes up first. POST /assets says where to PUT the bytes: one URL for most files, numbered parts for large ones. POST /assets/{id}/complete then returns the asset's url, which goes into inputs like any other URL. An upload is kept for 24 hours.

    upload.py
    import os
    import requests
    API = "https://api.rendobar.com"
    HEADERS = {"Authorization": f"Bearer {os.environ['RENDOBAR_API_KEY']}"}
    def upload(path: str) -> str:
    """Upload a local file and return the URL a job reads it from."""
    res = requests.post(
    f"{API}/assets",
    headers=HEADERS,
    json={"filename": os.path.basename(path), "size": os.path.getsize(path)},
    timeout=30,
    )
    res.raise_for_status()
    init = res.json()
    asset_id = init["data"]["id"]
    with open(path, "rb") as f:
    if init["status"] == "presigned":
    # One PUT straight to storage, no key needed.
    requests.put(init["upload"]["url"], data=f, timeout=600).raise_for_status()
    body = {}
    elif init["status"] == "multipart":
    # Large files come back as numbered parts of equal size.
    size = init["upload"]["partSize"]
    parts = []
    for part in init["upload"]["parts"]:
    f.seek((part["partNumber"] - 1) * size)
    put = requests.put(part["url"], data=f.read(size), timeout=600)
    put.raise_for_status()
    parts.append({"partNumber": part["partNumber"], "etag": put.headers["ETag"]})
    body = {"parts": parts}
    else:
    raise RuntimeError(f"Unexpected upload status {init['status']}")
    res = requests.post(f"{API}/assets/{asset_id}/complete", headers=HEADERS, json=body, timeout=60)
    res.raise_for_status()
    return res.json()["data"]["url"]
    # run_ffmpeg is the function from the top of the page.
    job = run_ffmpeg(
    "ffmpeg -i clip.mov -c:v libx264 -crf 23 -c:a aac out.mp4",
    {"clip.mov": upload("clip.mov")},
    )
  6. Take a webhook instead of polling

    Register an endpoint in the dashboard under Webhooks and Rendobar POSTs job.completed or job.failed to it when a job ends. Check the signature before you trust the body. It is an HMAC-SHA256 of the timestamp, a dot and the raw body, keyed by your webhook secret. The webhooks guide lists every event.

    app.py (Flask)
    import hashlib
    import hmac
    import os
    import time
    from flask import Flask, abort, request
    app = Flask(__name__)
    SECRET = os.environ["RENDOBAR_WEBHOOK_SECRET"].encode()
    def verified(raw: bytes, timestamp: str, signature: str) -> bool:
    """Rendobar signs "{timestamp}.{body}" with HMAC-SHA256."""
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
    return False
    digest = hmac.new(SECRET, timestamp.encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(digest, signature.removeprefix("sha256="))
    @app.post("/rendobar-webhook")
    def rendobar_webhook():
    raw = request.get_data()
    if not verified(
    raw,
    request.headers.get("X-Rendobar-Timestamp", ""),
    request.headers.get("X-Rendobar-Signature", ""),
    ):
    abort(401)
    payload = request.get_json()
    data = payload["data"]
    # save_video and log_failure are your own code.
    if payload["event"] == "job.completed":
    save_video(data["jobId"], data["output"]["file"]["url"])
    elif payload["event"] == "job.failed":
    log_failure(data["jobId"], data["error"])
    return "ok"
  7. Run many jobs with asyncio

    The same two calls on httpx.AsyncClient. asyncio.gather sends every job at once and waits for all of them. They run side by side up to your plan's concurrent job limit: 1 on Free, 20 on Pro and 50 on Studio.

    transcode_async.py
    import asyncio
    import os
    import httpx
    API = "https://api.rendobar.com"
    HEADERS = {"Authorization": f"Bearer {os.environ['RENDOBAR_API_KEY']}"}
    COMMAND = "ffmpeg -i source.mp4 -vf scale=1280:-2 -c:v libx264 -crf 23 -c:a aac out.mp4"
    async def run_ffmpeg(client: httpx.AsyncClient, command: str, inputs: dict[str, str]) -> dict:
    res = await client.post("/jobs", json={"type": "ffmpeg", "inputs": inputs, "params": {"command": command}})
    res.raise_for_status()
    job_id = res.json()["data"]["id"]
    while True:
    res = await client.get(f"/jobs/{job_id}")
    res.raise_for_status()
    job = res.json()["data"]
    if job["status"] in ("complete", "failed", "cancelled"):
    return job
    await asyncio.sleep(2)
    async def main() -> None:
    videos = ["https://example.com/a.mp4", "https://example.com/b.mp4", "https://example.com/c.mp4"]
    async with httpx.AsyncClient(base_url=API, headers=HEADERS, timeout=30) as client:
    # The jobs run side by side, up to your plan's concurrent job limit.
    jobs = await asyncio.gather(
    *(run_ffmpeg(client, COMMAND, {"source.mp4": url}) for url in videos)
    )
    for job in jobs:
    if job["status"] == "complete":
    print(job["id"], job["output"]["file"]["url"])
    else:
    print(job["id"], job["status"], job.get("error"))
    asyncio.run(main())

FAQ

Frequently asked questions

Is there a Python SDK for the FFmpeg API?

The API is JSON over HTTPS, so requests or httpx is the whole client. Two calls cover a job: POST /jobs sends it and GET /jobs/{id} reads it back. The code at the top of this page is a complete program, and the FFmpeg job reference lists every field.

Why does subprocess.run(["ffmpeg", ...]) raise FileNotFoundError?

The machine running Python has no ffmpeg binary on its PATH, which is common on serverless hosts, slim containers and hosted notebooks. A job sent to Rendobar's FFmpeg API needs no binary on your side. The same command runs on Rendobar's machines and Python only makes HTTP requests.

Which FFmpeg commands can I send from Python?

Any command that starts with ffmpeg and reads the inputs you pass. Filters, codecs and stream maps work as they do locally, and a command that writes several files returns each one in output.files. Options that read other files from disk, fetch over the network or run outside code are rejected with VALIDATION_ERROR before the job runs. A filter that reads a file by name, such as subtitles=, needs that file in inputs too.

How big can the input be, and how long can a job run?

Inputs can be up to 500 MB on Free and 10 GB on Pro and Studio. A job runs for up to 1 hour on Free and 9 hours on Pro and Studio. Set params.timeout, in seconds, to stop one sooner.

Can a job from Python encode on a GPU?

Yes. Put an NVENC encoder such as h264_nvenc in the command and the job runs on an NVIDIA L4, L40S or RTX PRO 6000, on Pro and Studio. Set params.compute to "gpu" or "cpu" to pick the hardware yourself.

How long does the output URL work?

Until output.expiresAt, a Unix time in milliseconds. Fetch the job again with GET /jobs/{id} for a fresh link. The file itself is kept for 7 days on Free, 30 on Pro and 90 on Studio.

What does it cost?

Jobs are billed per second of compute. A VP9 transcode we measured used 2.2 cores for 6.1 seconds and cost $0.0071. Every account starts with $5 of free credit and no card, and Rendobar bills nothing while you're not running jobs. Plans are on the pricing page.

Your command. Our infrastructure.

Bring your own commands. Run them on scalable CPU and GPU infrastructure, and pay only for compute time.