API developer resource

Convert files using our converter API

Welcome to the API area of online-convert.com. We have developed a set of public APIs 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 kindes 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

Overview

The conversions are performed through 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. Here you can define additional settings (like the screen size) as well.

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

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 Status
PHP SDK Github Packagist Production ready
Java SDK Github Maven Central Repository Production ready
Jax-RS SDK Github beta
Android SDK Github beta
Spring MVC SDK Github beta
Ruby SDK Github beta
Node.js Github beta
.NET (C#) SDK Github NuGet beta
Qt 5 C++ SDK Github beta
Tizen SDK Github beta
Objective-C SDK Github beta
Python SDK Github PyPI beta
Python3 SDK Github PyPI beta
Perl SDK Github beta
Swift SDK Github beta
Scala SDK Github beta

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

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.

To use the professional API, please contact us for a quote. The limitations of the free API version do not apply.

If you want to use the API for free, the following 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 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

Go up

Making calls

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

Endpoints

The API is accessed using SSL:
https://api2.online-convert.com

It can also be accessed without SSL:
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 and any tools meant to work with swaggers REST APIs will work with the API of online-convert.com.

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. Currently the job element is the only one that allows modifications.
  • DELETE: Removes existing elements via API.

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:\/\/bit.ly\/b2dlVA"
    }],
    "conversion": [{
        "target": "png"
    }]
}

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,
    "test": false,
    "conversion": [{
        "id": "407ced1d-1b36-11e5-8f2b-002590da1f50",
        "category": "image",
        "target": "png",
        "options": []
    }],
    "input": [{
        "id": "407cd2df-1b36-11e5-8f2b-002590da1f50",
        "type": "remote",
        "source": "http:\/\/bit.ly\/b2dlVA",
        "filename": "799px-Red_eyed_tree_frog_edit2.jpg",
        "size": 0,
        "created_at": "2015-06-25T14:32:32",
        "modified_at": "2015-06-25T14:32:32"
    }],
    "callback": "",
    "server": "https:\/\/www7.online-convert.com",
    "created_at": "2015-06-25T14:32:32",
    "modified_at": "2015-06-25T14:32:32"
}

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

Go up

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,
    "test": false,
    "conversion": [],
    "input": [],
    "callback": "",
    "server": "https:\/\/www7.online-convert.com",
    "created_at": "2015-06-25T14:32:32",
    "modified_at": "2015-06-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:\/\/bit.ly\/b2dlVA"
}

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:\/\/bit.ly\/b2dlVA",
    "filename": "799px-Red_eyed_tree_frog_edit2.jpg",
    "size": 0,
    "created_at": "2015-06-25T14:32:32",
    "modified_at": "2015-06-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,
    "test": false,
    "conversion": [],
    "input": [{
        "id": "407cd2df-1b36-11e5-8f2b-002590da1f50",
        "type": "remote",
        "source": "http:\/\/bit.ly\/b2dlVA",
        "filename": "799px-Red_eyed_tree_frog_edit2.jpg",
        "size": 0,
        "created_at": "2015-06-25T14:32:32",
        "modified_at": "2015-06-25T14:32:32"
    }],
    "callback": "",
    "server": "https:\/\/www7.online-convert.com",
    "created_at": "2015-06-25T14:32:32",
    "modified_at": "2015-06-25T14:32:32"
}

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,
    "test": false,
    "conversion": [{
        "id": "407ced1d-1b36-11e5-8f2b-002590da1f50",
        "category": "image",
        "target": "png",
        "options": []
    }],
    "input": [{
        "id": "407cd2df-1b36-11e5-8f2b-002590da1f50",
        "type": "remote",
        "source": "http:\/\/bit.ly\/b2dlVA",
        "filename": "799px-Red_eyed_tree_frog_edit2.jpg",
        "size": 0,
        "created_at": "2015-06-25T14:32:32",
        "modified_at": "2015-06-25T14:32:32"
    }],
    "callback": "",
    "server": "https:\/\/www7.online-convert.com",
    "created_at": "2015-06-25T14:32:32",
    "modified_at": "2015-06-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": "09f602f2-39ac-11e5-9484-448a5bd44b34",
    "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": [],
    "callback": "",
    "server": "https:\/\/www3.online-convert.com",
    "created_at": "2015-08-03T08:51:16",
    "modified_at": "2015-08-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.

POST https://www3.online-convert.com/upload-file/09f602f2-39ac-11e5-9484-448a5bd44b34 HTTP/1.1
X-Oc-Token: d1ad18eace9e778058facb23985988f4

------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,
    "created_at":"2015-08-03T08:51:17",
    "modified_at":"2015-08-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/09f602f2-39ac-11e5-9484-448a5bd44b34 HTTP/1.1
X-Oc-Token: d1ad18eace9e778058facb23985988f4

We will obtain the full information for the completed job.

{
    "id": "09f602f2-39ac-11e5-9484-448a5bd44b34",
    "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",
            "size": 77550,
            "created_at": "2015-08-03T08:51:17",
            "modified_at": "2015-08-03T08:51:17"
        }],
    "callback": "",
    "server": "https:\/\/www3.online-convert.com",
    "created_at": "2015-08-03T08:51:16",
    "modified_at": "2015-08-03T08:51:16"
}

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.

{
    "id": "407c9fcd-1b36-11e5-8f2b-002590da1f50",
    "token": "52b099c5d8e127278280873343add213",
    "type": "job",
    "status": {
        "code": "completed",
        "info": "The file has been successfully converted."
    },
    "process": true,
    "test": false,
    "conversion": [{
        "id": "407ced1d-1b36-11e5-8f2b-002590da1f50",
        "category": "image",
        "target": "png",
        "options": []
    }],
    "input": [{
        "id": "407cd2df-1b36-11e5-8f2b-002590da1f50",
        "type": "remote",
        "source": "http:\/\/bit.ly\/b2dlVA",
        "filename": "799px-Red_eyed_tree_frog_edit2.jpg",
        "size": 0,
        "created_at": "2015-06-25T14:32:32",
        "modified_at": "2015-06-25T14:32:32"
    }],
    "callback": "",
    "server": "https:\/\/www7.online-convert.com",
    "created_at": "2015-06-25T14:32:32",
    "modified_at": "2015-06-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\/download-file\/3d5ddd19b9d83a8cf859d761ecaba060",
    "size": 364,
    "created_at": "2015-06-24T10:29:06",
    "modified_at": "2015-06-24T10:29:06"
    }
]

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.

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."
    },
    "process": true,
    "test": false,
    "conversion": [...],
    "input": [....],
    "callback": "",
    "server": "https:\/\/www18.online-convert.com",
    "created_at": "2015-06-24T10:28:33",
    "modified_at": "2015-06-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
process Flag to determine if the job must be started or not. No True
test Flag to determine if the conversion is in test mode. Use this when accessing the API during development. No False
conversion An array of conversions used for the job. No null
input An array of input used for the job. No null
server Url for the server for uploading a file you want to convert. 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:\/\/bit.ly\/b2dlVA",
    "filename": "799px-Red_eyed_tree_frog_edit2.jpg",
    "size": 0,
    "created_at": "2015-06-24T10:28:52",
    "modified_at": "2015-06-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" or "upload". No Auto
source URL where the file has to be downloaded from. Yes  
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\/download-file\/3d5ddd19b9d83a8cf859d761ecaba060",
    "size": 36443747,
    "created_at": "2015-06-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.
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.

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