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 to switch between the SDKs.

Raw Requests cURL PHP node.js Ruby Python Java .NET

The full documentation for the PHP SDK is available at GitHub.

The full documentation for the node.js SDK is available at GitHub.

The full documentation for the Ruby SDK is available at GitHub.

The full documentation for the Python SDK is available at GitHub.

The full documentation for the Java SDK is available at GitHub.

The full documentation for the .NET SDK is available at GitHub.

PHP Code

// composer require cloudconvert/cloudconvert-php

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


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

node.js Code

// npm install --save cloudconvert

import CloudConvert from 'cloudconvert';

const cloudConvert = new CloudConvert('api_key');

Ruby Code

# Add to your Gemfile: gem "cloudconvert"

cloudconvert = CloudConvert::Client.new(api_key: "API_KEY", sandbox: false)

Python Code

  # pip install cloudconvert

  import cloudconvert
 
  cloudconvert.configure(api_key = 'API_KEY', sandbox = False)

Java Code

import com.cloudconvert.client.CloudConvertClient;

final CloudConvertClient cloudConvertClient =
    new CloudConvertClient(new StringSettingsProvider("api-url", "webhook-signing-secret"));

C# Code

/// dotnet add package CloudConvert.API

using CloudConvert.API;
using CloudConvert.API.Models.ExportOperations;
using CloudConvert.API.Models.ImportOperations;
using CloudConvert.API.Models.JobModels;
using CloudConvert.API.Models.TaskOperations;

var CloudConvert = new CloudConvertAPI("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.

Job Builder

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"
        }
    }
});

Ruby Code

job = cloudconvert.jobs.create({
  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"
    },
  ]
})

Python Code

job = cloudconvert.Job.create(payload={
     "tasks": {
         'import-my-file': {
              'operation': 'import/url',
              'url': 'https://my-url'
         },
         'convert-my-file': {
             'operation': 'convert',
             'input': 'import-my-file',
             'output_format': 'pdf',
             'some_other_option': 'value'
         },
         'export-my-file': {
             'operation': 'export/url',
             'input': 'convert-my-file'
         }
     }
 })

Java Code

final JobResponse createJobResponse = cloudConvertClient.jobs().create(
    ImmutableMap.of(
        "import-my-file",
            new UrlImportRequest()
                .setUrl("import-url"),
        "convert-my-file",
            new ConvertFilesTaskRequest()
                .setInput("import-my-file")
                .setOutputFormat("pdf"),
        "export-my-file",
            new UrlExportRequest()
                .setInput("convert-my-file")
    )
).getBody();

C# Code

var job = await CloudConvert.CreateJobAsync(new JobCreateRequest
      {
        Tasks = new
        {
          import_it = new ImportUrlCreateRequest
          {
            Url = "https://my.url/file.docx"
          },
          convert = new ConvertCreateRequest
          {
            Input = "import_it",
            Input_Format = "docx",
            Output_Format = "pdf"
          },
          export_it = new ExportUrlCreateRequest
          {
            Input = "convert"
          }
        }
      });

Wait for job completion

We recommend using webhooks to get notified when a job completes. Alternatively, you can use the synchronous API 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 specific files cause longer processing times than usual. Using an asynchronous approach with webhooks is beneficial in such cases.

Wait for job request

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

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);

Ruby Code

job = cloudconvert.jobs.wait(job.id)

Python Code

job = cloudconvert.Job.wait(id=job['id'])

Java Code

final JobResponse waitJobResponse =
    cloudConvertClient.jobs().wait(createJobResponse.getId()).getBody();

C# Code

var job = await CloudConvertAPI.WaitJobAsync(job.Data.Id); // Wait for job completion

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} status endpoint, or alternatively, in the body of the webhook payload. You can add the ?redirect=true query parameter to the status endpoint to get redirected to the export URL. 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://sync.api.cloudconvert.com/v2/jobs/6559c281-ed85-4728-80db-414561c631e9?redirect=true

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 file = cloudconvert.jobs.getExportUrls(job)[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);
});

Ruby Code

export_task = job.tasks.where(operation: "export/url").where(status: "finished").first

file = task.result.files.first

cloudconvert.download(file.url, destination: "/path/to/destination")

Python Code

for task in job["tasks"]:
    if task.get("name") == "export-it" and task.get("status") == "finished":
        export_task = task

file = export_task.get("result").get("files")[0]
cloudconvert.download(filename=file['filename'], url=file['url'])

Java Code

// Get an export/url task id
final TaskResponse exportUrlTask =
    waitJobResponse.getTasks().stream().filter(
         taskResponse -> taskResponse.getName().equals("export-my-file")
    ).findFirst().get();

// Get a url of export/url task
final String exportUrl =
    exportUrlTask
        .getResult()
        .getFiles()
        .get(0)
        .get("url");

// Get file as input stream using url of export/url task
final InputStream inputStream =
    cloudConvertClient.files().download(exportUrl).getBody();

C# Code

var exportTask = job.Data.Tasks.FirstOrDefault(t => t.Name == "export_it");

var fileExport = exportTask.Result.Files.FirstOrDefault();

using (var client = new WebClient()) client.DownloadFile(fileExport.Url, fileExport.Filename);

Convert Files

Optimize Files

Archives

Capture Websites

Merge Files

Convert Files

Capture Websites

Optimize Files

Other APIs

Automate

Documentation

Quickstart Guide

PHP Code

node.js Code

Ruby Code

Python Code

Java Code

C# Code

API Base URL

Starting Jobs

Create job request

Request Body

Example Response

cURL Command

Example Response

PHP Code

node.js Code

Ruby Code

Python Code

Java Code

C# Code

Wait for job completion

Wait for job request

Example Response

cURL Command

Example Response

PHP Code

node.js Code

Ruby Code

Python Code

Java Code

C# Code

Download output files

Download file

cURL download command

PHP Code

node.js Code

Ruby Code

Python Code

Java Code

C# Code