For using the CloudConvert API you need your personal API Key, which can be showed in your profile. For API support please feel free to contact us.

Official Wrappers

If you have problems 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
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 problems 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 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ß

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.

SVG to PNG Rasterize a vector SVG to a PNG image.
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, you have multiple possibilites to transmit the parameters:

  • Format the parameters as JSON request body. The Content-Type request header must be set to application/json.
  • Format the parameters as form urlencoded key/value pairs. The Content-Type request header should be multipart/form-data. This is the way browsers encode POSTs (submitted through forms) by default.
  • Append the parameters to the request URL (e.g. ?inputformat=flv&outputformat=mp4&apikey=...). This can be mixed with the two other methods.

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 * Set it to download, upload, s3 or ftp. (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 (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

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 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 * Set it to upload. (Required)
file * POST Field containing the input file to convert. (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.com/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="converteroptions[audio_bitrate]" value="128">
<input type="hidden" name="converteroptions[audio_normalize]" value="+20db">
<input type="file" name="file">
<input type="submit">
</form>

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

Just do a GET request to the process URL:

GET https://srv01.cloudconvert.com/process/v4cw72hf3
{
    "id": "v4cw72hf3",
    "url": "https://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
    },
}
            
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/v4cw72hf3",
        "downloads": 0
    },
    "endtime": 1357588279
}
            

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

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/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.com/download/dnpmItJ2/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.
Please note: The process URLs are only for one-time use. To restart the conversion you need to create a new process URL.

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.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": "https://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.

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