Convertio API Documentation

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"
}

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"
}

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"
}

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)"
}

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"
}

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"
}

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