API developer ressource

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 file conversion process to our beefy server farm to speed up conversion time
  • integrate a file conversion service on your website, app or extension

Requirements

Although the service is free to use in the basic version, 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/
  • Some limitations apply in the free API version but can be lifted when using our paid professional API usage package. Please ask for a quote.

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...
Extracting the API key from confirmation email

Workflow


Further options:

Sending an XML reqest with a link to download the source file from the web

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

In this XML request you give us all the necessary information to convert your file.
The following XML request is an example with an URL that points to the file you want to convert:
					
<?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 you must set it to 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. The URL needs also to be encoded to create a valid XML file.
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:
Extracting the targetType from URL
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_HTTPHEADER, array("Content-type: multipart/form-data"));
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'
'10' => 'Parameter targetType and/or targetMethod is missing.',
'11' => 'Token not valid or has already been used.',
'12' => 'File must directly be sent to a server using the pattern http://www[integer].online-convert.com/queue-insert',
				

Advanced: Sending an XML reqest with the source file data embedded base64 encoded

Instead of sending us a link to your file you want to have converted, you can append 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.
Important: You need to send the upload request to a server as explained here.

Advanced: Sending a multipart POST request with the source file data included

As explained in the above section, you can directly upload your file to our servers within the XML request. Using base64 encoding to transfer the file correctly bloats the file size of the request by a third (by base64 design). Therefore we created the option to send us a multipart POST request with the file attached as it would be send when using an HTML form on a website. Here is an example of the XML request:
					
<?xml version="1.0" encoding="utf-8" ?>
<queue>
<apiKey>2e3152........03258494237510e6</apiKey>
<targetType>image</targetType>
  <targetMethod>convert-to-jpg</targetMethod>
  <testMode>true</testMode>
</queue>

				
Here is an example of the PHP code used to send a valid XML request using the multipart/form-data method:
					
<?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");
$request["file"] = "@/path_to_my_source_file/test.jpg";
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-type: multipart/form-data"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
$response = curl_exec($ch);
curl_close ($ch);
echo $response;
?>
				
Important: You need to send the upload request to a server as explained here.

Hint: Beginning with PHP 5.5, please use the following line to define your file for upload:
					
$request["file"] = new \CurlFile("/path_to_my_source_file/test.jpg");     

                                

Retrieve the status of a conversion process

If you choose to not redirect your users to our website using the link you got by the XML queue-insert request 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 regularly (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>

				
You can also use the token you have retrieved from the request-token functionality and used for conversion to get the status instead of the API key:
					
<?xml version="1.0" encoding="utf-8" ?>
<queue>
  <token>66af31aa1e27f18938e10500c8c5a13c</token>
  <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.'
				

Delete a file instantly after it has been converted and downloaded

We currently offer the ability to delete the converted file via XML request. This is usefull if you have downloaded the converted file and do not want to have it available on our servers for 24 hours. The request needs to be sent to http://api.online-convert.com/queue-manager

Example XML request to delete the converted file after conversion:
					
<?xml version="1.0" encoding="utf-8" ?>
<queue>
  <apiKey>2e3152........03258494237510e6</apiKey>
  <hash>07d6c1491bb5929acd71c531122d2906</hash>
  <method>deleteFile</method>
</queue>

				
<hash>: The unique hash you received from the response when inserting a job into the queue.
<method>: The method of the manager you want to call, in this case deleteFile.

The answer looks like this:
					
<?xml version="1.0" encoding="utf-8"?>
<queue-answer>
  <status>
    <code>300</code>
    <message>The file has been successfully deleted.</message>
  </status>
  <params>
    <dateProcessed>1262110552</dateProcessed>
    <hash>07d6c1491bb5929acd71c531122d2906</hash>
  </params>
</queue-answer>

				
<dateProcessed>: The date in unixtime when the file has been finished processing.
<hash>: The hash identification string of the file.

Possible return codes when managing the queue

'300' => 'The file has been successfully deleted.',
'301' => 'The file has not been deleted.',
'302' => 'Invalid method called.'
				

Advanced: Get the fastest conversion server when uploading a file

If you upload a file within the XML request instead of providing a download URL where we can download the file you want to convert, you need to call this XML method before uploading the file. It will do some load balancing and provide you with the server that has currently the most free queues and is therefore the fastest to convert your file. Here is an example XML request to http://api.online-convert.com/get-queue :
					
<?xml version="1.0" encoding="utf-8"?>
<queue>
	<apiKey>2e3152........03258494237510e6</apiKey>
	<targetType>audio</targetType>
</queue>

				
The answer looks like this:
					
<?xml version="1.0" encoding="utf-8"?>
<queue-answer>
  <status>
    <code>200</code>
    <message>Found free slot on server.</message>
  </status>
  <params>
    <server>http://www18.online-convert.com</server>
  </params>
</queue-answer>

				
Extracting the server from the <server> field will give you the current fastest server. You only need to add '/queue-insert' to the URL and are ready to send the file within the XML request to our server.

Note: Please do not call this method if you provide us with a link to download your source file. In this case we are able to automatically detect the fastest server for you.

Advanced: Create a one time token for your user to convert a file

Your API key should never be given to any of your users, neither manually nor embedded in an app or extension. The user would be able to extract your key and convert files that will be charged to you. If you have an application where your users send you the file and you then send us an XML request providing a download link pointing to your server, your user will never get your API key.

However, sometimes you might want to upload a file to us and use our API directly from the device of your customer. In order to not give the API key away to someone else, you can generate a conversion token. With this one time conversion token, you can generate a valid XML request to convert a file.

  1. Your application on the device of your user requests a token from your server.
  2. Your server appends your API key and requests a one time conversion token from us.
  3. Your server sends this conversion token to your customer.
  4. Your application on the device of your user creates a valid XML request to our server using the one time conversion voucher.

You need to send your token request to http://api.online-convert.com/request-token Here is an example XML request:
					
<?xml version="1.0" encoding="utf-8"?>
<queue>
	<apiKey>2e3152........03258494237510e6</apiKey>
</queue>

				
The answer looks like this:
					
<?xml version="1.0" encoding="utf-8"?>
  <status>
    <code>400</code>
    <message>Successfully created conversion token.</message>
  </status>
  <params>
    <token>cde0ae0f3ccd750ef651901db021fe25</token>
    <server>http://www18.online-convert.com</server>
  </params>

				
The server that has been returned is the current fastest server to convert your file and should be used to send your XML request to us using the queue-insert method.

You can use the following code to convert a file with a one time voucher from your users device. Note that you need to add either a download URL or upload the file within the XML request as described above.
					
<?xml version="1.0" encoding="utf-8" ?>
<queue>
<token>cde0ae0f3ccd750ef651901db021fe25</token>
<targetType>image</targetType>
  <targetMethod>convert-to-jpg</targetMethod>
  <testMode>true</testMode>
  <notificationUrl>http://www.example.com/notifyme.php</notificationUrl>
</queue>

				

More source code examples

We have set up a github repository with source code examples using this API for Bash, .NET, Java, PHP, Python, Ruby and node.js. Please feel free to use them. If you find errors or have enhanced the code, we would be very happy for your pull requests.

Limitations for free usage

Our API is available in two flavours, a free version and a paid version for professional use. To avoid abuse of our free API service and to provide high availability to all users, some limitations apply.
  • Maximum free 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 the limitations mentioned above, please contact us. We have very competitive prices and you pay by the amount of conversions only. In addition, you will be able to send your XML requests and get your downloads encrypted via HTTPS. The premium services can not be used for extending the API usage.

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.