API Documentation

Start a New Conversion

In order to start a new conversion you need to do a following POST request:

POST https://api.convertio.co/convert

Usage example:
curl -i -X POST -d '{"apikey": "_YOUR_API_KEY_", "file":"http://google.com/", "outputformat":"png"}' http://api.convertio.co/convert
Parameter
Field Type Description
apikey String Your API Key
input String Method of providing the input file.
Default Value:url
Allowed Values: url,raw,base64,upload
file String URL of the input file (if input=url), or file content (if input = raw/base64)
filename optional String Input filename including extension (file.ext). Required if input = raw/base64
outputformat String Output format, to which the file should be converted to.
options optional Object Conversion options. Now used to define callback URL, enable OCR and setting up its options. You may find available OCR conversion options here and callback example here.

 

Return SUCCESS
Field Type Description
code Int HTTP Status Code
status String Always 'ok' on Success
data Object Result data
data.id String Your Conversion ID
data.minutes String API conversion minutes available on the balance

 

Success Response (example):
HTTP/1.1 200 OK
{
  "code": 200,
  "status": "ok",
  "data": {
    "id": "9712d01edc82e49c68d58ae6346d2013",
    "minutes": 107
  }
}
Return ERROR
Field Type Description
code Int HTTP Status Code
status String Always 'error' on Error
error String User-friendly Error String

 

Error Response (example):
HTTP/1.1 401 Unauthorized
{
  "code": 401,
  "status": "error",
  "error": "This API Key is invalid"
}
Send a Sample Request
url

Parameters:

String
String
String
String
String
Object

Direct File Upload For Conversion

This step required only if chooses input = 'upload' on previous step. In order to upload file for conversion, you need to do a following PUT request

PUT https://api.convertio.co/convert/:id/:filename

Usage example:
curl -i -X PUT --upload-file 'test.bmp' http://api.convertio.co/convert/_ID_/test.bmp
Parameter
Field Type Description
id String Conversion ID, obtained on POST call to /convert
filename String Input filename including extension (file.ext)

 

Return SUCCESS
Field Type Description
code Int HTTP Status Code
status String Always 'ok' on Success
data Object Result data
data.id String Your Conversion ID
data.file String Filename of your file
data.size Int Size of uploaded file in Bytes

 

Success Response (example):
HTTP/1.1 200 OK
{
  "code": 200,
  "status": "ok",
  "data": {
    "id": "9712d01edc82e49c68d58ae6346d2013",
    "file": "test.bmp",
    "size": "1025470"
  }
}
Return ERROR
Field Type Description
code Int HTTP Status Code
status String Always 'error' on Error
error String User-friendly Error String

 

Error Response (example):
HTTP/1.1 401 Unauthorized
{
  "code": 401,
  "status": "error",
  "error": "No convertion minutes left"
}
Send a Sample Request
url

Parameters:

String
String

Get Status of the Conversion

In order to get status of a conversion you need to do a following GET request with :id, obtained on previous step

GET https://api.convertio.co/convert/:id/status

Usage example:
curl -i -X GET http://api.convertio.co/convert/_ID_/status
Parameter
Field Type Description
id String Conversion ID, obtained on POST call to /convert

 

Return SUCCESS
Field Type Description
code Int HTTP Status Code
status String Always 'ok' on Success
data Object Result data
data.id String Your Conversion ID
data.step String Conversion Step
Allowed Values: wait,finish,convert,upload
data.step_percent Int Step Progress in %
data.minutes Int API Minutes used by this conversion
data.output Object Output file information
data.output.url String URL of the file to download
data.output.size Int Size of the file in bytes
data.output.files Object If there are multiple output files (i.e. converting a multi-page DOC to JPG) data.output will contain a link to a ZIP file, which contains all output files. If you would like to get the output files individual, you can use data.output.url/file.ext, where file.ext - is the name of the individual file

 

Success Response (example):
HTTP/1.1 200 OK
{
  "code": 200,
  "status": "ok",
  "data": {
    "id": "9712d01edc82e49c68d58ae6346d2013",
    "step": "finish",
    "step_percent": 100,
    "minutes": 1,
    "output": {
      "url": "https://lisa.convertio.me/d31c0ed50efd097e34c6b23fa555445d/http-google-com_4.png",
      "size": "36102"
    }
  }
}
Return ERROR
Field Type Description
code Int HTTP Status Code
status String Always 'error' on Error
error String User-friendly Error String

 

Error Response (example):
HTTP/1.1 422 Unprocessable Entity
{
  "code": 422,
  "status": "error",
  "error": "Input file appears to be corrupted"
}
Send a Sample Request
url

Parameters:

String

Get Result File Content

In order to get result file of a conversion you need to do a following GET request (As an alternative to this step you may use output URL from previous step, but be advised, that this URL is bounded to the host IP address and can't be hotlinked or shared with third parties)

GET https://api.convertio.co/convert/:id/dl/:type

Usage example:
curl -i -X GET http://api.convertio.co/convert/_ID_/dl
Parameter
Field Type Description
id String Conversion ID, obtained on POST call to /convert
type optional String File Format. Always base64-encoded
Allowed Values: base64

 

Return SUCCESS
Field Type Description
code Int HTTP Status Code
status String Always 'ok' on Success
data Object Result data
data.id String Your Conversion ID
data.type String content encoding
Allowed Values: base64
data.content String content of the file

 

Success Response (example):
HTTP/1.1 200 OK
{
  "code": 200,
  "status": "ok",
  "data": {
    "id": "9712d01edc82e49c68d58ae6346d2013",
    "encode": "base64",
    "content": "_FILE_CONTENT_"
  }
}
Return ERROR
Field Type Description
code Int HTTP Status Code
status String Always 'error' on Error
error String User-friendly Error String

 

Error Response (example):
HTTP/1.1 422 Unprocessable Entity
{
  "code": 422,
  "status": "error",
  "error": "File is not ready yet, finished with errors or had been deleted (check file status)"
}
Send a Sample Request
url

Parameters:

String
String

Delete File/Cancel Conversion

In order to stop a conversion or to delete a file you need to do a following GET request

DELETE https://api.convertio.co/convert/:id

Usage example:
curl -i -X DELETE http://api.convertio.co/convert/_ID_
Parameter
Field Type Description
id String Conversion ID, obtained on POST call to /convert

 

Return SUCCESS
Field Type Description
code Int HTTP Status Code
status String Always 'ok' on Success
message String User-friendly Error String

 

Success Response (example):
HTTP/1.1 200 OK
{
  "code": 200,
  "status": "ok",
  "message": "File deleted"
}
Return ERROR
Field Type Description
code Int HTTP Status Code
status String Always 'error' on Error
error String User-friendly Error String

 

Error Response (example):
HTTP/1.1 404 Not Found
{
  "code": 404,
  "status": "error",
  "error": "File not found"
}
Send a Sample Request
url

Parameters:

String

List of Conversions

In order to get a list of your conversions and their statuses do following POST request:

POST https://api.convertio.co/convert/list

Usage example:
curl -i -X POST -d '{"apikey": "_YOUR_API_KEY_", "status": "all", "count": 3}' http://api.convertio.co/convert/list
Parameter
Field Type Description
apikey String Your API Key
status String Filter by file status
Default Value:all
Allowed Values: all,uploading,converting,finished,failed
count Int Latest {count} files

 

Return SUCCESS
Field Type Description
code Int HTTP Status Code
status String Always 'ok' on Success
data Object[] Result data
data.id String Conversion ID
data.status String Conversion Status
Allowed Values: uploading,converting,finished,failed,unknown
data.minutes Int API Minutes used by this conversion
data.inputformat String Input file format (detected by our converter)
data.outputformat String Output file format (specified by the user)
data.filename String File name, if applicable
data.error String User-friendly error string, in case of failed conversion

 

Success Response (example):
HTTP/1.1 200 OK
{
  "code": 200,
  "status": "ok",
  "data": [
    {
      "id": "7d5c9dba440e618ed6eb1adae69c10d6",
      "status": "finished",
      "minutes": "1",
      "inputformat": "DOC",
      "outputformat": "PDF",
      "filename": "report-94b97c5b.doc"
    },
    {
      "id": "aa235eee271c5c4453890d7bca48b49a",
      "status": "failed",
      "minutes": "0",
      "inputformat": "",
      "outputformat": "PDF",
      "filename": "report-9a497c5b.xlsb",
      "error": "CONVERTER: Can't determine Type of the Input File [MIME: application\/octet-stream]"
    },
    {
      "id": "ce4d5442bd662b97c2a6456b3fa74b1d",
      "status": "failed",
      "minutes": "0",
      "inputformat": "",
      "outputformat": "MKV",
      "filename": "video.avi",
      "error": "UPLOADER: Operation timed out after 600000 milliseconds with 62290101 out of 72502797 bytes received"
    },
    {
      "id": "712f2e88a46d3a0444e52cc7d7f602a6",
      "status": "converting",
      "minutes": "0",
      "inputformat": "PDF",
      "outputformat": "HTML",
      "filename": "printable.pdf"
    }
  ]
}
Return ERROR
Field Type Description
code Int HTTP Status Code
status String Always 'error' on Error
error String User-friendly Error String

 

Error Response (example):
HTTP/1.1 401 Unauthorized
{
  "code": 401,
  "status": "error",
  "error": "This API Key is invalid"
}
Send a Sample Request
url

Parameters:

String
String
Int

Conversion Options [Callback URL]

You may provide callback URL, when starting the conversion. This URL get notified when conversion is finished (either successful or not). If the callback URL did not respond within 10 seconds or the HTTP response code >= 500 request will be retried for up to 5 times with an interval of 10 seconds.

This is the example of how to start conversion with callback URL defined:
POST https://api.convertio.co/convert

Usage example of how to initiate conversion with callback URL:
curl -i -X POST -d '{"apikey": "_YOUR_API_KEY_", "input": "base64", "file":"_BASE64_ENCODED_PDF_FILE", "outputformat":"docx", "options": {"callback_url": "http://PATH/TO/PUBLIC/URL.php"}}' http://api.convertio.co/convert

Callback URL gets notified when conversion is finished:
http://PATH/TO/PUBLIC/URL.php?id=_ID_&step=_STEP_
Callback URL parameters
Field Type Description
id String Your Conversion ID
step String finished (successful conversion)
failed (failed conversion)

Conversion Options [OCR]

These options may be used to enable callback, OCR and setting up its options.
The example below extract pages 1-3,7,12 from PDF and convert it into editable DOCX file with text written in English + Spanish.
POST https://api.convertio.co/convert

Usage example of how to initiate an OCR:
curl -i -X POST -d '{"apikey": "_YOUR_API_KEY_", "input": "base64", "file":"_BASE64_ENCODED_PDF_FILE", "outputformat":"docx", "options": {"ocr_enabled": true, "ocr_settings": {"langs": ["eng","spa"], "page_nums": "1-3,7,12"}}}' http://api.convertio.co/convert
OCR-related parameters
Field Type Description
outputformat String Output format, to which the file should be converted to.
Allowed Values for OCR: TXT, RTF, DOCX, XLSX, XLS, CSV, PPTX, PDF, EPUB, DJVU, FB2
options.ocr_enabled optional Bool Setting it to true enables OCR.
options.ocr_settings Object Required, if options.ocr_enable = true
options.ocr_settings.page_nums optional String Page numbers to extract from input file. Rich syntax supported, i.e.: 1-3,5,7-9,4
options.ocr_settings.langs Array This is the array of language codes. The more languages you set - the slower the recognition. Use the minimal set you can. You can find the list of the available language codes below
Language codes list
lang_code Language
afr Afrikaans
sqi Albanian
ara Arabic (Saudi Arabia)
arm_east Armenian (Eastern)
arm_west Armenian (Western)
aze_cyrl Azeri (Cyrillic)
aze Azeri (Latin)
eus Basque
bel Belarusian
bul Bulgarian
cat Catalan
ceb Cebuano
chi_sim Chinese Simplified
chi_tra Chinese Traditional
hrv Croatian
ces Czech
dan Danish
dut Dutch
nld Dutch (Belgian)
eng English
epo Esperanto
est Estonian
fij Fijian
fin Finnish
fra French
glg Galician
deu German
grk Greek
haw Hawaiian
heb Hebrew
hun Hungarian
isl Icelandic
ind Indonesian
gle Irish
ita Italian
jpn Japanese
kaz Kazakh
kir Kirghiz
kon Kongo
kor Korean
kur Kurdish
lat Latin
lav Latvian
lit Lithuanian
mkd Macedonian
mal Malay (Malaysian)
mlt Maltese
nor Norwegian (Bokmal)
pol Polish
por Portuguese
bra Portuguese (Brazilian)
ron Romanian
rus Russian
sco Scottish
srp Serbian (Cyrillic)
srp_latn Serbian (Latin)
slk Slovak
slv Slovenian
som Somali
spa Spanish
swa Swahili
swe Swedish
tgl Tagalog
tah Tahitian
tgk Tajik
tat Tatar
tha Thai
tur Turkish
turk Turkmen
uig_cyr Uighur (Cyrillic)
uig Uighur (Latin)
ukr Ukrainian
uzb_cyrl Uzbek (Cyrillic)
uzb Uzbek (Latin)
vie Vietnamese
cym Welsh