This documentation provides a detailed step-by-step guide on how to do conversions using the CloudConvert API. For using the CloudConvert API you need your personal API Key, which can be showed on your dashboard. For API support please feel free to contact us.

Formatting Requests

The CloudConvert API follows the basic standards for REST APIs. All requestes and responses are UTF8 encoded JSON.

For doing POST requests to the API the requests have to be formatted as shown:

POST https://api.cloudconvert.com/process
Authorization: Bearer API_KEY
Content-Type: application/json

{
    "inputformat": "flv",
    "outputformat": "mp4"
}

It is also possible to append any of the parameters to the request URL (e.g. ?inputformat=flv&outputformat=mp4&apikey=...). This can be mixed with providing parameters in the JSON body.

In order to start a new conversion you need to create a new Process ID first. Each Process ID is for one-time use only and can only be used for converting one file.

Parameter Description
inputformat * Current format of the file. (Required)
outputformat * Output format, to which the file should be converted. (Required)
mode The mode of the process. Defaults to convert. Other possible values are info, combine, archive and extract. (Optional)

A response could look like this:

{
    "url": "//srv01.cloudconvert.com/process/v4cw72hf3"
    "id": "v4cw72hf3",
    "host": "srv01.cloudconvert.com",
    "expires": "2014-09-12 13:13:00",
    "maxtime": 18000,
    "minutes": 264
}

In this case, srv01.cloudconvert.com/process/v4cw72hf3 is your Process URL. Now you can use the provided URL to upload the file, to check the status of the conversion and to download the converted file.

To get the actual conversion started, you need to do a POST request to the obtained Process URL.

Input Parameters
input * Method of providing the input file. Set it to download, upload, raw, base64, s3, openstack, azure, googlecloud or ftp. (Required)
file * Provide the the input file. This value depends on the input method (see below). (Required)
files Array of files, if you want to provide multiple input files. This value depends on the input method. (Optional)
filename Override the input filename including extension (file.ext). If not set, we will try to detect the filename. (Optional)
tag Custom tag for you to identify the conversion. Can also be an object. Does not have any effect. (Optional)
Conversion Parameters
outputformat * Output format, to which the file should be converted to. Needs to be set to the same value as in the create process request. (Required)
converteroptions[...] Object of conversion type specific options. Possible keys and values can be obtained using the API Console. (Optional)
preset The ID of one of your presets. You can load your predefined converter options here. (Optional)
mode The mode of the process. Defaults to convert. Other possible values are info, combine, archive and extract. Needs to be set to the same value as in the create process request. (Optional)
timeout Timeout in seconds after the conversion will be cancelled. As default your account wide timeout will be used (5h for paid accounts). (Optional)
Output Parameters
email Can be set to true for email notification after the conversion is finished. (Optional)
output Storage for the output file. Can be set to dropbox, googledrive, s3, openstack, azure, googlecloud or ftp. (Optional)
callback Provide a callback URL for notification when the conversion is finished. (Optional)
wait If set to true the request blocks until the conversion is finished. (Optional)
download If set to true the request blocks until the output file is available and will then start the download immediately. Can be set to inline for displaying the output file in browser (instead of offering the download). (Optional)
save If set to true the conversion files will be saved on CloudConvert. Otherwise all files will be deleted immediately after the first download. This option is useful if you want to convert the same file multiple times. (Optional)

Now your file is processing and you can check the status and/or download the output file.

Input method: Download

This is the recommended way of providing the input file. Why? Because asynchronous! (see our best practices).

Parameter Description
input * Set it to download. (Required)
file * Provide the full URL (including http://) of the input file. (Required)

Input method: Upload

The second possibility is to upload the input file with a separate request. This makes the API response to this request an unique upload.url. Check the section on how to do file uploads which explains how to use this URL. The conversion will start as soon as you have uploaded the input file.

Parameter Description
input * Set it to upload. (Required)

Input method: Raw / Base64

This method is only recommend if the input files are relatively small and/or only available as strings, not saved to disk.

Parameter Description
input * Set it to raw respectively base64. (Required)
file * Provide the content (respectively the base64 encoded content) of the input file. (Required)
filename * Set the input filename including extension (file.ext). (Required)

Shortcut: The convert API

The /convert API endpoint does the first two steps (creating a Process ID and starting the Process) with just one API call. Therefore just send all the parameters combined to the /convert endpoint. The /convert endpoint will first create and start a process with your given parameters and afterwards redirect you using a 303 redirect to the Process URL (or, alternatively, if you have set the download parameter, to the output file). Checkout the API Console, which is using this API.

If the parameter input was set to upload when starting the converison, an unique upload.url will be returned by the request:

{
    "id": "v4cw72hf3",
    "url": "//srv01.cloudconvert.com/process/v4cw72hf3",
    "message": "Waiting for the upload of input files",
    "step": "input",
    "upload": {
        "url": "//srv01.cloudconvert.com/upload/~Gl47wdgf6"
    }
}

The provided upload.url can be used for providing the input file.


To upload the input file, make a PUT request to the upload.url and append the input filename (including file extension), for example:

PUT https://srv01.cloudconvert.com/upload/~Gl47wdgf6/inputfile.jpg
Content-Length: 98344

... JPEG data ...

If the request succeeds, the server returns the HTTP 200 OK status code along with some metadata:

{
    'file': 'inputfile.jpg',
    'size': 98344,
    'message': 'File saved.'
}

Alternatively you can make a POST request formatted as multipart/form-data. The field of the file should be named file.

POST https://srv01.cloudconvert.com/upload/~Gl47wdgf6
Content-Type: multipart/form-data; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Disposition: file; filename="inputfile.jpg"
Content-Size: 98344
Content-Type: application/octet-stream

... JPEG data ...

The multipart upload method is the way browsers encode POSTs (submitted through forms) by default. The upload.url is an unique URL which does not allow to gain any information about the actual conversion. Thus you can provide a form to your end users and allow them to directly upload their files to CloudConvert:

<form action="//srv01.cloudconvert.com/upload/~Gl47wdgf6" method="POST" enctype="multipart/form-data">
<input type="file" name="file">
<input type="submit">
</form>

Just do a GET request to the process URL:

GET https://srv01.cloudconvert.com/process/v4cw72hf3
{
    "id": "v4cw72hf3",
    "url": "//srv01.cloudconvert.com/process/v4cw72hf3",
    "percent": 55.12,
    "message": "Converting to mp4...",
    "step": "convert",
    "starttime": 1357588277,
    "expire": 1357595479,
    "input": {
        "type": "upload",
        "filename": "Cloud Atlas Extended Trailer #1 (2012) HD.flv",
        "size": 14558739,
        "name": "Cloud Atlas Extended Trailer #1 (2012) HD",
        "ext": "flv"
    },
    "converter": {
        "format": "mp4",
        "type": "ffmpeg",
        "options": {
            "audio_codec": "FLAC"
        }
    },
}
            

By appending ?wait to the process URL, the request will block until the conversion is finished (or failed with an error).

A conversion can pass through the following steps:

Step Description
input Input file is downloaded, e.g. from a URL or S3 storage.
wait Conversion has to wait for some reason. Happens only in very special cases.
convert The actual conversion takes place.
output The output file is uploaded, e.g. to S3, Google Drive or Dropbox.
error Something went wrong. message contains an error description. See here how to handle error.
finished We are done!

The output file can be downloaded using output.url. The converted file is available as soon as step is set to finished.

It is also possible to start the download via output.url if the conversion was just started and is not finished. In this case, the request blocks until the output file is available and will then start the download immediately.

GET https://srv01.cloudconvert.com/process/v4cw72hf3
{
    "id": "v4cw72hf3",
    [...]
    "output": {
        "filename": "Cloud Atlas Extended Trailer #1 (2012) HD.mp4",
        "ext": "mp4",
        "size": 10920297,
        "url": "//srv01.cloudconvert.com/download/~ugl5vnrpfO",
        "downloads": 0
    },
    "endtime": 1357588279
}
            

You can append the ?inline parameter to the output.url if you want to display the output file in browser (instead of offering a download).

Please note that as default all output files are automatically deleted after the first download. This means the output URL does only work once. To prevent this, use the save parameter when starting the converison. If the conversion was started with the save parameter, the download links are valid up to 24h.

Multiple output files

In some cases it might be possible that there are multiple output files (e.g. converting a multi-page PDF to JPG):

{
    "id": "dnpmItJ2",
    [...]
    "output": {
        "filename": "multiple_pages.zip",
        "ext": "zip",
        "files": [
            "multiple_pages-1.jpg",
            "multiple_pages-2.jpg",
            "multiple_pages-3.jpg",
            "multiple_pages-4.jpg",
        ],
        "size": 10920297,
        "url": "//srv01.cloudconvert.com/download/~us2tvnBpfE",
        "downloads": 0
    },
    "endtime": 1357588279
}
            

Calling output.url will offer you a ZIP file, which contains all output files. If you would like to get the output files individual, you can use output.url/file.ext

A finished (or aborted) conversion can be deleted with calling a request with the HTTP verb DELETE on the process URL. This will delete all files of the conversion immediately and irreversible from our servers. If the conversion is still running, it will first cancel it and afterwards delete it.

By providing a callback URL when starting the conversion, it is possible to get notified when the conversion is finished. When the conversion completed (or ended with an error), we will do the following GET request:

GET callback url?id=....&url=...
Parameter Description
id Process ID of the finished conversion
url Process URL. You should call this URL for detailed information, like the download URL of the output file.
step This can be either finished or error.

If the request fails (network error) or your server returns with HTTP error >=500, we will retry to request the callback url up to 5 times with 5 seconds in between. The callback URL will only be used for the current conversion. If you would like to get notified of the status of all of your conversions, have a look on our Hooks API.

You can list all running, finished and failed proccesses, which were started with your API Key:

GET https://api.cloudconvert.com/processes
Authorization: Bearer API_KEY
[
    {
        "id": "v4cw72hf3",
        "host": "srv01.cloudconvert.com",
        "step": "finished",
        "starttime": "2013-01-07 23:03:53",
        "endtime": "2013-01-07 23:04:02",
        "url": "//srv01.cloudconvert.com/process/v4cw72hf3"
    }
]

There are a few best practices you should consider when using our API:

  • The first one is the most important one: Make your implementation asynchronous! CloudConvert was designed from ground up to be used asynchronous. It is not a good idea to block your application by a file conversion and/or uploads/downloads of files to/from CloudConvert. To achieve complete asynchronous behavior do the implementation as described:
    1. Use the input metod download. By letting CloudConvert pull the input file from your server via an URL you don't need to block your implementation by a long-lasting upload request. Even if your files are not available via public URL, please consider to make your input files available to CloudConvert via signed URLs.
    2. Provide a callback URL or use a hook. There is no need to constantly pull the status of a conversion. We will notify you when we are done.
    3. If you are converting huge files, consider to let CloudConvert do task of storing the output file (e.g. by providing FTP or S3 access).
  • Even if our infrastructure was designed that it can handle peak load, you should avoid huge batch requests. In case of a huge batch request our system might have to queue your requests in order to protect our infrastructure and other users. This queuing is user-wise and makes sure other users are not affected. The bottom line is that you should avoid to bundle your API requests (for example cronjob initiated requests). Instead do the requests constantly and on-demand.

Handling errors

The CloudConver API responses with standard HTTP status codes (e.g. 404 for a not found process or 401 for unauthorized requests). If a conversion fails, the status code can be one of the following:

Status Code Description
400 The conversion failed because some parameters are missing or wrong.
422 The conversion failed because of a conversion error. Most likely the input file is corrupt or some parameters are wrong. message contains the error description.
503 The conversion failed because there is currently no conversion host available or the conversion host had an internal error. In this case a Retry-After header is available, which recommends the delay in seconds to restart the conversion (See below).
Please note: The process URLs are only for one-time use. To restart the conversion you need to create a new process URL.

Throttling

In certain cases, CloudConvert needs to throttle requests to make sure that individuals and apps do not adversely affect the experience of other users. In such cases the API responses with error code 503 or 429 and the Retry-After header with the number of seconds your app should wait before sending more requests. In the event that 503 or 429 errors are received, an exponential backoff algorithm is recommended.

HTTP/1.1 429 Too Many Requests
Retry-After: 30