The CloudConvert REST API offers you great possibilites to convert files in the same way as you can do on the CloudConvert website. Therefore you need your personal API Key, which can be showed in your profile. For more intensive use and/or if you would like us to extend the API please feel free to contact us.

Implementation Examples

Coding Language Description Source / Documentation Author
PHP Sample implementaion for client side and server side conversions GitHub CloudConvert
node.js Non-blocking API for CloudConvert GitHub Wildhoney
Ruby Ruby wrapper for CloudConvert GitHub pandurang90
Python Python API wrapper for CloudConvert GitHub gcq
.NET CloudConvert API .NET Wrapper GitHub MadScripter

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.

POST https://api.cloudconvert.org/process
{
    "apikey": "API Key",
    "inputformat": "flv",
    "outputformat": "mp4"
}
Parameter Description
inputformat Current format of the file. (Required)
outputformat Output format, to which the file should be converted. (Required)
apikey Your personal API Key. Alternatively you can use the X-CloudConvert-ApiKey header. (Required)

All options can be sent as JSON body (as shown above). Alternatively you can also send the options as URL paramaters (?inputformat=flv&outputformat=mp4&apikey=).

A response could look like this:

{
    "url": "https://srv01.cloudconvert.org/process/v4cw72hf3"
}              

In this case, v4cw72hf3 is your Process ID. Now you can use the provided URL to upload the file, to check the status of the conversion and afterwards to download the converted file.

There are different possibilites of providing the input file for the conersion:

  • CloudConvert downloads the input file from a URL
  • Upload the input file using an POST multipart/form-data upload
  • Using S3 as input/output storage

Downloading the input file from a URL

Therefore you need to do a POST request, providing your conversion options, to the obtained Process URL.

POST https://srv01.cloudconvert.org/process/v4cw72hf3
{
    input: "download",
    file: "http://public.url/to/my/file.ext",
    filename: "file.ext",
    outputformat: "mp3",
    options: {
        "audio_bitrate": "128",
        "audio_normalize": "+20db"   
    }
}
Parameter Description
input Set it to download. (Required)
file Provide the URL of the input file. (Required)
outputformat Output format, to which the file should be converted to. (Required)
filename Sets the input filename including extension (file.ext). If not set, CloudConvert will try to detect the filename from the URL. (Optional)
size Sets the size of the input file in bytes. This is used for checking the progress of the download. (Optional)
email Can be set to '1' for email notification after the conversion is finished. (Optional)
output Storage for the output file. Can be set to dropbox, googledrive or S3. (Optional)
callback Provide a callback URL for notification when the conversion is finished. (Optional)
options[...] Conversion type specific options (Optional)

Now your file is processing and you can regularly check the status.

Alternative: Uploading the input file

The second possibility is to upload the input file directly from the clients browser. CORS and Flash crossdomain uploading is both supported.

The following options should be sent as POST multipart/form-data.

Parameter Description
input Input type, set it to upload. (Required)
file POST Field containing the input file to convert. (Required)
outputformat Output format, to which the file should be converted to. (Required)

A simple HTML form which converts any file to MP3 with 128kbits and +20db audio normalization could look like this:

<form action="https://srv01.cloudconvert.org/process/v4cw72hf3" method="POST" enctype="multipart/form-data">
<input type="hidden" name="input" value="upload">
<input type="hidden" name="outputformat" value="mp3">
<input type="hidden" name="options[audio_bitrate]" value="128">
<input type="hidden" name="options[audio_normalize]" value="+20db">
<input type="file" name="file">
<input type="submit">
</form>

Just do a GET request to the process URL:

GET https://srv01.cloudconvert.org/process/v4cw72hf3
{
    "id": "v4cw72hf3",
    "url": "https://srv01.cloudconvert.org/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"
        },
        "duration": 341.25
    },
}
            
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 actucal 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.
finished We are done!

If the conversion is complete, step is set to finished and the output section will be available. The output file can be downloaded using output.url

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

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": "https://srv01.cloudconvert.org/download/dnpmItJ2",
        "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 (e.g. in this case: https://srv01.cloudconvert.org/download/dnpmItJ2/multiple_pages-1.jpg)

You can cancel a running conversion by requesting process url/cancel :

GET https://srv01.cloudconvert.org/process/v4cw72hf3/cancel

A finished (or aborted) conversion can be deleted with calling process url/delete . 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.

GET https://srv01.cloudconvert.org/process/v4cw72hf3/delete

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.

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

GET https://api.cloudconvert.org/processes?apikey= API Key
[
    {
        "id": "v4cw72hf3",
        "host": "srv01.cloudconvert.org",
        "step": "finished",
        "starttime": "2013-01-07 23:03:53",
        "endtime": "2013-01-07 23:04:02",
        "url": "https://srv01.cloudconvert.org/process/v4cw72hf3"
    }
]
            

Calling /conversiontypes will return all possible conversion types and possible options. Both parameters inputformat and outputformat are optional.

GET https://api.cloudconvert.org/conversiontypes?inputformat= mp4 &outputformat= mp3
[
    {
        "inputformat": "mp4",
        "outputformat": "mp3",
        "converter": "ffmpeg",
        "converteroptions": {
            "audio_codec": "MP3",
            "audio_bitrate": "128",
            "audio_channels": null,
            "audio_frequency": null,
            "trim_from": null,
            "trim_to": null,
            "audio_normalize": null
        }
    }
]
            

converteroptions shows all possible options and their default values for this conversion. These options can be specified at the start of a conversion.

It is possible to use Amazon S3 as storage both for input and output of conversions. Therefore we recommend for security reasons to create a seperate accessKey / secretKey pair with limited rights. For downloading files CloudConvert needs the s3:GetObject permission, for uploading the s3:PutObject permission.

The following example shows how to start such a conversion:

POST https://srv01.cloudconvert.org/process/v4cw72hf3
{
    input: {
        s3 : {
            accesskeyid: "my_accessKeyId",
            secretaccesskey: "my_secretAccessKey",
            bucket: "some.bucket.name"
        }
    },
    file: "file.png",
    outputformat: "pdf",
    output: {
        s3 : {
            accesskeyid: "my_accessKeyId",
            secretaccesskey: "my_secretAccessKey",
            bucket: "some.bucket.name"
        }
    },
}
Parameter Description
input/output.s3.accesskeyid The Amazon S3 accessKeyId. It is possible to use different S3 access keys / buckets for input and output. (Required)
input/output.s3.secretaccesskey The Amazon S3 secretAccessKey. (Required)
input/output.s3.bucket The Amazon S3 bucket where to download the input file or upload the output file. (Required)
input/output.s3.region Specify the Amazon S3 endpoint, e.g. us-west-2 or eu-west-1. As default us-east-1 will be used. (Optional)
file S3 key of the input file (normally the filename, including path). (Required)
filename Sets the input filename including extension (file.ext). If not set, CloudConvert will try to detect the filename from the key. (Optional)
output.s3.key S3 key for storing the output file. If not set the key will be choosen automatically (filename.outformat). (Optional)