This is the official Ruby SDK for the CloudConvert API v2.

Build Status Latest Stable Version Total Downloads License


Add this line to your application's Gemfile:

gem "cloudconvert"

And then execute:

bundle install

Or install it yourself as:

gem install cloudconvert

Creating API Client

cloudconvert = "API_KEY", sandbox: false)

Or set the environment variables CLOUDCONVERT_API_KEY and CLOUDCONVERT_SANDBOX and use:

cloudconvert =

Creating Jobs{
  tasks: [
      name: "import-my-file",
      operation: "import/url",
      url: "https://my-url"
      name: "convert-my-file",
      operation: "convert",
      input: "import-my-file",
      output_format: "pdf",
      some_other_option: "value"
      name: "export-my-file",
      operation: "export/url",
      input: "convert-my-file"

Downloading Files

CloudConvert can generate public URLs for using export/url tasks.

You can use these URLs to download output files:

exported_url_task_id = "84e872fc-d823-4363-baab-eade2e05ee54"
task = cloudconvert.tasks.wait(exported_url_task_id) # Wait for job completion
file = task.result.files.first
export =

By default the remote file will be downloaded into a temporary location and returned as a Tempfile. If you would like the file to be downloaded to a specific location on disk, you can specify the :destination option:

export =, destination: "/path/to/destination")

The download method is powered by the Down gem, for the full list of arguments see the the down docs.

Uploading Files

Uploads to CloudConvert are done via import/upload tasks (see the docs):

job ={
    tasks: [
            name: "upload-my-file",
            operation: "import/upload",

After you've created a import/upload task, you can upload a file:

upload_task = job.tasks.where(operation: "import/upload").first

response = cloudconvert.tasks.upload("/path/to/sample.pdf", upload_task)

updated_task = cloudconvert.tasks.find(

Alternatively, instead of a path, you can pass in an open IO object:

file ="/path/to/sample.pdf")
response = cloudconvert.tasks.upload(file, upload_task)

If you need to manually specify a mimetype or filename use our file wrapper:

file ="/path/to/sample.pdf", "video/mp4", "sample.mp4")
response = cloudconvert.tasks.upload(file, upload_task)


Webhooks can be created on the CloudConvert Dashboard, where you can also find the signing secret.

If you're using Rails, you'll want to configure a route to receive the CloudConvert webhook POST requests:

# config/routes.rb
resource :cloudconvert_webhooks, controller: :cloud_convert_webhooks, only: :create

Then create a new controller that uses our processor concern:

# app/controllers/cloudconvert_webhooks_controller.rb
class CloudConvertWebhooksController < ActionController::Base
  include CloudConvert::Webhook::Processor

  # Handle job.created event
  def job_created(event)
    # TODO: handle job.created webhook

  # Handle job.finished event
  def job_finished(event)
    # TODO: handle job.finished webhook

  # Handle job.failed event
  def job_failed(event)
    # TODO: handle job.failed webhook


  def webhook_secret(event)

Alternatively, you can verify the payload yourself:

payload =
signature = request.headers["CloudConvert-Signature"]
secret = "..." # You can find it in your webhook settings

if CloudConvert::Webhook::verify(payload, signature, secret)
  event = CloudConvert::Webhook::event(payload) == "job.finished"
  puts event.job.tasks.count

Or by passing in a request:

CloudConvert::Webhook::verify_request(request, secret)

The verify/verify_request methods return true/false, use verify! or verify_request! if you'd rather raise a CloudConvert::Webhook::Error.

You can read the full list of events CloudConvert can notify you about in our documentation.

Signed URL

Signed URLs allow converting files on demand only using URL query parameters. The Ruby SDK allows to generate such URLs. Therefore, you need to obtain a signed URL base and a signing secret on the CloudConvert Dashboard.

base = '' # You can find it in your signed URL settings.
signing_secret = '...' # You can find it in your signed URL settings.
cache_key = 'cache-key' # Allows caching of the result file for 24h

job = {
  tasks: {
    "import-it": { operation: "import/url", filename: "test.file", url: "http://invalid.url" },
    "convert-it": { input: "import-it", operation: "convert", output_format: "pdf" },

url = CloudConvert::SignedUrl.sign(base, signing_secret, job, cache_key)


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Bug reports and pull requests are welcome on GitHub at

Unit Tests

rspec --tag unit

Integration Tests

rspec --tag integration

By default, this runs the integration tests against VCR recordings of the Sandbox API with an official CloudConvert account. If you would like to use your own account, you can set your API key using the CLOUDCONVERT_API_KEY environment variable and disable VCR with VCR=off or by using the rake spec:sandbox task. In this case you need to whitelist the following MD5 hashes for Sandbox API (using the CloudConvert dashboard).

53d6fe6b688c31c565907c81de625046  input.pdf
99d4c165f77af02015aa647770286cf9  input.png


The gem is available as open source under the terms of the MIT License.