How to use our API to convert media files directly

Welcome to the community of online-convert.com. We have developed a set of free APIs to allow developers direct access to our conversion methods.

Intended audience

Using the API might be interesting for you if you want to:

• convert files regularly
• outsource the conversion process to our beefy server farm to speed up conversion time
• integrate a conversion service on your website

Requirements

Although the service is free to use, some requirements apply:

• You need to register for free to receive your personal API-key
• You need to put a logo of online-convert.com on your website and link it to http://www.online-convert.com/

Getting started: Obtain your personal API key

After you have registered and confirmed your email address, you can extract the API key from the confirmation email we have send you. The following example will give you an API key starting with 2e31...

Create an XML request

To insert a conversion request in the queue of our servers, you need to send an XML request to the following address: http://api.online-convert.com/queue-insert

You have two options to send us the data you want to have converted. You can send us either a URL of a file we will then download and convert or you can send us the file data directly within the XML request.
The following XML request is an example with a file to convert specified by an URL:

				
<?xml version="1.0" encoding="utf-8" ?>
<queue>
  <apiKey>2e3152........03258494237510e6</apiKey>
  <targetType>image</targetType>
  <targetMethod>convert-to-jpg</targetMethod>
  <testMode>true</testMode>
  <sourceUrl>http://www.online-convert.com/images/image-converter.png</sourceUrl>
  <notificationUrl>http://www.example.com/notifyme.php</notificationUrl>
</queue>

				

<apiKey>: Copy your personal API key here.
<targetType>: The target type of the conversion process (e.g. image, video, ...). Details below.
<targetMethod>: The target method of the conversion process (e.g. convert-to-mp3, convert-to-mp4, ...)
<testMode>: Set to true during development and the conversions will not count, but truncated to 10 seconds. In production: false
<sourceUrl>: Provide here the full URL where we can download the file without access restrictions. Please remember to encode the URL to obtain a valid XML file, in PHP you can use urlencode()
<notificationUrl>: Provide here the full URL that should be called when the conversion process finishes. It will send you a POST request with all parameters in the POST variable called "queue-answer" about the status of the queue as explained here and it can be used to trigger a script on your server.

To obtain the targetType and the targetMethod for your XML file, go to the converter on our website you want to use and look at the URL. From there you can extract the two values you need from the URL. The subdomain is the targetType and the HTML file name is the targetMethod:

If you do not want to send us an URL and instead choose the option to send us the file within the XML request, you can download an example here. When you insert your API key in this file, you should already be able to get a XML response from our servers. Test: Which women is it? ;-) Note: The <fileData> needs to be base64 encoded.

Here is a list of all XML options available when using our API file converter.

How to send us your XML file

When you have changed all the parameters in the XML file based on your needs, you can send the XML file to our servers to start a conversion. Don't worry if something is wrong with your XML, we have detailed error responses for you to help you along.

With the following PHP example (JAVA and other languages support this as well), you can send an XML file to our server for testing and you will receive an XML response. When developing you normally will create the XML data dynamically by a script and send it directly without saving it to an extra XML file.

				
<?php
$ch = curl_init("http://api.online-convert.com/queue-insert");
$request["queue"] = file_get_contents("/path_to_my_xml_file/my_xml_file.xml");
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
$response = curl_exec($ch);
curl_close ($ch);
echo $response;
?>
				

Note: It is important that the data is sent via POST inside the POST variable named "queue". In other words, the XML must be sent like a form variable named queue.

The XML response

After you have sent your request via XML to our servers, we insert the conversion into a queue and process the file as soon as possible. If your XML has been crafted correctly, the XML response looks like this:

				
<?xml version="1.0" encoding="utf-8"?>
<queue-answer>
  <status>
    <code>0</code>
    <message>Successfully inserted job into queue.</message>
  </status>
  <params>
    <downloadUrl>http://www.online-convert.com/result/07d6c1491bb5929acd71c531122d2906</downloadUrl>
    <hash>07d6c1491bb5929acd71c531122d2906</hash>
  </params>
</queue-answer>
				
				

To read and process the XML file and if you are using PHP, you can use the PHP function simplexml. Of course, other programming languages like JAVA also provide functions to read an XML file easily.

If you got a successful response from our server, you can use the URL in <downloadUrl> to redirect your users to download the file. If you don't want to redirect your user to our website, the next chapter is waiting for you.

Possible return codes of the XML response

'0' => 'Successfully inserted job into queue'
'1' => 'No API key or invalid API key given.'
'2' => 'Source URL and file data given. Please specify only one.'
'3' => 'No valid target conversion selected. Please check targetType and targetMethod.'
'4' => 'Could not insert queue to database. Please verify your parameters.'
'5' => 'Conversion limit of conversions per 24h reached. Used conversions used: '
'6' => 'XML structure invalid. Please check.'
'7' => 'Could not save file on server.'
'8' => 'The XML file is empty'
'9' => 'Too many concurrent requests'

Advanced: Retrieve status of conversion process and direct download URL

If you choose to not redirect your users to our website and prefer to receive the converted file directly, we have created another XML request at the URL: http://api.online-convert.com/queue-status

With this request, you can check the status of the conversion process regularely (e.g. queued, processing, error, ...). If the conversion has been completed successfully, you will receive a special crafted download link where you can download the converted file directly to your machine. Please note that the minimum amount of time between calling this script again for the same file to retrieve the status must be at least 10 seconds.

Example XML request to receive the status of a conversion process:

				
<?xml version="1.0" encoding="utf-8" ?>
<queue>
  <apiKey>2e3152........03258494237510e6</apiKey>
  <hash>07d6c1491bb5929acd71c531122d2906</hash>
</queue>

				

<hash>: The unique hash you received from the response when inserting a job into the queue.

The answer looks like this:

				
<?xml version="1.0" encoding="utf-8"?>
<queue-answer>
  <status>
    <code>100</code>
    <message>The file has been successfully converted.</message>
  </status>
  <params>
    <downloadCounter>2</downloadCounter>
    <dateProcessed>1262110552</dateProcessed>
    <directDownload>http://www.online-convert.com/download-file/<unique_id></directDownload>
    <checksum>679e4138e0769191d7a4eb44e9165b95</checksum>
    <target_size>6308</target_size>
    <convert_to>jpg</convert_to>
    <mime_type>image/jpg</mime_type>
    <hash>c6c81eceeb4e64b6b9810b6d93920200</hash>
  </params>
</queue-answer>

				

<downloadCounter>: Number of download of this file
<dateProcessed>: The date in unixtime when the file has been finished processing
<directDownload>: The link to directly download the file from our servers
<checksum>: The MD5 checksum of the file to verify correct download to your server
<target_size>: The file size of the converted file in Kilobyte (KB)
<convert_to>: The file extension of the target file
<mime_type>: The mime type of the target file
<hash>: The hash identification string of the file

Possible return codes when retrieving the status of a conversion process

'100' => 'The file has been successfully converted.'
'101' => 'The file is waiting in the queue for being processed.'
'102' => 'The file is currently downloading from the source URL.'
'103' => 'The file is waiting in the queue to be downloaded.'
'104' => 'The file is currently being processed.'
'105' => 'The file has not been converted due to errors.'
'106' => 'Hash not valid.'

Limitations

To avoid abuse of our free API service and to provide high availability to all users, some limitations apply.

• Maximum conversions within 24 hours: 30
• Maximum upload size per file: 100 Megabyte
• Maximum 10 downloads per file within one day. After one day, the converted file is deleted.
• You are allowed to only use one API-key per website/project/company/individual

If you want to use our file converter API without limitations, please contact us. We have very competitive prices. The premium services can not be used for extending the API.

Further help

If you are stuck and need help, please don't hesitate to contact us. Also if you need features we currently do not offer or if you want to convert more than our limits allow. We are sure that we are the conversion business you need.