API developer resource

Convert files using our converter API

Welcome to the API area of online-convert.com. We have developed a public REST API to allow developers direct access to our conversion methods. It provides easy access to all conversion functionalities available at online-convert.com. Please feel free to contact us with all kinds of comments you may have, feature requests, questions and when help is needed. We are constantly improving our services.

This is the documentation of version 2 of our API. If you need information about version 1 (deprecated), click here.

Intended audience

Using the API might be interesting for you if you want to:
  • integrate a file conversion service on your website, app or extension
  • convert files regularly
  • outsource the file conversion process to our fast server farm to speed up conversion time

Requirements

Our API is available in two flavours: a free version and a paid version for professional use. For both types you need a personal API key. Please register for free to obtain this key. After you have confirmed your email address, you will see your API key on the subscription page.

Go up

Definitions

The conversions are performed through conversion jobs. These jobs need the following information:

  • One or more input files. It can be a singe file or a list of files you want to convert.
  • One or more conversion definitions to specify the target file formats. It is possible to specify several conversion here, to create for example videos with different quality settings from one input. There you can define settings like the screen size as well.

After you have defined all parameters and started the conversion job, the API generates one or more output objects. They contain information and links to the converted files.

Go up

Introduction

The calls to the API are made through different URLs and methods.

Endpoints

The API is accessed using SSL (recommended) or without SSL:
https://api2.online-convert.com | http://api2.online-convert.com

This is the API schema URL:
https://api2.online-convert.com/schema

The schema defines the API. The whole documentation will follow the definitions given in this schema.

The schema follows the Swagger 2.0 specification.

The API uses a REST architecture for interaction. That means that every single URI represents a different object in the API and the actions requested through the HTTP methods.

The current methods allowed to interact with the API are:

  • GET: Gathers information of the object. It will not, by any means, modify data on the server.
  • POST: Creates new elements in the API. Used to create the different objects in the API.
  • PATCH: Modifies an existing element in the API.
  • DELETE: Removes existing elements via API.

Go up

Get to know our API with Postman

We are making heavy use of an application called "Postman" to test and execute API calls manually. You can download it here. Of course there is no need to use Postman when accessing our API. It is just a convenient tool for testing and debugging API calls.

We also provide a collection and an environment that can be used within Postman so you can quick start testing our API.

Go up

Video tutorials

We have created a set of video tutorials to help you quick start creating your own application.

Go up

Quick start: Convert one file to another format

In order to create a simple conversion of a file located at an external URL, the following request is made.

POST /jobs HTTP/1.1
Host: https://api2.online-convert.com
X-Oc-Api-Key: <your API key here>
Content-Type: application/json
{
    "input": [{
        "type": "remote",
        "source": "http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg"
    }],
    "conversion": [{
        "target": "png"
    }]
}
curl \
    -H "X-Oc-Api-Key: <your API key here>" \
    -H "Content-Type: application/json" \
    -X POST \
    -v \
    -d "{\"input\": [{\"type\":\"remote\",\"source\":\"http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg\"}],\"conversion\":[{\"target\": \"png\"}]}" \
     https://api2.online-convert.com/jobs
<?php
    $endpoint = 'https://api2.online-convert.com/jobs';
    $apikey = '<your API key here>;
    $debug = TRUE;

    $json_resquest = '{
        "input": [{
            "type": "remote",
            "source": "http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg"
         }],
        "conversion": [{
            "target": "png"
         }]
    }';

    // No need to change parameters below this line.

    $ch = curl_init($endpoint);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $json_resquest);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'X-Oc-Api-Key: '.$apikey,
        'Content-Type: application/json',
        'cache-control: no-cache'
    ));
    if ($debug) {
        curl_setopt($ch, CURLOPT_HEADER, TRUE);
        curl_setopt($ch, CURLINFO_HEADER_OUT, TRUE);
    }

    $response = curl_exec($ch);
    $info = curl_getinfo($ch);
    $error =  curl_error($ch);
    curl_close($ch);
    if ($debug) {
        var_dump($info);
    }
    echo $response."\n";
    if (!empty($error)) {
        echo $error;
    }
?>

require 'uri'
require 'net/http'

url = URI("http://api2.online-convert.com/jobs")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["x-oc-api-key"] = '<your API key here>'
request["content-type"] = 'application/json'
request["cache-control"] = 'no-cache'
request.body = "{\"input\":[{\"type\":\"remote\",\"source\":\"http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg\"}],\"conversion\":[{\"category\":\"image\",\"target\":\"png\"}]}"

response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"input\":[{\"type\":\"remote\",\"source\":\"http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg\"}],\"conversion\":[{\"category\":\"image\",\"target\":\"png\"}]}");
Request request = new Request.Builder()
    .url("http://api2.online-convert.com/jobs")
    .post(body)
    .addHeader("x-oc-api-key", "<your API key here>")
    .addHeader("cache-control", "no-cache")
    .build();

Response response = client.newCall(request).execute();

import requests

url = "http://api2.online-convert.com/jobs"

payload = "{\"input\":[{\"type\":\"remote\",\"source\":\"http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg\"}],\"conversion\":[{\"category\":\"image\",\"target\":\"png\"}]}"
headers = {
    'x-oc-api-key': "<your API key here>",
    'content-type': "application/json",
    'cache-control': "no-cache"
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

var client = new RestClient("http://api2.online-convert.com/jobs");
var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("x-oc-api-key", "<your API key here>");
request.AddParameter("application/json", "{\"input\":[{\"type\":\"remote\",\"source\":\"http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg\"}],\"conversion\":[{\"category\":\"image\",\"target\":\"png\"}]}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

var http = require("http");

var options = {
    "method": "POST",
    "hostname": "api2.online-convert.com",
    "port": null,
    "path": "/jobs",
    "headers": {
        "x-oc-api-key": "<your API key here>",
        "content-type": "application/json",
        "cache-control": "no-cache"
    }
};

var req = http.request(options, function (res) {
    var chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function () {
        var body = Buffer.concat(chunks);
        console.log(body.toString());
    });
});

req.write(JSON.stringify({ input: [ { type: 'remote', source: 'http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg' } ],
conversion: [ { category: 'image', target: 'png' } ] }));
req.end();

var data = JSON.stringify({
    "input": [
        {
            "type": "remote",
            "source": "http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg"
        }
    ],
    "conversion": [
        {
            "category": "image",
            "target": "png"
        }
    ]
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
    if (this.readyState === 4) {
        console.log(this.responseText);
    }
});

xhr.open("POST", "http://api2.online-convert.com/jobs");
xhr.setRequestHeader("x-oc-api-key", "<your API key here>");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("cache-control", "no-cache");

xhr.send(data);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "http://api2.online-convert.com/jobs");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "cache-control: no-cache");
headers = curl_slist_append(headers, "content-type: application/json");
headers = curl_slist_append(headers, "x-oc-api-key: <your API key here>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\"input\":[{\"type\":\"remote\",\"source\":\"http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg\"}],\"conversion\":[{\"category\":\"image\",\"target\":\"png\"}]}");

CURLcode ret = curl_easy_perform(hnd);

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "http://api2.online-convert.com/jobs"

    payload := strings.NewReader("{\"input\":[{\"type\":\"remote\",\"source\":\"http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg\"}],\"conversion\":[{\"category\":\"image\",\"target\":\"png\"}]}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("x-oc-api-key", "<your API key here>")
    req.Header.Add("content-type", "application/json")
    req.Header.Add("cache-control", "no-cache")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

import Foundation

let headers = [
    "x-oc-api-key": "<your API key here>",
    "content-type": "application/json",
    "cache-control": "no-cache"
]
let parameters = [
    "input": [
        [
            "type": "remote",
            "source": "http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg"
        ]
    ],
    "conversion": [
        [
            "category": "image",
            "target": "png"
        ]
    ]
]

let postData = NSJSONSerialization.dataWithJSONObject(parameters, options: nil, error: nil)

var request = NSMutableURLRequest(URL: NSURL(string: "http://api2.online-convert.com/jobs")!,
cachePolicy: .UseProtocolCachePolicy,
timeoutInterval: 10.0)
request.HTTPMethod = "POST"
request.allHTTPHeaderFields = headers
request.HTTPBody = postData

let session = NSURLSession.sharedSession()
let dataTask = session.dataTaskWithRequest(request, completionHandler: { (data, response, error) -> Void in
    if (error != nil) {
        println(error)
    } else {
        let httpResponse = response as? NSHTTPURLResponse
        println(httpResponse)
    }
})

dataTask.resume()

The only required elements to start the conversion are input and conversion. Take into account that both input and conversion field are an array of objects.

The API will respond with a 201 status code and the content of the newly created job. The information missing in the request will be populated with default values.

{
    "id": "407c9fcd-1b36-11e5-8f2b-002590da1f50",
    "token": "52b099c5d8e127278280873343add213",
    "type": "job",
    "status": {
        "code": "completed",
        "info": "The file has been successfully converted."
    },
    "process": true,
    "conversion": [{
        "id": "407ced1d-1b36-11e5-8f2b-002590da1f50",
        "category": "image",
        "target": "png",
        "options": []
    }],
    "input": [{
        "id": "407cd2df-1b36-11e5-8f2b-002590da1f50",
        "type": "remote",
        "source": "http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg",
        "filename": "example_small.jpg",
        "size": 0,
        "created_at": "2017-03-25T14:32:32",
        "modified_at": "2017-03-25T14:32:32"
    }],
    "output": [{
        "id": "142de18d-1a4b-11e5-8f2b-002590da1f50",
        "source": {
            "conversion": "407ced1d-1b36-11e5-8f2b-002590da1f50",
            "input": [
                "407cd2df-1b36-11e5-8f2b-002590da1f50"
            ]
        },
        "uri": "https://www30.online-convert.com/dl/web1/download-file/142de18d-1a4b-11e5-8f2b-002590da1f50/example_small.png",
        "size": 364,
        "created_at": "2017-03-25T14:33:06",
        "status": "enabled",
        "content_type": "image/png",
        "downloads_counter": 0,
        "checksum": "d77971e8628bd71013f37866783d7942"
    }],
    "callback": "",
    "server": "https://www7.online-convert.com/dl/web1",
    "created_at": "2017-03-25T14:32:32",
    "modified_at": "2017-03-25T14:32:32"
}

To obtain the download link of the converted file, you can also have a look at obtain conversion details.

A detailed Howto has been written to show you step by step on how you can convert a file using the API.

Go up

Setting conversion options

Options like audio channels and bit depth can be set in the following way:

POST /jobs HTTP/1.1
Host: https://api2.online-convert.com
X-Oc-Api-Key: <your API key here>
Content-Type: application/json
{
    "conversion": [{
        "target": "wav",
        "category": "audio",
        "options": {
            "download_password": null,
            "frequency": 8000,
            "channels": "mono",
            "normalize": false,
            "pcm_format": "pcm_f32le"
        }
    }],
    "input": [{
        "type": "remote",
        "source": "http://www.example.com/test.mp3"
    }]
}

To obtain the available formats and all available options, just call the following URL (example for WAV, replace GET parameter):
https://api2.online-convert.com/conversions?target=wav

You can beautify the JSON code of the conversions settings by using this JSON beautifier.

Extended example for converting files

As specified in the API conversion job description, none of the fields for a job are mandatory. This way, a job can be created just by an empty request. This creates a basic skeleton and allows to add missing source files, options, and target file formats later.

POST /jobs HTTP/1.1
Host: https://api2.online-convert.com
X-Oc-Api-Key: <your API key here>
Content-Type: application/json

{
}

Many of the fields will be automatically filled, but without setting the input and conversion, the job can not be processed.

The API will respond with a 201 status code and the skeleton of the newly created job. The information missing in the request will be populated with the default values.

{
    "id": "407c9fcd-1b36-11e5-8f2b-002590da1f50",
    "token": "52b099c5d8e127278280873343add213",
    "type": "job",
    "status": {
        "code": "incomplete",
        "info": "Missing information to run the job."
    },
    "process": true,
    "conversion": [],
    "input": [],
    "output": [],
    "callback": "",
    "notify_status": false,
    "server": "https://www7.online-convert.com/dl/web1",
    "spent": 0,
    "created_at": "2017-03-25T14:32:32",
    "modified_at": "2017-03-25T14:32:32"
}

Both input and conversion arrays are empty, hence the status is set to incomplete, meaning that there is missing information before the job can be processed.

In order to complete and process the job, the missing information must be added to the corresponding sub entities.

Specifying the source files

Adding a new source file is done by a POST call to the input at the job endpoint.

POST /jobs/407c9fcd-1b36-11e5-8f2b-002590da1f50/input HTTP/1.1
Host: https://api2.online-convert.com
X-Oc-Api-Key: <your API key here>
Content-Type: application/json
{
    "type": "remote",
    "source": "http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg"
}

This will create an input (the file you want to convert) for the previously created job:

{
    "id": "407cd2df-1b36-11e5-8f2b-002590da1f50",
    "type": "remote",
    "source": "http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg",
    "filename": "example_small.jpg",
    "size": 0,
    "created_at": "2017-03-25T14:32:32",
    "modified_at": "2017-03-25T14:32:32"
}

We can now request the information about the job through a GET request to the job object.

GET /jobs/407c9fcd-1b36-11e5-8f2b-002590da1f50 HTTP/1.1
Host: https://api2.online-convert.com
X-Oc-Api-Key: <your API key here>
Content-Type: application/json
    

The recently created input is now shown in the job. The status is still incomplete since there is no conversion (the target file format) set for the job.

{
    "id": "407c9fcd-1b36-11e5-8f2b-002590da1f50",
    "token": "52b099c5d8e127278280873343add213",
    "type": "job",
    "status": {
        "code": "incomplete",
        "info": "Missing information to run the job."
    },
    "process": true,
    "conversion": [],
    "input": [{
        "id": "407cd2df-1b36-11e5-8f2b-002590da1f50",
        "type": "remote",
        "source": "http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg",
        "filename": "example_small.jpg",
        "size": 0,
        "created_at": "2017-03-25T14:32:32",
        "modified_at": "2017-03-25T14:32:32"
    }],
    "callback": "",
    "server": "https://www7.online-convert.com/dl/web1",
    "created_at": "2017-03-25T14:32:32",
    "modified_at": "2017-03-25T14:32:32"
                    }

Source of type "input_id"

You can also specify an input of type "input_id" so you can use an input file from a previous conversion again. This way you can for example avoid uploading twice. This is only possible if you created the job the "input_id" is taken from.

For example from the previous information about the job you take the Input Id "407cd2df-1b36-11e5-8f2b-002590da1f50" from this section:

{
    "input": [{
        "id": "407cd2df-1b36-11e5-8f2b-002590da1f50",
        "type": "remote",
        "source": "http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg",
        "filename": "example_small.jpg",
        "size": 0,
        "created_at": "2017-03-25T14:32:32",
        "modified_at": "2017-03-25T14:32:32"
    }]
}

Adding a new source file of type "input_id" is done by a POST call to the input at the job endpoint.

POST /jobs/edcfb0a3-980b-47da-8648-345f2611d676/input HTTP/1.1
Host: https://api2.online-convert.com
X-Oc-Api-Key: <your API key here>
Content-Type: application/json
{
    "type": "input_id",
    "source": "407cd2df-1b36-11e5-8f2b-002590da1f50"
}

Source of type "gdrive_picker"

Google drive picker allows you to access files stored in your google drive account. You can find information about it in the official page.

Adding a new source file of type "gdrive_picker" is done by a POST call to the input at the job endpoint.

POST /jobs/407c9fcd-1b36-11e5-8f2b-002590da1f50/input HTTP/1.1
Host: https://api2.online-convert.com
X-Oc-Api-Key: <your API key here>
Content-Type: application/json
{
    "type": "gdrive_picker",
    "source": "put google drive picker file id here",
    "credentials": {
        "token": "put google drive picker token for the selected file here"
    },
    "content_type": "if this is a specific google document",
    "filename": "name of the input file"
}

Meaning of each field:

  • type:
    • Specifies that we want to use the google drive picker input
  • source:
    • This must contain the "FILE ID" given back by the google drive picker
  • credentials:
    • This must be an array containing the credentials for the selected file
    • At the moment you only need to pass the "token" field inside it
    • The "token" field is returned by the google drive picker when a file is selected
  • content_type:
    • This field is mandatory when you select a Google Document
    • You can leave this field empty if you are selecting any other kind of file (e.g. pdf, png, zip...)
  • filename:
    • This is the file name of the google drive picker file
    • If this field is not sent the file will be downloaded with the name `output.`

Base64 as input

It is also possible to send us a base64 encoded input source. To do this send a POST request to the following endpoint. At first you have to create a job and get the "server" from the answer to use it as the Host to send the following call to.

"Content" is the base64 encoded data. "Filename" is optional. If not specified you get a file like "output.png".

POST /upload-base64/407c9fcd-1b36-11e5-8f2b-002590da1f50/ HTTP/1.1
Host: https://www4.online-convert.com/dl/web1
X-Oc-Api-Key: <your API key here>
Content-Type: application/json
{
    "content": "data:text/plain;base64,dGVzdCBzdHJpbmc=",
    "filename": "testFilename"
}

Adding a conversion

Adding a conversion implies to POST a conversion to the job endpoint.

POST /jobs/407c9fcd-1b36-11e5-8f2b-002590da1f50/conversions HTTP/1.1
Host: https://api2.online-convert.com
X-Oc-Api-Key: <your API key here>
Content-Type: application/json
{
    "target": "png"
}

This will create an input to the previously created job and set the target file format:

{
    "id": "407ced1d-1b36-11e5-8f2b-002590da1f50",
    "category": "image",
    "target": "png",
    "options": []
}

We can now request the information about the job through a GET request again to check that the conversion has been added.

GET /jobs/407c9fcd-1b36-11e5-8f2b-002590da1f50? HTTP/1.1
X-Oc-Api-Key: <your API key here>
Host: https://api2.online-convert.com
Content-Type: application/json
    

Then, the recently created information will be shown in the job and the status will be moved to queued since all required information is present.

{
    "id": "407c9fcd-1b36-11e5-8f2b-002590da1f50",
    "token": "52b099c5d8e127278280873343add213",
    "type": "job",
    "status": {
        "code": "queued",
        "info": "The file is waiting in the queue for being processed."
    },
    "process": true,
    "conversion": [{
        "id": "407ced1d-1b36-11e5-8f2b-002590da1f50",
        "category": "image",
        "target": "png",
        "options": []
    }],
    "input": [{
        "id": "407cd2df-1b36-11e5-8f2b-002590da1f50",
        "type": "remote",
        "source": "http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg",
        "filename": "example_small.jpg",
        "size": 0,
        "hash": "573c1aef67f08f31c191913e70e8a2d0",
        "checksum": "573c1aef67f08f31c191913e70e8a2d0",
        "content_type": "image/jpeg",
        "created_at": "2017-03-25T14:32:32",
        "modified_at": "2017-03-25T14:32:32"
    }],
    "output": [],
    "callback": "",
    "notify_status": false,
    "server": "http://www7.online-convert.com/dl/web1",
    "spent": 0,
    "created_at": "2017-03-25T14:32:32",
    "modified_at": "2017-03-25T14:32:32"
}

After you have submitted all required information, the conversion is automatically started. To avoid this and to add more parameters or more conversions, set "process" to false once you create the job skeleton.

Go up

Uploading files

When completing a job with the input information required for the conversion, you may want to upload the file directly to the server, instead of providing a download link where the API get's the file to convert.

In the following example, we will create a job with all the information except for the input.

POST https://api2.online-convert.com/jobs HTTP/1.1
Content-Type: application/json
X-Oc-Api-Key: <your API key here>

{
    "conversion": [{
        "target": "pdf"
    }]
}

We will obtain an incomplete job missing the input file information:

{
    "id": "407c9fcd-1b36-11e5-8f2b-002590da1f50",
    "token": "d1ad18eace9e778058facb23985988f4",
    "type": "job",
    "status": {
        "code": "incomplete",
        "info": "Missing information to run the job."
    },
    "process": true,
    "conversion": [{
        "id": "09f62043-39ac-11e5-9484-448a5bd44b34",
        "target": "pdf",
        "category": "document",
        "options": {
            "ocr": null,
            "language": null
        }
    }],
    "input": [],
    "output": [],
    "callback": "",
    "notify_status": false,
    "server": "https://www4.online-convert.com/dl/web1",
    "spent": 0,
    "created_at": "2017-03-03T08:51:16",
    "modified_at": "2017-03-03T08:51:16"
}

Now, instead of sending the information about where to download the file, we will upload the file directly to the server.

The created job already has a server assigned, which is defined in the server value in the job information. We can now POST the file to the given server using the job ID and token for identification.

Please note that, even if not mandatory, it is highly recommended to set a unique id for each input that you send. This can prevent conversion problems in some corner cases. You don't need to send a full UUID compliant string https://en.wikipedia.org/wiki/Universally_unique_identifier. A unique numeric index can be enough.

POST https://www4.online-convert.com/upload-file/407c9fcd-1b36-11e5-8f2b-002590da1f50 HTTP/1.1
X-Oc-Token: d1ad18eace9e778058facb23985988f4
X-Oc-Upload-Uuid: 682edbbc-d261-42ef-a40b-92c24eb1d4ab

------WebKitFormBoundaryePkpFF7tjBAqx29L
Content-Disposition: form-data; name="file"; filename="myfile.png"
Content-Type: image/png

... contents of file goes here ...
------WebKitFormBoundaryePkpFF7tjBAqx29L-

This request will create a new input to the job of the upload type.

{
    "id":"0a3ef31a-39ac-11e5-9484-448a5bd44b34",
    "type":"upload",
    "source":"dd330e0c12353458c2deaced8cff5c44",
    "filename": "myfile.png",
    "size":77550,
    "hash": "573c1aef67f08f31c191913e70e8a2d0",
    "checksum": "573c1aef67f08f31c191913e70e8a2d0",
    "content_type": "image/png",
    "created_at":"2017-03-03T08:51:17",
    "modified_at":"2017-03-03T08:51:17"
}

With this new input, the job is complete and will be processed. This is the information we get about the job:

GET https://api2.online-convert.com/jobs/407c9fcd-1b36-11e5-8f2b-002590da1f50 HTTP/1.1
X-Oc-Token: d1ad18eace9e778058facb23985988f4

We will obtain the full information for the completed job.

{
    "id": "407c9fcd-1b36-11e5-8f2b-002590da1f50",
    "token": "d1ad18eace9e778058facb23985988f4",
    "type": "job",
    "status": {
        "code": "complete",
        "info": "The file has been successfully converted."
    },
    "process": true,
    "conversion": [{
        "id": "09f62043-39ac-11e5-9484-448a5bd44b34",
        "target": "pdf",
        "category": "document",
        "options": {
            "ocr": null,
            "language": null
        }
    }],
    "input": [{
            "id": "0a3ef31a-39ac-11e5-9484-448a5bd44b34",
            "type": "upload",
            "source": "dd330e0c12353458c2deaced8cff5c44",
            "filename": "myfile.png"
            "size": 77550,
            "hash": "573c1aef67f08f31c191913e70e8a2d0",
            "checksum": "573c1aef67f08f31c191913e70e8a2d0",
            "content_type": "image/jpeg",
            "created_at": "2017-03-03T08:51:17",
            "modified_at": "2017-03-03T08:51:17"
        }],
    "output": [{
        "id": "142de18d-1a4b-11e5-8f2b-002590da1f50",
        "source": {
            "conversion": "09f62043-39ac-11e5-9484-448a5bd44b34",
            "input": [
                "0a3ef31a-39ac-11e5-9484-448a5bd44b34"
            ]
        },
        "uri": "https://www30.online-convert.com/dl/web1/download-file/142de18d-1a4b-11e5-8f2b-002590da1f50/myfile.pdf",
        "size": 364,
        "created_at": "2017-03-24T10:29:06",
        "status": "enabled",
        "content_type": "image/png",
        "downloads_counter": 0,
        "checksum": "d77971e8628bd71013f37866783d7942"
    }],
    "callback": "",
    "server": "https://www4.online-convert.com/dl/web1",
    "created_at": "2017-03-03T08:51:16",
    "modified_at": "2017-03-03T08:51:16"
}

Chunked Upload

It is also possible to do a chunked upload to our system. To do this simply post the chunks to the same URL as described above. Besides the x-oc-token you have to send the following headers with every chunk.
  • x-oc-upload-uuid
    • Use your uniquely generated identifier here. Can be any string, even a numeric index, but have to be unique.
  • Content-Range
    • The content range of the current chunk in this format: start-end/total.
    • E.g. "Content-Range:bytes 0-1048575/5230812" for the first 1MB chunk of an approximately 5MB file.

Cloud Storage

You can use different options for cloud storage integration, you can find them listed below.

Amazon S3

To let our servers download files directly from your Amazon S3 storage you need to follow these instructions:

  • Grant the following permissions to your bucket:
    • s3:GetObject
      • Used to download a file.
    • s3:PutObject
      • Used to store a file. (supported soon)
    • s3:PutObjectAcl
      • Used to grant different Access Control List (ACL) when storing a file. (supported soon)
  • Take a look at the following example on how to send a job with an Amazon S3 input:
                            POST /jobs HTTP/1.1
    Host: https://api2.online-convert.com
    X-Oc-Api-Key: 
    Content-Type: application/json
    
    {
      "conversion": [
        {
          "target": "png"
        }
      ],
      "input": [
        {
          "type": "cloud",
          "source": "amazons3",
          "parameters": {
            "bucket": "your.bucket.name",
            "file": "the complete path to the file"
          },
          "credentials": {
            "accesskeyid": "your access key id",
            "secretaccesskey": "your secret access key"
          }
        }
      ]
    }
                        
Field Description Required Default
input.type Specifies the type of the input, for cloud storage it has to be cloud. Yes Auto
input.source Tells our servers which cloud storage provider we must contact, in this case has to be amazons3. Yes Auto
input.parameters.bucket Determines from which bucket our servers will get the file. Yes Auto
input.parameters.region Indicates the region configured for your bucket, list of Amazon S3 region names can be found here
If you don't specify this field and your bucket is configured to use another region, any download will fail.
No eu-central-1
input.parameters.file Amazon S3 key of the object to download, usually looks like a normal file path E.G. pictures/mountains.jpg. Yes Auto
input.credentials.accesskeyid The Amazon S3 access key id. Yes Auto
input.credentials.secretaccesskey The Amazon S3 secret access key. Yes Auto
input.credentials.sessiontoken Used together with secretaccesskey and accesskeyid to authenticate with temporary credentials.
For more information on how to generate temporary credentials please check how to install AWS CLI tool and doing a call to AWS STS get-session-token.
No Auto

Conversion Results

Using the GET method for the job, we can get information at any time about the status of the conversion.

GET /jobs/407c9fcd-1b36-11e5-8f2b-002590da1f50 HTTP/1.1
Host: https://api2.online-convert.com
X-Oc-Api-Key: <your API key here>
Content-Type: application/json
    

The information about the process is in the status field. When the conversion is finished, the status will change to completed. Also the output is present in the answer.

{
    "id": "407c9fcd-1b36-11e5-8f2b-002590da1f50",
    "token": "52b099c5d8e127278280873343add213",
    "type": "job",
    "status": {
        "code": "completed",
        "info": "The file has been successfully converted."
    },
    "process": true,
    "conversion": [{
        "id": "407ced1d-1b36-11e5-8f2b-002590da1f50",
        "category": "image",
        "target": "png",
        "options": []
    }],
    "input": [{
        "id": "407cd2df-1b36-11e5-8f2b-002590da1f50",
        "type": "remote",
        "source": "http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg",
        "filename": "example_small.jpg",
        "size": 0,
        "created_at": "2017-03-25T14:32:32",
        "modified_at": "2017-03-25T14:32:32"
    }],
    "output": [{
        "id": "142de18d-1a4b-11e5-8f2b-002590da1f50",
        "source": {
            "conversion": "407ced1d-1b36-11e5-8f2b-002590da1f50",
            "input": [
                "407cd2df-1b36-11e5-8f2b-002590da1f50"
            ]
        },
        "uri": "https://www30.online-convert.com/dl/web1/download-file/142de18d-1a4b-11e5-8f2b-002590da1f50/example_small.png",
        "size": 364,
        "created_at": "2017-03-25T14:33:06",
        "status": "enabled",
        "content_type": "image/png",
        "downloads_counter": 0,
        "checksum": "d77971e8628bd71013f37866783d7942"
    }],
    "callback": "",
    "server": "https://www7.online-convert.com/dl/web1",
    "created_at": "2017-03-25T14:32:32",
    "modified_at": "2017-03-25T14:32:32"
}

For successfully completed jobs, we can obtain the result of the conversion by accessing the output objects array at the proper endpoint.

GET /jobs/407c9fcd-1b36-11e5-8f2b-002590da1f50/output HTTP/1.1
Host: https://api2.online-convert.com
X-Oc-Api-Key: <your API key here>
Content-Type: application/json
    

This will return a list for all the output files of the conversion. At the moment the output will contain only one file but it may contain more than one in certain cases.

[
    {
    "id": "142de18d-1a4b-11e5-8f2b-002590da1f50",
    "source": {
        "conversion": "11c3d829-1a4b-11e5-8f2b-002590da1f50",
        "input": [
            "0bcc113a-1a4b-11e5-8f2b-002590da1f50"
        ]
    },
    "uri": "https://www30.online-convert.com/dl/web1/download-file/142de18d-1a4b-11e5-8f2b-002590da1f50/example_small.png",
    "size": 364,
    "created_at": "2017-03-24T10:29:06",
    "status": "enabled",
    "content_type": "image/png",
    "downloads_counter": 0,
    "checksum": "d77971e8628bd71013f37866783d7942"
    }
]

A conversion may take some time and the converted file will not be available instantly. You can either set a "callback" in the job and provide a URL the API will call once the conversion has been finished. Or you poll the job every 5 seconds or so to get an updated status.

If you set the optional flag "notify_status" to true you get a call to the specified callback URL for every status update of the job.

Objects

The objects are the representation of the different elements that can be accessed via the API.

Job

The job object is the most important one in the API and represents a conversion being made, to be made, or made using online-convert.com

https://api2.online-convert.com/jobs
{
    "id": "000cfeba-1a4b-11e5-8f2b-002590da1f50",
    "token": "b377d7df8e7a5f5de91dd5add2666aa4",
    "type": "job",
    "status": {
        "code": "completed",
        "info": "The file has been successfully converted."
    },
    "errors": [],
    "process": true,
    "conversion": [...],
    "input": [....],
    "output": [...],
    "callback": "http://callback.url",
    "notify_status": false,
    "server": "https://www18.online-convert.com/dl/web1",
    "spent": 0,
    "created_at": "2017-03-24T10:28:33",
    "modified_at": "2017-03-24T10:29:06"
}

The required fields are only required, when the job is created via POST. They are not required when modifying a job.

When a field is not provided, a default value will be used. Those fields which value is set to auto, will be set automatically by the server.

Field Description Required Default
id Unique identifier for the job. No Auto
token Unique token that provides authentication for modifying the job. No Auto
type Type of job. Currently the only allowed value is 'job'. No Auto
status Status of the object will contain one of the status available for a job. No Auto
errors Errors that happened while downloading or converting No Auto
process Flag to determine if the job must be started or not. No True
conversion An array of conversions used for the job. No null
input An array of input used for the job. No null
output An array of outputs made by the job. No Auto
callback Callback url for the status updates. No null
notify_status If set to true, a callback will be sent for each job status change. No false
server Url for the server for uploading a file you want to convert. No Auto
spent Conversion minutes spent to complete the job. No Auto
created_at Date when the job was created. No Auto
modified_at Date when the job was last modified No Auto

Input

The input object belongs to a job and defines the file that will be converted through the job conversion. The file you want to convert is called the source file.

https://api2.online-convert.com/jobs/[job_id]/input
{
    "id": "0bcc113a-1a4b-11e5-8f2b-002590da1f50",
    "type": "remote",
    "source": "http://static.online-convert.com/example-file/raster%20image/jpg/example_small.jpg",
    "filename": "example_small.jpg",
    "size": 0,
    "hash": "573c1aef67f08f31c191913e70e8a2d0",
    "checksum": "573c1aef67f08f31c191913e70e8a2d0",
    "content_type": "image/jpeg",
    "created_at": "2017-03-24T10:28:52",
    "modified_at": "2017-03-24T10:29:02"
}
Field Description Required Default
id Unique identifier for the input file. No Auto
type Type of the input can be either "remote", "upload", "input_id", "gdrive_picker". No Auto
source URL where the file has to be downloaded, the Input Id from a previous conversion, data from the Google drive picker. Yes  
filename The filename of the file. No Auto
hash (deprecated, use checksum instead) File hash for content verification. No Auto
checksum Hash for content verification. No Auto
content_type Content type for file conversion definition. No Auto
size File size. No Auto
created_at Date when the input was created. No Auto
modified_at Date when the input was last modified. No Auto

Conversion

The conversion object belongs to a job and defines the conversion type that must be applied to the input files.

https://api2.online-convert.com/jobs/[job_id]/conversions
{
    "id": "11c3d829-1a4b-11e5-8f2b-002590da1f50",
    "category": "image",
    "target": "png",
    "options": []
}
Field Description Required Default
id Unique identifier for the conversion. No Auto
category Category for the conversion. No Auto
target Target format of the converted file. Yes  
options List of allowed options for the given target. No {}

Output

The output object belongs to a job and contains the information of the generated files after the conversion.

https://api2.online-convert.com/jobs/[job_id]/output
 {
    "id": "142de18d-1a4b-11e5-8f2b-002590da1f50",
    "source": {
        "conversion": "11c3d829-1a4b-11e5-8f2b-002590da1f50",
        "input": [
            "0bcc113a-1a4b-11e5-8f2b-002590da1f50"
        ]
    },
    "uri": "https://www30.online-convert.com/dl/web1/download-file/142de18d-1a4b-11e5-8f2b-002590da1f50/example_small.png",
    "size": 36443747,
    "status": "enabled",
    "content_type": "image/png",
    "downloads_counter": 0,
    "checksum": "d77971e8628bd71013f37866783d7942",
    "created_at": "2017-03-24T10:29:06"
}

The output object is read-only and generated by the API when the job is completed.

Field Description
id Unique identifier for the output file.
source Indicates the identifiers for the input files and conversion used to generate the output file.
uri Direct download URL of the converted file.
size File size of the converted file.
status Status of the output, when disabled the file will not be able to download.
content-type The mime type of the output file.
downloads_counter Number of times the output has been downloaded.
checksum Checksum of the file.
created_at Date when the converted file was created.

Go up

Statuses

The different status codes available for a job.

Code Description
incomplete Missing information to run the job.
ready The job is ready but not marked to be processed yet.
queued The file is waiting in the queue for being processed.
downloading The file is currently downloaded from the source URL.
pending The file is waiting in the queue to be downloaded.
processing The file is currently being converted.
completed The file has been successfully converted.
failed The file has not been converted due to errors.
invalid The Hash is not valid.

Go up

Official wrapper

In the following list you will find all languages where we have created an SDK for to get easy access to our API. They are hosted on GitHub. We would really appreciate your help with enhancing the SDKs for lesser known languages. Pull requests and requests for new feature are very welcome. Of course you can use our API directly without using our SDKs as outlined in the following paragraphs.

Language we support Version control Package Repository
PHP SDK Github Packagist
Java SDK Github JAR Maven Central Repository
Android SDK Github
Perl SDK Github

Go up

Prices

If you want to use the API for free, the following limitations apply:

  • Amount of free conversion minutes within 24 hours: 30
  • Maximum upload size per file: 100 MB
  • You need to put a logo of online-convert.com on your website and link it to http://www.online-convert.com/
  • You are allowed to use only one API-key per website/project/company/individual

If you want to use the paid API, the limitation of the free API do not apply. The price for each conversion depends on the amount of CPU time needed to convert the file. Each conversion costs at least one conversion minute and they can be bought as prepaid packages:

Conversion minutes Package price Price per conversion minute
50010 USD0.02 USD/conversion minute
1,00018 USD0.018 USD/conversion minute
5,00085 USD0.017 USD/conversion minute
10,000150 USD0.015 USD/conversion minute
50,000700 USD0.014 USD/conversion minute
100,0001,200 USD0.012 USD/conversion minute
200,0002,200 USD0.011 USD/conversion minute
300,0003,000 USD0.010 USD/conversion minute
500,0004,000 USD0.008 USD/conversion minute
1,000,0006,000 USD0.006 USD/conversion minute
All prices include tax where applicable. Files we can not process are not charged. You will receive a proper invoice.

You can buy the prepaid packages after your free registration here: Buy prepaid API conversion packages. Invoice based contracts are available as well as Service Level Agreements (SLAs).

We are one of the fastest file conversion services available with a huge customer base. Our API is using a large and extremely reliable server farm to provide high quality conversions. Please feel free to compare our speed, reliability and conversion quality.

Go up

Upgrading

Upgrading from API version 1 to the API version 2 it is not straight forward. The new version introduces major changes:

  • The new version now follows the REST architecture. There are several URIs representing the different objects to interact with, while the action is made by the HTTP method.
  • The data exchange format is now JSON. XML can be added on request.
  • The errors are reflected in the HTTP status codes.
  • The authentication token work differently since the token now belong to the conversion jobs.

If you are a customer using API version 1 and would like to migrate to the powerful API version 2, don't hesitate to contact us if you need help. The API version 1 is deprecated but will work as long as our customers rely on it.

Go up

Endpoints

Below is a list of all possible endpoints that may help you to navigate through our API.

You can use the below form to test any API endpoint. Be aware that the calls you make are live on the site (so don't delete anything you don't really want removed).