File Conversions API

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 found 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:

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.

API Versioning

The current API version 1 is both available via the /v1 prefix or no prefix at all. For clarity we recommend using the API endpoints including the /v1 prefix. The upcoming API version 2 will use the /v2 prefix.

In the past our documentation did not use the /v1 prefix. Thus, using no prefix will always point to API v1, even if we switch to API v2 as the primary version. After releasing API v2, API v1 will be supported for at least two more years.

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.

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
}

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.

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

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.

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.

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.

Content-Length: 98344

... JPEG data ...

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

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

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

{
    "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"
        }
    },
}
            

A conversion can pass through the following steps:

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.

{
    "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:

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:

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:

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