Skip to content

Ruby SDK

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

Installing

Install it with your package manager. Ruby 2.7+.

$ gem install runconvert

Initializing

RunConvert::Client.new(api_key: nil, base_url: …, timeout: 60, 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

require "runconvert"

rc = RunConvert::Client.new # reads RUNCONVERT_API_KEY

Parameters

  • api_key:StringYour API key. Defaults to the RUNCONVERT_API_KEY environment variable.
  • base_url:StringDefaults to https://api.runconvert.com/v3.
  • timeout:IntegerSeconds per API request. Default 60. Uploads and downloads have no limit.
  • max_retries:IntegerRetries 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
require "runconvert"

rc = RunConvert::Client.new

result = rc.convert("report.docx", to: "pdf", out_dir: "out")
p result.saved # => ["out/report.pdf"]
["out/report.pdf"]

Convert

Convert a file

rc.convert(file, to:, from: nil, options: {}, out_dir: nil, filename: nil, tag: nil, timeout: nil) { |job| … } → 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. Pass a block to see progress.

Example

result = rc.convert("report.docx", to: "pdf", out_dir: "out")
p result.saved
["out/report.pdf"]

Parameters

  • fileString | IOA local path, an http(s) URL (imported by RunConvert), or an IO.Required
  • to:StringThe target format, e.g. "pdf" or "mp3".Required
  • from:StringThe source format. Read from the file name or URL when left out; needed for bytes or streams without a filename.
  • options:HashEngine options for the conversion, e.g. audioBitrate or image_quality. List them with Formats → engines for a pair.
  • out_dir:StringSave the results in this folder (created if needed). Without it nothing is downloaded; use the result's files.
  • filename:StringThe file's name when you pass bytes or a stream.
  • tag:StringA label to find the job later, e.g. "invoices".
  • timeout:NumericSeconds to wait for the job before giving up.
  • &block{ |job| … }Called with the job after every check, e.g. to show progress.

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: nil, metadata: nil) → Hash

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: %w[a b], input_format: "pdf", output_format: "pdf" },
  "export" => { operation: "export/url", input: "merge" }
}, tag: "merge")

Parameters

  • tasksHashNamed task definitions. Names use letters, digits, - or _ (up to 64 characters).Required
  • tag:StringA label to find the job later, e.g. "invoices".
  • metadata:HashYour own key-value data, returned with the job and in webhooks.

Returns

The job, with its tasks.

Get a job

rc.jobs.get(id) → Hash

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")
puts 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

  • idStringThe job's ID.Required

Returns

The job, with its tasks.

List jobs

rc.jobs.list(status: nil, tag: nil, page: nil, per_page: nil, include_tasks: false) → Hash

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)
page["data"].each { |job| puts job["id"] }
{
  "data": [ { "id": "job_01hx4k9m2p7w", "status": "finished", … } ],
  "meta": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3 }
}

Parameters

  • status:StringOnly jobs with this status: waiting, processing, finished, error or canceled.
  • tag:StringA label to find the job later, e.g. "invoices".
  • page:IntegerPage number, from 1.
  • per_page:IntegerJobs per page (max 100).
  • include_tasks:BooleanInclude each job's tasks.

Returns

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

Every job

rc.jobs.each(**filters) { |job| … } → Enumerator

Every job, page by page, so you can loop over all of them without handling pages yourself. Without a block it returns an Enumerator.

Example

Loop over all jobs
rc.jobs.each(tag: "invoices") do |job|
  puts "#{job['id']} #{job['status']}"
end

Parameters

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

Wait for a job

rc.jobs.wait(id, timeout: nil, raise_on_error: true) { |job| … } → Hash

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

done = rc.jobs.wait(job["id"], timeout: 300)
RunConvert::Jobs.exported_files(done).each { |f| rc.files.download(f, "out") }

Parameters

  • idStringThe job's ID.Required
  • timeout:NumericSeconds to wait. Raises WaitTimeoutError after it.
  • raise_on_error:BooleanFail when the job ends in error (default). Turn off to get the failed job back instead.
  • &block{ |job| … }Called with the job after every check, e.g. to show progress.

Returns

The finished job.

Cancel a job

rc.jobs.cancel(id) → Hash

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

Example

Cancel
rc.jobs.cancel("job_01hx4k9m2p7w")

Parameters

  • idStringThe job's ID.Required

Returns

The canceled job.

Delete a job

rc.jobs.delete(id) → nil

Deletes a job and its files.

Example

Delete
rc.jobs.delete("job_01hx4k9m2p7w")

Parameters

  • idStringThe job's ID.Required

Result files

RunConvert::Jobs.exported_files(job) → Array<Hash>

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

Example

List results
RunConvert::Jobs.exported_files(job).each do |f|
  puts "#{f['filename']} #{f['url']}"
end
[
  { "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
]

Parameters

  • jobHashA finished job, with its tasks.Required

Files

Upload a file

rc.files.upload(task, file, filename: nil) → nil

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

Example

Upload
upload = job["tasks"].find { |t| t["name"] == "upload" }
rc.files.upload(upload, "image.png")

Parameters

  • taskHash | StringThe upload task from the created job, or its upload URL.Required
  • fileString | IOA local path or an IO.Required
  • filename:StringThe file's name when you pass bytes or a stream.

Download a result

rc.files.download(file, dir, filename: nil) → String

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

Example

Download
RunConvert::Jobs.exported_files(job).each do |f|
  puts rc.files.download(f, "out")
end
out/report.pdf

Parameters

  • fileHash | StringA result file from a job's export task, or its URL.Required
  • dirStringThe folder to save into.Required
  • filename:StringSave under this name instead.

Returns

The saved file's path.

Formats

List formats

rc.operations.list(category: nil) → Hash

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

Example

Audio formats
catalog = rc.operations.list(category: "audio")
puts catalog["formats"].size

Parameters

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

Targets for a format

rc.operations.for_input(input) → Hash

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

Example

What MP4 converts to
mp4 = rc.operations.for_input("mp4")
mp4["outputs"].each { |o| puts "#{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

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

Engines for a pair

rc.operations.for_pair(input, output) → Hash

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")
pair["engines"][0]["options"].each { |o| puts o["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

  • inputStringThe input format, e.g. "mp4".Required
  • outputStringThe output format, e.g. "mp3".Required

Account

Credits and team

rc.me → Hash

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

Example

Credits left
puts rc.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

RunConvert::Webhooks.verify(raw_body, signature, secret) → Boolean

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
ok = RunConvert::Webhooks.verify(
  request.body.read,
  request.env["HTTP_X_RUNCONVERT_SIGNATURE"],
  ENV["RUNCONVERT_WEBHOOK_SECRET"]
)

Parameters

  • raw_bodyStringThe raw request body, exactly as received (not parsed JSON).Required
  • signatureStringThe X-RunConvert-Signature header.Required
  • secretStringYour webhook's signing secret.Required

Parse an event

RunConvert::Webhooks.construct_event(raw_body, signature, secret) → Hash

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

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

Example

Sinatra
post "/webhooks/runconvert" do
  event = RunConvert::Webhooks.construct_event(
    request.body.read,
    request.env["HTTP_X_RUNCONVERT_SIGNATURE"],
    ENV["RUNCONVERT_WEBHOOK_SECRET"]
  )
  puts "done #{event['job']['id']}" if event["event"] == "job.finished"
  200
rescue ArgumentError
  400
end
{
  "event": "job.finished",
  "job": { "id": "job_01hx4k9m2p7w", "status": "finished", … }
}

Parameters

  • raw_bodyStringThe raw request body, exactly as received (not parsed JSON).Required
  • signatureStringThe X-RunConvert-Signature header.Required
  • secretStringYour 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
begin
  rc.convert("report.docx", to: "pdf", out_dir: "out")
rescue RunConvert::JobFailedError => e
  puts "conversion failed: #{e.task['reason']}"
rescue RunConvert::Error => e
  puts "#{e.status} #{e.code} #{e.message}"
end
422 BILLING_INSUFFICIENT_CREDITS Insufficient credits.

Error types

  • RunConvert::ErrorclassThe API said no: #status (HTTP status), #code (e.g. BILLING_INSUFFICIENT_CREDITS), #message.
  • RunConvert::JobFailedErrorclassThe job ended in error: #job, and #task with code, reason and message.
  • RunConvert::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::Client.new(max_retries: 4, timeout: 30)

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

Add to Preferred Sources