Quickstart Guide

This guide leads you through a typical implementation of the CloudConvert API. This contains starting a job, wait for job completion and handle the result of the job. The quickstart guide can be seen as an entry point. For a more in deep documentation please use the menu on the left to directly jump to a specific topic.

You can find example requests and code examples for our SDKs in the right column. Please use the buttons on the right to switch between raw requests, cURL commands, PHP code and node.js code.

PHP Code

use \CloudConvert\CloudConvert;
use \CloudConvert\Models\Job;
use \CloudConvert\Models\Task;


$cloudconvert = new CloudConvert([
    'api_key' => 'API_KEY',
    'sandbox' => false
]);

node.js Code

import CloudConvert from 'cloudconvert';

const cloudConvert = new CloudConvert('api_key');

API Base URL

https://api.cloudconvert.com/v2

Starting Jobs

On the right you can find the creation of a typical job. It downloads a file from an URL (import/url operation), converts this file to PDF and creates a URL to converted file (export/url operation).

If you are using a storage provide like S3, Azure, Google Cloud or OpenStack we recommend using the corresponding import and export operations. CloudConvert can take care of fetching and storing files from/to your storage.

Depending on the input and output format, the available options for the convert operation do vary. You can use the Job Builder to generate the payload of your job. It shows all available operations and the possible options.

Create job request

POST https://api.cloudconvert.com/v2/jobs

Request Body

{
  "tasks": {
    "import-my-file": {
      "operation": "import/url",
      "url": "https://my.url/file.docx"
    },
    "convert-my-file": {
      "operation": "convert",
      "input": "import-my-file",
      "output_format": "pdf"
    },
    "export-my-file": {
      "operation": "export/url",
      "input": "convert-my-file"
    }
  }
}

Example Response

{
  "data": {
    "id": "6559c281-ed85-4728-80db-414561c631e9",
    "status": "processing",
    "tasks": [
      ...
    ]
  }
}

cURL Command

$ curl -X POST "https://api.cloudconvert.com/v2/jobs" \
       -H "Authorization: Bearer API_KEY" \
       -H "Content-type: application/json" \
       -d '{
  "tasks": {
    "import-my-file": {
      "operation": "import/url",
      "url": "https://my.url/file.docx"
    },
    "convert-my-file": {
      "operation": "convert",
      "input": "import-my-file",
      "output_format": "pdf"
    },
    "export-my-file": {
      "operation": "export/url",
      "input": "convert-my-file"
    }
  }
}'

Example Response

{
  "data": {
    "id": "6559c281-ed85-4728-80db-414561c631e9",
    "status": "processing",
    "tasks": [
      ...
    ]
  }
}

PHP Code

$job = (new Job())
    ->addTask(
        (new Task('import/url', 'import-my-file'))
            ->set('url', 'https://my.url/file.docx')
    )
    ->addTask(
        (new Task('convert', 'convert-my-file'))
            ->set('input', 'import-my-file')
            ->set('output_format', 'pdf')
    )
    ->addTask(
        (new Task('export/url', 'export-my-file'))
            ->set('input', 'convert-my-file')
    );

$cloudconvert->jobs()->create($job);

node.js Code

let job = await cloudConvert.jobs.create({
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://my.url/file.docx"
        },
        "convert-my-file": {
            "operation": "convert",
            "input": "import-my-file",
            "output_format": "pdf"
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
});

Wait for job completion

We recommend using webhooks to get notified when a job completes. Alternatively, you can use the /jobs/{ID}/wait endpoint to wait for job completion, as shown on the right.

In general, please avoid to block your application until a CloudConvert job completes. There might be cases in which we need to queue your job which results in longer processing times than usual. Using an asynchronous approach with webhooks is beneficial in such cases.

Wait for job request

GET https://api.cloudconvert.com/v2/jobs/6559c281-ed85-4728-80db-414561c631e9/wait

Example Response

{
  "data": {
    "id": "6559c281-ed85-4728-80db-414561c631e9",
    "status": "finished",
    "tasks": [
      {
        "id": "7f110c42-3245-41cf-8555-37087c729ed2",
        "name": "import-my-file",
        "operation": "import/url",
        "status": "finished"
      },
      {
        "id": "7a142bd0-fa20-493e-abf5-99cc9b5fd7e9",
        "name": "convert-my-file",
        "operation": "convert",
        "status": "finished"
      },
      {
        "id": "36af6f54-1c01-45cc-bcc3-97dd23d2f93d",
        "name": "export-my-file",
        "operation": "export/url",
        "status": "finished",
        "result": {
          "files": [
            {
              "filename": "file.pdf",
              "url": "https://storage.cloudconvert.com/eed87242-577e-4e3e-8178-9edbe51975dd/file.pdf?temp_url_sig=79c2db4d884926bbcc5476d01b4922a19137aee9&temp_url_expires=1545962104"
            }
          ]
        }
      }
    ]
  }
}

cURL Command

$ curl -g "https://api.cloudconvert.com/v2/jobs/6559c281-ed85-4728-80db-414561c631e9/wait" \
       -H "Authorization: Bearer API_KEY"

Example Response

{
  "data": {
    "id": "6559c281-ed85-4728-80db-414561c631e9",
    "status": "finished",
    "tasks": [
      {
        "id": "7f110c42-3245-41cf-8555-37087c729ed2",
        "name": "import-my-file",
        "operation": "import/url",
        "status": "finished"
      },
      {
        "id": "7a142bd0-fa20-493e-abf5-99cc9b5fd7e9",
        "name": "convert-my-file",
        "operation": "convert",
        "status": "finished"
      },
      {
        "id": "36af6f54-1c01-45cc-bcc3-97dd23d2f93d",
        "name": "export-my-file",
        "operation": "export/url",
        "status": "finished",
        "result": {
          "files": [
            {
              "filename": "file.pdf",
              "url": "https://storage.cloudconvert.com/eed87242-577e-4e3e-8178-9edbe51975dd/file.pdf?temp_url_sig=79c2db4d884926bbcc5476d01b4922a19137aee9&temp_url_expires=1545962104"
            }
          ]
        }
      }
    ]
  }
}

PHP Code

$cloudconvert->jobs()->wait($job);

node.js Code

job = await cloudConvert.jobs.wait(job.id);

Download output files

Our example is using the export/url operation to generate a download URL of output file. This URL can be found in the response of the /jobs/{ID}/wait endpoint, or alternatively, in the body of the webhook payload. The example on the right shows how to download the file. Please note that export URLs are valid for 24 hours only.

If you are using an export method like S3 or Azure, you don't need to manually download output files, of course.

Download file

GET https://storage.cloudconvert.com/eed87242-577e-4e3e-8178-9edbe51975dd/data.txt?temp_url_sig=79c2db4d884926bbcc5476d01b4922a19137aee9&temp_url_expires=1545962104

cURL download command

$ curl -O "https://storage.cloudconvert.com/eed87242-577e-4e3e-8178-9edbe51975dd/data.txt?temp_url_sig=79c2db4d884926bbcc5476d01b4922a19137aee9&temp_url_expires=1545962104"

PHP Code

$file = $job->getExportUrls()[0];

$source = $cloudconvert->getHttpTransport()->download($file->url)->detach();
$dest = fopen('output/' . $file->filename, 'w');

stream_copy_to_stream($source, $dest);

node.js Code

const exportTask = job.tasks.filter(task => task.operation === 'export/url' && task.status === 'finished')[0];
const file = exportTask.result.files[0];

const writeStream = fs.createWriteStream('./out/' + file.filename);

http.get(file.url, function(response) {
    response.pipe(writeStream);
});

await new Promise((resolve, reject) => {
    writeStream.on('finish', resolve);
    writeStream.on('error', reject);
});