This is the API v2 documentation. API v2 is currently in preview state and not recommended for production use! Read more about API v2 in our blog post.

Convert Files

Create convert tasks

Create a task to convert one input file from input_format to output_format. Requires the task.write scope.

Arguments
input string or array, required The ID of the input task for the conversion, normally the import task. Multiple task IDs can be provided as an array.
input_format string, optional The current format of the file, e.g. pdf. If not set, the extension of the input file is used as input format.
output_format string, required The target format to convert to.
Converting {{ inputFormat }} to {{ outputFormat }} is not supported.
engine string, optional Use a specific engine for the conversion. We recommend setting an engine because the default engine for the conversion type might change in future.
engine_version string, optional Use a specific engine version for the conversion.
filename string, optional Choose a filename (including extension) for the output file.
If the conversion produces multiple output files, printf style placeholders are possible (e.g. myfile-%d.pdf produces the output files myfile-1.pdf, myfile-2.pdf and so on).
... optional Conversion and engine specific options. Depends on input_format and output_format.
Select input and output format above to show additional conversion options.
{{ option.name }} optional, {{ option.type }} Defaults to {{ option.default }}. Possible values: , .

Returns

The created task. You can find details about the task model response in the documentation about the show tasks endpoint.

archivetool Engine

Arguments
engine archivetool
engine_versions Possible values: 1.0 (default)
input_format Possible values: 7z , ace , alz , arc , arj , bz , bz2 , cab , cpio , deb , dmg , gz , img , iso , jar , lha , lz , lzma , lzo , rar , rpm , rz , tar , tar.7z , tar.bz , tar.bz2 , tar.gz , tar.lzo , tar.xz , tar.z , tbz , tbz2 , tgz , tz , tzo , xz , z , zip
output_format Possible values: rar , tar , tar.bz2 , tar.gz , zip , 7z
password string, optional Password to open the archive.

7z Engine

Arguments
engine 7z
engine_versions Possible values: 1.0 (default)
input_format Possible values: dmg , img , iso
output_format Possible values: 7z , rar , tar , tar.bz2 , tar.gz , tar.lzo , zip

ffmpeg Engine

Arguments
engine ffmpeg
engine_versions Possible values: 3.3.3 , 4.1.1 (deprecated) , 4.1.4 (default)
input_format Possible values: 3g2 , 3gp , 3gpp , aac , ac3 , aif , aifc , aiff , amr , au , avi , caf , cavs , dv , dvr , flac , flv , gif , m2ts , m4a , m4b , m4v , mkv , mod , mov , mp3 , mp4 , mpeg , mpg , mts , mxf , oga , ogg , rm , rmvb , swf , ts , vob , voc , wav , weba , webm , wma , wmv , wtv
output_format Possible values: aac , aiff , m4a , mp3 , wav , ac3 , aif , aifc , amr , au , caf , flac , m4b , oga , voc , weba , wma , gif , 3g2 , avi , mkv , mov , mp4 , webm , 3gp , 3gpp , cavs , dv , dvr , flv , m2ts , m4v , mod , mpeg , mpg , mts , mxf , ogg , rm , rmvb , swf , ts , vob , wmv , wtv
audio_codec enum, optional Codec to encode the audio. Use "copy" to copy the stream without re-encoding. Defaults to copy . Possible values: copy , aac , aac_he_1 , aac_he_2
audio_bitrate integer, optional Audio bitrate. Defaults to 128 .
audio_qscale integer, optional Controls the bitrate range for the VBR MP3. The range is 0-9 where a lower value is a higher quality.
video_codec enum, optional Codec to encode the video. Use "copy" to copy the stream without re-encoding. Defaults to gif . Possible values: copy , gif
width integer, optional Set output video width.
height integer, optional Set output video height.
crf integer, optional The Constant Rate Factor (CRF) sets the quality of the video. The range of the CRF scale is 0–51, where 0 is lossless, 23 is the default, and 51 is worst quality possible. Defaults to 23 .
preset enum, optional The preset is a collection of options that will provide a certain encoding speed to compression ratio. Defaults to medium . Possible values: ultrafast , superfast , veryfast , faster , fast , medium , slow , slower , veryslow
tune enum, optional Settings based upon the specifics of your input. Possible values: film , animation , grain , stillimage , fastdecode , zerolatency , psnr , ssim
profile enum, optional Set output to a specific H264 compatibility profile. Possible values: baseline , main , high , high10 , high422 , high444
level enum, optional Set output to a specific H264 compatibility profile level. Possible values: 1 , 1b , 1.1 , 1.2 , 1.3 , 2.0 , 2.1 , 2.2 , 3.0 , 3.1 , 3.2 , 4.0 , 4.1 , 4.2 , 5.0 , 5.1 , 5.2

sfark Engine

Arguments
engine sfark
engine_versions Possible values: 3.0 (default)
input_format Possible values: sfark
output_format Possible values: sf2

inkscape Engine

Arguments
engine inkscape
engine_versions Possible values: 0.92.3 , 0.92.4 (default)
input_format Possible values: ai , cdr , cgm , emf , eps , pdf , ps , sk , sk1 , svg , svgz , vsd , wmf
output_format Possible values: dxf , pdf , eps , png , ps , emf , svg , wmf
text_to_path boolean, optional Convert texts to paths (for more accurate fonts).
width integer, optional Set the output width in pixels (Overrides the pixel_density setting).
height integer, optional Set the output height in pixels (Overrides the pixel_density setting).
pixel_density integer, optional Set the resolution (in pixels per inch) the input file is rendered at. Defaults to 96 .

cadconverter Engine

Arguments
engine cadconverter
engine_versions Possible values: 8.9 (default)
input_format Possible values: dwg , dxf
output_format Possible values: dxf , dwg , pdf , bmp , eps , gif , jpg , png , tiff , cgm , svg , wmf
autocad_version enum, optional Possible values: 25 , 26 , 9 , 10 , 11 , 12 , 13 , 14 , 2000 , 2004 , 2007 , 2010
all_layouts boolean, optional Convert all layouts.
width integer, optional Set the output width in pixels.
height integer, optional Set the output height in pixels.
auto_zoom boolean, optional Auto zoom extend.

graphicsmagick Engine

Arguments
engine graphicsmagick
engine_versions Possible values: 1.3.31 (default)
input_format Possible values: 3fr , arw , bmp , cr2 , crw , dcr , dng , emf , eps , erf , gif , heic , ico , jpeg , jpg , mos , mrw , nef , odd , orf , pdf , pef , png , ppm , ps , psd , raf , raw , svg , svgz , tif , tiff , webp , x3f , xcf , xps
output_format Possible values: pdf , bmp , eps , gif , ico , jpg , odd , png , ps , psd , tiff , webp
width integer, optional Output width in pixels.
height integer, optional Output height in pixels.
fit enum, optional Sets the mode of resizing the image. "Max" resizes the image to fit within the width and height, but will not increase the size of the image if it is smaller than width or height. "Crop" resizes the image to fill the width and height dimensions and crops any excess image data. "Scale" enforces the image width and height by scaling. Defaults to max . Possible values: max , crop , scale
strip boolean, optional Remove any metadata such as EXIF data.
pixel_density integer, optional Set the resolution (in pixels per inch) the input file is rendered at. Defaults to 300 .
auto_orient boolean, optional Automatically rotate the image correctly, based on EXIF information which usually is set using a gravity sensor in digital cameras. Defaults to true .
pages string, optional Page range (e.g. 1-3) or comma separated list (e.g. 1,2,3) of pages.
quality integer, optional JPEG compression level from 1 (lowest image quality and highest compression) to 100 (best quality but least effective compression). The default is to estimate the quality based on your input image.

imagemagick Engine

Arguments
engine imagemagick
engine_versions Possible values: 7.0.8 (default)
input_format Possible values: 3fr , arw , bmp , cr2 , crw , dcr , dng , emf , eps , erf , gif , heic , ico , jpeg , jpg , mos , mrw , nef , odd , orf , pdf , pef , png , ppm , ps , psd , raf , raw , svg , svgz , tif , tiff , webp , x3f , xcf , xps
output_format Possible values: pdf , bmp , eps , gif , ico , jpg , odd , png , ps , psd , tiff , webp
width integer, optional Output width in pixels.
height integer, optional Output height in pixels.
fit enum, optional Sets the mode of resizing the image. "Max" resizes the image to fit within the width and height, but will not increase the size of the image if it is smaller than width or height. "Crop" resizes the image to fill the width and height dimensions and crops any excess image data. "Scale" enforces the image width and height by scaling. Defaults to max . Possible values: max , crop , scale
strip boolean, optional Remove any metadata such as EXIF data.
pixel_density integer, optional Set the resolution (in pixels per inch) the input file is rendered at. Defaults to 300 .
auto_orient boolean, optional Automatically rotate the image correctly, based on EXIF information which usually is set using a gravity sensor in digital cameras. Defaults to true .
pages string, optional Page range (e.g. 1-3) or comma separated list (e.g. 1,2,3) of pages.
quality integer, optional JPEG compression level from 1 (lowest image quality and highest compression) to 100 (best quality but least effective compression). The default is to estimate the quality based on your input image.

libreoffice Engine

Arguments
engine libreoffice
engine_versions Possible values: 6.0.0 , 6.1.5 (default)
input_format Possible values: abw , csv , doc , docm , docx , dps , et , htm , html , lwp , odp , ods , odt , pps , ppsx , ppt , pptm , pptx , ps , rtf , txt , wpd , wps , xls , xlsm , xlsx , zabw
output_format Possible values: doc , docx , html , odt , pdf , rtf , txt , eps , odp , ppt , pptx , ods , xls , xlsx , csv , swf
embed_images boolean, optional Embed images as base64 inline images.
pages string, optional Page range (e.g. 1-3) or comma separated list (e.g. 1,2,3) of pages.
pdf_a boolean, optional Create PDF/A-1.
password string, optional Password to open the file.

calibre Engine

Arguments
engine calibre
engine_versions Possible values: 3.31 , 3.45 (default)
input_format Possible values: azw , azw3 , azw4 , cbc , cbr , cbz , chm , docx , epub , fb2 , htm , html , htmlz , lit , lrf , mobi , odt , pdb , pdf , pml , prc , rb , rtf , snb , tcr , txt , txtz
output_format Possible values: pdf , rtf , txt , azw3 , epub , lrf , mobi , oeb , pdb

ddjvu Engine

Arguments
engine ddjvu
engine_versions Possible values: 3.5 (default)
input_format Possible values: djvu
output_format Possible values: pdf

office Engine

Arguments
engine office
engine_versions Possible values: 2019 (default)
input_format Possible values: doc , docm , docx , dot , dotx , html , odt , pot , potx , ppt , pptm , pptx , xls , xlsm , xlsx , odp , ods
output_format Possible values: docx , html , odt , pdf , rtf , txt , doc , xps , ppt , pptx , odp , xls , xlsx , ods , emf
password string, optional Password to open the file.
pages string, optional Page range (e.g. 1-3).
optimize_print boolean, optional Optimize the output for printing. If set to false, output is optimized for viewing on screen. Defaults to true .
pdf_a boolean, optional Create PDF/A-1.
embed_images boolean, optional Embed external images in the document.
hidden_slides boolean, optional Include hidden slides in the output.
output_type enum, optional Defaults to slides . Possible values: slides , handout
slides_per_handout_page integer, optional Only applied if output_type is handout. Defaults to 6 .
first_slide_number integer, optional This overrides the number of the first slide.
pages_fit_wide integer, optional Sets the number of pages wide the worksheet will be scaled to when it is printed.
pages_fit_tall integer, optional Sets the number of pages tall the worksheet will be scaled to when it is printed.
decimal_separator string, optional
thousands_separator string, optional

wkhtml Engine

Arguments
engine wkhtml
engine_versions Possible values: 0.12.5 (default)
input_format Possible values: htm , html
output_format Possible values: pdf , jpg , png
page_orientation enum, optional Defaults to portrait . Possible values: portrait , landscape
print_media_type boolean, optional Use the media print CSS styles. Defaults to true .
page_width float, optional Page width in cm.
page_height float, optional Page height in cm.
margin_top float, optional Page top margin in mm. Defaults to 10 .
margin_bottom float, optional Page bottom margin in mm. Defaults to 10 .
margin_left float, optional Page left margin in mm. Defaults to 10 .
margin_right float, optional Page right margin in mm. Defaults to 10 .
smart_shrinking boolean, optional Defaults to true .
print_background boolean, optional Render the background of websites. Defaults to true .
wait_time integer, optional Additional time in ms to wait after the page load.
zoom float, optional Zoom level to display the website. Defaults to 1 .
screen_width integer, optional Screen width in px. Defaults to 1440 .
screen_height integer, optional Screen height in px. If not set, the full height of the website will be used.
headers dictionary, optional Object of additional headers to send with the request. Can be used to access URLs that require authorization.

chrome Engine

Arguments
engine chrome
engine_versions Possible values: 73 (deprecated) , 74 (deprecated) , 75 (deprecated) , 76 (deprecated) , 77 , 78 (default)
input_format Possible values: htm , html , svg
output_format Possible values: pdf , jpg , png
pages string, optional Page range (e.g. 1-3) or comma separated list (e.g. 1,2,3) of pages.
zoom float, optional Zoom level to display the website. Defaults to 1 .
page_width float, optional Page width in cm.
page_height float, optional Page height in cm.
margin_top float, optional Page top margin in mm. Defaults to 10 .
margin_bottom float, optional Page bottom margin in mm. Defaults to 10 .
margin_left float, optional Page left margin in mm. Defaults to 10 .
margin_right float, optional Page right margin in mm. Defaults to 10 .
print_background boolean, optional Render the background of websites. Defaults to true .
display_header_footer boolean, optional Create a header and a footer with the URL and page numbers.
wait_until enum, optional load: consider navigation to be finished when the load event is fired. domcontentloaded: consider navigation to be finished when the DOMContentLoaded event is fired. networkidle0: consider navigation to be finished when there are no more than 0 network connections for at least 500 ms. networkidle2: consider navigation to be finished when there are no more than 2 network connections for at least 500 ms. Defaults to load . Possible values: load , domcontentloaded , networkidle0 , networkidle2
wait_for_element string, optional CSS selector for element to wait for (e.g. "body" or "#element").
wait_time integer, optional Additional time in ms to wait after the page load.
screen_width integer, optional Screen width in px. Defaults to 1440 .
screen_height integer, optional Screen height in px. If not set, the full height of the website will be used.
width integer, optional Set the output width in pixels.
height integer, optional Set the output height in pixels.
quality integer, optional JPEG compression level from 1 (lowest image quality and highest compression) to 100 (best quality but least effective compression). The default is to estimate the quality based on your input image.

pandoc Engine

Arguments
engine pandoc
engine_versions Possible values: 1.12 (default)
input_format Possible values: html , md , rst , tex , txt
output_format Possible values: md , tex , txt , docx , html , odt , pdf , rst , rtf
output_markdown_syntax enum, optional Possible values: strict , mmd , pandoc , github
input_markdown_syntax enum, optional Possible values: strict , mmd , pandoc , github

iwork Engine

Arguments
engine iwork
engine_versions Possible values: 1.0 (default) (experimental)
input_format Possible values: key , numbers , pages
output_format Possible values: pdf , doc , docx , txt , epub , ppt , pptx , csv , xls , xlsx

bcl Engine

Arguments
engine bcl
engine_versions Possible values: 5.0 (default)
input_format Possible values: pdf
output_format Possible values: doc , docx , rtf

poppler Engine

Arguments
engine poppler
engine_versions Possible values: 0.62.0 , 0.71.0 (default)
input_format Possible values: pdf
output_format Possible values: html , txt , jpg , png , tiff
pages string, optional Page range (e.g. 1-3).
images boolean, optional Defaults to true .
pixel_density integer, optional Set the resolution (in pixels per inch) the input file is rendered at. Defaults to 300 .
width integer, optional Set the page width in pixels (Overrides the pixel_density setting).
height integer, optional Set the page height in pixels (Overrides the pixel_density setting).
quality integer, optional JPEG compression level from 1 (lowest image quality and highest compression) to 100 (best quality but least effective compression). The default is to estimate the quality based on your input image.

pdf2htmlex Engine

Arguments
engine pdf2htmlex
engine_versions Possible values: 0.14.6 (default)
input_format Possible values: pdf
output_format Possible values: html
pages string, optional Page range (e.g. 1-3).
outline boolean, optional
zoom float, optional Defaults to 1.5 .
embed_css boolean, optional Defaults to true .
embed_javascript boolean, optional Defaults to true .
embed_images boolean, optional Defaults to true .
embed_fonts boolean, optional Defaults to true .
bg_format enum, optional Defaults to png . Possible values: png , jpg , svg

qpdf Engine

Arguments
engine qpdf
engine_versions Possible values: 8.2.1 (default)
input_format Possible values: pdf
output_format Possible values: pdf
pages string, optional Page range (e.g. 1-3) or comma separated list (e.g. 1,2,3) of pages.

unoconv3 Engine

Arguments
engine unoconv3
engine_versions Possible values: 3.5 (default)
input_format Possible values: sda , sdc , sdw
output_format Possible values: html , pdf , doc , docx , odt , rtf , txt , eps , odp , ppt , pptx , csv , ods , xls , xlsx , swf
pages string, optional Page range (e.g. 1-3) or comma separated list (e.g. 1,2,3) of pages.
pdf_a boolean, optional
password string, optional

rsvg Engine

Arguments
engine rsvg
engine_versions Possible values: 2.44 (default)
input_format Possible values: svg
output_format Possible values: pdf , eps , png , ps
width integer, optional Set the width in pixels.
height integer, optional Set the height in pixels.

texlive Engine

Arguments
engine texlive
engine_versions Possible values: 2016 (default)
input_format Possible values: tex
output_format Possible values: pdf

fontforge Engine

Arguments
engine fontforge
engine_versions Possible values: 4-Aug-2015 (default)
input_format Possible values: eot , otf , svg , ttf , woff
output_format Possible values: otf , ttf , woff , eot , svg

icnsutils Engine

Arguments
engine icnsutils
engine_versions Possible values: 1.5 (default)
input_format Possible values: icns , png
output_format Possible values: png , icns

mupdf Engine

Arguments
engine mupdf
engine_versions Possible values: 1.15.0 , 1.16.1 (default)
input_format Possible values: pdf , xps
output_format Possible values: png , svg
pixel_density integer, optional Set the resolution (in pixels per inch) the input file is rendered at. Defaults to 300 .
width integer, optional Set the page width in pixels (Overrides the pixel_density setting).
height integer, optional Set the page height in pixels (Overrides the pixel_density setting).
alpha boolean, optional Render pages with an alpha channel and transparent background.
pages string, optional Page range (e.g. 1-3) or comma separated list (e.g. 1,2,3) of pages.
text_to_path boolean, optional Convert texts to paths (for more accurate fonts).

Endpoint

POST https://api.cloudconvert.com/v2/convert

Example Request

$ curl -X POST "https://api.cloudconvert.com/v2/convert" \
       -H "Authorization: Bearer API_KEY" \
       -H "Content-type: application/json" \
       -d '{
  "input": "73df1e16-fd8b-47a1-a156-f197babde91a",
  "input_format": "docx",
  "output_format": "pdf",
  "pages": "1-2",
  "optimize_print": true
}'

Example Response

{
  "data": {
    "id": "c85f3ca9-164c-4e89-8ae2-c08192a7cb08",
    "operation": "convert",
    "status": "processing",
    "message": null,
    "created_at": "2018-09-19T14:42:58+00:00",
    "started_at": "2018-09-19T14:42:58+00:00",
    "ended_at": null,
    "depends_on_tasks": {},
    "engine": "office",
    "engine_version": "2016",
    "payload": {
      "input": "73df1e16-fd8b-47a1-a156-f197babde91a",
      "input_format": "docx",
      "output_format": "pdf",
      "pages": "1-2",
      "optimize_print": true
    },
    "result": null
  }
}

List supported formats

List all supported formats, their engines and possible options.

Query Parameters
filter[input_format] string, optional The result will be filtered to include only possible conversions with a matching input format.
filter[output_format] string, optional The result will be filtered to include only possible conversions with a matching output format.
filter[engine] string, optional Filter result to only include conversions with a matching engine name.
filter[engine_version] string, optional Filter result to only include conversions with a matching engine version.
alternatives boolean, optional For some formats multiple alternative engines are available. If set to true, the result includes these alternative conversion types. Default to false.
include array, optional Include options and/or engine_versions in the result.

Returns

The list of possible conversion types.

Attributes
operation string Value is convert.
input_format string Format of the input file.
output_format string Format of the conversion result.
engine string Name of the engine.
options array Possible options for this conversion type. Available, if the include argument contains options.
Show child attributes
engine_versions array Compatible engine versions for this conversion type. Available, if the include argument contains engine_versions.
Show child attributes
deprecated boolean This format is deprecated.
experimental boolean This format is experimental.
meta dictionary Meta attributes.

Endpoint

GET https://api.cloudconvert.com/v2/convert/formats

Example Request

$ curl -g "https://api.cloudconvert.com/v2/convert/formats?filter[input_format]=pdf&include=options"

Example Response

{
  "data": [
    {
      "operation": "convert",
      "input_format": "docx",
      "output_format": "pdf",
      "engine": "office",
      "options": [
        {
          "name": "page_range",
          "type": "string",
          "default": null
        },
        {
          "name": "optimize_print",
          "type": "boolean",
          "default": true
        },
        {
          "name": "pdf_a",
          "type": "boolean",
          "default": false
        },
        {
          "name": "input_password",
          "type": "string",
          "default": null
        },
        {
          "name": "templating",
          "type": "dictionary",
          "default": null
        }
      ],
      "meta": {
        "group": "document"
      }
    },
    {
      ...
    },
    {
      ...
    }
  ]
}