Getting Started

Quickstart Guide

A typical implementation flow for the CloudConvert API

Quickstart Guide

This guide walks you through a typical implementation of the CloudConvert API. It covers creating a job, waiting for it to finish, and handling the result. Use this quickstart guide as an entry point. For more in-depth documentation, use the menu on the left to jump directly to a specific topic.

You can find example requests and SDK code examples below.

Starting Jobs

The following example shows how to create a typical job. It downloads a file from a URL (import/url operation), converts the file to PDF, and creates a download URL for the converted file (export/url operation).

If you are using a storage provider such as S3, Azure, Google Cloud, or OpenStack, we recommend using the corresponding import and export operations. CloudConvert can fetch files from your storage and store converted files there.

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

Raw HTTP Request

POSThttps://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": [
      ...
    ]
  }
}

SDK Examples

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

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

// npm install --save cloudconvert

import CloudConvert from 'cloudconvert';

const cloudConvert = new CloudConvert('API_KEY');

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

# pip install cloudconvert

import cloudconvert

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

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'
        }
    }
})

# Add to your Gemfile: gem "cloudconvert"

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

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

import com.cloudconvert.client.CloudConvertClient;
import com.cloudconvert.client.setttings.StringSettingsProvider;
import com.cloudconvert.dto.request.JobRequest;
import com.cloudconvert.dto.request.TaskRequest;
import com.cloudconvert.dto.request.ConvertFilesTaskRequest;
import com.cloudconvert.dto.request.UrlImportRequest;
import com.cloudconvert.dto.request.UrlExportRequest;
import com.cloudconvert.dto.response.JobResponse;
import com.google.common.collect.ImmutableMap;

final CloudConvertClient cloudConvertClient =
    new CloudConvertClient(new StringSettingsProvider("API_KEY", "WEBHOOK_SIGNING_SECRET"));

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

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

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

Waiting for Job Completion

We recommend using webhooks to be notified when a job completes. Alternatively, you can use the synchronous API endpointGET /v2/jobs/{id} to wait for job completion.

Raw HTTP Request

GEThttps://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"
            }
          ]
        }
      }
    ]
  }
}

SDK Examples

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

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

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

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

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

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

Downloading Output Files

This example uses the export/url operation to generate a download URL for the output file. You can find this URL in the response from the /jobs/{ID} status endpoint or in the body of the webhook payload. Add the ?redirect=true query parameter to the status endpoint to be redirected to the export URL. Export URLs are valid for only 24 hours.

If you are using an export method such as S3 or Azure, you do not need to manually download the output files.

Raw HTTP Request

GEThttps://api.cloudconvert.com/v2/jobs/6559c281-ed85-4728-80db-414561c631e9?redirect=true

SDK Examples

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

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

stream_copy_to_stream($source, $dest);

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

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

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

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

file = export_task.result.files.first

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

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

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

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

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

Introduction

Welcome to the CloudConvert API

Jobs

Create, list, show, wait for and delete jobs.