Skip to content

Python SDK

Convert files between 240+ formats from Python. One call uploads your file, converts it, waits and downloads the result; jobs, webhooks and the format list are there when you need more. Python 3.10+, standard library only.

PyPI ↗GitHub ↗Changelog ↗v0.1.0Python 3.10+MIT

Installing

Install it with your package manager. Python 3.10+.

$ pip install runconvert

Initializing

RunConvert(api_key=None, *, base_url=…, timeout=60.0, max_retries=2)

Create one client and reuse it. Without an API key it reads the RUNCONVERT_API_KEY environment variable. Get a key in Dashboard → API Keys, and keep it on your server: never put it in browser or mobile app code.

Example

from runconvert import RunConvert

rc = RunConvert()  # reads RUNCONVERT_API_KEY

Parameters

  • api_keystrYour API key. Defaults to the RUNCONVERT_API_KEY environment variable.
  • base_urlstrDefaults to https://api.runconvert.com/v3.
  • timeoutfloatSeconds per API request. Default 60. Uploads and downloads have no limit.
  • max_retriesintRetries for network errors, 429 and 5xx. Default 2.

Quick start

Convert a file in one call: the SDK uploads it, converts it, waits for the job and saves the result.

Example

Convert a file
from runconvert import RunConvert

rc = RunConvert()

result = rc.convert("report.docx", "pdf", out_dir="out")
print(result.saved)  # ['out/report.pdf']
['out/report.pdf']

Convert

Convert a file

rc.convert(file, to, *, from_=None, options=None, out_dir=None, filename=None, tag=None, on_update=None, timeout=None) → ConvertResult

Converts one file in one call: uploads a local file (or imports a URL), converts it, waits for the job and, when an output folder is given, downloads the result. Uses credits.

Example

result = rc.convert("report.docx", "pdf", out_dir="out")
print(result.saved)
['out/report.pdf']

Parameters

  • filestr | bytes | fileA local path, an http(s) URL (imported by RunConvert, nothing to upload), bytes, or a binary file or stream.Required
  • tostrThe target format, e.g. "pdf" or "mp3".Required
  • from_strThe source format. Read from the file name or URL when left out; needed for bytes or streams without a filename.
  • optionsdictEngine options for the conversion, e.g. audioBitrate or image_quality. List them with Formats → engines for a pair.
  • out_dirstrSave the results in this folder (created if needed). Without it nothing is downloaded; use the result's files.
  • filenamestrThe file's name when you pass bytes or a stream.
  • tagstrA label to find the job later, e.g. "invoices".
  • on_updateCallable[[dict], None]Called with the job after every check, e.g. to show progress.
  • timeoutfloatSeconds to wait for the job before giving up.

Returns

ConvertResult with job (the finished job), files (each with filename, url and size) and saved (local paths, when out_dir is set).

Jobs

Create a job

rc.jobs.create(tasks, *, tag=None, metadata=None) → dict

Creates a job from named tasks that run in order: import → convert → export. Tasks refer to each other by name in input. The job comes back with its tasks; an upload task carries the upload_url to send your file to.

Example

job = rc.jobs.create({
    "a": {"operation": "import/url", "source_url": "https://example.com/cover.pdf"},
    "b": {"operation": "import/url", "source_url": "https://example.com/body.pdf"},
    "merge": {"operation": "convert", "input": ["a", "b"],
              "input_format": "pdf", "output_format": "pdf"},
    "export": {"operation": "export/url", "input": "merge"},
}, tag="merge")

Parameters

  • tasksdict[str, dict]Named task definitions. Names use letters, digits, - or _ (up to 64 characters).Required
  • tagstrA label to find the job later, e.g. "invoices".
  • metadatadictYour own key-value data, returned with the job and in webhooks.

Returns

The job, with its tasks.

Get a job

rc.jobs.get(job_id) → dict

Gets one job with its tasks: status, credits used, and the result files of its export tasks.

Example

Get a job
job = rc.jobs.get("job_01hx4k9m2p7w")
print(job["status"])
{
  "id": "job_01hx4k9m2p7w",
  "status": "finished",
  "tag": "invoices",
  "credits_used": 2,
  "created_at": "2026-11-16T09:12:04Z",
  "ended_at": "2026-11-16T09:12:09Z",
  "tasks": [
    { "name": "import-1", "operation": "import/direct/upload", "status": "finished" },
    { "name": "convert-1", "operation": "convert", "status": "finished" },
    { "name": "export-1", "operation": "export/url", "status": "finished",
      "result": { "files": [
        { "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
      ] } }
  ]
}

Parameters

  • job_idstrThe job's ID.Required

Returns

The job, with its tasks.

List jobs

rc.jobs.list(*, status=None, tag=None, page=None, per_page=None, include_tasks=False) → dict

One page of jobs, newest first, with paging details. Filter by status or tag.

Example

Finished jobs
page = rc.jobs.list(status="finished", per_page=20)
for job in page["data"]:
    print(job["id"])
{
  "data": [ { "id": "job_01hx4k9m2p7w", "status": "finished", … } ],
  "meta": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3 }
}

Parameters

  • statusstrOnly jobs with this status: waiting, processing, finished, error or canceled.
  • tagstrA label to find the job later, e.g. "invoices".
  • pageintPage number, from 1.
  • per_pageintJobs per page (max 100).
  • include_tasksboolInclude each job's tasks.

Returns

One page: {"data": [jobs], "meta": {page, per_page, total, total_pages}}.

Every job

rc.jobs.all(**filters) → Iterator[dict]

Every job, page by page, so you can loop over all of them without handling pages yourself.

Example

Loop over all jobs
for job in rc.jobs.all(tag="invoices"):
    print(job["id"], job["status"])

Parameters

  • **filtersThe same filters as list(): status, tag, per_page, include_tasks.

Wait for a job

rc.jobs.wait(job_id, *, timeout=None, on_update=None, raise_on_error=True) → dict

Polls a job until it finishes (every 0.7 s, slowing to 3 s). Fails with the task's code and reason if the job fails, and stops after the timeout if you give one.

Example

job = rc.jobs.wait(job["id"], timeout=300)
for f in Jobs.exported_files(job):
    rc.files.download(f, "out")

Parameters

  • job_idstrThe job's ID.Required
  • timeoutfloatSeconds to wait. Raises WaitTimeoutError after it.
  • on_updateCallable[[dict], None]Called with the job after every check, e.g. to show progress.
  • raise_on_errorboolFail when the job ends in error (default). Turn off to get the failed job back instead.

Returns

The finished job.

Cancel a job

rc.jobs.cancel(job_id) → dict

Cancels a job's pending tasks. Credits for tasks that didn't finish are refunded.

Example

Cancel
rc.jobs.cancel("job_01hx4k9m2p7w")

Parameters

  • job_idstrThe job's ID.Required

Returns

The canceled job.

Delete a job

rc.jobs.delete(job_id) → None

Deletes a job and its files.

Example

Delete
rc.jobs.delete("job_01hx4k9m2p7w")

Parameters

  • job_idstrThe job's ID.Required

Result files

Jobs.exported_files(job) → list[dict]

The files produced by a finished job's export tasks: file name, a temporary download URL and size.

Example

List results
from runconvert import Jobs

for f in Jobs.exported_files(job):
    print(f["filename"], f["url"])
[
  { "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
]

Parameters

  • jobdictA finished job, with its tasks.Required

Files

Upload a file

rc.files.upload(task, file, *, filename=None) → None

Sends a file to an import/direct/upload task before its deadline. Use it with a job you created yourself.

Example

Upload
upload = next(t for t in job["tasks"] if t["name"] == "upload")
rc.files.upload(upload, "image.png")

Parameters

  • taskdict | strThe upload task from the created job, or its upload URL.Required
  • filestr | bytes | fileA local path, bytes or a binary file object.Required
  • filenamestrThe file's name when you pass bytes or a stream.

Download a result

rc.files.download(file, out_dir, filename=None) → str

Saves a result file into a folder, keeping its name, and returns the path. Streams, so big files use little memory.

Example

Download
for f in Jobs.exported_files(job):
    path = rc.files.download(f, "out")
    print(path)
out/report.pdf

Parameters

  • filedict | strA result file from a job's export task, or its URL.Required
  • out_dirstrThe folder to save into.Required
  • filenamestrSave under this name instead.

Returns

The saved file's path.

Formats

List formats

rc.operations.list(*, category=None) → dict

Every input format and what it converts to. Public: no API key needed.

Example

Audio formats
catalog = rc.operations.list(category="audio")
print(len(catalog["formats"]))

Parameters

  • categorystrOnly one category: document, image, video, audio, ebook, archive, font, cad, …

Returns

{"categories": [...], "formats": [...]}

Targets for a format

rc.operations.for_input(input_format) → dict

What one format converts to, with the credit cost of each conversion. Public.

Example

What MP4 converts to
mp4 = rc.operations.for_input("mp4")
for o in mp4["outputs"]:
    print(o["format"], o["credits"])
{
  "format": "mp4",
  "category": "video",
  "outputs": [
    { "format": "mp3", "category": "audio", "engine": "ffmpeg", "credits": 1 },
    { "format": "gif", "category": "image", "engine": "ffmpeg", "credits": 4 },
    …
  ]
}

Parameters

  • input_formatstrThe input format, e.g. "mp4".Required

Engines for a pair

rc.operations.for_pair(input_format, output_format) → dict

The engines for one conversion and the options its convert task accepts, e.g. bitrate or quality. Public.

Example

MP4 → MP3 options
pair = rc.operations.for_pair("mp4", "mp3")
for opt in pair["engines"][0]["options"]:
    print(opt["name"])
{
  "input": "mp4",
  "output": "mp3",
  "engines": [
    { "name": "ffmpeg", "credits": 1,
      "options": [
        { "name": "audioBitrate", "type": "string",
          "description": "Target audio bitrate in kbps.",
          "supported_values": ["32k", "48k", "64k", "80k", …] },
        …
      ] }
  ]
}

Parameters

  • input_formatstrThe input format, e.g. "mp4".Required
  • output_formatstrThe output format, e.g. "mp3".Required

Account

Credits and team

rc.me() → dict

The account, team and credit balance behind the API key.

Example

Credits left
me = rc.me()
print(me["credits"]["total_remaining"])
{
  "user": { "email": "[email protected]", "full_name": "Ada Lovelace" },
  "team": { "name": "Acme" },
  "credits": { "mode": "wallet", "total_remaining": 4820 }
}

Webhooks

Verify a signature

verify_signature(raw_body, signature, secret) → bool

Checks that a webhook delivery really came from RunConvert: an HMAC-SHA256 of the raw request body with your webhook secret, compared with the X-RunConvert-Signature header in constant time.

Example

Verify
from runconvert import verify_signature

ok = verify_signature(
    request.get_data(),
    request.headers.get("X-RunConvert-Signature"),
    os.environ["RUNCONVERT_WEBHOOK_SECRET"],
)

Parameters

  • raw_bodystr | bytesThe raw request body, exactly as received (not parsed JSON).Required
  • signaturestrThe X-RunConvert-Signature header.Required
  • secretstrYour webhook's signing secret.Required

Parse an event

construct_event(raw_body, signature, secret) → dict

Verifies the signature and parses the event in one step. Fails if the signature is wrong.

Raises ValueError when the signature doesn't match: answer 400 and ignore the request.

Example

Flask
from runconvert import construct_event

@app.post("/webhooks/runconvert")
def runconvert_webhook():
    try:
        event = construct_event(
            request.get_data(),
            request.headers.get("X-RunConvert-Signature"),
            os.environ["RUNCONVERT_WEBHOOK_SECRET"],
        )
    except ValueError:
        return "", 400
    if event["event"] == "job.finished":
        print("done", event["job"]["id"])
    return "", 200
{
  "event": "job.finished",
  "job": { "id": "job_01hx4k9m2p7w", "status": "finished", … }
}

Parameters

  • raw_bodystr | bytesThe raw request body, exactly as received (not parsed JSON).Required
  • signaturestrThe X-RunConvert-Signature header.Required
  • secretstrYour webhook's signing secret.Required

More

Errors

Every failure is a typed error. The API's code tells you what happened, for example BILLING_INSUFFICIENT_CREDITS, UNAUTHORIZED or INVALID_DATA.

Example

Handle errors
from runconvert import RunConvertError, JobFailedError

try:
    rc.convert("report.docx", "pdf", out_dir="out")
except JobFailedError as e:
    print("conversion failed:", e.task["reason"])
except RunConvertError as e:
    print(e.status, e.code, e.message)
422 BILLING_INSUFFICIENT_CREDITS Insufficient credits.

Error types

  • RunConvertErrorclassThe API said no: .status (HTTP status), .code (e.g. BILLING_INSUFFICIENT_CREDITS), .message.
  • JobFailedErrorclassThe job ended in error: .job, and .task with code, reason and message.
  • WaitTimeoutErrorclasswait() ran past its timeout: .job is the job as last seen.

Retries and timeouts

Network errors, rate limits (429) and server errors (5xx) are retried twice with backoff, honouring Retry-After. Creating a job is only retried when the request never reached the API, so a job is never created twice.

Example

Tune retries
rc = RunConvert(max_retries=4, timeout=30)

Like RunConvert? Set us as a preferred source on Google.

Add to Preferred Sources