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.

Official Wrappers

If you have issues with one of our wrappers please open an issue on the GitHub project page. Of course, feel free to improve and modify them.

Coding Language Source / Documentation
PHP GitHub
node.js GitHub
Python GitHub
Swift GitHub

Third Party Wrappers

Please note that these wrappers are not created by us and we can not fully support them. If you have issues with them just open an issue on their GitHub project page. Please let us know if you created a new wrapper, we gladly would like to list it here.

Coding Language Description Source / Documentation Author
PHP/Laravel A Laravel wrapper for the CloudConvert API. GitHub Robbie Paul
node.js Non-blocking API for CloudConvert GitHub Wildhoney
Java Jersey-client based implementation of the CloudConvert API GitHub aioobe
Ruby A ruby wrapper for the CloudConvert API GitHub edwinv710
Ruby Another Ruby wrapper for CloudConvert GitHub pandurang90
Python Python API wrapper for CloudConvert GitHub gcq
Go CloudConvert Go client package GitHub tgulacsi
.NET CloudConvert API .NET Wrapper GitHub aliencube
.NET Another CloudConvert API .NET Wrapper GitHub MadScripter
Perl Perl command line client GitHub Jakob Voß
R R package to convert file format using CloudConvert API GitHub Mukul Chaware

Interactive Examples

The following interactive examples can give you a quick overview how the CloudConvert API works. You can adjust these examples easily to your specific use case. Also, have a look at our API console, which generates ready-to-use code snippets.

SVG to PNG Rasterize a vector SVG to a PNG image. Can be adapted to any other conversion type easily.
Video conversion Get codec information and a thumbnail about an existing MP4 file; convert it to different resolutions.
Website to PNG Get a website screenshot as PNG.
Merge PDFs Combine two PDFs to one PDF.

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
Content-Type: application/json

{
    "apikey": "API Key",
    "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.

POST https://api.cloudconvert.com/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 Authorization: Bearer header. (Required)

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.

POST https://srv01.cloudconvert.com/process/v4cw72hf3
{
    input: "download",
    file: "http://public.url/to/my/file.ext",
    filename: "file.ext",
    outputformat: "mp3",
    converteroptions: {
        "audio_bitrate": "128",
        "audio_normalize": "+20db"
    }
}
Input Parameters
input * Method of providing the input file. Set it to download, upload, s3, ftp, raw or base64. (Required)
file * Provide the URL of the input file. (Required)
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. (Required)
converteroptions[...] Conversion type specific options. Possible 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)
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 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 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. Checkout the API Console, which is using this API. This method is not recommend if you upload huge files or if the conversion process may take a longer time.

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 with two different upload methods:

Simple Upload

To use simple upload, 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.'
}

Multipart Upload

In this case a POST request must be 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"
        },
        "duration": 341.25
    },
}
            

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 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. 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 (e.g. in this case: https://srv01.cloudconvert.com/download/~us2tvnBpfE/multiple_pages-1.jpg)

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.

DELETE https://srv01.cloudconvert.com/process/v4cw72hf3

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

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 not available via public URL, please consider to make your input files available to CloudConvert via signed URLs.
    2. Provide a callback URL. 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).
  • The second best practice comes hand in hand with the first one: Don't relay on certain conversion time. We do put a lot of effort to provide fast and reliable conversions. Most our conversions are done within seconds. Nevertheless, there might be the case that your usually fast conversions takes longer: If files are transferred through networks congestions comes into play, which we sometimes cannot influence. Also, even in the times of cloud computing, it might happen that we have to queue your request until our infrastructure has been scaled. Thus your application design should not relay on a certain time. If your conversions are user-initiated you should always let your users know what exactly is going on and provide them progress information, if possible.
  • 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. When our infrastructure detects such high load it might need some time to scale and to handle this. 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.

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.

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

GET https://api.cloudconvert.com/processes?apikey= 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"
    }
]
            

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

GET https://api.cloudconvert.com/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. To find out possible values please use the API Console.

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. If you set a ACL different from "private" for the output file for you will need the s3:PutObjectAcl permission.

The following example shows how to start such a conversion:

POST https://srv01.cloudconvert.com/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.sessiontoken Auth using AWS Security Token Service. Optional additional to accessKeyId/secretAccessKey. (Optional)
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)
output.s3.path Filename (S3 key), including path, for the output file. If this value ends with "/" the output file is stored in the corresponding directory. (Optional)
output.s3.acl S3 ACL for storing the output file. Possible values include: private, public-read, public-read-write, authenticated-read, bucket-owner-read, bucket-owner-full-control. (Default: private, Optional)

You can use any FTP server as storage both for input and output of conversions. Therefore we recommend for security reasons to create a seperate user / password login to your FTP server with limited rights.

The following example shows how to start such a conversion:

POST https://srv01.cloudconvert.com/process/v4cw72hf3
{
    input: {
        ftp : {
            host: "someftp.host",
            user: "my_user_name",
            password: "my_password"
        }
    },
    file: "file.doc",
    outputformat: "jpg",
    output: {
        ftp : {
            host: "someftp.host",
            user: "my_user_name",
            password: "my_password"
        }
    },
}
Parameter Description
input/output.ftp.host * The FTP server host. (Required)
input/output.ftp.port The port the FTP server is bind to. (Optional, Default: 21)
input/output.ftp.user * FTP username. (Required)
input/output.ftp.password * FTP password. (Required)
file * Filename, including path, of the input file. (Required)
output.ftp.path Filename, including path, for the output file. If not set the key will be choosen automatically (filename.outformat). If this value ends with "/" the output file is stored in the corresponding directory. (Optional)