Conversions with options

Introduction

A conversion allows you to specify a set of options that will change the output of your conversion.

This, for example, allows you to turn a colourful image into black and white or resize a video.

Discover available options

Take the following example: We want to convert an image to png, but in addition to that, it should be monochrome.

How can you find out if this is available and what other options you have to edit your file?

There is a list of all conversions and conversion options available here: https://api.api2convert.com/v2/conversions

The list can also be filtered by target: https://api.api2convert.com/v2/conversions?target=png

Example Code

The information you get looks similar to this:

{
   "id":"59",
   "target":"png",
   "category":"image",
   "options":{
      ... many options here ...
      "color":{
         "type":"string",
         "enum":[
            "colored",
            "gray",
            "monochrome",
            "negate",
            "1980",
            "1900"
         ],
         "default":"colored",
         "description":"Color to apply the image"
      },
      ... many more options here ...
   }
}

There you see that the monochromeoption we were looking for is available.

Now we can proceed to create a job with the options that we need.

Discover available presets

For some conversion targets we offer the option to select a public preset from us. This preset will internally set some conversion options to meet a special target device or platform. To find out which presets are available, we provide the following endpoint: https://api.api2convert.com/v2/presets

Here, you can also set some parameters to find a specific preset. You can use category, target and filter. Filter will search the preset name and can be a comma separated list of search terms.

E.g. https://api.api2convert.com/v2/presets?category=video&target=mp4&filter=facebook,hq

The information you get looks similar to the example code.

The result can also include your custom presets. To find out how to save your own preset have a look here.

The value you have to set for the option preset is the id. So, if you want to use the "Facebook HQ 1280x720 (HD) 25fps" preset, you set the option "preset": "5ad9f696-7930-4991-9f03-460c3d703b89".

If you combine a preset with other options of your choice, we always overwrite the preset options with the manually set options.

Now we can proceed to create a job with the options that we need.

Example Code

[
    {
        id: "2c450e57-ef64-469d-8245-c39535994de2",
        name: "Facebook HQ 1280x720 (HD) 23.976fps",
        category: "video",
        target: "mp4",
        scope: "public"
    },
    {
        id: "5ad9f696-7930-4991-9f03-460c3d703b89",
        name: "Facebook HQ 1280x720 (HD) 25fps",
        category: "video",
        target: "mp4",
        scope: "public"
    },
    ...
]

Create jobs with options

To create jobs with options for the conversions, use the options key to pass the according options and their values.

The following request is used to convert an image with the options color and rotate, applying the 1980 color filter and rotating it by 180 degrees.

Example Code

curl -X POST \
  https://api.api2convert.com/v2/jobs \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-oc-api-key: <your API key here>' \
  -d '{
    "input": [{
        "type": "remote",
        "source": "https://example-files.online-convert.com/raster%20image/png/example_small.png"
    }],
    "conversion": [{
        "category": "image",
        "target": "png",
        "options": {
            "color": "1980",
            "rotate": 180
        }
    }]
}'

Create jobs with options Example

The following request is used to convert an mp4 with the options preset.

Example Code

curl -X POST \
  https://api.api2convert.com/v2/jobs \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-oc-api-key: <your API key here>' \
  -d '{
    "input": [{
        "type": "remote",
        "source": "https://example-files.online-convert.com/video/mp4/example_2s.mp4"
    }],
    "conversion": [{
        "category": "video",
        "target": "mp4",
        "options": {
            "preset": "5ad9f696-7930-4991-9f03-460c3d703b89"
        }
    }]
}'

Modify conversion options

If a job is not yet started, you may need to patch it to modify the conversion's options. You can reach the goal by sending a conversion PATCH request to the endpoint:

/v2/jobs/<job_id>/conversions/<conversion_id>

with the new options inside the body like in the following example.

Let's assume that your job with id f496edcb-64e2-4f76-abf0-74f75338d4eb has a conversion with id 1886af23-86ac-461e-9a86-87d018260043 that looks like the following:

Example Code

"conversion": [{
    "id": "1886af23-86ac-461e-9a86-87d018260043",
    "target": "gif",
    "category": "image",
    "options": {
        "download_password": null,
        "allow_multiple_outputs": false,
        "dpi": 300,
        "width": 500,
        "height": 300,
        "crop_top": null,
        "crop_bottom": null,
        "crop_left": null,
        "crop_right": null,
        "crop_origin_x": null,
        "crop_origin_y": null,
        "crop_width": null,
        "crop_height": null,
        "color": "1980",
        "enhance": null,
        "normalize": null,
        "sharpen": null,
        "antialias": null,
        "despeckle": null,
        "equalize": null,
        "deskew": null,
        "rotate": null,
        "preset": null,
        "alpha_channel": null
    },
    "metadata": {},
    "output_target": []
}]

Patches

Now, let's assume you want to modify the options by removing dpi, updating the image's size (width x height) and setting deskew.

Your PATCH request should look like the following:

Example Code

PATCH /v2/jobs/f496edcb-64e2-4f76-abf0-74f75338d4eb/conversions/1886af23-86ac-461e-9a86-87d018260043 HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "options": {
        "dpi": null,
        "width": 1024,
        "height": 768,
        "deskew": true
    }
}

Other options

Note that all of the other options will keep the old values, like e.g. "color": "1980".

If you send a
GET /v2/jobs/f496edcb-64e2-4f76-abf0-74f75338d4eb
request, the conversion object in the response will reflect your PATCH like in the example code below.

Please, note that you can PATCH only the options and metadata objects of the conversions.

Example Code

"conversion": [{
    "id": "1886af23-86ac-461e-9a86-87d018260043",
    "target": "gif",
    "category": "image",
    "options": {
        "download_password": null,
        "allow_multiple_outputs": false,
        "dpi": null,
        "width": 1024,
        "height": 768,
        "crop_top": null,
        "crop_bottom": null,
        "crop_left": null,
        "crop_right": null,
        "crop_origin_x": null,
        "crop_origin_y": null,
        "crop_width": null,
        "crop_height": null,
        "color": "1980",
        "enhance": null,
        "normalize": null,
        "sharpen": null,
        "antialias": null,
        "despeckle": null,
        "equalize": null,
        "deskew": true,
        "rotate": null,
        "preset": null,
        "alpha_channel": null
    },
    "metadata": {},
    "output_target": []
}]

Custom User Presets

We offer the possibility to save a set of options for a certain target as a preset, so it can be easily used in later conversions. These presets are only visible for the user that saved them.

The following request creates a preset for a PNG conversion with the options color and rotate, and sets the name to "my preset".

Example Code

POST /v2/presets HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "name": "my preset",
    "target": "png",
    "options": {
        "color": "1980",
        "rotate": 180
    }
}

Finding Custom Presets

To find out how to use your preset proceed to create a job with the options that we need to make use of your preset.

To get all information for one preset, send the following request:

Example Code

>GET /v2/presets/<preset id here> HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "name": "my new preset name"
}

Modifing a Custom Preset

If you want to modify a preset e.g. to set other options or a different name, you can send a patch request for the preset id you want to modify.

Example Code

PATCH /v2/presets/<preset id here> HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "name": "my new preset name"
}

Deleting a Custom Preset

To delete a preset, simply send a delete request for the preset id you want to delete.

Example Code

DELTE /v2/presets/<preset id here> HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache