Convert Files

Create convert tasks

Job Builder

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.
This conversion type is marked as experimental.
... 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: , .
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).
engine string, optional Use a specific engine for the conversion.

engine_version string, optional Use a specific engine version for the conversion.
timeout integer, optional Timeout in seconds after the task will be cancelled. By default, tasks time out after 5 hours.

Returns

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

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.
credits integer The base amount of conversion credits this conversion type consumes.
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",
      "credits": 1,
      "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"
      }
    },
    {
      ...
    },
    {
      ...
    }
  ]
}