CloudConvertdocs
Getting Started

Quickstart Guide

Typical implementation flow of the CloudConvert API

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 below.

Starting Jobs

Below 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.

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

Wait for job completion

We recommend using webhooks to get notified when a job completes. Alternatively, you can use the synchronous API endpoint GET /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);

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.

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

Introduction

Welcome to the CloudConvert API

Jobs

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