Skip to content

Advanced Options

FreeConvert provides a comprehensive set of advanced options for converting, compressing, and merging files. These options are also available through the API.

Using the advanced options endpoint, you can retrieve all available options for a given operation and file type combination. The following example demonstrates how to use these options.

To retrieve the advanced options for converting a JPG to PDF, make a request to the advanced options API as shown below:

GET https://api.freeconvert.com/v1/query/options/convert?input_format=jpg&output_format=pdf

The response will be similar to the following:

JPG to PDF Advanced Options

{
  "sourceExt": "jpg",
  "targetExt": "pdf",
  "operation": "convert",
  "options": [
    {
      "name": "strip",
      "hint": "Strip the image of any profiles, EXIF, and comments to reduce size",
      "data_type": "boolean",
      "default_value": "true"
    },
    {
      "name": "pdf_page_size",
      "hint": "",
      "data_type": "string",
      "type": "enum",
      "enum_values": [
        {
          "value": "1240.2x1753.95",
          "hint": "A4"
        },
        {
          "value": "same-as-image",
          "hint": "Same as image"
        },
        {
          "value": "1753.95x2480.25",
          "hint": "A3"
        },
        ...
      ]
    },
    {
      "name": "enlarge_images_to_fit",
      "hint": "Use this option if you want to enlarge small images to fit the PDF page size.",
      "data_type": "boolean",
      "default_value": "true",
      "conditions": [
        {
          "name": "pdf_page_size",
          "required": true,
          "meta": [
            {
              "value": "1240.2x1753.95",
              "label": "A4"
            },
            {
              "value": "1753.95x2480.25",
              "label": "A3"
            },
            ...
          ]
        }
      ]
    },
    ...
  ]
}

The response includes an options array containing all available advanced options for the requested operation. Each option contains the following common fields:

  • name - The name of the option that should be specified in the job.
  • hint - The use case of the option.
  • data_type - The data type accepted by the engine for this option.
  • default_value - If the option is not included in the job, this value will be used.

The type: enum field is present when data_type is a string that only permits specific values. In this case, the enum_values field provides a list of the permitted values for that option.

Some options require certain conditions to be met in order to take effect. In the example response, the enlarge_images_to_fit option requires a pdf_page_size value to also be present in the job. Conditions can include:

  • name - The name of the other option that this option depends on.
  • meta - The values that the condition option must have for the dependent option to take effect.
  • required - Indicates whether the condition option must be included in the job. If false, the dependent option can exist independently; however, if the condition option is also present, it must have one of the values specified in the condition meta.

For example, to convert a JPG file to PDF with the PDF page set to A4 and images kept at their original size without scaling, the options to specify in the job would be:

{
  "pdf_page_size": "1240.2x1753.95",
  "enlarge_images_to_fit": false
}