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.
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.
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.
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 }
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.
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) |
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) |
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) |
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:
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
.
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:
{ "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.
{ "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.
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:
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:
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 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. |
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