API Documentation


Getting Started

We provide access to the Conversion Tools services via the HTTP-based REST API using the token authentication. API request and response are formatted in JSON.


Libraries

We maintain the following official REST API libraries:


Authentication

When account is created we generate the API Token for accessing the Conversion Tools REST API.

API Token can be found at your Profile.

API Token should be passed to HTTP request in the Authorization HTTP header with the Bearer authentication scheme as follows:

Authorization: Bearer <API Token>

The following sample request checking the access to the Conversion Tools REST API:


curl -sSX GET https://api.conversiontools.io/v1/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Token>"


API URL

Conversion Tools REST API is available at:

https://api.conversiontools.io/v1/

API Requests

API Request should contain the following components:

  • The HTTP method, one of GET or POST
  • Authorization HTTP header with API Token
  • Content-Type HTTP header with type application/json
  • A JSON request body which depends on the API command, see list of API commands below

The folllowing sample API request creates new conversion task:


curl -sSX POST https://api.conversiontools.io/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Token>" \
  -d '{
  "type": "convert.website_to_image",
  "options": {
    "url": "http://google.com",
    "image_format": "jpg"
  }
}'


API Response

General format of the API response has error field and some optional <data>:

{
  "error": "<error text>",
  <data>
}

In case of success, <error text> will be empty (null), for example:

{
  "error": null,
  "task_id": "4147c475ffe94ec8a11aff9a6a8f437a"
}

In case of error, <error text> will contain the error description, for example:

{
  "error": "Bad request"
}

API Reference

File conversion process consists of the following 4 steps:

  1. Upload file to the server (optional step when URL is provided)
  2. Run conversion task
  3. Get conversion task status
  4. Download the result file

Step 1. Upload file to the Conversion Tools Server

In case when you providing the file by Internet URL - start with a Step 2.

For file upload use a HTTP POST file upload request with the Content-Type: multipart/form-data header.

See sample request below.


Request:

POST https://api.conversiontools.io/v1/files

Headers:

Authorization: Bearer <API Token>
Content-Type: multipart/form-data

Input parameters:

file(required)A file reference

Response:

Success response will contain file_id field, which contains the identifier of the uploaded file:

{
  "error": null,
  "file_id": "be87de1a680c4451a49a72df3fecd3fd"
}

This file_id value should be used in the following step (Run conversion task).


Sample request using curl:


curl -sSX POST https://api.conversiontools.io/v1/files \
  -H "Authorization: Bearer <API Token>" \
  -F "file=@/home/user/Desktop/test.xml"

Please note: -F parameter of curl automatically adding header Content-Type: multipart/form-data to the request.


Step 2. Run conversion task

Request:

POST https://api.conversiontools.io/v1/tasks

Headers:

Authorization: Bearer <API Token>
Content-Type: application/json

Input parameters:

type(required)Conversion type, for example convert.website_to_pdf. See list of available conversion types.
options(required)Set of options, different for every conversion task, see the tables below.

options parameters generic for every conversion task:

file_id(required, when converting the file uploaded to the server)For conversions which require a file to be uploaded, this is the file_id returned by POST /files request (from Step 1).
url(required, when converting the file from the Internet by link)For conversions which accepts file by URL, this is a place to put it.

options parameters specific per conversion task:

Please click on the conversion type to see the list of available options.

convert.mp4_to_mp3 - Convert MP4 to MP3 Online - MP4 to MP3 Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
bitrate(optional)default
96
128
160
192
256
320

For optional parameters the default value highlighted in bold text.

convert.wav_to_mp3 - Convert WAV to MP3 Online - WAV to MP3 Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
bitrate(optional)default
96
128
160
192
256
320

For optional parameters the default value highlighted in bold text.

convert.wav_to_flac - Convert WAV to FLAC Online - WAV to FLAC Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.flac_to_mp3 - Convert FLAC to MP3 Online - FLAC to MP3 Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
bitrate(optional)default
96
128
160
192
256
320

For optional parameters the default value highlighted in bold text.

convert.website_to_pdf - Convert HTML to PDF Online - HTML to PDF Converter
ParameterRequiredPossible values
file_id(required, when converting the uploaded file)file_id of the file to convert
url(required, when converting the file from url)Internet URL of the file to convert
orientation(optional)Landscape
Portrait
pagesize(optional)A4
B5
Letter
colormode(optional)colored
grayscale
background(optional)yes
no
images(optional)yes
no
javascript(optional)yes
no

For optional parameters the default value highlighted in bold text.

convert.word_to_pdf - Convert Word to PDF Online - Word to PDF Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.powerpoint_to_pdf - Convert PowerPoint to PDF Online - PowerPoint to PDF Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.word_to_text - Convert Word to Text Online - Word to TXT Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.powerpoint_to_text - Convert PowerPoint to Text Online - PowerPoint to TXT Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.jpg_to_pdf - Convert JPG to PDF Online - JPG to PDF Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
orientation(optional)Landscape
Portrait

For optional parameters the default value highlighted in bold text.

convert.png_to_pdf - Convert PNG to PDF Online - PNG to PDF Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
orientation(optional)Landscape
Portrait

For optional parameters the default value highlighted in bold text.

convert.website_to_jpg - Convert Website to JPG. Create Website Thumbnail. Save Website as Image. HTML to JPG Converter
ParameterRequiredPossible values
url(required)Internet URL of the file to convert
images(optional)yes
no
javascript(optional)yes
no

For optional parameters the default value highlighted in bold text.

convert.website_to_png - Convert Website to PNG. Create Website Thumbnail. Save Website as Image. HTML to PNG Converter
ParameterRequiredPossible values
url(required)Internet URL of the file to convert
images(optional)yes
no
javascript(optional)yes
no

For optional parameters the default value highlighted in bold text.

convert.html_table_to_csv - Convert HTML Table to CSV Online - HTML to CSV Converter
ParameterRequiredPossible values
file_id(required, when converting the uploaded file)file_id of the file to convert
url(required, when converting the file from url)Internet URL of the file to convert
delimiter(optional)comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.excel_to_pdf - Convert Excel to PDF Online - Excel to PDF Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
orientation(optional)Landscape
Portrait

For optional parameters the default value highlighted in bold text.

convert.excel_to_html - Convert Excel to HTML Online - Excel to HTML Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.excel_to_csv - Convert Excel to CSV Online - Excel to CSV Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
delimiter(optional)comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.ods_to_csv - Convert OpenOffice Calc ODS to CSV Online - ODS to CSV Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
delimiter(optional)comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.ods_to_pdf - Convert OpenOffice Calc ODS to PDF Online - ODS to PDF Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
orientation(optional)Landscape
Portrait

For optional parameters the default value highlighted in bold text.

convert.ods_to_excel - Convert OpenOffice Calc ODS to Excel Online - ODS to Excel Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.csv_to_excel - Convert CSV to Excel Online - CSV to Excel Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
delimiter(optional)comma
semicolon
vertical_bar
tabulation
split_excel_rows_limit(optional)yes
no

For optional parameters the default value highlighted in bold text.

convert.csv_to_xml - Convert CSV to XML Online - CSV to XML Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
delimiter(optional)comma
semicolon
vertical_bar
tabulation
header(optional)Use first line of the CSV file as a columns header:
yes
no

For optional parameters the default value highlighted in bold text.

convert.excel_to_xml - Convert Excel to XML Online - Excel to XML Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
header(optional)Use first line of the CSV file as a columns header:
yes
no

For optional parameters the default value highlighted in bold text.

convert.xml_to_csv - Convert XML to CSV Online - XML to CSV Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
delimiter(optional)comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.xml_to_excel - Convert XML to Excel Online - XML to Excel Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
split_excel_rows_limit(optional)yes
no

For optional parameters the default value highlighted in bold text.

convert.excel_xml_to_excel_xlsx - Convert Excel XML to Excel XLSX Online - Excel XML to XLSX Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.pdf_to_csv - Convert PDF to CSV Online - PDF to CSV Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
delimiter(optional)comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.pdf_to_excel - Convert PDF to Excel Online - PDF to Excel Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.pdf_to_jpg - Convert PDF to JPG Online - PDF to JPG Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
image_resolution(optional)values in PPI (pixel per inch):
72
150
300
600
jpeg_quality(optional)0 - 100 (default: 80)
colormode(optional)colored
grayscale
progressive_jpeg(optional)yes
no

For optional parameters the default value highlighted in bold text.

convert.pdf_to_png - Convert PDF to PNG Online - PDF to PNG Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
image_resolution(optional)values in PPI (pixel per inch):
72
150
300
600
colormode3(optional)colored
grayscale
monochrome
background_color(optional)white
transparent

For optional parameters the default value highlighted in bold text.

convert.pdf_to_tiff - Convert PDF to TIFF Online - PDF to TIFF Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
image_resolution(optional)values in PPI (pixel per inch):
72
150
300
600
colormode3(optional)colored
grayscale
monochrome
background_color(optional)white
transparent

For optional parameters the default value highlighted in bold text.

convert.pdf_to_svg - Convert PDF to SVG Online - PDF to SVG Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
image_resolution(optional)values in PPI (pixel per inch):
72
150
300
600
pagesize(optional)A4
B5
Letter

For optional parameters the default value highlighted in bold text.

convert.pdf_to_text - Convert PDF to Text Online - PDF to Text Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.png_to_jpg - Convert PNG to JPG Online - PNG to JPG Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.jpg_to_png - Convert JPG to PNG Online - JPG to PNG Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.epub_to_mobi - Convert ePub to MOBI Online - ePub to MOBI Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.mobi_to_epub - Convert MOBI to ePub Online - MOBI to ePub Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.epub_to_pdf - Convert ePub to PDF Online - eBook to PDF Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.mobi_to_pdf - Convert MOBI to PDF Online - eBook to PDF Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.azw_to_pdf - Convert AZW to PDF Online - eBook to PDF Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.azw3_to_pdf - Convert AZW3 to PDF Online - eBook to PDF Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.fb2_to_pdf - Convert FB2 to PDF Online - eBook to PDF Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.fbz_to_pdf - Convert FBZ to PDF Online - eBook to PDF Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.pdf_to_epub - Convert PDF to ePub Online - PDF to eBook Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.pdf_to_mobi - Convert PDF to MOBI Online - PDF to eBook Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.pdf_to_azw - Convert PDF to AZW Online - PDF to eBook Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.pdf_to_azw3 - Convert PDF to AZW3 Online - PDF to eBook Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.pdf_to_fb2 - Convert PDF to FB2 Online - PDF to eBook Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.pdf_to_fbz - Convert PDF to FBZ Online - PDF to eBook Converter
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.remove_exif - Remove EXIF Data from Photos Online
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.


The folllowing sample API request creates new conversion task:


curl -sSX POST https://api.conversiontools.io/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Token>" \
  -d '{
  "type": "convert.website_to_image",
  "options": {
    "url": "http://google.com",
    "image_format": "jpg"
  }
}'


Response:

{
  "error": "<error text>",
  "task_id": "<task_id>"
}

In case of error, <error text> will be any not null text value, it will contain the description of error.

{
  "error": "Bad type",
}

In case of success, it will return <task_id>. You should use Get conversion task status request to find out when conversion task will be finished.

{
  "error": null,
  "task_id": "4147c475ffe94ec8a11aff9a6a8f437a"
}

Step 3. Get conversion task status

You should perform this check in a loop, until task will be finished (see status field).

Important! Please send this request not more often than every 5-10 seconds.

Request:

GET https://api.conversiontools.io/v1/tasks/<task_id>

Headers:

Authorization: Bearer <API Token>
Content-Type: application/json

URL parameters:

task_id(required)This is the task_id returned in the previous step.

The folllowing sample API request check the conversion task status:


curl -sSX GET https://api.conversiontools.io/v1/tasks/d9b5369bfc6541d88581d4ff80954917 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Token>"


Response:

{
  "error": "<error text>",
  "status": "<status>",
  "file_id": "<file_id>"
}

In case of error, <error text> will be any not null text value, it will contain the description of error.

status is one of the following:

  • PENDING - task is queued and waiting to be processed
  • RUNNING - task is running
  • SUCCESS - task is finished successfully
  • ERROR - task is finished with an error

When status is PENDING or RUNNING, response will have an empty file_id field, for example:

{
  "error": null,
  "status": "RUNNING",
  "file_id": null
}

When status is SUCCESS, response will have file_id of the result file, for example:

{
  "error": null,
  "status": "SUCCESS",
  "file_id": "ce87de1a680c4451a49a72df3fecd3fe"
}

When status is ERROR, response will have error field with description of the error:

{
  "error": "Wrong file format",
  "status": "ERROR",
  "file_id": null
}

When status returned as SUCCESS or ERROR - this means that the conversion process is finished and you can download the result file using file_id (request is described in the next step) or analyse the error.


Step 4. Download result file

Request:

GET https://api.conversiontools.io/v1/files/<file_id>

Headers:

Authorization: Bearer <API Token>
Content-Type: application/json

URL parameters:

<file_id>(required)This is the file_id of the file you need to download, for example, file_id returned in the previous step get task status.

Response:

The response will contain a Content-Disposition: attachment; HTTP header, which should trigger the file download process (if you're using a browser).


Available Conversion Types
Conversion TypeDescription
convert.mp4_to_mp3Convert MP4 to MP3 Online - MP4 to MP3 Converter
convert.wav_to_mp3Convert WAV to MP3 Online - WAV to MP3 Converter
convert.wav_to_flacConvert WAV to FLAC Online - WAV to FLAC Converter
convert.flac_to_mp3Convert FLAC to MP3 Online - FLAC to MP3 Converter
convert.website_to_pdfConvert HTML to PDF Online - HTML to PDF Converter
convert.word_to_pdfConvert Word to PDF Online - Word to PDF Converter
convert.powerpoint_to_pdfConvert PowerPoint to PDF Online - PowerPoint to PDF Converter
convert.word_to_textConvert Word to Text Online - Word to TXT Converter
convert.powerpoint_to_textConvert PowerPoint to Text Online - PowerPoint to TXT Converter
convert.jpg_to_pdfConvert JPG to PDF Online - JPG to PDF Converter
convert.png_to_pdfConvert PNG to PDF Online - PNG to PDF Converter
convert.website_to_jpgConvert Website to JPG. Create Website Thumbnail. Save Website as Image. HTML to JPG Converter
convert.website_to_pngConvert Website to PNG. Create Website Thumbnail. Save Website as Image. HTML to PNG Converter
convert.html_table_to_csvConvert HTML Table to CSV Online - HTML to CSV Converter
convert.excel_to_pdfConvert Excel to PDF Online - Excel to PDF Converter
convert.excel_to_htmlConvert Excel to HTML Online - Excel to HTML Converter
convert.excel_to_csvConvert Excel to CSV Online - Excel to CSV Converter
convert.ods_to_csvConvert OpenOffice Calc ODS to CSV Online - ODS to CSV Converter
convert.ods_to_pdfConvert OpenOffice Calc ODS to PDF Online - ODS to PDF Converter
convert.ods_to_excelConvert OpenOffice Calc ODS to Excel Online - ODS to Excel Converter
convert.csv_to_excelConvert CSV to Excel Online - CSV to Excel Converter
convert.csv_to_xmlConvert CSV to XML Online - CSV to XML Converter
convert.excel_to_xmlConvert Excel to XML Online - Excel to XML Converter
convert.xml_to_csvConvert XML to CSV Online - XML to CSV Converter
convert.xml_to_excelConvert XML to Excel Online - XML to Excel Converter
convert.excel_xml_to_excel_xlsxConvert Excel XML to Excel XLSX Online - Excel XML to XLSX Converter
convert.pdf_to_csvConvert PDF to CSV Online - PDF to CSV Converter
convert.pdf_to_excelConvert PDF to Excel Online - PDF to Excel Converter
convert.pdf_to_jpgConvert PDF to JPG Online - PDF to JPG Converter
convert.pdf_to_pngConvert PDF to PNG Online - PDF to PNG Converter
convert.pdf_to_tiffConvert PDF to TIFF Online - PDF to TIFF Converter
convert.pdf_to_svgConvert PDF to SVG Online - PDF to SVG Converter
convert.pdf_to_textConvert PDF to Text Online - PDF to Text Converter
convert.png_to_jpgConvert PNG to JPG Online - PNG to JPG Converter
convert.jpg_to_pngConvert JPG to PNG Online - JPG to PNG Converter
convert.epub_to_mobiConvert ePub to MOBI Online - ePub to MOBI Converter
convert.mobi_to_epubConvert MOBI to ePub Online - MOBI to ePub Converter
convert.epub_to_pdfConvert ePub to PDF Online - eBook to PDF Converter
convert.mobi_to_pdfConvert MOBI to PDF Online - eBook to PDF Converter
convert.azw_to_pdfConvert AZW to PDF Online - eBook to PDF Converter
convert.azw3_to_pdfConvert AZW3 to PDF Online - eBook to PDF Converter
convert.fb2_to_pdfConvert FB2 to PDF Online - eBook to PDF Converter
convert.fbz_to_pdfConvert FBZ to PDF Online - eBook to PDF Converter
convert.pdf_to_epubConvert PDF to ePub Online - PDF to eBook Converter
convert.pdf_to_mobiConvert PDF to MOBI Online - PDF to eBook Converter
convert.pdf_to_azwConvert PDF to AZW Online - PDF to eBook Converter
convert.pdf_to_azw3Convert PDF to AZW3 Online - PDF to eBook Converter
convert.pdf_to_fb2Convert PDF to FB2 Online - PDF to eBook Converter
convert.pdf_to_fbzConvert PDF to FBZ Online - PDF to eBook Converter
convert.remove_exifRemove EXIF Data from Photos Online

Need help?

If you have any questions regarding the use of the Conversion Tools REST API - feel free to contact us.